POD vs. reST for standalone writing?

[Aahz]

In article <mailman.1051591198.24028.python-list at python.org>,
Andrew Bennetts  <andrew-pythonlist at puzzling.org> wrote:
>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?

The inline context uses ``:Foo:`` as the role attribute for interpreted
text.  For example, in my writing, I have a :chapter:`Foo` role.

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

Adding in the base attribute, I don't think that can be done, but I
might be wrong.  You might be able to twist around it through
auto-generation of roles:

    :twisted.internet:`reactor.run`

but David Goodger would probably kill me for suggesting it.  ;-)

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

You'd have to write code that figures out the context.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"In many ways, it's a dull language, borrowing solid old concepts from
many other languages & styles:  boring syntax, unsurprising semantics,
few automatic coercions, etc etc.  But that's one of the things I like
about it."  --Tim Peters on Python, 16 Sep 93