Hi!
----
[Sending response to the list so the information can be referenced in the future]
----- Original Message -----
From: "Roland Mainz" <rmainz(a)redhat.com>
To: "Pavel Reichl" <preichl(a)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(a)redhat.com
\__\/\/__/ IPA/Kerberos5 team
/O /==\ O\
(;O/ \/ \O;)