Does anyone have experience using Markdown format for embedded
documentation in Racket, including generating Scribble docs (to be the
most cooperative Racket citizen)?
How well has that worked, in practice? Do you end up having to kludge
things, and do you find you can't express things you want to, that you
could in Scribble?
Background and comments...
Long ago, I used embedded Texinfo format for documenting Scheme
programs, and later made a Scribble backend after Scribble was created.
The result out of Scribble's formatter was poor, compared to docs from
Scribble source (e.g., the Texinfo couldn't express types in procedure
signatures).
I was reminded of Markdown because some Rust embeded documentation is
using it, in 3-slash comments, and their docs look pretty good
(excepting a usability problem in how they split across pages). Rust has
complicated type information (more complicated than anything I've seen
in Racket), but they seem to scrape the type declarations from the code,
in the examples I've seen so far. I haven't looked at this yet, and
don't yet know whether there's an option for expressing documented type
information manually in the Markdown, when it can't be scraped.
I'm trying to decide whether to do my next embedded docs thing using
3-semicolon Markdown in comments -- rather than Scribble in at-reader
forms that the `#lang` special-cases, or Scribble in 3-semicolon
comments. (I also have some experience scraping type info from Racket,
and was surprised by the number of forms I had to handle, for lambdas
and contracts alone, before I even got to TR.)
Currently, 99% of my current interest is in the stock Scribble forms
(including the BNF ones), and only 1% is in package-specific extensions
of Scribble forms. I have already had occasion for package-specific
extensions, such as for detailed spec citations shorthand, and for
concepts like
"http://www.neilvandyke.org/racket/roomba/#(part._.Sensor._.Packets)",
but those haven't been crucial. Extensions become more important for
`#lang` that introduce major API concepts other than procedures,
methods, etc., so I suppose that might be a reason to stick with
Scribble as the source format for all docs.
Then there's potentially losing things like `@tech`, and the distinction
between `@racket` and `@code`. Though the current Scribble CSS is
distinguishing those less than the original did, anyway. Maybe an
optional Markdown extension, like "r`foo`" would work, for the people
who want to retain things like `@racket`.
--
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 [email protected].
For more options, visit https://groups.google.com/d/optout.
