Re: [Docutils-develop] Formatting bulleted list of email addresses

[David G. <go...@py...>]

Bill Bumgarner wrote:
> Say I want to do a section that contains nothing but a bulleted list of
> people, with each person being a mailto: link.
> 
> How should that be formatted?
> 
> =========================
> People
> ------
> 
> * `Bill Bumgarner`__
> __ mailto:"Bill Bumgarner" <bb...@co...>
> 
> * `Joe Smith`__
> __ mailto:"Joe Smith" <jo...@fo...>
> ==========================

The error messages are correct.  You'll have to reformat.

> If i remove the spaces from the mailto URLs (bummer-- anyway to format
> mailtos as shown above??):
  
I don't think you can encode the "common name" of an email recipient in a
URI.  URIs can't have spaces.  According to RFC 1738:

    No additional information other than an Internet mailing address
    is present or implied.

> If I put a newline after each * line, the resulting HTML has each
> bullet in its own <ul></ul> block.  Why would the anonymous hyperlink
> cause that? 

The target has to be left-aligned with the paragraph (indented relative for
the "*") for it to be part of the list item; otherwise the list ends.

> The anon link should be invisible to the structure of the
> doc, I would think.

I wouldn't ;).  The unindented block ends the list.  It would require a
special exception to go back and stitch blocks together for "invisible"
intervening blocks.  But what about cases where the "invisible" blocks were
*intended* to separate other constructs (that's the whole point of empty
comments, for example)?  I think it would add too much conceptual
complexity.

If you want to keep the targets together with the references, do this::

    * `Bill Bumgarner`__

      __ mailto:bb...@co...

(As a convenience, "mailto:" isn't strictly required in any of these target
forms.  Email addresses are distinctive enough to be unambiguous.)

The blank line is required to separate the paragraph from the target.  To
save some vertical space, you could put all the targets after the list::

    * `Bill Bumgarner`__
    * `Joe Smith`__

    __ bb...@co...
    __ jo...@fo...

Or you could use embedded URIs::

    * `Bill Bumgarner <bb...@co...>`__
    * `Joe Smith <jo...@fo...>`__

-- 
David Goodger  <go...@py...>  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/