[Doc-SIG] Grump about field lists

[Tony J Ibbs (Tibs)]

Warning - I may be disagreeing with opinions of my own that I've pushed
in the past. But then, you should all be used to that by now...

A "normal" field list::

    :first: something
    :second: something else
    :third: and again

produces a (sub)tree structure something like the following::

    <field_list>
        <field>
            <field_name> first
            <field_body> something
        <field>
            <field_name> second

and so on. However, some field names are treated specially::

    :author: Me
    :Date: 29th February 200

gives::

    <author> David Goodger
    <date> 29th February 200

I believe that this special treatment is (a) because some fields are
felt to be "special" and should thus be easy to extract from the tree,
and (b) because when what evolved into field lists was being proposed on
Doc-SIG, this was the sort of thing that was expected to happen for
*all* field names (I gloss over history greatly, of course).

Note that I realise that this special casing is only done in the block
at the *start* of the document (foreshadow_)...

However, I now find that I don't like this division of fields into
"normal" and "special", for two broad reasons.

Broad reason 1: implementation
------------------------------
When trying to output HTML from a DPS tree, it is useful if I can
produce a decent result without any pre-processing of the tree. The only
place that I can't currently see this as being possible (subject to a
*little* bit of special casing when it comes to folding in indirect
hyperlinks) is for the "special" fields above.

For "normal" field lists, I have a *list* - that is, a grouping of
adjacent field list items - which facilitates treating them *as* a
group. For the "special" fields, there is no such linkage.

This could, of course, be solved to *some*extent by insisting that these
field list items *also* become children of a <field_list> node -
obviously one would then allow mixing, so one could do::

    :Author: Me
    :Cat: in a hat

to obtain::

    <field_list>
        <author> Me
        <field>
            <field_name> Cat
            <field_body> in a hat

although that seems messy in a different way...

(Hmm - and surely there *is* a Good Thing about being able to point to
the Bibliographic Data *as* a subtree of the document. I think that's
actually a very important point. So, whatever else is done, can these
things please be shifted into a <field_list> subtree.)

Broad reason 2: theory
----------------------
Having had my mind drawn to this, I think I have some general objections
to the idea, anyway.

The first is simply that I don't think it is necessary. I think that it
should be possible to handle any action that can be done with an
``<author>`` tag as easily with a ``<field>`` that has the correct
subtree. And if it isn't, then transfer the field name to be an
attribute, so that::

    <field>
        <field_name> Fred
        ...

becomes::

    <field name="Fred">
        ...

The second is that I'm a bit unhappy with the ad-hoc nature of adding
names - let us say that I have a document with a field name "History"
(not unreasonable). What happens if reST introduces this as a standard
tag at some time - suddenly, my customised Writer code will get *very*
confused at the new parsing.

Speaking of which, I especially don't like the out-reference to RCS/CVS
keywords. The `RCS keyword recognition` section says that any RCS
keyword shall be a bibliographic keyword. This is unfriendly to the poor
user, because it *requires* them to study a different document before
they can figure out unused keywords (even if they're using DPS/reST to
write a discourse on cats, or something inherently non-programming), and
also because it nails us to a moving target over which we have no
control (we can't stop CVS adding a new keyword to its list, unlikely as
we may hope that to be).

Also, in that section, "status" and "date" are named, but these are
already mentioned in the previous section (and do you *really* think you
can automatically convert all dates into ISO 8601 format? what about
10/12/01? (which is the month? and the day? and what century? (not that
I'd guarantee that that *is* the year, if I were you!))

If we're going to support RCS/CVS keywords directly, can we please
prefix them with RCS (or CVS) - e.g., "CVSDate" or "cvsdate" - to make
it clear what we mean?

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

Tibs

(Hmm - having said I thought that :title: was unlikely to happen, there
it is for all to see. Oh well, I never was much good at channeling. Or
remembering.)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)