POD vs. reST for standalone writing?
eichin at metacarta.com
eichin at metacarta.com
Mon Apr 28 22:21:59 EDT 2003
So, after a recent bad experience with LyX and version skew, I was
looking at alternatives for software end-user and administrator
documentation. The constraints are pretty simple:
* produce good html and PDF
** via linux tools, and highly preferably free ones
* be editable on multiple platforms
** linux first, but also, osx, windows
* support "literal computer output" and screen shots
DocBook was under consideration (and was used for some man pages and
standalone docs) but has a high learning curve, and none of the
windows dtd-aware or docbook-aware editing tools actually seemed to
*work* well enough to hand them to non-techies (the techies, on linux,
are already happy with emacs and vi :) Also, the subject of the
documentation changes rapidly enough that having document specialists
just isn't acceptable, everyone involved needs to be able to update
things.
Anyway, POD came up as a documentation format in a related context (in
particular, "I'm going on vacation, here's a walk through of how that
code works, don't call me" :) and it was very effective for output
that was dominated by verbatim code snippets interspersed with text;
in fact *easier* to write in than raw HTML would have been, though
probably no more expressive. PDF output was not unreasonable (via
html or more directly via latex, so I haven't had to dig further.)
Now I start seeing mention of reStructuredText (especially in comments
about pyCon.) reST files look very "ascii art" on the input side, but
after a little experiment, that seems to make them *harder* to write,
if somewhat (and I think only a little) easier to read.
Am I missing something? Is there actually a reST clear short hand,
and a tool that expands it to full-blown ascii-art? Or is at least
fuzzy in the counting of dashes and other punctuation for marking
different levels?
(POD is perhaps a little too simple, but a first cut POD Parser class
in python, with a derived pod2html was the work of a recent
cross-country plane flight, so that's not all bad... and I'm not sure
that a pod2reST would be that hard either...)
More information about the Python-list
mailing list