POD vs. reST for standalone writing?

[Ian Bicking]

On Mon, 2003-04-28 at 23:17, David Goodger wrote:
> eichin at metacarta.com wrote:
> > 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. 
> 
> 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.)
> 
> As for being harder to write, that may be true, especially if the author 
> isn't used to the markup yet.  In reStructuredText, readability is 
> deemed far more important than writability.  But with increasing 
> familiarity comes increasing ease of writing.

I would say (emphatically!) that reST is good for writing, and that's
why I like it, more than for reading.  Sure, I know (X)HTML just fine,
but using it in documentation does not appeal to me one bit.  Honestly,
I can't think of a worse format for writing... it's good for
extensibility, and it's well known, but it's not easy on the fingers (or
on the brain, while I'm trying to write about code, not think about what
I'm typing).

As far as learning to write... it takes a little bit.  Linking still
confuses me sometimes.  But you can use it easily enough without knowing
anything about it, and it pretty much works... so I don't think it's
that big of a problem.  Perhaps it would help if a few of the more
obscure kinds of linking and annotation could be turned into a clearer
set of orthogonal features.

  Ian