POD vs. reST for standalone writing?

[Andrew Bennetts]

On Tue, Apr 29, 2003 at 09:37:33AM -0400, David Goodger wrote:
> Andrew Bennetts wrote:
> >Hmm, interesting.  I thought the :Foo: syntax was for definition lists, not
> >inline in text?
> 
> As a block-level device, it's used for field lists:
> 
>     :Author: Me
>     :Date: Today

Right, that's what I meant by "definition lists".

> It's also used in inline text, to extend interpreted text roles 
> (explicit markup):
> 
>     Here is some `interpreted text`:role:.
> 
> Both uses attach a label or classifier to something.

Ah, ok.  I didn't know that form.

[snip discussion of how my example might be supported with future
enhancements to reStructuredText]

> However, the above is not typical reStructuredText usage.  When a 
> document gets to that level of complexity, it may be beyond what 
> reStructuredText aims to support.  ReStructuredText doesn't aim to be a 
> solution to every problem, just to the most common 80%-90%.

Exactly :)

I don't see Lore and reStructuredText as being competitors -- they're aimed
at different "markets" (although there may be a slight overlap?).

> >And how would I make the ReST tools link that to my API documentation
> >generated with pydoc, epydoc, or whatever?
> 
> Currently, with URL links.  Again, there's been some discussion about 
> using other methods (perhaps XLink/XPath-based), but no implementation 
> yet.  How does Lore link to outside docs?

By default, it knows how to link to epydoc-generated API docs[1].  A typical
invocation might be:

    lore --config baseurl=http://mysite/doc/api/%s.html mydocument.html

The "%s" will be substituted for the API name.  For other URL schemes, you
could write your own output plugin that overrides the processing of that
tag.  Ideally, I'd like to include at least vanilla pydoc/happydoc support
that you could access with --config apitype=pydoc or similar.  Potentially,
this sort of information could be embedded in the template rather than
passed as --config options.

I should note that Lore is still fairly young, and while it's settled down
quite alot, it is still undergoing a fair bit of development, so there are
some rough edges.  If this bothers you, wait a few months :)

> >(Btw, don't get me wrong; I *like* ReST for some uses.  I just think it's
> >better suited to wikis than to reference manuals and the like.  I don't
> >really like ReST's liberal use of punctuation in large doses.)
> 
> The "liberal use of punctuation in large doses" only really kicks in for 
> advanced uses.  Personally, I find occasional punctuation easier to 
> ignore than <ubiquitous> <angle> <brackets>.  To each his own :-).

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 them.
Much of the time, I'm sure that reStructuredText will be the choice -- I
hope that sometimes, someone will find Lore useful.

I must admit I'm not a great fan of <lots> <of> <angle> <brackets> either,
but Lore isn't too bad most of the time.  And while it's a little more
verbose, there's also a significant benefit to using tags rather than syntax
for markup: you can look up a tag name or an attribute value in
documentation far more easily than you can arbitrary syntax.  You'll never
look at Lore source and go, "now what the hell does ::..__"xyzzy"==::
mean?!" ;)

-Andrew.

[1] Except we use a small hack to epydoc to make it generate easier to
    predict filenames.  By default it uses "x.y.z-class.html" or
    "x.y.z-function.html", and so on, but it's more convenient if all Lore
    needs to link to is "x.y.z.html", so we make it do that.