Open Stack

Greetings,

I've cut release 2.1.0 of the clouddocs-maven-plugin that supports a
method for including more than one time even when it contains xml:ids.
Up to now, it was challenging to do this because the duplicated content
would result in duplicate ids and an invalid document.

If you are using the olink-maven-plugin in your pom, please update it so
that you use version 1.2.6 of it and then update the
clouddocs-maven-plugin to version 2.1.0. Also please use the latest
version of the rackbook framework by following these instructions:
http://docs.rackspace.com/oxygen/

Examples:

Say there's a file foo.xml that contains a <section> with an xml:id and
perhaps a few other xml:ids on subsections, figures, or whatever. For
some reason, you'd like to include it more than once in the same
document. Now you can do:

   <xi:include href="foo.xml" />

   <!-- elsewhere in the same doc -->

   <xi:include
       href="foo.xml"
       db:idprefix="second-use-of-this-stuff-"/>

When the 2nd xinclude is resolved, it will prefix any xml:ids with
"second-use-of-this-stuff-". Controlling the prefix added to the
xincluded ids is important if any of these ids are used to generate the
file names.

Important: You must declare the db prefix, generally at the root element
of any file in which you use db:idprefix:

   xmlns:db="http://docbook.org/ns/docbook"

Note: Unfortunately, Oxygen doesn't yet know about the idfixup stuff, so
when you use this feature, Oxygen and other validation tools may report
errors about duplicate ids or broken xrefs that will not be problems
when you build the doc. I hope that a future version of Oxygen will
support these features when doing validation.

In some cases, you may not care about controlling the prefix added. Say
in section.xml you have the admontion:

<important xml:id="important-stuff">
      <para>This is very important.</para>
</important>

This is a great admonition that you want to use in another chapter. You
can now pull it in by doing:

<xi:include href="section.xml"
            xpointer="element(important-stuff)"
            db:idfixup="auto"/>

The attribute db:idfixup="auto" tells the system to generate a random
prefix for the ids in the xincluded content. Since this admonition's id
isn't used to generate a file name and we don't need to xref to it,
that's fine. We get to reuse or great admonition without getting
duplicate ids.

You can read more about this mechanism generally here:

http://docbook.org/docs/transclusion/2010-12-09/transclusion.html#d6e179

Regards,
David