Re: [docbook] alternative topic proposal

[Jirka Kosek <jirka@kosek.cz>]

Bob Stayton wrote:

> I think this is a simple and elegant way to create modular content
> using familiar DocBook elements and two new elements,
> topic and topicref.

I quite like your proposal, but I think that we can go even further and 
completely decouple pieces of modular content from assembly information. 
This feature was already implemented in website and it will allow us to 
create interoperable format used for customized chunking ($chunk.toc 
parameter in the stylesheets).

You will create set of small modules -- it is almost irrelevant whether 
they will use section, topic, article or whatever as their root element. 
They you will have contentmap element which will be used to assemble 
content into right order and nesting. For example:

<contentmap>
   <topicref href="XMLCatalogs.xml">
    <topicref  href="WhyUseXMLCatalogs.xml"/>
    <topicref  href="HowToWriteCatalogs.xml">
        <topicref  href="ResolveDTDLocation.xml"/>
        <topicref  href="LocateXSLstylesheet.xml"/>
        <topicref  href="MapWebAddress.xml"/>
        <topicref  href="MapWithRewrite.xml"/>
        <topicref  href="MultipleCatalogs.xml"/>
    </topicref>
    <topicref  href="ExampleDocBookCatalog.xml"/>
    <topiciref  href="HowToUseCatalog.xml">
        <topicref  href="InSaxon.xml"/>
        <topicref  href="InXalan.xml"/>
        <topicref  href="InXsltproc.xml"/>
    </topicref>
   </topicref>
</contentmap>

To make this more flexible we can add renderas attribute to map this 
structure to already existing processing model:

<contentmap>
   <topicref href="XMLCatalogs.xml" renderas="chapter">
    <topicref  href="WhyUseXMLCatalogs.xml" renderas="sect1"/> <!-- this 
would be default value of renderas under chapter -->
    <topicref  href="HowToWriteCatalogs.xml">
        <topicref  href="ResolveDTDLocation.xml"/>
        <topicref  href="LocateXSLstylesheet.xml"/>
        <topicref  href="MapWebAddress.xml"/>
        <topicref  href="MapWithRewrite.xml"/>
        <topicref  href="MultipleCatalogs.xml"/>
    </topicref>
    <topicref  href="ExampleDocBookCatalog.xml"/>
    <topiciref  href="HowToUseCatalog.xml">
        <topicref  href="InSaxon.xml"/>
        <topicref  href="InXalan.xml"/>
        <topicref  href="InXsltproc.xml"/>
    </topicref>
    <topicref href="biblio.xml" renderas="bibliography"/>
   </topicref>
</contentmap>

The default behaviour could be either that renderas is inferred from 
root element of referenced module (if we will not use topic element for 
modules) or must be specified manually at least on root topicref and 
rendering of nested topicref could be inferred (e.g. topicrefs inside 
<topicref renderas="chapter"/> will be treated as sect1).

And finally we can add more attributes for controlling chunking.

<contentmap>
   <topicref href="XMLCatalogs.xml" outputchunk="XMLCatalogs.html">
    <topicref  href="WhyUseXMLCatalogs.xml">
    <topicref  href="HowToWriteCatalogs.xml" outputchunk="HowTo.html">
        <topicref  href="ResolveDTDLocation.xml"/>
        <topicref  href="LocateXSLstylesheet.xml"/>
        <topicref  href="MapWebAddress.xml"/>
        <topicref  href="MapWithRewrite.xml"/>
        <topicref  href="MultipleCatalogs.xml"/>
    </topicref>
    <topicref  href="ExampleDocBookCatalog.xml" outputchunk="..."/>
    <topiciref  href="HowToUseCatalog.xml"  outputchunk="...">
        <topicref  href="InSaxon.xml" outputchunk="..."/>
        <topicref  href="InXalan.xml" outputchunk="..."/>
        <topicref  href="InXsltproc.xml" outputchunk="..."/>
    </topicref>
   </topicref>
</contentmap>

New elements contentmap and topicref will not be part of DocBook schema 
but they will be defined in a completely separate schema for 
contentmaps. We could eventually add also topic element into DocBook 
schema. But such element will be allowed only as a root element 
(couldn't be child of any other element) and its content have to be 
discussed more carefully, but I think that it should be very similar to 
section. That way only one new element topic would be added into DocBook 
schema and this addition wouldn't change any existing content model.

This solution is also able to respond to RFE about having section and 
task on the same level as siblings. You can freely reference sections 
and tasks from content map.

This approach would cause only very conservative change in DocBook 
schema, but at the same time it will address I hope all new requests for 
more modular and topic-like authoring.

				Jirka

-- 
------------------------------------------------------------------
   Jirka Kosek     e-mail: jirka@kosek.cz     http://www.kosek.cz
------------------------------------------------------------------
   Profesionální školení a poradenství v oblasti technologií XML.
      Podívejte se na náš nově spuštěný web http://DocBook.cz
        Podrobný přehled školení http://xmlguru.cz/skoleni/
------------------------------------------------------------------
                    Nejbližší termíny školení:
     ** XSLT 23.-26.10.2006 ** XML schémata 13.-15.11.2006 **
      ** DocBook 11.-13.12.2006 ** XSL-FO 11.-12.12.2006 **
------------------------------------------------------------------
   http://xmlguru.cz    Blog mostly about XML for English readers
------------------------------------------------------------------

OpenPGP digital signature