[Doc-SIG] "Topic" (was Re: some ideas for reStructuredText & document model)

[David Goodger]

Two nights ago I wrote:
>> - Add a "sidebar" element to the DTD? Like a generic admonition or
>>   floating mini-section. Useful for TOC, system messages section,
>>   abstract, etc.

I further explained the idea last night, in terms of DocBook's
"SimpleSect". Tony Ibbs wrote back to me:

[Tony]
> When you say "sidebar", I think of text run down the side of the main
> body of text, essentially in a figure. It's still not entirely clear to
> me if that's what you mean by the term.

That's not my intended meaning, and I apologize for the misleading term.
Similarly to a literal "sidebar", the construct doesn't fall into the
strict section-subsection hierarchy, but it's not meant to be floating
or rendered along the side (although it could be). I don't like the
DocBook term "SimpleSect" at all (many DocBook names are similar:
gratuitously verbose and abbreviated at the same time). Racking my
brains (lightly) for another term, I recall one I came up with for a
client's documentation, "topic". Yes, that's better I think.

>> - SimpleSects...
> 
> I still don't understand the purpose of these, unless they are
> essentially text in a "figure".

Essentially, yes. I imagine rendering them offset from the rest of the text
somehow, perhaps indented, perhaps in a box or with a different-coloured
background.

-------------

So, "topic" it is. I've reworked the DTD's structural model::

    <!ENTITY % structure.model
      " ( ( (%body.elements; | topic)+,
            (transition, (%body.elements; | topic)+ )*,
            (%structural.elements;)* )
        | (%structural.elements;)+ ) ">

This model is rather imposing but necessarily so. It is used in the
"document" and "section" elements' content models, after their titles
etc. In essence, it says that each document or section contains either:

- multiple body elements and/or topics, optionally interspersed with
  transitions (but transitions cannot occur at the beginning or end, nor
  may there be two transitions in a row), followed by zero or more
  sections; or

- one or more sections (whose contents are recursively the same as this
  model).

There's currently no way to directly create a "topic" in reStructuredText,
although it would be easy to create a directive to do so. I see them being
generated by the processing system for various purposes.

-- 
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