[rust-dev] Documentation

Ralph Giles giles at thaumas.net
Wed Jan 4 11:47:50 PST 2012


On 4 January 2012 13:05, Graydon Hoare <graydon at mozilla.com> wrote:

> Maybe that's ok? Maybe PDFs and "printed manuals" and such are vestigial
> nonsense we can consign to history?

As someone who likes PDF, I'd say there aren't any tools which are
good at producing both HTML and PDF output.

I like PDF because it gives me a single file I can download and refer
to later. I don't print them out every often, but it's very nice to
have and refer to without needing a network connection (or waiting for
round-trip latency whenever I change sections).

In our codec work we've had the most success using latex directly.
Being able to properly represent equations is a real win there, and
our developers tend to be at least somewhat familiar with the format.
The drawback is that there are no good latex to HTML tools, and one
doesn't get contributions from anyone who hasn't climbed the learning
curve.

Going the other direction is much easier; if you don't need equations,
I'd recommend starting with markdown/texinfo/doxygen, etc. and
generating various output formats from that.

I'd also remark that documentation is never one-size-fits-all.
Extract-and-generate is a nice place to start, and certainly better
than nothing, but it doesn't replace a written manpage, for example.
It's more important to focus on making the documentation findable and
maintainable than to have the source be in any unified format.

FWIW,
 -r


More information about the Rust-dev mailing list