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" <chrischiasson.name>
To: "Scott Hudson" <scottys.loggmail.com>
Cc: "Bob Stayton" <bobssagehill.net>;
"Sean Wheller" <seaninwords.co.za>;
<docbooklists.oasis-open.org>; "Dave Pawson"
<davepdpawson.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.loggmail.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/nod
e/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
>> > bobssagehill.net
>> >
>> >
>> > ----- Original Message ----- From: "Scott
Hudson"
>> > <scottys.loggmail.com>
>> > To: "Chris Chiasson" <chrischiasson.name>
>> > Cc: "Bob Stayton" <bobssagehill.net>; "Sean Wheller"
>> > <seaninwords.co.za>; <docbooklists.oasis-open.org>; "Dave Pawson"
>> > <davepdpawson.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 <bobssagehill.net> wrote:
>> >>>> ----- Original Message -----
>> >>>> From: "Sean Wheller"
<seaninwords.co.za>
>> >>>> To: <docbooklists.oasis-open.org>
>> >>>> Cc: "Bob Stayton"
<bobssagehill.net>; "Dave Pawson"
>> >>>> <davepdpawson.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
>> >>>> bobssagehill.net
>> >>>>
>> >>>>
>> >>>>
>> >>>>
>> >>>>
------------------------------------------------------------
---------
>> >>>> To unsubscribe, e-mail:
docbook-unsubscribelists.oasis-open.org
>> >>>> For additional commands, e-mail:
docbook-helplists.oasis-open.org
>> >>>>
>> >>>>
>> >>>
>> >>>
>> >>
>> >>
>> >
>> >
>> >
>>
>>
>>
>>
>
>
> --
> http://chris.chiasson.nam
e/
>
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-helplists.oasis-open.org
>
>
>
------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org
|