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 racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to