Re: [docbook] alternative topic proposal

["Bob Stayton" <bobs@sagehill.net>]

Hi Jirka,
I like your proposal too.  So now we have three proposals for modular 
authoring (Norm's, mine, and Jirka's). And they aren't necessarily mutually 
exclusive it seems.  I agree that this stuff is not for version 5.0 of 
DocBook, because I think it will take a bit of time to sort it out.  We 
could, for example, implement an external schema module for contentmap as a 
first step, without changing 5.0 at all.  And then look at adding 
topic/topicref elements later, if we feel there is still a need for them.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net


----- Original Message ----- 
From: "Jirka Kosek" <jirka@kosek.cz>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: "Sean Wheller" <sean@inwords.co.za>; <docbook@lists.oasis-open.org>; 
"Dave Pawson" <davep@dpawson.co.uk>
Sent: Tuesday, October 31, 2006 6:54 AM
Subject: Re: [docbook] alternative topic proposal

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