OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook] Profiling blocks of paragraphs


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
> 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
>>
>>
>
>



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]