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