Re: [docbook-tc] proposal: add topic element to DocBook

[Norman Walsh <ndw@nwalsh.com>]

"Bob Stayton" <bobs@sagehill.net> writes:

> appropriate for a topic.  Also, article currently cannot
> be a child of chapter or appendix.

I wonder if that's a bug.

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

Do you want to make an attempt to describe these relationships from
within the topic, or leave that to the assembly layer?

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

Do you really want an enumerated list of class values, or does it make
more sense to allow a type attribute, which is open-ended by default?

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

The assembly layer can construct nested topics, can't it?

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

I've long suspected we would eventually need a topic element. The
strongest arguments aren't technical, in my mind, they're about user
expectations and perception.

This proposal seems like the right thing to me.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Convictions are more dangerous
http://www.oasis-open.org/docbook/ | enemies of truth than lies.--
Chair, DocBook Technical Committee | Nietzsche

PGP signature