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

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

-----Original Message-----
From: Dave Pawson [mailto:dave.pawson@gmail.com] 
Sent: Tuesday, July 14, 2009 9:20 AM
To: docbook-tc@lists.oasis-open.org
Subject: Re: [docbook-tc] proposal: add topic element to DocBook

On 13/07/2009, Norman Walsh <ndw@nwalsh.com> wrote:
> "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.

Instinctively (to me) it feels right Norm? Why do you see it as a
possible bug?

Gershon: I also always thought this behavior was by design. I think it's
right.


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

Open ended please? That lets us mimic 'the other house' ideas, and
extend as needed within docbook?

Gershon: How far do we plan to take this? We're surely not planning to
go the whole specialization route, so we'll have a single topic info
model that authors would use for their various topic types. In this
case, I think it's best to leave this as a free text value like @type.


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

That would  break Bobs rule that topics can't be nested (which seems
right to make them stand alone.
  Multiple sibling topics within an assembly though, yes.

Gershon: I think the distinction is that a topic element cannot contain
nested child topic elements. This is a GOOD THING that DITA does not
fully enforce, and users are constantly misusing this ability. In the
map, references to topics can nest. So the map view allows nesting of
topics at the TOC or structure level, but a topic may not nest topic
elements. This ensure each topic is a standalone entity (for want of a
better word) while, at the same time, allowing assemblies to use a rich
delivery structure. Hope I'm clarifying and not confusing...


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

And me. Possibly since I have slowly accepted it over the time it's been
discussed on this list!

Will it (and assemblies) be documented in tdg Norm, they are quite
different from much of other docbook markup?

Gershon: I think these new items should be documented in therein, though
maybe in a later release? We could knock up an article in the meantime
that describes the new assemblies and related things. Then we'd just
need to merge that article into the guide at a later time when we have a
DocBook release that supports all this cool stuff...

Cheers,
Gershon