#260 Ability to transclude text.

v5.0 FU for 6.0
open
nobody
8
2009-07-14
2009-07-13
Kate Wringe
No

Currently, it is very difficult to transclude the content of an element but not the element itself. The xinclude xpointer scheme is not a standard and thus it has only been adopted by the libxml processor. Using file entities can quickly create a file management nightmare. Would it be possible to implement support for something like conrefs for DocBook?

Discussion

  • Kate Wringe
    Kate Wringe
    2009-07-14

    • labels: --> DocBook XML
    • milestone: --> v5.0 FU for 6.0
    • priority: 5 --> 8
     
  • Kate Wringe
    Kate Wringe
    2009-07-14

    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.

     
  • Kate Wringe
    Kate Wringe
    2009-07-20

    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.

     
  • Kate Wringe
    Kate Wringe
    2009-08-17

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

     
  • Norman Walsh
    Norman Walsh
    2009-11-18

    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.