[Doc-SIG] inline hyperlink targets

[David Goodger]

While working on the outline of doctree.txt_, I wanted to categorize the
elements. My first try was with a nested list structure::

    - Root element: document_
    
    - Body elements:
    
      - General body elements: paragraph_, literal_block_,
        block_quote_, doctest_block_, table_, figure_, footnote_
    
      - Lists: bullet_list_, enumerated_list_, definition_list_,
        field_list_, option_list_

But I wanted to be able to refer back to each item from other parts of the
document. That made me change the structure to one of nested sections::

    Root Element
    ============
    document_
    
    Body Elements
    =============
    
    General Body Elements
    ---------------------
    paragraph_, literal_block_, block_quote_, doctest_block_,
    table_, figure_, footnote_
    
    Lists
    -----
    bullet_list_, enumerated_list_, definition_list_,
    field_list_, option_list_

This solution rankles. Why let the markup determine the structure of my
writing? That's backwards. But the best I could do with the current syntax
would be to include a bunch of hyperlink targets. And in order not to break
up the list, the targets would have to be inside the list items::

    - .. _root element:
    
      Root element: document_
    
    - .. _body element:
    
      Body elements:
    
      - .. _general body elements:
      
        General body elements: paragraph_, literal_block_,
        block_quote_, doctest_block_, table_, figure_, footnote_
    
      - .. _lists:
      
        Lists: bullet_list_, enumerated_list_,
        definition_list_, field_list_, option_list_

Very awkward. Then I came up with the idea of allowing explicit hyperlink
targets as inline markup::

    - _`Root element`: document_
    
    - _`Body elements`:
    
      - _`General body elements`: paragraph_, literal_block_,
        block_quote_, doctest_block_, table_, figure_, footnote_
    
      - _`Lists`: bullet_list_, enumerated_list_,
        definition_list_, field_list_, option_list_

This seems to work. It can be rationalized as a natural consequence of the
rest of reStructuredText's hyperlink syntax. I have two concerns:

- This markup seems a little too noisy at first. But that may be
  because it's coming at the beginning of a list item, and is
  followed by a colon (which is *not* part of the markup). An
  example in the middle of a paragraph helps to alleviate this
  concern::

      The _`quick brown fox` jumped over the lazy dog.

- Should the backquotes be required, even for single-word targets?
  Initially I'd say yes, because leading-underscore terms are so
  common in code, and in the documentation of said code as well.
  Trailing-underscore terms are much less common.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net