[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] proposal: add topic element to DocBook
-----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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]