[Doc-SIG] Re: [Docstring-develop] pydps futures (was RE: Document titles)

[David Goodger]

Tony J Ibbs (Tibs) wrote:
> Combs
> -----
> The metaphor of combing through hair to remove tangles is a bit
> iffy, but I like the term (I think David calls them Filters, which
> is less obvious to me)

Strictly speaking, a filter reduces the amount of information. Rather
than "combs", I'd use the common term: "transforms".

Tony's made a good start listing the transforms we'll need. Looking at
them and thinking of others, we will need to identify which transforms
are parser-specific and which are generic. The "bibliographic field
list" transform is obviously parser-specific, but must be run after
the "section promotion" transform (what Tony calls "TitleComb").

>   David - a question or two on this. Each autonumbered
>   footnote/footnote reference has the attribute 'auto'
>   set to "1". I want to *insert* actual footnote numbers
>   into the tree.

Auto-numbered footnotes have attribute ``auto=1`` and no label.
Auto-numbered footnote_references have no reference text (they're
empty elements). If you resolve the numbering, just add a label
element to the beginning of the footnote, and reference text to the
footnote_reference. Take this input::

    References to the first ([A]_), third ([#spam]_), and second
    ([#]_) footnotes.

    .. [A] This footnote is labeled with "A".
    .. [#] This footnote is auto-numbered.
    .. [#spam] This footnote has autonumber name "spam".

Parsed (watch for empty footnote_reference elements: indentation)::

    <document>
        <paragraph>
            References to the first (
            <footnote_reference refname="a">
                A
            ), third (
            <footnote_reference auto="1" refname="spam">
            ), and second
            (
            <footnote_reference auto="1">
            ) footnotes.
        <footnote name="a">
            <label>
                A
            <paragraph>
                This footnote is labeled with "A".
        <footnote auto="1">
            <paragraph>
                This footnote is auto-numbered.
        <footnote auto="1" name="spam">
            <paragraph>
                This footnote has autonumber name "spam".

Only the first footnote_reference contains reference text. After
auto-numbering resolution, the tree should become::

    <document>
        <paragraph>
            References to the first (
            <footnote_reference refname="a">
                A
            ), third (
            <footnote_reference auto="1" refname="spam">
                2
            ), and second
            (
            <footnote_reference auto="1" refname="_footnote 1">
                1
            ) footnotes.
        <footnote name="a">
            <label>
                A
            <paragraph>
                This footnote is labeled with "A".
        <footnote auto="1" name="_footnote 1">
            <label>
                1
            <paragraph>
                This footnote is auto-numbered.
        <footnote auto="1" name="spam">
            <label>
                2
            <paragraph>
                This footnote has autonumber name "spam".

The labels and reference text are added to the two auto-numbered
footnotes & footnote_references. The unnamed auto-numbered footnote
& reference need name & refname attributes. Let's use "_footnote " +
footnote number for those attributes (a name-mangling unlikely to
occur in the real world; note that this hasn't been documented yet).
Of course (!), the implicitlinks and refnames instance attributes of
the dps.nodes.document instance must be updated. (It will soon be my
pleasure to document the dps/nodes.py data structure, since I'm
gradually forgetting its details.)

After adding labels and reference text, the "auto" attributes can be
ignored.

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