[rust-dev] Documentation

Marijn Haverbeke marijnh at gmail.com
Wed Jan 4 11:24:19 PST 2012


I agree with what Matt suggested on IRC -- that non-HTML docs mostly
don't matter anymore.

Markdown's syntax rules are an abomination, but in practice their
poorly thought-out corner cases don't really get in the way much. It
has 'won' as far as HTML-near markup languages go, and almost every
programmer is fluent in it.

>  - A tutorial written in hand-extended markdown and processed
>   by hand-written javascript

The tutorial is actually standard markdown, with the addition of using
the definition list extension (which is supported by most parsers),
and doing some post-processing on code blocks to syntax-highlight them
and to remove some magic directives to make it possible to execute
them (thus making it easy to keep it in sync with the actual
compiler). This code post-processing is completely orthogonal to the
markup format we use -- something like it would have to happen in
texinfo as well. (The choice of JS for the rendering script was
prompted by the fact that we already have a very good Rust highlighter
in JS -- the CodeMirror mode I wrote).

Integrating markdown in rustdoc seems like a very good idea. In
general, my vote is for more markdown.


More information about the Rust-dev mailing list