POD vs. reST for standalone writing?

David Mertz mertz at gnosis.cx
Tue Apr 29 17:39:31 CEST 2003

|Yep.  For Twisted's documentation (now over 200 pages as a PDF), I think
|Lore was the right choice (even if we did have to invent it first).  Other
|users will have to make their own decisions about what's right for

FWIW, I wrote my whole 500+ page book (http://gnosis.cx/TPiP/) using my
own "smart ASCII" format, which is even lighter than reST.  Actually, I
believe it is quite a lot "lighter" (take a look).  The final
book--which I believe is quite attractive--is generated 100% from the
smart ASCII source... including use of fonts, headers, cross-references,
decorative elements, and so on.  The chain is (smart ASCII -> LaTeX ->
PDF -> Publisher puts it on paper; a somewhat more crude HTML outputer
is included in an appendix of the book itself, FWIW).

Then again, there is a lot of special casing involved in this format.
The conversion applies to *this specific* book, rather than to every
documentation project.  For example, all cross references are introduced
by the phrase "SEE ALSO," at the start of a paragraph, and the stuff
that comes after has to be a comma separated list of linkable targets.
But given how I want to book to be, this is no more and no less than
what is needed.  Something like the following is extremely easy to
write... and to read without any special training in the format:

  SEE ALSO, [float], `int`, `long`, `sys.maxint`, [operator]

It's true that there is something slightly "funny" about the square
brackets and backticks.  You would not necessarily know at a glance that
the brackets surround module names, and backticks surround standard
function names.  But not knowing it does not distract much from reading
(and the same convention is used in all contexts). reST has a similar
property in readability, but with a larger "vocabulary" of special
names (which is both more expressive and more confusing).

Similarly, starting a header with the words "CHAPTER" or "SECTION" or
"TOPIC" each mean something a bit different to the final output.  But
deciding among those is *exactly* what I need to do while writing, it's
not at all a matter of *remembering* an odd syntax variant.  Even
the horizontal lines of dashes I occassionally use in the source are
only there to make the source look nicer in 'less', they don't affect
the processing.  And for a reader of the ASCII format, this is a
transparent, IMO, as anything can possibly be.  But again, the
organization and "markup" is specific to a book of a fairly similar sort
to mine.

As well...  I lied slightly in the above.  I also did the compositing of
my book.  I can generate a *pretty good* book with no annoying special
punctuation/markup.  But for a *final* book, there are a lot of things
to worry about:  whitespacing between words cannot be too loose,
consecutive lines should not begin with the same words, facing pages
must balance in length, successive lines should not both end with
hyphen, and so on.  At the end of the process (and not at the prior
URL), I used a number of really picky and obscure extra punctuation to
adjust for these camera-ready requirements.  Mostly, I chose a bunch of
hi-bit ASCII characters or obscure punctuation sequences to force layout
issues on a page-by-page basis.  If I were to change the page size by
1/4" or change any fonts, these odd markups would need to go in entirely
different places.  But frankly, I don't think that reST, DocBook, Lore,
or anything else, would manage to avoid such manual final touches for
book-quality output.

Yours, David...

 mertz@  _/_/_/_/ THIS MESSAGE WAS BROUGHT TO YOU BY: \_\_\_\_    n o
gnosis  _/_/             Postmodern Enterprises            \_\_
.cx    _/_/                                                 \_\_  d o
      _/_/_/ IN A WORLD W/O WALLS, THERE WOULD BE NO GATES \_\_\_ z e

More information about the Python-list mailing list