Hi Scott,
Just to be clear, putting block content between topics or topicrefs is not
something I proposed. I was thinking of something parallel to the current
chapter/section structure, where once you start a section in a chapter, you
don't include any more block elements ampng them.
DITA committee member JoAnn Hackos wrote a paper on transitional text. The
paper questions the need for such transitional text in technical writing.
http://dita.xml.org/node/1410
Personally, for DocBook I would want to keep the usage of topicref really
simple and not permit it. I could be convinced otherwise. Maybe we could
make title optional in topic to serve such a purpose. Write a short topic
and reference it with topicref to provide the transition. That keeps it
modular, and you can reuse the transition topic. 8^)
Bob Stayton
Sagehill Enterprises
DocBook Consulting
----- Original Message -----
From: "Scott Hudson" <>
To: "Chris Chiasson" <>
Cc: "Bob Stayton" <>; "Sean Wheller" <>;
<>; "Dave Pawson" <>
Sent: Monday, October 30, 2006 10:53 PM
Subject: Re: [docbook] alternative topic proposal
> If you use Bob's example below, you could put para or most other allowed
> children of chapter between topicrefs...
>
> Of course, if you want seques inside of a topicref and between nested
> topicrefs, then we'd have to adjust the model for topicref.
>
> Then again, you can always do what the DITA folks recommend: if you need
> transitional text, stick it into a separate topic. Of course, that
> transitional topic won't meet the standalone requirement at that point,
> but that's the same situation in DITA...
>
> --Scott
>
> Chris Chiasson wrote:
>> What if one needed an interstitial paragraph to segue from one
>> subtopic to another?
>>
>> On 10/31/06, Bob Stayton <> wrote:
>>> ----- Original Message -----
>>> From: "Sean Wheller" <>
>>> To: <>
>>> Cc: "Bob Stayton" <>; "Dave Pawson"
>>> <>
>>> 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
>>>
>>>
>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail:
>>> For additional commands, e-mail:
>>>
>>>
>>
>>
>
>
