Re: [Docutils-develop] Proposal: auto-class for docinfo fields

[Guenter M. <mi...@us...>]

On 2015-06-09, Jeffrey C  Jacobs wrote:
> Guenter Milde <milde <at> users.sf.net> writes:
>> Mind, that this is a far more "intrusive" change, as it changes the
>> document model. (I'd say this requires affirmative approval by David
>> G.)

> True, but here's a brief use-case analysis.  Contact is generic, it
> *could* be an email address, it *could* be a number.  It *shouldn't* be
> an address as the address is already its own bibliographic field.

True.

> If the writer needs to distinguish between e-mail and phone numbers,
> such as whether to generate a mail-to link automatically for e-mail and
> only email, the writer-developer faces what is commonly considered a
> rabbit hole of special cases to fully implement e-mail address matching
> through regular expressions or otherwise.  This is work I argue the
> document writer is better equipped to solve.

This case is already cared for: the Docutils parser has the regular
expression for email address and already converts this to a link:

The example ::

  :author: me
  :contact: me...@ex...

is converted to the doctree ::

  <document source="/tmp/foo.rst">
      <docinfo>
          <author>
              me
          <contact>
              <reference refuri="mailto:me...@ex...">
                  me...@ex...


> I don't propose eliminating contact as a field as it can still be a
> generic place holder but I suggest the email and phone fields so that
> at the document tree level these fields can be distinct elements that
> are accessible to writers at the docinfo level to be typed metadata for
> instance in a mail-to link.

Whether other use cases merit a distinct email or phone field (or both) is
up to the rST inventor.

> The Address-first-line is less of a concern to me as it can be
> determined programmatically rather easily.

Indeed, as the input of a multi-line address is

        <address xml:space="preserve">
            Neue Straße 27
            01234 Witzhausen
            BRD

keeping the newlines.

> The author-last-name bibliographic field may be too specific.  Perhaps
> something along the lines of nickname or short-name so as to provide
> the most flexibility.  Worst case, one could use the Organisation field
> to accomplish this but it's a bit of a stretch to conflate nickname with
> Organisation.

I would not use Organisation.  Again, this can be extracted programmatically
(it is in the parser -- to distinguish author vs. authors) See
docs/ref/rst/restructuredtext.html#bibliographic-fields
for the details.

> But I agree, at the rst-level this goes into David's purview and wont
> be added to the rst spec and thus doc utils for a version or two at best
> to allow folks to adapt.  But I think these 3 fields will make the
> document model more robust and better defined at the level of document
> processing.

Adding something/extending choice is usually not a big problem for
*users*. Rather, the problem is for writer writers, as new elements in
the doc tree would require support by all standard writers (and better by
3rd party writers too).

>> Chances for such a change increase, if you prepare a complete patch
>> (or feature branch), including a test case and complete documentation
>> update (doctree, rst syntax, ...).

> I think I can try to hack something like "email", "phone" and "nickname"
> out.  Might take a while but like I say changes of this level require
> quite a bit of time to be included in a standard.


Günter