[Doc-SIG] Representation of Horizontal Rules
David Goodger
goodger@users.sourceforge.net
Fri, 19 Oct 2001 17:57:29 -0400
[Excerpted from the new file `DPS Document Tree Structure`__, which
I've just begun. It will be on the web site once the snapshot is
taken tonight. Not much in it yet though.
__ http://docstring.sourceforge.net/spec/doctree.txt
I'm leaning towards solution #2. Those of you working with the
document tree, writing code or style sheets, please let me know if
this will cause problems beyond minor revisions.]
Having added the "horizontal rule" construct to the reStructuredText
spec, a decision has to be made as to how to reflect the construct in
the implementation of the document tree. Given this source::
Document
========
Paragraph
--------
Paragraph
The horizontal rule indicates a "transition" (in prose terms) or the
start of a new "division". Before implementation, the parsed document
tree would be::
<document>
<section name="document">
<title>
Document
<paragraph>
Paragraph
-------- <--- error here
<paragraph>
Paragraph
There are several possibilities for the implementation.
1. Implement horizontal rules as "divisions" or segments. A "division"
is a title-less, non-hierarchical section. The first try at an
implementation looked like this::
<document>
<section name="document">
<title>
Document
<paragraph>
Paragraph
<division>
<paragraph>
Paragraph
But the two paragraphs are really at the same level; they shouldn't
appear to be at different levels. There's really an invisible
"first division". The horizontal rule splits the document body into
two segments, which should be treated uniformly.
2. Treating "divisions" uniformly brings us to the second
possibility::
<document>
<section name="document">
<title>
Document
<division>
<paragraph>
Paragraph
<division>
<paragraph>
Paragraph
With this change, documents and sections will directly contain
divisions and sections, but not body elements. Only divisions will
directly contain body elements. Even without a horizontal rule
anywhere, the body elements of a document or section would be
contained within a division element. This makes the document tree
deeper. This is similar to the way HTML treats document contents:
grouped within a <BODY> element.
3. Implement them as "transitions", empty elements::
<document>
<section name="document">
<title>
Document
<paragraph>
Paragraph
<transition>
<paragraph>
Paragraph
A transition would be a "point element", not containing anything,
only identifying a point within the document structure. This keeps
the document tree flatter, but the idea of a "point element" like
"transition" smells bad. A transition isn't a thing itself, it's
the space between [#]_ two divisions.
.. [#] Cool song by Dave Matthews. First time I heard it, I thought
it was Peter Gabriel. Matthews' voice on this song sounds
uncannily like Gabriel's, and the style & lyrics wouldn't be
out of place either. Totally off topic.
--
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