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
|
