@Matthew, @Stephen: Empty {} won't work because @foo[bar]{} is equivalent
to @(foo bar). Also note that Scribble manual trims whitespace, so you
can't "trick" it by writing @(foo bar " ") (or equivalently @foo[bar]{ })
@John: I agree with you that defthing is not ideal because we don't really
want to define these functions in the guide, and there should be links to
the actual definitions in the reference. However, considering alternative
forms that are currently available, I find it to be a good compromise.
Normally in tutorials, we would simply show examples (e.g.,
https://docs.racket-lang.org/guide/pairs.html). But web-server is weird
because the request object is given to you by the language. While it's
possible to construct the request object manually, it's really a pain.
Hence, to write an example of request-bindings, you need to bring in the
whole language setup (hash lang line, the start function, etc.). I don't
think it is okay to do this over and over again (note that there's an
example already at the end of that section)
Therefore, I find that simply showing the contract of these functions are
detailed enough to let users understand how to use them (plus, there are
brief explanations how these functions work already in the preceding
paragraphs).
Really, what I am proposing here is a defthing-like form that simply shows
the contract and have proper links to the actual definition.
----
Regardless of the above discussion, I still wonder why the absence of
SIntrapara could be desirable.
On Monday, January 14, 2019 at 1:08:49 PM UTC-8, spdegabrielle wrote:
>
> Adding a {} after @devthing[...] to get @devthing[...]{} didn't fix the
> vertical spacing between the lines.
> What I did: @defthing[request-bindings (request? . -> . bindings?)]{}
>
> I took a look at asn1
> https://github.com/rmculpepper/asn1/blob/master/asn1-doc/scribblings/types.scrbl
>
> http://docs.racket-lang.org/asn1/types.html?q=asn1
>
> @defthing[]{} works correctly in the asn1 manual because the curly
> brackets are populated.
>
> is there a way I can force a couple of <br/> in scribble? (as a temporary
> measure - I'm not keen to change the scribble/manual, scribble/doc or the
> CSS stylesheets etc.)
>
> Stephen
>
> PS Would pollen be a better fit for a tutorial format?
>
> On Mon, Jan 14, 2019 at 7:51 PM 'John Clements' via Racket Users <
> racket...@googlegroups.com <javascript:>> wrote:
>
>> I think the use of defthing here is not really correct; I would argue
>> that if you’re going to use a defthing, you should go ahead and provide the
>> definition of the thing. Otherwise, just put in a reference to the name, so
>> that the user can click through to see the definition. I think that this
>> “in-between” use where you have the header but not the textual definition
>> is violating user expectations in a confusing way…
>>
>> John
>>
>>
>> > On Jan 14, 2019, at 11:46 AM, Matthew Butterick <m...@mbtype.com
>> <javascript:>> wrote:
>> >
>> > I believe the `defthing` tags need an empty {} after them.
>> >
>> >
>> >> On Jan 13, 2019, at 11:51 PM, Sorawee Porncharoenwase <
>> sorawe...@gmail.com <javascript:>> wrote:
>> >>
>> >> This seems to be a known and expected output, however. According to
>> https://docs.racket-lang.org/demo-manual-m2/Definition_Blocks.html:
>> >>
>> >> Since no explanation flow is attached to the above defform use,
>> there’s no SIntrapara block around the table (just a <p>).
>> >>
>> >> The question is, when is this ever a desired output? It seems
>> objectively ugly and confusing in all use cases.
>> >
>> >
>> > --
>> > You received this message because you are subscribed to the Google
>> Groups "Racket Users" group.
>> > To unsubscribe from this group and stop receiving emails from it, send
>> an email to racket-users...@googlegroups.com <javascript:>.
>> > For more options, visit https://groups.google.com/d/optout.
>>
>>
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "Racket Users" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to racket-users...@googlegroups.com <javascript:>.
>> For more options, visit https://groups.google.com/d/optout.
>>
>
--
You received this message because you are subscribed to the Google Groups
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
