[Doc-SIG] FW: [Docutils-develop] Forcing line breaks

[David Goodger]

(Forwarding to the Doc-SIG to solicit opinions.)

[Adam]
>>> Is there any way to force line breaks? Example of usage::
>>> 
>>>   :Name:    Adam Chodorowski
>>>   :Address: The Street
>>>             11111 The Town
>>>             The Country
>>>   :Phone:   +11-111111

[David]
>> If you're using a recent snapshot, it's already taken care of for
>> you. The "Address" field should produce the equivalent of a
>> line_block element, which is exactly what you describe.

[Adam]
> I'm guessing that is only valid for a bibliographic fields...

Yes.  Special processing in a specific context, which cannot be
assumed anywhere else.

>> - You shouldn't really be using field lists in the first place.
>>   They're for extension syntax (docinfo & directive options).  I'll
>>   make this more explicit in the docs.  Perhaps a table or a
>>   definition list would be better?
> 
> I disagree strongly on this. Why on earth shouldn't fields lists be
> usable as a construct of their own?

On April 25, I clarified the spec to say this about field lists: "They
are not intended to be an alternative to definition lists or tables."
I made this admonition stronger yesterday: "Field lists should only be
used when and where application code specifically expects them; they
should *not* be used as arbitrary constructs in documents."

Before you begin your reply, please read to the end.  (It's one of my
thinking-an-issue-through-to-the-end essays.)

> Definition lists do fit *conceptually*, but unfortunately not with
> regard to presentation. When you specify contact information or
> similar data, you almost always do it like this::
> 
>   Name:    Adam Chodorowski
>   Address: The Street 42
>            11111 The City
>   Country: Sweden
>   Phone:   +46-8-1111111

Actually, I would write it like this::

    Adam Chodorowski
    The Street 42
    11111 The City
    Sweden
    phone +46-8-1111111

Most of the labels are redundant; people know how to read addresses
from context.

> Having definition lists is *not* intuitive for the reader
...
> nobody excepts contact information to be presented that way.

I wouldn't expect contact information to be presented the "field list"
way either.  Are conventions so different in Sweden?  Do you really
need to label everything?  (But this is avoiding the real issue.)

> Field lists are IMHO perfect for "single vertical table rows". Just
> what the doctor ordered. ;-)

This may a case of abusing markup because it gives the desired
results.  In DocBook terms, it's like a doc writer using <emphasis>
instead of <glossterm>, because they want italics in the output.  A
*side effect* of <glossterm> may be italics, but the main effect may
be quite different (hyperlinking all glossterms to a glossary, for
example).

But I do see Adam's point.  I've been moving towards thinking about
field lists purely as an extension syntax, not as a generic construct.
 Partly this is due to outside influence, the incessant
"reStructuredText is too complex!" from certain parties.  So we have
to choose:

1. Field lists shall be restricted to extension syntax use (directive
   options, docinfo) only.

2. Field lists shall also be available to authors as a generic
   two-column table/list construct.

There are consequences.  If we choose #1, we should remove field list
support from writers; it would be an error for an unprocessed field
list to remain in the document tree.  If we choose #2, we should ask
ourselves, are field lists generic *enough*?

The current field list syntax (geared toward extension syntax use,
choice #1) was modeled after RFC 2822's fields and JavaDoc's "@tags".
It limits field names to single (possibly compound) words.  Anything
after whitespace is taken to be field arguments, which are
semantically and presentationally separate from field names.  Field
arguments allow the equivalent of a JavaDoc "@param name description"
tag.

In Adam's contact info block above, there's a "phone" field.  What if
he wants to differentiate between phone numbers (home, cell, pager)?
Let's assume that in Swedish we cannot rework the field names into
single words; we *have* to use multiple words.  We'd want this as
output::

    Home Phone:   +46-8-1111111
    Cell Phone:   +46-8-2222222
    Pager Number: +46-8-3333333

The closest we could get with current field lists would be like this::

    :Home-Phone:   +46-8-1111111
    :Cell-Phone:   +46-8-2222222
    :Pager-Number: +46-8-3333333

(Underscores could be used instead of hyphens.)  I doubt that this
would be acceptable to most document authors, and the output (with
hyphens intact) would look strange to readers.  The alternative is to
redefine field lists to allow multi-word field names, and use a
different syntax for field arguments.  Perhaps something like this::

    :Field name <field arguments>: Field body

Or perhaps we just drop the idea of field arguments altogether, and
rely on the application code to parse the field name as it likes.

Apart from the test suite, the only place where field arguments are
used is in the "meta" directive, which produces <meta> tags.  This is
from tools/test.txt::

    .. meta::
       :keywords: reStructuredText, test, parser
       :description lang=en: A test document, containing at least one
           example of each reStructuredText construct.

The "meta" directive code would have no problem extracting the
"lang=en" argument from the field name.  The "meta" directive would
specify that the first word of the field name would be taken as the
"name" attribute, and the rest should be "attname=value" attribute
definitions.

I'm beginning to like this change.  If we drop the notion of "field
arguments", field lists become simpler and fully generic.  Then I'd
drop my objection to their use as a generic document construct.  Any
objections to this change?

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/