POD vs. reST for standalone writing?

[Andrew Bennetts]

On Tue, Apr 29, 2003 at 12:18:37AM -0400, Aahz wrote:
> In article <mailman.1051584944.30800.python-list at python.org>,
> Andrew Bennetts  <andrew-pythonlist at puzzling.org> wrote:
> >
> >  - 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>
> >    )
> 
> You're wrong::
> 
>     :API:`twisted.internet.reactor.run`
> 
> Granted that isn't currently trivial to add, but it's definitely
> possible.

Hmm, interesting.  I thought the :Foo: syntax was for definition lists, not
inline in text?  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.]

And how would I make the ReST tools link that to my API documentation
generated with pydoc, epydoc, or whatever?

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

-Andrew.