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-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

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
bobssagehill.net


----- Original Message ----- 
From: "Geraint North" <gerainttransitive.com>
To: <docbooklists.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-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

Thanks Bob - they look like three promising solutions.

I'll talk to our documentation guys to see what they think,
but I'm  
leaning towards option 1, because:
- I'm not currently that familiar with xi:include and XML
catalogs  
(although I expect I'll familiarise myself with them soon
enough)
- I believe that many of the profiled pieces are the order
of a few  
paragraphs in length, which might make shifting things out
into other  
files overkill.
- I believe that I can customise XMLMind nicely to make the
process  
straightforward - it requires less of a paradigm shift than
moving  
from a single-file model of documents to a multi-file one,
although  
we may end up going multi-file in the future anyway, as we
find that  
we want to share content across multiple documents.

Thanks for taking the time to write such a thoughtful
response - very  
much appreciated.

Thanks,

Geraint North
Principal Engineer
Transitive


On 10 Sep 2007, at 20:29, Bob Stayton wrote:

> 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
> bobssagehill.net
>
>
> ----- Original Message ----- From: "Geraint
North"  
> <gerainttransitive.com>
> To: <docbooklists.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-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