Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#259 add a topic element

v5.1
open-fixed
Norman Walsh
5
2010-06-23
2009-07-11
Robert Stayton
No

With the advent of a new assembly feature in DocBook, the
time has come to consider adding a new element for modular
topics that can be assembled into larger units
of delivery.

The design goals of this proposal are:

a. To provide a designated element for authoring
modular content, each instance of which "stands alone", but
which also has relationships to other modules.

b. Design the topic element to be very general, so
that it can be adapted for many types of topics.

c. Make the addition of topic backwards compatible
with DocBook 5.0.

d. Clearly distinguish topics and sections.

Here are is the proposed design for topic:

1. The content model for topic is identical to that of section.

2. A topic type is indicated by a class attribute value.
For example, "task", "reference", "concept", etc.

3. A topic cannot include topic children. Allowing a topic
to contain other topic elements breaks the semantic of
"standalone unit of information".

4. A topic can contain section children to subdivide its content
for clarity and ease of reference.

5. A section element cannot contain a topic element.
Placing a topic inside a section implies the topic
depends on the section parent for its context.
It also hopelessly muddles the distinction between
topic and section.

6. Allow topic as a child of book or part. This allows you
to author groups of topics in a convenient container.
Such topics could be siblings of chapters and other
component elements, the way article can be such a sibling.

7. Allow topic as a child of chapter or appendix, but not
as a sibling of section. This also allows you to author
groups of topics in a convenient container, this time
grouped into a chapter or appendix. There is an additional
constraint, though. A chapter can contain either section
children or topic children, but not both. This is to
maintain a clear distinction between topics and sections.

A new topic element is needed because no other DocBook
element meets the needs for authoring standalone units of
information. A section element is not appropriate, because
it implies a "section of something" with a larger context.
The article element comes closest, but it allows appendix,
acknowledgements, and colophon children, which are not
appropriate for a topic. Also, article currently cannot
be a child of chapter or appendix.

A new topic element would fit right in with the design
of assemblies in DocBook.

Discussion

  • Norman Walsh
    Norman Walsh
    2010-06-23

    First attempt added to V5.1

     
  • Norman Walsh
    Norman Walsh
    2010-06-23

    • status: open --> open-fixed