POD vs. reST for standalone writing?

[eichin at metacarta.com]

> That's significant: "somewhat (and I think only a little) easier to
> read".  I designed reStructuredText to be a *lot* easier to
> read. Opinions vary of course, I think mostly determined by what
> you're used to.  (Some people think in XML, others dream in TeX.  Not
> me.)

Oh, very much so - and what I dream in is often much influenced by
what I've been coding/speaking recently... which is why POD struck a
cord after doing a few months of python programming, actually (the
whole "oh, just indent the literal stuff" part, the rest is very
light.) (15 years ago, I could type LaTeXish equations faster than
many people could write them on paper, and certainly faster than they
appeared on most chalkboards :-)  Not today, though.)

And I certainly see the value of biasing towards the reader - decades
of C and C++ justify significant overreaction in that regard :)  At
the same time, the need to encourage casual writers is still there.

The particular writability issue that comes to mind is the use of
underlining characters, quoting from quickstart.html:

Chapter 1 Title
===============

Section 1.1 Title
-----------------

Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~

and the description "The underline/overline must be at least as long
as the title text."  My first problem with this is that if changing
the content causes the markup to need changing, the markup changes
will be a bit more error prone.  The next is that level for a given
punctuation type is based on, if I'm not misinterpreting this, what
punctuation usage has been seen *in this document*, which makes moving
selections among a small set of documents a little harder, unless you
have an explicit style guide (in which case, why not represent it
outright in the code?)

POD here would just say

=head1 Chapter 1 Title

=head2 Section 1.1 Title

=head3 Section 1.1.1 Title

(ignoring that in both reST and POD, you'd really just say "Title" for
all three and leave the numbering/layering to the stylesheets.)

Perhaps this is just one corner of the notation - but I'm looking for
a case that simply doesn't have all that much notation, or that much
to explain to the end user.

(more to come, apologies for stopping in the middle, there have been a
wealth of good comments here...)