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
[EMAIL PROTECTED]
----- Original Message ----- From: "Geraint North"
<[EMAIL PROTECTED]>
To: <[email protected]>
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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
