re: https://github.com/racket/web-server/issues/50
Hi, I've copied comment on the Continue issue from GitHub because I consider Continue and important and valuable resource. It is linked from the Racket home page, I've referred to it many times and continue(Ha!) to do so as I learn more about building web applications in Racket, and due to the prominence of the Continue tutorial, I suspect it is a common starting point for many who are new to Racket. Obviously you only see GitHub issues if you are @mentioned or have subscribed, so I have copied it here for feedback: --update to issue #50: To summarise; function signatures rendering reduce readability of the Continue Tutorial (thanks @sorawee <https://github.com/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 <https://github.com/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 <https://github.com/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 <http://docs.racket-lang.org/continue/index.html#%28part._.Using_.Formlets%29> 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 <https://github.com/racket/web-server/issues/53> Notes: - the tiny gap between the signature and subsequent text doesn't occur in other manuals - the formlets section <http://docs.racket-lang.org/continue/index.html#%28part._.Using_.Formlets%29> 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 <http://docs.racket-lang.org/reference/symbols.html#%28def._%28%28quote._~23~25kernel%29._symbol~3f%29%29> to demonstrate) On Tue, Jan 15, 2019 at 11:47 PM Stephen De Gabrielle < spdegabrie...@gmail.com> wrote: > Hi Sorawee, > > This is a blight on an otherwise brilliant tutorial. Sadly I don't have > the time to resolve it. > > Lacking a clear solution I've added an issue > https://github.com/racket/web-server/issues/50 > > A short term solution much be to drop @defthing[] and use a monospace > font, maybe using @tt[]? > > Kind regards, > > Stephen > > > https://github.com/racket/scribble/blob/master/scribble-lib/scribble/private/manual-proc.rkt > > https://github.com/racket/web-server/blob/master/web-server-doc/web-server/scribblings/tutorial/continue.scrbl > > On Tue, Jan 15, 2019 at 3:43 PM Greg Hendershott < > greghendersh...@gmail.com> wrote: > >> On Tue, Jan 15, 2019 at 10:04 AM Sorawee Porncharoenwase >> <sorawee.pw...@gmail.com> wrote: >> > >> > Yup. This is exactly the proposal I made above, but you stated it far >> more clear :) >> >> Whoops. Insufficient coffee. Sorry! >> >> -- >> 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. >> > -- 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.
