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