POD vs. reST for standalone writing?

Aahz aahz at pythoncraft.com
Tue Apr 29 06:24:53 CEST 2003


In article <7gd6j6kpq0.fsf at pikespeak.metacarta.com>,
 <eichin at metacarta.com> wrote:
>
>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

Aside from the screen shots issue, reST does reasonably well (reST may
in fact handle screen shots fine; I just can't say it does from personal
experience).

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

You certainly don't need to use all of reST's power; you can teach your
users the minimum they need to get their work done.  But there's no
getting around the fact that reST does provide all that power, and users
who play around will run into it.  I wouldn't say that reST is intended
to be easy to write; it's intended to provide a balance between
writability and readability.  It's a text format that's human readable,
providing much (but far from all) the power of DocBook or LaTex.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"In many ways, it's a dull language, borrowing solid old concepts from
many other languages & styles:  boring syntax, unsurprising semantics,
few automatic coercions, etc etc.  But that's one of the things I like
about it."  --Tim Peters on Python, 16 Sep 93




More information about the Python-list mailing list