[Doc-SIG] Re: Grump about field lists

[David Goodger]

Tony J Ibbs (Tibs) wrote:
> I would be happiest, though, if the bibliographic items were grouped
> together under a single DPS tree node

OK, done. The element is 'docinfo'. It satisfies the desire for an
explicit element hierarchy (encapsulation). The relevant bits of
dps/spec/gpdi.dtd are::

    <!ELEMENT document
        ((title, subtitle?)?, docinfo?, %structure.model;)>

    <!-- Container for bibliographic elements. May not be empty. -->
    <!ELEMENT docinfo
        (((%bibliographic.elements;)+, abstract?) | abstract)>

> I don't know the Docbook DTD, and don't *quite* see why it is
> obviously bad to have "title" in two places...

Docbook allows duplicate titles (& subtitles)::

    <book>
        <title>
            Title text #1
        <bookinfo>
            <title>
                Title text #2

Makes one ask, "What's the difference between the titles? Which one do
you render?"

Being a multipurpose DTD, Docbook is very loose. And big. Sometimes
too loose. And too big. The users of Docbook have to limit themselves
to a strict subset otherwise it soon becomes unmanageable.

> Hmm - does that mean that we should add "Mode" or "Style" as an
> extra such bibliographic field name

No. Please, no!

"Mode" or "Style" should not be set from within the document. Rather,
they should be chosen when processing the document, either statically
(set by "pysource2html" script), as command-line options ("--mode book
--output html"), or understood from context somehow.

>     :Mode: HTML
>     :Style: Article

If something like this ever really becomes necessary, the way to do it
would be with a directive, not a field list.

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