[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Updated transclusion proposal
On 20.8.2014 10:13, Jirka Kosek wrote: >> d. Jirka to update "DocBook Transclusions" document to reflect >> the new XInclude 1.1 features. > > Continued, will be ready for September meeting. Hi folks, please find first very rough attempt to update transclusions as a layer on top of XInclude 1.1. Some features are missing compared to previous draft, but once XInclude 1.1 is implemented solution will be more standards-based. 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 rep. ------------------------------------------------------------------ Bringing you XML Prague conference http://xmlprague.cz ------------------------------------------------------------------Title: DocBook Transclusion
DocBook TransclusionNaN September 2014Table of Contents This document describes syntax, semantics and processing model
of DocBook transclusion mechanism. Please be aware that this is early
stage draft – everything described below might change or disappear
completely. This proposal tries to resolve Requirements
for transclusion in DocBook. DocBook TC welcomes any
feedback on this draft, especially from users and developers of
DocBook authoring and processing tools. Plese direct your comments to
DocBook mailing list by sending email to
Actually, for now the document is written more like tutorial. If DocBook TC decides to incorporate this into DocBook, more formal and precise specification will follow. NotePrevious version of this draft proposed new elements
This resulted in a loss of some features, notably:
The following namespace bindings are assumed if namespace prefix is used in the text of this document:
XInclude 1.1 [XI11] in section 4.3 Attribute Copying when processing XML defines new feature which can be used for passing around attributes that control transclusion processing. Processing model of XInclude 1.1 based transclusion is simple. First XInclude processing is done. Then before normal DocBook processing additional DocBook transclusion step is applied which can modify some attributes. DocBook transclusion processor must support the following attributes:
Transcluded content can contain an How IDs are going to be adjusted during transclusion is
controlled by the Of course if IDs are adjusted then all corresponding references has
to be also corrected. This is controlled by By using various combinations of Example 1. Module with sample procedure <?xml version="1.0" encoding="UTF-8"?> <procedure xmlns="http://docbook.org/ns/docbook" xml:id="paper-insert"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="s1"><para>Make sure that you have paper.</para></step> <step><para>Insert paper into printer. If you don't have paper consult <xref linkend="s1"/></para></step> </procedure> Now lets assume that we want to transclude this module twice to show how we can deal with duplicate IDs problem. Example 2. Automatic ID/IDREF adjustment <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml" db:idfixup="auto"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml" db:idfixup="auto"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="d2e22---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="d2e22---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e22---s1" /></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:id="d2e36---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="d2e36---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e36---s1" /></para> </step> </procedure> </chapter> </book> We have to specify Example 3. Global linkscope <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml" db:idfixup="auto"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml" db:idfixup="auto" db:linkscope="global"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="d2e22---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="d2e22---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e22---s1" /></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:id="d2e36---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="d2e36---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e22---s1" /></para> </step> </procedure> </chapter> </book> We used Example 4. Local linkscope <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml" db:idfixup="auto" db:linkscope="local"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml" db:idfixup="auto"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="d2e22---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="d2e22---buy">buying one</link>.</para> <step xml:id="d2e22---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e22---s1" /></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:id="d2e36---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="d2e36---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e36---s1" /></para> </step> </procedure> </chapter> </book> We used Example 5. Manually assigned prefix <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml" db:id="install-proc" db:idfixup="prefix" db:prefix="install-proc_"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml" db:id="maintain-proc" db:idfixup="prefix" db:prefix="maintain-proc_"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="install-proc_paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="install-proc_s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="install-proc_s1"/></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:id="maintain-proc_paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="maintain-proc_s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="maintain-proc_s1"/></para> </step> </procedure> </chapter> </book> If we care about the resulting IDs after transclusion we can manually assign some meaningful prefix before IDs in transcluded document. Example 6. Disabling ID fixup <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="s1"/></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:id="paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="s1"/></para> </step> </procedure> </chapter> </book> Default behaviour of XInclude is not to do any postprocessing like DocBook transclusions. The resulting document thus contain duplicated IDs. Example 7. Stripping IDs <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml" db:idfixup="auto"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml" db:idfixup="strip"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="d2e22---paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="d2e22---s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e22---s1" /></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="d2e22---s1" /></para> </step> </procedure> </chapter> </book> We have stripped all IDs from the second transcluded procedure by
Example 8. Retaining original IDs <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <xi:include href="procedure.001.xml" db:linkscope="user"/> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <xi:include href="procedure.001.xml" db:idfixup="strip" db:linkscope="user"/> </chapter> </book> Result of transclusion: <?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook"> <title>Definitive Printer Guide</title> <chapter xml:id="buy"> <title>Buying printer</title> <para>Grab money, go to shop, ...</para> </chapter> <chapter> <title>Quick installation guide</title> <para>Carefully follow all procedures bellow.</para> <procedure xml:id="paper-insert" xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step xml:id="s1"> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="s1"/></para> </step> </procedure> </chapter> <chapter> <title>Maintenance</title> <para>Be friendly to your printer when you speak to it.</para> <para>If green led is blinking, please add missing paper using the following procedure.</para> <procedure xml:base="file:/e:/texts/docbook/tc/transclusions/procedure.001.xml"> <title>Inserting paper into printer</title> <para>This procedure is targeted to printer owners. If you don't have printer, consider <link linkend="buy">buying one</link>.</para> <step> <para>Make sure that you have paper.</para> </step> <step> <para>Insert paper into printer. If you don't have paper consult <xref linkend="s1"/></para> </step> </procedure> </chapter> </book> We have stripped all IDs from the second transcluded procedure by
Should be there option to preserve original IDs (without prefix) in output when doing prefixes? A. Sample transclusion processor written in XSLT 2.0Please note that this sample transclusion processor is not yet feature complete. It supports only subset of proposal. [XI11] XML Inclusions (XInclude) Version 1.1. W3C Candidate Recommendation. 8 October 2013. Available at http://www.w3.org/TR/2013/CR-xinclude-11-20131008/ |
Attachment:
signature.asc
Description: OpenPGP digital signature
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]