[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Transclusion requirements/use-cases
> b. Jirka to write up requirements document for transclusions in DocBook. > CONTINUE Hi folks, sorry for long delay -- I have finally created draft of transclusion requirements. It is not list of requirements but merely list of use-cases which lead to requirements. If you think that at the end there should be digested list of requirements, I can add it. Please let me know if I have omitted some use-case you have came across during your work. I have been thinking about transclusions little bit and I have quite comprehensive proposal already in my head. But we should collect all possible use-cases first. Have a nice day, Jirka -- ------------------------------------------------------------------ Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz ------------------------------------------------------------------ Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing ------------------------------------------------------------------ OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member ------------------------------------------------------------------Title: Requirements for transclusion in DocBook
06/09/2010 Abstract This document summarizes uses-cases for transclusion of content in DocBook documents. This document should help DocBook TC in deciding whether existing standards like XInclude are sufficient for the task or whether DocBook specific mechanism should be designed. Requirements for transclusion capability are repeating over the time, the last one which was discussed is http://sourceforge.net/tracker/index.php?func=detail&aid=2820947&group_id=21935&atid=384107. Table of Contents Many technical publication use repeating boilerplate text for things like product names or product versions. It is useful if such text is defined only once per document (or set of documents) and then just referenced. This approach prevents typos and makes updates and rebranding of content very easy. This use-case can be solved by using internal entities. This is well supported in processing tools and to some extent in authoring tools. However entities are somewhat hard to maintain when you use modular documents at the same time. Also entities and their references are not part of XDM so they do not survive XSLT processing which makes various “document massaging” tasks challenging. Example 1. Using entities for shared strings <!ENTITY product-version "3.14"> <!ENTITY product-name "FooWiz"> <!ENTITY corp-name "ACME Inc."> … <para>The latest version of <application>&product-name;</application> from &corp-name; is &product-version;.</para> XInclude when combined with proper XPointer schema can be used for transclusion of single element or even only its text content. In this setup there can be separate file with definition of shared texts which are then reused in other documents. Example 2. Definition file for further XInclude referencing <article xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Shared texts</title> <para><phrase xml:id="product-version">3.14</phrase></para> <para><phrase xml:id="product-name">FooWiz</phrase></para> <para><phrase xml:id="corp-name">ACME Inc.</phrase></para> </article> The problem is that support for different XPointer schemes varies between implementations. Almost all implementations support referencing to element specified by its ID as shown in the following example. Example 3. Using XIncludes for shared texts <… xmlns:xi="http://www.w3.org/2001/XInclude"> … <para>The latest version of <application><xi:include href="shared-texts.xml" xpointer="product-name"/></application> from <xi:include href="shared-texts.xml" xpointer="corp-name"/> is <xi:include href="shared-texts.xml" xpointer="product-version"/>.</para> … This solution has two problems. The actual reference to shared
texts is very verbose because each Solution is to use more advanced XPointer scheme. This leads to the more arcane markup, support in tools is very bad, bud there are no duplicated IDs and excessive markup. Example 4. Using XIncludes for shared texts without duplicating source elements <… xmlns:xi="http://www.w3.org/2001/XInclude"> … <para>The latest version of <application><xi:include href="shared-texts.xml" xpointer="xpointer(id('product-name')/text())"/></application> from <xi:include href="shared-texts.xml" xpointer="xpointer(id('corp-name')/text())"/> is <xi:include href="shared-texts.xml" xpointer="xpointer(id('product-version')/text())"/>.</para> … This use-cases is similar to UC-1. The only difference now is that shared text can appear in an attribute value. This is not very common requirement for DocBook document, but because of differences between element and attribute values in XML separate use-cases is created. This use-case can be solved only by using internal entities. This is well supported in processing tools and to some extent in authoring tools. Example 5. Using entities for shared strings in attribute values <!ENTITY product-version "3.14"> <!ENTITY product-name "FooWiz"> … <section xreflabel="Installation of &product-name; &product-version;"> … Some documents use conditional content. Shared text then can be also subject to conditional processing. This use-case can be solved by using conditional sections which can enclose entity definitions. Do we need example here? It is rarely used feature. As typical XInclude scenarios include complete elements not just their content, it is possible to define several parallel elements with different profiling attributes set, enclose them with another element and then do inclusion. Example 6. Definition file for further XInclude referencing with conditional text <article xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Shared texts</title> … <para><phrase xml:id="product-name"><phrase os="win">Windows Protector</phrase><phrase os="linux">Linux Protector</phrase></phrase></para> … </article> For large documents it is often impractical to edit them as a single large XML file. It is practical to split large document (e.g. book) into few smaller ones (e.g. chapters) and just include them into “master” document. This approach is also useful for reusing of boilerplate texts like legalnotices. This use-case can be solved by using external entities. This is well supported in processing tools and to some extent in authoring tools. Also entities and their references are not part of XDM so they do not survive XSLT processing which makes various “document massaging” task challenging. External entities doesn't work very well if there are multiple levels of inclusions as entities can be declared only in the “main” document. Example 7. Using entities for modularized documents … <!ENTITY chapter1 SYSTEM "chapter1.xml"> <!ENTITY chapter2 SYSTEM "chapter2.xml"> … <book …> <info> <title>A Book</title> </info> &chapter1; &chapter2; <index/> </book> XInclude works very well for this use-case. Example 8. Using XIncludes for modularized documents <book … xmlns:xi="http://www.w3.org/2001/XInclude"> <info> <title>A Book</title> </info> <xi:include href="chapter1.xml"/> <xi:include href="chapter2.xml"/> <index/> </book> Some types of documentation are highly modular and composed from large number of small units. These units can be whole chapters, smaller self-standing units like section or topic, or it can be quite small chunk of content like admonition. If each such unit is used only once in document then there is no problem and we are working only with highly modular document (see UC-4). But if one unit is included more then once then we can face several problems. If elements in units have assigned unique IDs (by using There are different strategies which can be used to managed units and IDs which are transcluded more then once:
Unfortunately there is no satisfying solution to this use-case. DocBook XSL stylesheet can be customized to link only to the first occurrence of ID (see http://www.sagehill.net/docbookxsl/DuplicateIDs.html). Sometimes it is necessary to include foreign content into DocBook document. Examples of such foreign content are:
Text files with programlistings can be transcluded by DocBook
|
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]