example-tutorial para-en.xml, NONE, 1.1 Makefile, 1.26, 1.27 example-tutorial-en.xml, 1.22, 1.23

[Tommy Reynolds (jtr)]

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"</phrase>
+      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>