[Doc-SIG] Re: Grump about field lists

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> Tony J Ibbs (Tibs) wrote:
> > However, some field names are treated specially::
> >     :author: Me
> > gives::
> >     <author> David Goodger
>
> Please note, there is *no* automatic conversion of "Me" into "David
> Goodger"! !!!

Aaagh! Yes, it was a typo (well, a cut-and-paste-o). Sorry.

> I felt that the bibliographic elements (author, date, version, etc.)
> were useful to a generic document, so added them to the DTD.
> Naturally, I wanted to provide some mechanism to the reStructuredText
> authors to include those elements in their doucments. The past Doc-SIG
> discussions and PEP syntax suggested that field lists were the way to
> go. It's a bit of syntax overloading, but practical.

Well, the good news is that your explanation (mostly omitted) made lots
of sense to me, and I'm withdrawing much of my worry (which is a relief
to *me*, at least).

I would be happiest, though, if the bibliographic items were grouped
together under a single DPS tree node - I don't care about the name, and
don't particularly worry whether the term "list" is in it or not (the
tree requires things to be ordered by being a tree, so *all* collections
are going to be instantiated as "lists" regardless, whether one
conceptualises them as list or group!). I'm happy with any of the tags
you came up with - "docinfo" is OK by me.

> (But then we face the question: what goes inside 'docinfo', and
> what doesn't? I think most people would agree 'title' is too generic
> to go inside 'docinfo'. What about 'subtitle'? See the Docbook DTD for
> a cautionary example: its 'bookinfo' etc. elements contain 'title', as
> does the 'book' itself.)

Hmm - I *like* the idea of placing them together *because* it makes them
easy to find - and if we are saying that they must "come together as the
first thing in the document or the second thing after a title" then we
are *making* them all come together. That, to me, encourages me to
represent that fact.

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

> I envisage these bibliographic elements being laid out in various
> ways: like a title page of a book, like the first page of the Python
> Library Reference, etc. I do *not* see them being laid out as a field
> list, at least not exclusively, and not for anything but experimental
> output (e.g., verbatim output of the raw input for verification
> purposes).

This was (probably) the crucial point I was missing. I think your
example would sit well in the document, as an explanation (of one of the
reasons) for doing this. Of course, to me, it's also another reason to
group them together under one node of the tree...

> > (Hmm - and surely there *is* a Good Thing about being able
> > to point to the Bibliographic Data *as* a subtree of the
> > document.
>
> Why?

Erm - "because"...

It's difficult for me to articulate - we've *said* they belong together.
We want to *use* them together (in your example, to produce title page
info). It makes it slightly easier to tell if we have a particular item
or not. We don't want to lose them (!) - it just feels neater to keep
them in one package so they don't "fall out". It makes the tree tidier.
Maybe I'm just compulsive...

> If you just need an element around them for ease of processing, a
> 'docinfo' would be easy to add.

> At first I was exasperated, thinking you were being exceedingly
> pedantic ;-),

No, I really hadn't understood, as your further explanation makes clear
to me. Specifically:

> 3. The sole contents of the field is an expanded RCS keyword, of
>    the form '$Keyword: data $'.

I was assuming that "RCS keyword" meant the field list name - i.e., that
when you said "RCS date" you meant something that looked like::

    :date: <some text>

I hadn't realised that you actually meant::

    :name: <RCS keyword>: <appropriate text>

Looking back at the document, it still wouldn't be obvious to me
(whereas your new explanation does make it obvious), despite your use of
the words "The 'RCSfile' keyword" in the explanation - that use of
"keyword" didn't trigger strongly enough for me, I guess, probably
because you then go on to say "the 'Date' keyword" when I was thinking
about the "Date" field name).

As you've put it now, it's plainly a good idea (which makes me sigh with
relief, as I *know* you have a good sense of design).

> > .. _foreshadow:: Hmm, that's another problem with the "special
> >    treatment" - it only happens in one place. So I probably have
> >    to be able to cope with the same "quantity" represented by
> >    either of two means, anyway, if I want to go data-mining.
>
> I don't follow; please explain.

Just that if I have::

    :something: text

at the start of the document, it will produce a different representation
in the tree structure than if it occurs elsewhere. In my original
worries, that was much more significant (because (a) I hadn't gotten the
"title page" scenario, and (b) I was worried about random "RCS" field
names).

> > (Hmm - having said I thought that :title: was unlikely to happen,
> > there it is for all to see.
>
> You're referring to your docstring-develop message?
>
> The reason for 'title' being recognized as a bibliographic field name
> was for generality, and specifically to support the PEP header syntax
> as an alternate reader/"input mode". For the PEP Reader, the
> bibliographic elements should be extended to include all of the PEP
> header fields. If the redundant inclusion of 'title' in the standard
> set of bibliographic fields is painful, it would be easy to remove it
> and only put it back for the PEP Reader.

I'm actually not worried about it - but I think that some guidance could
be given to usage (when we figure out what that guidance is!). I wonder
if we're going to end up with things like the LaTeX document styles,
where one declares what "bibliographic elements" one wants according to
the function of the document.

Hmm - does that mean that we should add "Mode" or "Style" as an extra
such bibliographic field name - I suspect we should (I'm sure this was
discussed earlier).

Examples::

    :Mode: Article
    :Mode: Book
    :Mode: PEP
    :Mode: HTML

(that last one is being a bit naughty, of course - maybe it should be
"HTML page").
Or perhaps one even has::

    :Mode: HTML
    :Style: Article

where the "mode" indicates that we are enabling HTML specific things
(support for <hr>, etc.)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)