POD vs. reST for standalone writing?

[David Goodger]

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

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.

> I guess what I'm asking is, what would be the ReST
> equivalent of:
> 
>     <p>To start the reactor, use the <code class="API"
>     base="twisted.internet">reactor.run</code> method.  To stop it, use
>     <code class="API" base="twisted.internet">reactor.stop</code>.</p>
>
> [The optional base attribute provides the fully qualified name to 
> allow the text to be linked to the right part of the API docs, but
> doesn't affect the final display.]

These examples, with the extra attributes, are not directly 
translatable: interpreted text roles are not currently parameterizable 
in reStructuredText.  There is some discussion underway on how to 
parameterize roles or define document-local roles, so it might be 
translated something like this:

     .. :api-ti: role:: api
        :base: twisted.internet

     To start the reactor, use the :api-ti:`reactor.run` method.  To stop
     it, use :api-ti:`reactor.stop`.

This is not yet implemented though, either because nobody has needed it, 
or not needed it enough to do the work.  Docutils/reStructuredText is 
also still undergoing development.

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%.

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

> (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 :-).

-- David Goodger