Author: jtr
Update of /cvs/docs/example-tutorial
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv27221
Modified Files:
Makefile example-tutorial-en.xml
Added Files:
para-en.xml
Log Message:
Utilize the proper <xi:include> idiom to obtain the content of some
useless paragraph.
--- NEW FILE para-en.xml ---
<para>
This paragraph was obtained via an
<wordasword><xi:include></wordasword> element, just for an
example.
</para>
Index: Makefile
===================================================================
RCS file: /cvs/docs/example-tutorial/Makefile,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- Makefile 17 Jan 2006 21:11:02 -0000 1.26
+++ Makefile 30 Jan 2006 19:11:23 -0000 1.27
@@ -16,6 +16,7 @@
#
LANGUAGES = en de
DOCBASE = example-tutorial
+XMLEXTRAFILES-en= para-en.xml
#
######################################################
include ../docs-common/Makefile.common
Index: example-tutorial-en.xml
===================================================================
RCS file: /cvs/docs/example-tutorial/example-tutorial-en.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- example-tutorial-en.xml 21 Jan 2006 19:32:04 -0000 1.22
+++ example-tutorial-en.xml 30 Jan 2006 19:11:23 -0000 1.23
@@ -18,7 +18,7 @@
<article id="example-tutorial" lang="en">
-&FDP-INFO;
+ &FDP-INFO;
<section id="sn-some-section">
<title>Some Section</title>
@@ -30,7 +30,13 @@
since those tags will make sections less modular, i.e., harder to
relocate without changing a lot of other markup.
</para>
-
+ <xi:include href="para-en.xml"
xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:fallback>
+ <para>
+ Could not find the <filename>para-en.xml</filename> file
+ </para>
+ </xi:fallback>
+ </xi:include>
<para>
Keep text within the <command>title</command> tags on the same
line as the tags. Nesting the title on a separate line from the
@@ -51,7 +57,8 @@
avoided. To install any RPM package, use the following syntax:
</para>
<screen>
-<userinput><command>rpm -ivh
<replaceable>pkgname</replaceable>-<replaceable>version</replaceable>.<replaceable>arch</replaceable>.rpm</command></userinput>
+<userinput><command>rpm -ivh
<replaceable>pkgname</replaceable>-<replaceable>version</replaceable>.<replaceable>arch</replaceable>.rpm</command>
+ </userinput>
</screen>
<para>
Notice that the <command>screen</command> section is entirely
@@ -64,7 +71,8 @@
sample.
</para>
<screen>
-<userinput><command>grep snmptrap
/etc/services</command></userinput>
+<userinput><command>grep snmptrap /etc/services</command>
+ </userinput>
<computeroutput>snmptrap 162/udp snmp-trap # Traps for
SNMP</computeroutput>
</screen>
<para>
@@ -157,6 +165,41 @@
</procedure>
</section>
+ <section id="sn-external-files">
+ <title>Including External Files</title>
+
+ <para>
+ An alternative to declaring and using system entities to obtain
+ the content from other files is to use an
+ <firstterm>XInclude</firstterm> reference. These work similarly to
+ include files in familiar programming languages. Using the
+ XInclude feature allows an entire file, or just a part of it, to
+ be copied into the current document. External files are referenced
+ using an <abbrev>URI</abbrev> so they may be located anywhere,
+ even across the Internet.
+ </para>
+
+ <para>
+ The official documentation for the XInclude feature may be found
+ at the <ulink
url="http://www.w3.org/TR/XInclude"/> web site. A
+ somewhat dated description at
+ <ulink
url="http://www.sagehill.net/docbookxsl/ModularDoc.html"/>
+ may be a more readible starting reference.
+ </para>
+
+ <para>
+ Using the XInclude facility with DocBook requires a special
+ technique to allow the document to pass XML validation. Often
+ examples show adding the phrase
+
<
phrase>xmlns:xi="http://www.w3.org/2001/XInclude"<...
+ to a top-level element such as
+ <wordasword><chapter></wordasword>. Unfortunately this
+ causes the DocBook file to fail validation. The solution is to
+ place the namespace declaration directly in the <xi:include>
+ element:
+ </para>
+ </section>
+
<index id="generated-index"></index>
</article>