Re: [Docstring-develop] DPS - possible bugs/features

[David G. <go...@us...>]

[Tony]
> First, I've uploaded a new pydps

Great; I'll have to take a look at it. Where should it be installed on
the source tree? (Perhaps a short README.txt file?)

Tony's problem #1 is regarding a transformation that takes place when
a document contains a single section and nothing else (with the
possible exception of comments and a bibliographic field list). The
section is 'promoted' to the document level.

Ueli's analysis is very good, spot-on. This promotion was a conscious
decision, for exactly the reasons he states. How else would you
specify a document title, especially in a standalone .rtxt file?

But I can see why it would be cumbersome when dealing with Python
source (PySource). Normally a docstring doesn't have an explicit
title; the title gets assigned from the docstring's parent object's
name. There will inevitably be odd cases where there is a leading
title, however. Perhaps this parser-specific transformation should be
made optional [#]_. Then you can treat everything as generic sections
until integration is complete.

.. [#] Along with bibliographic field list interpretation, RCS keyword
   filtering, and whatever other conveniences we dream up.

[Ueli]
> Now, it seems to me that the structures of documents and sections
> are close relatives:
> 
> - A document may or may not have a title, a section always has one.

It is actually intended that by the time the document tree gets to the
writer, it must have a title. The parser can't always determine the
title by itself, such as in PySource mode. The PySource reader is
expected to supply all the titles as appropriate.

> - A document may have a subtitle, bibliographic elements, and an
>   abstract.  A section has none of these.
> - The rest of the content follows the same model.

Correct.

> Can thus sections be treated as simpler cases of documents (instead of
> the other way round, which is how I understand your post)?  I'm not
> sure how I would exploit this, though...

Basically, yes, sections are simple sub-documents. The top-level
document does need to be special-cased in the end however. HTML pages
need their titles!

[Tony]
> 2. When processing the string module (yes, I know it isn't marked as
>    containing reST texts!), the text::
> 
>        [1:2]
> 
>    (or similar) is incorrectly identified as a link. Not a Good Thing.

``1:2`` won't be a link (as your example confirms), but ``a:b`` will
be. Why? Because according to RFC2396, 'a' could be a URI scheme (as
in 'http' or 'mailto'). The solution? Use inline literals.

[Ueli]
> Anyway, when I have something useful, I may post it here

Yes, please! Your explanation of the situation was quite eloquent.

> -- but only if everybody promises not to laugh out loud...

Never! <aghast>

-- 
David Goodger    go...@us...    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net