Re: [docbook] Profiling blocks of paragraphs

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

I don't think you are missing anything in the DocBook spec.  This is a 
general problem in XML, not just DocBook.  There is no general container 
element because it makes for incredibly complicated content models for 
elements, because such containers could be used at so many different levels 
of element nesting.  It works for inlines with phrase because those content 
models are so simple.

I know of three workarounds for this problem.  Each of these requires 
changing the way you do things, so they might not work in your situation.

Solution #1: in your XML source, use a different attribute from xml:id to 
hold the id string, and convert such attributes to xml:id in the profiling 
step.  I have used @remap for such purposes.  A customization of the 
profiling stylesheet can convert any remap attribute to an xml:id, at the 
same time it is selecting out the content, leaving you with one section 
with each id value.  The file could be valid both before and after 
profiling.  This assumes you don't use remap for other purposes.

Solution #2: divide up your XML source into modular files, use XIncludes to 
include the modules, and put the profiing attributes on the xi:include 
elements.  You'll have to customize the xi:include DTD to allow such 
attributes.  You would put each such section element with its duplicate 
xml:id into a separate file, so there is not duplication in the including 
document.  Your main source document has an xi:include element for each 
duplicate section but with different profiling attributes.  To process, you 
run profiling first as a separate step (which results in a single 
xi:include for each duplicate section), then the XSLT process with XInclude 
processing to pull in the included section and format it.

Solution #3: divide up your XML source into modular files as above, but put 
a single unprofiled xi:include element in the main document for each such 
section.  During processing, use a different xml catalog for each profile 
to map those hrefs to different section files.

There are pros and cons for each of these approaches, and I can provide 
more details if you need them.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net


----- Original Message ----- 
From: "Geraint North" <geraint@transitive.com>
To: <docbook@lists.oasis-open.org>
Sent: Monday, September 10, 2007 2:02 AM
Subject: [docbook] Profiling blocks of paragraphs


> Our product ships on a number of different platforms, and thus our 
> (mostly common) documentation uses profiling (with the arch  attribute) 
> so that we can build each variant as required.  Often,  whole sections 
> are different (e.g. installation instructions vary  between Linux and 
> Solaris versions of our product).
>
> Now, we can't do this:
>
> <section xml:id="Installation" arch = "Linux">
> <title>Installation</title>
> <para>...</para>
> <para>...</para>
> <para>...</para>
> </section>
>
> <section xml:id="Installation" arch = "Solaris">
> <title>Installation</title>
> <para>...</para>
> <para>...</para>
> <para>...</para>
> </section>
>
> ...because you can't have two elements with the same xml:id, but we  need 
> the xml:id to be consistent so that our cross-references work  cleanly.
>
> What I want to do is this:
>
> <section xml:id="Installation">
> <title>Installation</title>
> <contentgroup  arch = "Linux">
> <para>...</para>
> <para>...</para>
> <para>...</para>
> </contentgroup>
>
> <contentgroup  arch = "Solaris">
> <para>...</para>
> <para>...</para>
> <para>...</para>
> </contentgroup>
> </section>
>
> But as far as I can see, there is no <contentgroup> equivalent, so it 
> looks like we'll have to do this:
>
> <section xml:id="Installation">
> <title>Installation</title>
> <para arch = "Linux">...</para>
> <para arch = "Linux">...</para>
> <para arch = "Linux">...</para>
> <para arch = "Solaris">...</para>
> <para arch = "Solaris">...</para>
> <para arch = "Solaris">...</para>
> </section>
>
> Which is cumbersome and likely to be bug-prone over time.  Am I  missing 
> anything in the docbook spec, or is there really nothing that  fulfils 
> the requirement?
>
> Thanks,
>
> Geraint North
> Principal Engineer
> Transitive
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
>
>
>