POD vs. reST for standalone writing?

[David Goodger]

eichin at metacarta.com wrote:
> The particular writability issue that comes to mind is the use of
> underlining characters, quoting from quickstart.html:
...
> 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.

If you're liable to edit your titles a lot, just use extra-long underlines:

     Title
     ==============================================================

That gives you plenty of room for growth.

> 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

There is no one best way, IMO.  Given good enough tools, the problem 
disappears, whatever scheme is used.  There's some Emacs code to aid 
with title underline style changes when editing reStructuredText files.

Explicitly specified levels have their own shortcomings.  They have to 
be edited when the doc structure changes (change all "head2" to "head3", 
but don't forget to change all "head3" to "head4" first [etc etc] or 
else the doc structure will be screwed).

With underline styles, doc structure can be altered by adding new 
styles.  For example, a 1st-level section can become a 2nd-level section 
by adding a new top-level title.

> 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.

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.

-- David Goodger