DocBook

The DocBook is reluctant to add conref. Several TC members
familiar with DITA implementations assert that it's problematic
and difficult to implement. What's more, it doesn't really solve
the problems associated with duplicate IDs because IDs on the
descendants of the conref'd element may be duplicates.

The specific problem that conref solves can be addressed by
XPointer schemes less powerful than the full xpointer() scheme
(which is never likely to be completed).

The existing xpath() schemes have received some adoption and are
powerful enough to implement the equivalent of conref.

The TC would like to find a solution that addresses the problem
this RFE raises, but haven't seen anything yet that is
substantially better than other existing standards.

The following proposal describes a problem that currently exists when
transcluding content using the xpointer framework and element scheme;
however, the ideas can be extended to include other transclusion methods.
Regardless of the transclusion method that is adopted by DocBook, the
method needs to address authoring issues related to transclusion.

The current transclusion method requires writers to manually track content
that is transcluded across the collection. This is cumbersome and error
prone--it is easy to change the content in the xincluded file so
that it no longer makes sense within the xincluding file. DocBook needs an
automated method to track this information so that it could be exposed to
the writers so that they are aware that they are viewing and editing
content that is transcluded.

We propose augmenting the data in the xref target database to include
information that a topic is being reused (xincluded). For example, the
targetdatabase could contain a column that contains the path(s) of the
xincluding file for each targetptr. Maintaining this information could
reduce the number of times that future build processes/scripts build the
same topic. When a topic is built, if it's a topic that is being reused,
the built content could be stored as a temporary object that could be
reused in the other locations where the topic is included.

If this information was available, we are confident that authoring tools
could leverage the xinclude information to provide a visual cue to authors
that the topic they are editing is being reused elsewhere. Currently there
is no way to do this without implementing a Content Management System
(CMS).

The element scheme does get us half-way to our goal (although, we had to
get a workaround from oXygen to get our Xerces processor to handle them
properly.
The element scheme is fine when you are transcluding text between books
provided that you only need to transclude the element once; otherwise you
have duplicate ID problems.
The element scheme does not help you transclude text within a book as it
creates duplicate ID problems--this is the use case that we are trying to
solve.

We can't think of a case where we'd want to transclude within a book
anything larger than a sidebar or note; hence we are not concerned about
the problem of IDs of nested children, etc.. Between books, we do
transclude chapters and sections; however, we also use conditions on the
text to ensure unique IDs.

In our documentation, we have a lot of clauses, options, fields, etc., that
have the same definitions, which are defined in the same book. We'd like to
be able to transclude these definitions within the same file and not have a
problem with duplicate IDs. The xpointer scheme appeals to us as it allows
us to create a new element with a new ID and transclude the contents of
another element.

We would like a solution that allows us to accomplish the following:

1) Duplicate information between books without having to create separate
files for the duplicated/transcluded material. Currently, we can use
xpointer=element(uniqueID) to accomplish this; however, we required a
workaround to get our Xerces processor to handle this scheme.

2) Duplicate information within a book.
Currently, you can duplicate information within a book by:
* Using xpointer=pointer(uniqueID); however, this scheme is not part of
the
XML standard and it is not widely supported by the processors or
tools.
* Using file entities; however, the root elements in these file
entities cannot
have IDs. Also, you cannot olink to the transcluded content.