[SSSD] Using XInclude for DocBook/XML manpages ... / was: Re: xml schema used for generating man pages

Roland Mainz rmainz at redhat.com
Fri Jan 16 20:16:19 UTC 2015



Hi!

----

[Sending response to the list so the information can be referenced in the future]

----- Original Message -----
> From: "Roland Mainz" <rmainz at redhat.com>
> To: "Pavel Reichl" <preichl at redhat.com>
> Sent: Thursday, January 15, 2015 1:43:49 PM
> Subject: Re: xml schema used for generating man pages
[snip]
> > I was editing information about an option that is in multiple files,
> > problem is that part of the description is file specific while part is
> > common for all the files. Is it possible to include file that doesn't
> > have a single parent node? Please see attached link that documents the
> > problem even more.
> 
> What about using xml:include in such cases ?
[snip]

Below are some random notes about using xincludes:
** /usr/bin/xmllint and /usr/bin/xsltproc require the option --xincludes to do any XInclude processing... without that option no xinclude processing is done (this is intentional because there are cases where the xinclude statements should be processed in a later stage in a XML processing chain)


** There are two XInclude modes which are interesting for DocBook processing (<xi:...> being the XInclude namespace - see examples):
1. <xi:include href="URL" />, which includes a whole XML document
Note that the XML document must be valid and must include all namespace declarations or it will not work
2. <xi:include href="URL" parse="text" />, which includes a text file as plain text and automagically does all the necessary quoting, e.g. special characters like '>', '<' etc. are converted to XML entities. This is very useful for tags like <programlisting> where in the past lots of effort and patches were needed to fix the layout.
Note that any leading spaces before xi:include are included in the output of <programlisting> because they are already part of the text data for <programlisting>


** It is possible to include XML fragments... but that requires XPointer and that's another long email... so I defer that until someone needs it


** Below are some example files which show how to use it (full versions attached to this email as "sssd_docbook_man_xinclude20150116_001.pax.gz", use GNU tar or AST pax to unpack):
-- snip --
$ (for i in 'true.1.xml' 'authors.xml' 'true.1.example1.txt' ; do printf '\n#### %s\n' "$i" ; cat -n "$i" ; done)

#### true.1.xml
[snip]
     4  <!-- BEGIN true.1.xml -->
     5
     6  <!-- define refnentry tag and declare the xinclude namespace with the prefix 'xi:...' -->
     7  <refentry xmlns="http://docbook.org/ns/docbook" version="4.1" xmlns:xi="http://www.w3.org/2001/XInclude" id="true">
     8
[snip]
    37  <refsect1>
    38      <title>Usage</title>
    39
    40      <para>
    41          ...
    42      </para>
    43
    44      <para>The command can be run like this:
    45        <informalexample>
    46          <programlisting>
    47  <!-- include text file as plain text segment (i.e. attribute parse="text") - no extra quoting etc. required -->
    48  <!-- withing "programlisting" tags the leading spaces before xi:include are included in the output, too!! -->
    49  <xi:include href="true.1.example1.txt" parse="text" />
    50          </programlisting>
    51        </informalexample>
    52      </para>
    53  </refsect1>
    54
    55  <refsect1>
    56    <title>Author</title>
    57
    58    <para>
    59    <xi:include href="authors.xml" />
    60    </para>
    61  </refsect1>
    62    
    63  </refentry>
    64  <!-- END true.1.xml -->

#### authors.xml
[snip]
     4  <!-- BEGIN authors.xml -->
     5
     6  <!-- first element in this include file must define the namespaces or $ xsltproc # will choke -->
     7
     8  <simplelist  xmlns="http://docbook.org/ns/docbook" version="4.1" xmlns:xi="http://www.w3.org/2001/XInclude" id="true">
     9    <member><othercredit><firstname>Mark</firstname> <surname>Lillibridge</surname> <affiliation><orgname>MIT Project Athena</orgname></affiliation></othercredit></member>
    10    <member><othercredit><firstname>Roland</firstname> <surname>Mainz</surname> <affiliation><orgname>University Giessen</orgname></affiliation></othercredit></member>
    11  </simplelist>
    12
    13  <!-- END authors.xml -->

#### true.1.example1.txt
     1  $ true
     2  $ printf '<result>%d</result>\n' $?
-- snip --

Now $ xsltproc --xinclude /usr/share/sgml/docbook/xsl-ns-stylesheets-1.78.1/html/docbook.xsl true.1.xml >x.html # can be used to convert the "true.1.xml" manpage to HTML and all include stuff is done automagically

BTW: IMHO it is wise that any XML documents shipped in binary RPMs should have all their XInclude references resolved because otherwise we have to keep track where the fragments we want to include are located.
Also, Chrome, FireFox, Seamonkey and w3m do not support XIncludes (e.g. not for XHTML, MathML or SVG) because there are unresolved issues (like event handling, how do handle loops etc. or that full XInclude support requires full XPointer support and that's not a can-of-worms, it's at least a swimming-pool-of-snakes... ;-( )

----

Bye,
Roland

-- 
  __ .  . __
 (o.\ \/ /.o) rmainz at redhat.com
  \__\/\/__/  IPA/Kerberos5 team
  /O /==\ O\  
 (;O/ \/ \O;)
 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: sssd_docbook_man_xinclude20150116_001.pax.gz
Type: application/x-gzip
Size: 1887 bytes
Desc: not available
URL: <https://lists.fedorahosted.org/pipermail/sssd-devel/attachments/20150116/5d02af57/attachment.gz>


More information about the sssd-devel mailing list