Giters

racket / web-server

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Tutorial 'continue.scrbl' signatures rendering confusing to readers

spdegabrielle opened this issue · comments

commented

The rendering of signatures in the Continue tutorial is confusing to readers

In the tutorial, functions are often described, then followed by their signature in the familiar scribble/manual format.

Unfortunately the hairline at the top of the signature, in addition to the large gap above, and lack of a gap below gives the impression the signature is associated with the subsequent text.

e.g. http://docs.racket-lang.org/continue/index.html?q=specform#%28def._%28%28lib._web-server%2Fservlet..rkt%29._extract-binding%2Fsingle%29%29

My suggestion is the rendering of continue is changed to support the 'description followed by signature' style of the text. I'd suggest moving the hairline to the bottom of the signature, and increasing the spacing between the signature and the subsequent paragraph.

Options to resolve;

  • a different css stylesheet for continue.scribble
  • an new signature function that handles spacing differently
  • other options?

https://github.com/racket/web-server/blob/master/web-server-doc/web-server/scribblings/tutorial/continue.scrbl

https://github.com/racket/scribble/blob/master/scribble-lib/scribble/private/manual-proc.rkt

commented

Ya, it does look weird now. How about just inserting some linebreaks after the signatures to make sure they are offset enough?

commented

I think inserting link breaks is a good temporary solution. In any case, as John Clements said in the mailing list (https://groups.google.com/forum/#!topic/racket-users/hGmq8pzgRGc), using defthing/defproc/def* in the guide is not ideal because we don't want to define anything and it wouldn't link to the actual definition in the Racket reference.

I propose that there should be another family of forms that references the def* forms. Greg Hendershott proposed ref* which I think is brilliant.

commented
commented

We could also re-word to give the defthings a definition, e.g. #51

I agree ref* would be great for parts of Continue.

commented

@sorawee @greghendershott @jeapostrophe @jbclements @mbutterick

Hi,

To summarise; function signatures rendering reduce readability of the Continue Tutorial (thanks @sorawee for raising this)

Options suggested to resolve this include

  1. adding line breaks (an interim measure) [done]
  2. creating new signature functions
  3. reword the tutorial
  4. create a new signature function @ref*[]{}
  5. [pollen](http://docs.racket-lang.org/pollen/quick-tour.html) by @mbutterick might be a better fit than scribble/manual for tutorial documents (my suggestion - though I admit I don't have any experience with pollen - I just think the beautiful racket tutorials)

I see the Continue tutorial as a flagship tutorial for Racket and worth investing some time in.
I've decided to try dedicate some time both to work on it in any way I can, and to recruit others to the task, with the understanding that any changes need approval from Jay (@jeapostrophe ) the author/maintainer.

To my mind these the suggestions above can be decided into two broad groups;

  1. coding to make the document rendering suit the existing text
  2. update the text

i'd like to suggest that both are good proposals and not mutually exclusive;

  • the coding to better support tutorial style documents could be some combination of
    • updating scribble/manual (adding a @ref@[]{} function)
    • creating a `scribble/tutorial'
    • porting to pollen
  • the rewriting could include
    • rewording to work better with the signature functions,
    • rewriting to eliminate the signatures as used in the formlets section

Is anyone interested in doing or leading one of these tasks, or recruiting someone else who could? (contribution to the racket project looks great on a CV)

On the topic of rewriting please see issue #53

Notes:

  • the tiny gap between the signature and subsequent text doesn't occur in other manuals
  • the formlets section doesn't use the scribble/manual signature functions @defthing[]{} etc.
  • the problem of no break between the signature function and following text doesn't appear in other scribble/manual documents (I've included some images below from continue and The Racket Reference to demonstrate)

screenshot 2019-01-18 at 08 42 42

screenshot 2019-01-18 at 08 41 27

screenshot 2019-01-18 at 08 42 48

screenshot 2019-01-18 at 08 41 10

commented

To make the belonging of @defthing[]{} more clear I suggest the new proposed @ref@[]{} to be indented, to get the effect similar to (minus text centering):

To verify that a set of bindings contains a particular field, use
@racket[exists-binding?]:

@centered{
@defthing[exists-binding? (symbol? bindings? . -> . boolean?)]}

@linebreak[]

With these functions, we can design functions that consume @racket[request]s
and respond to them usefully.
commented

See also specform, which is like defform but with #:link-target? #f and indented. It sounds like the idea of ref forms is similar, so maybe specform is a useful guide — or maybe not, since specform is among the oldest and cruftiest parts of Scribble, and I don't think it has been used much.

commented

IMHO specform looks really close to how I would envisage ref to look - only switching the size of top and bottom margins and visually that would be it. As to syntax/grammar - should it be like defthing, defproc, defform, etc.? Or maybe every def... should have its ref... equivalent that would differ only in margins, indentation and #:link-target? #f.
EDIT: I suppose that's what was suggested above with ref* anyway.