Improve doc descriptions of dbhtml filename and dir.

diff --git a/xsl/html/pi.xsl b/xsl/html/pi.xsl
index f9652dd3977cbe90af1ef172f2a54ba5fe38b9e7..2e555088416cfc606ee64449d373ac3ad907e9f5 100644 (file)
--- a/xsl/html/pi.xsl
+++ b/xsl/html/pi.xsl
@@ -226,6 +226,31 @@
       as a child of a <tag>mediaobject</tag> to specify a
       directory into which any long-description files for that
       <tag>mediaobject</tag> will be written.</para>
+
+<para>The output directory specification is inherited by all
+chunks of the descendants of the element.  If descendants need
+to go to a different directory, then add another 
+<tag class="xmlpi">dbhtml dir</tag> processing
+instruction as a child of the source element
+for that chunk, and specify the path relative to the
+ancestor path.</para>
+
+<para>For example, to put most chunk files into 
+<filename class="directory">shared</filename>
+but one chapter into 
+<filename class="directory">exception</filename>
+at the same level, use:</para>
+
+<programlisting><![CDATA[<book>
+  <?dbhtml dir="shared"?>
+  ...
+  <chapter>
+    <?dbhtml dir="../exception"?>
+  </chapter>
+</book>
+]]></programlisting>
+
+
   </refdescription>
   <refsynopsisdiv>
     <synopsis><tag class="xmlpi">dbhtml dir="<replaceable>path</replaceable>"</tag></synopsis>
@@ -259,9 +284,17 @@
 <doc:pi name="dbhtml_filename" xmlns="">
   <refpurpose>Specifies a filename for a chunk</refpurpose>
   <refdescription>
-    <para>When chunking output, use the <tag class="xmlpi">dbhtml filename</tag>
+<para>When chunking output, use the <tag class="xmlpi">dbhtml filename</tag>
       PI as a child of a chunk source to specify a filename for
-      the output file for that chunk.</para>
+      the output file for that chunk. Include the filename suffix.</para>
+
+<para>You cannot include a directory path in the filename value,
+or your links may not work.  Add a 
+<tag class="xmlpi">dbhtml dir</tag> processing instruction
+to specify the output directory. You can also combine the two
+specifications in one processing instruction: 
+<tag class="xmlpi">dbhtml dir="mydir" filename="myfile.html"</tag>.</para>
+
   </refdescription>
   <refsynopsisdiv>
     <synopsis><tag class="xmlpi">dbhtml filename="<replaceable>filename</replaceable>"</tag></synopsis>