[Doc-SIG] Representation of Horizontal Rules

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