[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] alternative topic proposal
Hi Chris, Perhaps I wasn't clear, but I meant that topicref is an element, not an attribute. The href attribute in topicref points to the xml:id of a topic, which is to be pulled in like an XInclude at that point. I'm suggesting the content model of topicref is (topicref*), which would allow it to be used to create a hierarchy of topics similar to a hierarchy of section elements. In terms of processing, the assembly process could be done using XSLT's document() function. The advantage of using a stylesheet is that it can implement a policy to actively manage the xml:id attributes of elements you pull in, so that you can alter duplicate ID values when a topic is reused. Also, the resolution of topicrefs should be complete before the regular XSLT formatting takes place, so that xrefs and numbering sequences can proceed normally, as they do now with system entities and XIncludes, both of which are resolved before the styles are applied. Bob Stayton Sagehill Enterprises DocBook Consulting bobs@sagehill.net ----- Original Message ----- From: "Chris Chiasson" <chris@chiasson.name> To: "Bob Stayton" <bobs@sagehill.net> Cc: <docbook@lists.oasis-open.org> Sent: Saturday, October 28, 2006 4:50 PM Subject: Re: [docbook] alternative topic proposal > What exacly would this topic ref attribute allow one to do? Include > the element with that ref in another piece of content, but without > bringing along xml:ids? > > What would be the difference between <topic> and <section > topicref="something">? > > On 10/27/06, Bob Stayton <bobs@sagehill.net> wrote: >> I'm pretty strongly opposed to mixing topic and section >> elements as siblings. I think that will produce such a >> hash that neither authors nor stylesheets will understand it. >> >> I would suggest a different model for modular Docbook, similar >> to Norm's, but different in a few aspects. My goals here >> are to designate a topic as a standalone unit, but permit >> it to be used within one or more larger contexts that >> include hierarchy, and remain comaptibile with DocBook. >> >> 1. Add a <topic> element with the same content model as >> <section>. Because I believe a topic is intended to be a >> standalone unit, I would not allow a topic to contain other >> topics, but I would allow a topic to contain sections. >> Nesting topics greatly confuses a topic's status as a >> standalone unit. However, a topic may need to divide its >> content into sections for clarity and ease of reference. >> >> 2. Sections do not contain topics. >> >> 3. Give topic a class attribute to differentiate >> topic types (same as Norm's proposal). >> If someone wants different element names or customized >> content models, then they can customize the DocBook schema. >> >> 4. Allow topic in book and part >> as a sibling to chapter|appendix|preface. >> That makes it like article if you need a flat >> collection of topics. I'm not sure if Norm's proposal >> meant topic as a sibling >> to chapter or as a mutually exclusive alternative. I >> mean as a sibling. If you mix them, then it is >> up to the application to determine how to present them. >> >> 5. Define chapter (and any other element that contains >> section) to contain *either* sections or topics, but >> not both. If you use section, you can go to >> arbitrary depth. But it makes for a single level of topics within >> a chapter, with sections within topics providing further >> hierarchy if needed. >> >> 6. To accomodate a more extensive hierarchy of topics, >> allow book|chapter|appendix to contain topicref as well >> as topic. A topicref has an href attribute that points to >> a separate topic element stored elsewhere. This is the >> mapping feature of DITA. As in DITA, >> a topicref can contain other topicref elements. >> When processed, these can form a deeper hierarchy in >> the presentation of the output. >> >> So the content model of chapter and other elements >> that currently contain section would look like: >> >> chapter front matter (title, info, etc.) >> intro material (para, list, etc.) >> section* or (topic|topicref)* >> >> >> I believe this design has these advantages: >> >> 1. It keeps topic as a standalone unit. >> >> 2. It avoids mixing section and topic as siblings. >> >> 3. It permits arbitrary depth of a topic (using >> sections), if you need it. >> >> 4. It permits easy authoring of books or other units >> with inline topic elements. >> >> 5. It permits creating more extensive topic hierarchies >> using topicref, without sacrificing topic as a >> standalone unit. >> >> 6. It is very flexible and not overly prescriptive, in keeping >> with DocBook's design. >> >> >> Bob Stayton >> Sagehill Enterprises >> DocBook Consulting >> bobs@sagehill.net >> >> >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org >> For additional commands, e-mail: docbook-help@lists.oasis-open.org >> >> > > > -- > http://chris.chiasson.name/ > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]