On 4 January 2012 13:05, Graydon Hoare <[email protected]> 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 _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
