DocBook documentation stub added

[stg.git] / doc / help / xslt / params / textinsert.extension.xml

diff --git a/doc/help/xslt/params/textinsert.extension.xml b/doc/help/xslt/params/textinsert.extension.xml
new file mode 100644 (file)
index 0000000..a6f1ea4
--- /dev/null
+++ b/doc/help/xslt/params/textinsert.extension.xml
@@ -0,0 +1,62 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  version="5.0" xml:id="textinsert.extension">
+  <refmeta>
+    <refentrytitle>textinsert.extension</refentrytitle>
+    <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>textinsert.extension</refname>
+    <refpurpose>Enables the textinsert extension element</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <src:fragment xml:id="textinsert.extension.frag">
+  <xsl:param name="textinsert.extension" select="1"/>
+</src:fragment>
+  </refsynopsisdiv>
+  <refsection><info><title>Description</title></info>
+    <para>The textinsert extension element inserts the contents of
+      a file into the result tree (as text).</para>
+    <note>
+      <para>To use the textinsert extension element, you must use
+        either Saxon or Xalan as your XSLT processor (it doesn’t
+        work with xsltproc), along with either the DocBook Saxon
+        extensions or DocBook Xalan extensions (for more
+        information about those extensions, see <link
+          role="tcg" xlink:href="InstallingAProcessor.html#SaxonExtensions"
+          >DocBook Saxon Extensions</link> and <link
+          role="tcg" xlink:href="InstallingAProcessor.html#XalanExtensions"
+          >DocBook Xalan Extensions</link>), and you must set both
+        the <parameter>use.extensions</parameter> and
+        <parameter>textinsert.extension</parameter> parameters to
+        <literal>1</literal>.</para>
+      <para>As an alternative to using the textinsert element,
+        consider using an Xinclude element with the
+        <literal>parse="text"</literal> attribute and value
+        specified, as detailed in <link
+          role="tcg" xlink:href="ExternalCode.html#XIncludeCode"
+          >Using XInclude for text inclusions</link>.</para>
+    </note>
+  </refsection>
+  <refsection><info><title>See Also</title></info>
+    <para>You can also use the <tag
+        class="xmlpi">dbhtml-include href</tag> processing
+      instruction to insert external files — both files containing
+      plain text and files with markup content (including HTML
+      content).</para>
+  </refsection>
+  <refsection><info><title>More information</title></info>
+    <para>For how-to documentation on inserting contents of
+      external code files and other text files into output, see
+      <link
+        role="tcg" xlink:href="ExternalCode.html"
+        >External code files</link>.</para>
+    <para>For guidelines on inserting contents of
+      HTML files into output, see <link
+        role="tcg" xlink:href="InsertExtHtml.html"
+        >Inserting external HTML code</link>.</para>
+  </refsection>
+</refentry>