Skip to content

Commit 4f3617f

Browse files
tomschrtomschr
authored
Fix #40: Add <?dbhtml?> for chunking (#41)
* Describe dir and filename pseudo-attributes for `<?dbhtml?>` * Add example
1 parent 0f31593 commit 4f3617f

2 files changed

Lines changed: 128 additions & 0 deletions

File tree

‎en/xml/dbc-html.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,4 +154,5 @@
154154
<xi:include href="html/topic.chunking.xml"/>
155155
<!-- <xi:include href="html/topic.google-webfonts.xml"/> -->
156156
<!--<xi:include href="html/topic.consistent-ids.xml"/>-->
157+
<xi:include href="html/topic.chunking-pi.xml"/>
157158
</chapter>

‎en/xml/html/topic.chunking-pi.xml‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
License CC BY-NC-SA 3.0
4+
5+
This work is licensed under the
6+
"Namensnennung – Keine kommerzielle Nutzung – Weitergabe unter
7+
gleichen Bedingungen 3.0 Deutschland (CC BY-NC-SA 3.0)"
8+
http://creativecommons.org/licenses/by-nc-sa/3.0/de/deed.de
9+
10+
Read the English translation here:
11+
12+
"Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0)"
13+
http://creativecommons.org/licenses/by-nc-sa/3.0/
14+
15+
-->
16+
<!--<?xml-model href="file:../5.1/dbref.rnc" type="application/relax-ng-compact-syntax"?>-->
17+
18+
<section xml:id="dbc.html.chunkpi" remap="topic" version="5.1"
19+
userlevel="easy"
20+
xmlns="http://docbook.org/ns/docbook"
21+
xmlns:xi="http://www.w3.org/2001/XInclude"
22+
xmlns:xlink="http://www.w3.org/1999/xlink">
23+
<title>Setting your own Files and Directories Names during Chunking</title>
24+
<info>
25+
<keywordset>
26+
<keyword>chunk</keyword>
27+
<keyword>chunking</keyword>
28+
<keyword>pi</keyword>
29+
<keyword>processing instructions</keyword>
30+
</keywordset>
31+
<subjectset>
32+
<subject>
33+
<subjectterm>chunking</subjectterm>
34+
</subject>
35+
</subjectset>
36+
</info>
37+
38+
<section role="problem">
39+
<title>Problem</title>
40+
<para>
41+
You need a method to use the chunking process, but you want to
42+
define your own file and directory names for the HTML output.
43+
</para>
44+
</section>
45+
<section role="solution">
46+
<title>Solution</title>
47+
<para> The DocBook XSL stylesheets recognize the specific processing
48+
instruction (PI) <tag class="pi">dbhtml</tag> for HTML output to influence
49+
the chunking process. The PI knows the following pseudo-attributes:</para>
50+
<variablelist>
51+
<varlistentry>
52+
<term><tag class="pi">dbhtml dir="<replaceable>PATH</replaceable>"</tag></term>
53+
<listitem>
54+
<para>Specifies a directory name in which to write files. It is
55+
possible to add a trailing slash or leave it out, the stylesheets
56+
know how to deal with both cases.
57+
</para>
58+
</listitem>
59+
</varlistentry>
60+
<varlistentry>
61+
<term><tag class="pi">dbhtml filename="<replaceable>FILENAME</replaceable>"</tag></term>
62+
<listitem>
63+
<para>Specifies a file name for a chunk. The value must contain
64+
only the file name with an optional extension, but not any
65+
directories.
66+
</para>
67+
</listitem>
68+
</varlistentry>
69+
</variablelist>
70+
<para>You can combine <varname>filename</varname> and <varname>dir</varname>.
71+
Insert this processing instruction into your component of your XML file.
72+
</para>
73+
</section>
74+
<section role="discussion">
75+
<title>Discussion</title>
76+
<para>The <tag class="pi">dbhtml</tag> processing instruction should be
77+
inserted after the start tag of the component.
78+
Consider the following structure with such PIs:
79+
</para>
80+
<programlisting language="xml">&lt;book version="5.0" xml:id="book"
81+
xmlns="http://docbook.org/ns/docbook" xml:lang="en">
82+
&lt;?dbhtml dir="book"?>
83+
&lt;title>Chunking Test&lt;/title>
84+
&lt;preface xml:id="preface">
85+
&lt;?dbhtml dir="pre/"?>
86+
&lt;!-- ... -->
87+
&lt;/preface>
88+
&lt;chapter xml:id="intro">
89+
&lt;?dbhtml dir="intro" filename="index.html"?>
90+
&lt;!-- ... -->
91+
&lt;/chapter>
92+
&lt;appendix xml:id="app.overview">
93+
&lt;?dbhtml dir="app" filename="index.html"?>
94+
&lt;!-- ... -->
95+
&lt;/appendix>
96+
&lt;/book></programlisting>
97+
<para>When you transform it to HTML with the <filename>chunk.xsl</filename>
98+
stylesheet, you will get the following directory structure:</para>
99+
<screen>book/
100+
├── app/
101+
│   ├── ...
102+
│   └── index.html
103+
├── index.html
104+
├── intro/
105+
│   ├── ...
106+
│   └── index.html
107+
└── pre/
108+
   ├── ...
109+
└── pr01.html</screen>
110+
<para>You can combine other chunking parameters as described
111+
in <xref linkend="dbc.html.chunk"/>.</para>
112+
</section>
113+
<section role="seealso">
114+
<title>See Also</title>
115+
<itemizedlist>
116+
<listitem>
117+
<para><link xlink:href="http://www.sagehill.net/docbookxsl/Chunking.html"/></para>
118+
</listitem>
119+
<listitem>
120+
<para><link xlink:href="http://docbook.sf.net/release/xsl/current/doc/pi/dbhtml_dir.html"/></para>
121+
</listitem>
122+
<listitem>
123+
<para><link xlink:href="http://docbook.sf.net/release/xsl/current/doc/pi/dbhtml_filename.html"/></para>
124+
</listitem>
125+
</itemizedlist>
126+
</section>
127+
</section>

0 commit comments

Comments
 (0)