POD vs. reST for standalone writing?

[eichin at metacarta.com]

> That gives you plenty of room for growth.

Oh, good point, I could just always put in 79 column underlines in the
examples and people will just paste those and all will be fine...

> styles.  For example, a 1st-level section can become a 2nd-level

Ah, yeah, that would work better than pod-style explicitly counted
ones.  (You'd still have to require section authors to agree on what
depth punctuation to use, or a later section from a different author
would nest "under" later parts of the first one, but it does allow
simple motion.)

> If the end user in question is the *reader* (which is the case with
> reStructuredText), I think the underline-style method is most
> transparent.  In other words, the reader doesn't notice the markup or
> care.

I think I now see what the big difference in usage here is - reST
really does have a *primary* use of "read the reST source", whereas in
the context I'm concerned with, reading the source is primarily an
adjunct to editing it, so that reader-benefit gets only a little
multiplier against writer cost, whereas with the normal reST case,
there are still many more readers of unprocessed source than there
would be writers of it.  So that's where reST *really* flies,
especially for inlining with code... that it really allows casual
reading much more than anything else that I was considering.

I'll have to see if I can come up with a matrix of systems in terms of
writer-ease/cost and reader-ease/cost with and without tools or
processing (so, for example, HTML has greater writer-ease with
netscape composer or emacs sgml-mode than it does with vi; docbook
pretty much needs emacs psgml or frame/sgml to have any writer-ease at
all, and reader-ease requires output processing as well; nroff has a
high writer-cost [more than if generated from docbook, say] and an
insane reader-cost with no tools, but with simple processing [nroff]
reader-ease is high... tex/latex are easier to write than read raw,
but first stage tools are typesetting grade so they get good
reader-ease there.  Ok, so maybe most of that is subjective, but of
the ones mentioned, reST will likely win on "reader ease with no
tools" (with RFC-text and one of the homebrew systems mentioned in
this thread a close second, if I'd included them here... pod would be
ahead of tex, docbook, and html, but behind reST or any of the simple
text modes.)

I'll see if I can come up with a way to figure out a balance for these
(and maybe actually sketch out that grid, and in which tool? :-), and
use reST for more actual documents to give it a fairer comparison from
my end before we actually choose something.  (Now that I see it in
these terms, I understand why reST makes a lot more sense for python
than it does for what I had in mind, but still don't know where *that*
balance falls... "stay tuned" :-)