What doc format do you like writing in?
"John Gabriele" <[email protected]> Mon, 25 Sep 2006 17:41:13 -0400
| Newsgroups | gmane.comp.lang.ruby.documentation |
|---|---|
| Message-ID | <[email protected]> |
I'm curious what format folks here like writing their docs in (not necessarily the ones that go in with source code), and why they do or don't like certain formats. As for me: * rdoc -- I like its simplicity, but I end up writing lots of html when using it because it doesn't provide many special markup commands (which is actually probably a good thing). I end up typing <tt>this</tt> a lot when writing rdoc. Also, rdoc doesn't seem to let me include arbitrary html (ex., blockquotes or <div id="whatever">). As an aside, I've heard the actual rdoc code is difficult to hack on, though it looks pretty clean and well-commented. * LaTeX -- Produces very beautiful output (*especially* for mathematics), but can be a bear learning to make it do things outside of the basics (i.e., syntax highlighting code, hyperlinks, adding graphics (like screenshots)). Easy stuff with LaTeX is easy, hard stuff is quite difficult (IMO). * Textile (a la RedCloth) -- Very featureful. When I used it though, IIRC, it tended to require me to escape lots of symbols that would otherwise be markup commands. For example, typing ~/john, it would want to use that tilde as markup. Probably a little too much markup for my taste. * Markdown (a la BlueCloth) -- Looks great in a text editor. No tables or definition lists, but lets you put any html in that you want. No Emacs mode for markdown yet, but I hear one is on the way. * POD -- I haven't written hardly any pod, but looking at Perl's docs (and some raw pod), it seems very straightforward. I like the simplicity. I bet the pod parser is pretty simple and reliable due to having so little markup to deal with. And it comes with all those nice tools: pod2man, pod2html, pod2text, pod2latex. * DocBook -- very verbose. Also, the toolset seems a bit complicated to get used to. Not my thing. * Texinfo -- the GNU standard. Doesn't look too bad. Would need to learn more about bookmarks vs. cross-references, nodes, and some other info command stuff to use it well. Seems to work well with Emacs. ;) Also, I think you can get TeX-formatted math out of it (for, say, generating a pdf). Which ones did I miss? Any strong likes or dislikes? If you had your choice, what format would you write most of your docs in? Thanks, ---John