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
|