[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] alternative topic proposal
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 bobs@sagehill.net ----- Original Message ----- From: "Scott Hudson" <scottys.log@gmail.com> To: "Chris Chiasson" <chris@chiasson.name> Cc: "Bob Stayton" <bobs@sagehill.net>; "Sean Wheller" <sean@inwords.co.za>; <docbook@lists.oasis-open.org>; "Dave Pawson" <davep@dpawson.co.uk> 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 <bobs@sagehill.net> wrote: >>> ----- 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 >>> >>> >>> >>> >>> --------------------------------------------------------------------- >>> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org >>> For additional commands, e-mail: docbook-help@lists.oasis-open.org >>> >>> >> >> > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]