[Doc-SIG] inline hyperlink targets
David Goodger
goodger@users.sourceforge.net
Fri, 26 Oct 2001 00:30:38 -0400
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