POD vs. reST for standalone writing?

[Andrew Bennetts]

On Mon, Apr 28, 2003 at 10:21:59PM -0400, 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

I think you want Twisted's Lore format (which I am the maintainer of).

It is essentially a subset of XHTML, with a number of a pre-defined classes.
Take a look at the docs at http://twistedmatrix.com/documents/howto for an
example of Lore's output (and for Lore's documention!).

E.g., here is the source to one of the documents:
    http://twistedmatrix.com/documents/howto/defer.html
and here is the Lore'd HTML output:
    http://twistedmatrix.com/documents/howto/defer
and there are PS and PDFs too.

Let me know if you want any more information or help (or ask on the Twisted
list: twisted-python at twistedmatrix.com).  We developed this format and it's
tools for much the same reasons that are motivating you to look around:
  - LyX/LaTeX have too high a learning curve and the tools are difficult to
    obtain and install on some platforms.
  - DocBook has an equally bad learning curve and toolset.  We want to
    *encourage* contributions, not scare them away!
  - LaTeX also has crummy HTML rendering.
  - ReST isn't extensible enough; how do you add markup for, e.g. API
    references?  How do you plug that into your docutils installation?  You
    can't.  (The Lore markup for APIs is 
        <code class="API">twisted.internet.reactor.run</code>
    )

But consider Lore:
  - Lore's source format is mostly viewable directly, being XHTML (although
    it looks better after run through Lore, of course!), and it also comes
    with a "lint" tool, to identify markup errors in your documents.
  - Lore is extensible; it's easy to write your own Lore input plugin if you need
    to define markup that isn't available by default.  You can write your
    own output plugin, too -- e.g. the "slides" input plugin has a
    corresponding magicpoint output plugin.
  - Lore is easy to write, assuming your authors already know some HTML...    
  - Code samples don't have to be included inline in HTML -- they can be
    referenced from live .py (or .c, or .java, or ...) files that you can
    be run and test directly, but the source will be inlined (and
    pretty-printed, if the source format is supported) in the Lore output.
    There's support for simple inline code examples too, (just use e.g. <pre
    class="python">), and even then the lint tool will syntax check them for
    you (if they are of Python code) :)
  
Lore is still a fairly new system, and is still undergoing development, but
it's rapidly maturing.  Twisted finds it invaluable.  I recommend you take a
look!

Regards,

-Andrew.