[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] alternative topic proposal
Hi Chris, I'm not sure I understand your proposal. > Adding topicref (or sectionref) with the same content > model as section (besides the part that allows one to pull in content) So you are suggesting something like this example: <topicref href="HowToWriteCatalogs.xml"> <para>Some transition block elements that appear after the content referenced by href above, and before the content referenced by the topicrefs below</para> <topicref href="ResolveDTDLocation.xml"/> <topicref href="LocateXSLstylesheet.xml"/> [other topicrefs] </topicref> In the output presentation, the transition blocks would look like they were the end of the first topic, unless your stylesheet purposely formatted it differently to indicate transitional content. I presume the transition content model would be block elements and would not include section? More like the content model of simplesect? Bob Stayton Sagehill Enterprises DocBook Consulting bobs@sagehill.net ----- Original Message ----- From: "Chris Chiasson" <chris@chiasson.name> To: "Scott Hudson" <scottys.log@gmail.com> Cc: "Bob Stayton" <bobs@sagehill.net>; "Sean Wheller" <sean@inwords.co.za>; <docbook@lists.oasis-open.org>; "Dave Pawson" <davep@dpawson.co.uk> Sent: Tuesday, October 31, 2006 11:12 AM Subject: Re: [docbook] alternative topic proposal > But if topics (or sections or whatever non-block level element) were > the only types of elements that could be children of topicref (or > sectionref), then we end up without the ability to insert paragraphs > and other things at the ends of sections. Why loose a great capability > like that? > > Also, most people seem to be talking about adding two or more elements > to docbook. Adding topicref (or sectionref) with the same content > model as section (besides the part that allows one to pull in content) > would only require one new element and would add more capabilities > than the other proposals (I think). > > On 10/31/06, Scott Hudson <scottys.log@gmail.com> wrote: >> Right. I know you weren't proposing block content between topics, but >> was trying to address Chris' question regarding segue para between >> topics. The best practice would still be to create a separate >> transitional topic that you would reference via a topicref. >> >> I don't know that DocBook has to say that topics MUST be able to >> standalone, but that has certainly been the mantra in DITA. Transitional >> topics, by definition, would depend on context and thus not >> "standalone". >> >> Best regards, >> >> --Scott >> >> >> Bob Stayton wrote: >> > 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 >> >>>> >> >>>> >> >>> >> >>> >> >> >> >> >> > >> > >> > >> >> >> >> > > > -- > http://chris.chiasson.name/ > > --------------------------------------------------------------------- > 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]