Re: [docbook] alternative topic proposal

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

----- Original Message ----- 
From: "Sean Wheller" <sean@inwords.co.za>
To: <docbook@lists.oasis-open.org>
Cc: "Bob Stayton" <bobs@sagehill.net>; "Dave Pawson" <davep@dpawson.co.uk>
Sent: Monday, October 30, 2006 9:38 PM
Subject: Re: [docbook] alternative topic proposal


On Monday 30 October 2006 22:32, Bob Stayton wrote:
> f we also introduce the idea of topicref, then we are adding new
> capabilities to DocBook to assemble these modules into sequences and
> hierarchies. The difference from XInclude is that a topicref is resolved
> by an XSLT process, so the assembly process can actively filter and fix
> content rather than just copy it into place. That's a big gain in modular
> processing, if you need it.

I agree that this is a benefit. Still however, I am not convinced that this
must be an attribute of a new element. Why can't we have this anyway, on
existing elements?
------------------------------------------------------------------------------------
Actually, topicref is an element, not an attribute.  And topicref
does not contain any content of its own.  Perhaps
I need to show an example.  Here is how a chapter from my book:

   http://www.sagehill.net/docbookxsl/Catalogs.html

might be authored as topicrefs.  Each of the hrefs points to
an XML file that contains a single topic element.

<chapter>
    <title>XML catalogs</title>
    <para>A catalog in XML ...
    <para>There are two kinds of catalogs ...
    <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>
</chapter>

When an empty topicref is resolved, the referenced topic is
simply imported and assigned the current level in the
processing hierarchy of the output.  So the first topicref
would be equivalent to a sect1 in formatted output in this
instance.

When a topicref contains other topicrefs, that expresses
a hierarchy of topics.  The outer topic ref is imported and
assigned the current level of processing (another sect1
in this example).  After its content
ends, the children topicrefs are imported in the order given
and assigned formatting equivalent to sect2.

The result of processing this chapter should match
the output you see on my website.  If needed, the topics
could be reshuffled using a different topicref
hierarchy for a different purpose in another document.

I don't think it is possible to create a chapter file like
this using XIncludes and section files.  If you import
a section at level1, then that section file must
contain the XIncludes for any sections at level2 under it.

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

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net