mirror of https://github.com/tLDP/LDP
627 lines
24 KiB
XML
627 lines
24 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
-->
|
|
<section id="transformations">
|
|
<title>Transformations</title>
|
|
<warning><title>TLDP will convert your document</title>
|
|
<para>This section is about how to transform documents
|
|
from DocBook to other formats. If you do not need
|
|
to transform documents for your own web site, or to proof read the content, please <emphasis>skip this section</emphasis>.</para>
|
|
|
|
<para>
|
|
If you would like to transform your documents for
|
|
proofreading purposes, please use the <ulink
|
|
url="http://www.xml-dev.com/blog/xml2html.php">XML to HTML on-line
|
|
converter</ulink>. You will need to upload your XML file(s)
|
|
to a web site. Then simply drop the URL into the form and
|
|
click the submit button. Your document will be magically
|
|
transformed into a beautiful (and legible)
|
|
HTML document. External files are supported. You may use
|
|
either absolute or relative URIs.
|
|
</para>
|
|
|
|
<para>Another easy-to-use package is
|
|
<application>xmlto</application>. It is a front-end for
|
|
<application>xsltproc</application>. It is available as a
|
|
RedHat, Debian (etc) package or can be downloaded from <ulink
|
|
url="http://cyberelk.net/tim/xmlto/" />. You can use it to convert
|
|
documents with:</para>
|
|
|
|
<programlisting>
|
|
<prompt>bash$ </prompt><userinput>xmlto html <filename>mydoc.xml</filename></userinput>
|
|
<prompt>bash$ </prompt><userinput>xmlto txt <filename>mydoc.xml</filename></userinput>
|
|
</programlisting>
|
|
|
|
<para>
|
|
You do not ever need to transform documents
|
|
before submitting to the LDP. The LDP
|
|
volunteers have a system which transforms
|
|
your DocBook file into HTML, PDF and plain
|
|
text formats. There, you've been warned.
|
|
</para></warning>
|
|
|
|
<para>
|
|
Still here? Great! Transformations are
|
|
a pretty basic requirement to get what
|
|
you've written from a messy tag-soup into
|
|
something that can be read. This section
|
|
will help you get your system set up and
|
|
ready to transform your latest document
|
|
into other formats. This is very useful
|
|
is you want to <emphasis>see</emphasis>
|
|
your document before you release it to
|
|
the world.
|
|
</para>
|
|
|
|
<para>
|
|
There are currently two ways to transform
|
|
your document: Document Style Semantics and
|
|
Specification Language (DSSSL); and XML
|
|
Style sheets (XSLT). Although the LDP web site uses
|
|
DSSSL to convert documents you may use XSLT
|
|
if you want. You only need to choose <emphasis>one</emphasis> of these
|
|
methods. For more information about DSSSL read: <xref linkend="dsssl"
|
|
/>, for more information about XSLT read: <xref linkend="xsl" />.
|
|
</para>
|
|
|
|
<section id="dsssl">
|
|
<title>DSSSL</title>
|
|
<para>
|
|
There are three basic requirements to transform a document using DSSSL:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
The Document Style and Semantics Specification Language files
|
|
(these are plain text files). <xref linkend="dsssl-files" />
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>
|
|
The Document Type Definition file
|
|
which matches the DOCTYPE of your
|
|
document (this is a plain text file).
|
|
<xref linkend="dtd" />
|
|
</para></listitem>
|
|
<listitem><para>
|
|
A processor to do the actual work. <xref linkend="dsssl-processors" />
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="dsssl-files">
|
|
<title>The Style Sheets</title>
|
|
<para>There are two versions of the
|
|
Document Style Semantics and Specification Language
|
|
used by the LDP to transform documents from your
|
|
raw DocBook files into other formats (which are then
|
|
published on the Web). The LDP version of the style
|
|
sheets requires the Norman Walsh version--which
|
|
basically means if you're using DSSSL the Norman
|
|
Walsh version can be considered a requirement for
|
|
system setup.</para>
|
|
|
|
<formalpara>
|
|
<title>Norman Walsh DSSSL <ulink
|
|
url="http://docbook.sourceforge.net/projects/dsssl/" /></title>
|
|
<para>The
|
|
<indexterm><primary>DSSSL</primary></indexterm>
|
|
Document Style Semantics and Specification Language tells
|
|
Jade (see <xref linkend="dsssl-processors"/>) how to render
|
|
a DocBook document into print or on-line
|
|
form. The DSSSL is what converts a
|
|
<sgmltag>title</sgmltag> tag into an
|
|
<h1> HTML tag, or to 14 point bold Times Roman for
|
|
RTF, for example. Documentation for DSSSL is located at
|
|
the same site. Note that modifying the DSSSL doesn't modify
|
|
DocBook itself. It merely changes the way the rendered text
|
|
looks. The LDP uses a modified DSSSL (see below).</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>LDP DSSSL <ulink
|
|
url="http://www.tldp.org/authors/tools/ldp.dsl">http://www.tldp.org/authors/tools/ldp.dsl</ulink></title>
|
|
<para>The LDP DSSSL requires the Norman Walsh version (see
|
|
above) but is a slightly modified DSSSL to provide things
|
|
like a table of contents.</para>
|
|
</formalpara>
|
|
|
|
<example id="ex-dsssl">
|
|
<title><quote>Installing</quote> DSSSL style sheets</title>
|
|
<para>Create a base directory to store everything such as <filename moreinfo="none"
|
|
class="directory">/usr/share/sgml/</filename>. Copy the DSSSL
|
|
style sheets into a sub-directory named
|
|
<filename class="directory">dsssl</filename>.
|
|
</para>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dsssl-processors">
|
|
<title>DSSSL Processors</title>
|
|
<para>
|
|
<indexterm><primary>jade</primary></indexterm>
|
|
There are two versions of the <application>Jade</application> processor: the
|
|
original version by James Clark; and an open-source
|
|
version of approximately the same program, <application>OpenJade</application>.
|
|
You only need <emphasis>one</emphasis> of these programs. It should
|
|
be installed <emphasis>after</emphasis> the DTD
|
|
and DSSSL have been <quote>installed.</quote>
|
|
</para>
|
|
|
|
<variablelist>
|
|
<title>DSSSL Transformation Tools</title>
|
|
<varlistentry>
|
|
<term>Jade</term>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="ftp://ftp.jclark.com/pub/jade/" /></para>
|
|
<para>Currently, the latest version of the package is <filename>jade-1.2.1.tar.gz</filename>.</para>
|
|
<para>Jade is the front-end processor for SGML and
|
|
XML. It uses the DSSSL and DocBook DTD to perform the
|
|
verification and rendering from SGML and XML into the target
|
|
format.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>OpenJade</term>
|
|
<listitem>
|
|
<para><ulink
|
|
url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink></para>
|
|
<para>An extension of Jade written by the DSSSL
|
|
community. Some applications require jade, but are being
|
|
updated to support either software package.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="dsssl-setup">
|
|
<title>System Setup for DSSSL Transformations</title>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Tell your system where to find the SGML_CATALOG_FILES (yes, even if you
|
|
are using XML). You can find an example of how to do this in <xref
|
|
linkend="ex-catalog-files" />.
|
|
<!--
|
|
export
|
|
SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
|
|
$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog</command>
|
|
-->
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Download the DSSSL and DTD files and copy them into your working
|
|
directory. You can find an example of how to do this in <xref
|
|
linkend="ex-dsssl" /> and <xref linkend="ex-dtd" />.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="usingjade">
|
|
<title>Transformations with DSSSL</title>
|
|
<para>
|
|
Once your system is configured (see the previous section), you should
|
|
be able to start using <application>jade</application> to transform
|
|
your files from XML to XHTML.
|
|
</para>
|
|
|
|
<!--
|
|
<para>To do this you must add the following lines to the file
|
|
<filename>/etc/sgml/catalog</filename>, by bringing it up under
|
|
your favorite text editor:</para>
|
|
|
|
<informalexample>
|
|
<screen format="linespecific">
|
|
PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"
|
|
/usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl<co id="html"/>
|
|
|
|
PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
|
|
/usr/lib/sgml/stylesheets/nwalsh-modular/print/docbook.dsl<co
|
|
id="print"/>
|
|
|
|
PUBLIC "-//Norman Walsh//DOCUMENT DSSSL Library//EN"
|
|
/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl
|
|
|
|
PUBLIC "-//Norman Walsh//DOCUMENT DSSSL Library V2//EN"
|
|
/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl
|
|
</screen>
|
|
</informalexample>
|
|
-->
|
|
|
|
<para>
|
|
To create individual HTML files, point <application>jade</application>
|
|
at the correct DSL (style sheet). The following example uses the LDP
|
|
style sheet.
|
|
</para>
|
|
<screen format="linespecific">
|
|
<prompt>bash$ </prompt><command>jade -t xml -i html \
|
|
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
|
|
<replaceable>HOWTO.xml</replaceable></command>
|
|
</screen>
|
|
|
|
<para>
|
|
If you would like to produce a single-file HTML page, add the
|
|
<parameter>-V nochunks</parameter> parameter. You can specify the
|
|
name of the final HTML file by appending the command with <parameter>
|
|
> <replaceable>output.html</replaceable></parameter>.
|
|
</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>bash$ </prompt><command>jade -t xml -i html -V nochunks \
|
|
-d /usr/local/sgml/dsssl/stylesheets/ldp.dsl#html \
|
|
<replaceable>HOWTO.sgml</replaceable> > output.html</command>
|
|
</screen>
|
|
|
|
<note id="dcl-errors">
|
|
<title><emphasis>Not a function name</emphasis> errors</title>
|
|
<para>
|
|
If you get an error about <quote>is not a function name</quote>, you
|
|
will need to add a pointer to <filename>xml.dcl</filename>. It has
|
|
to be listed immediately before the pointer to your XML
|
|
document. Try one of the following locations:
|
|
<filename>/usr/lib/sgml/declaration/xml.dcl</filename>, or
|
|
<filename>/usr/share/sgml/declaration/xml.dcl</filename>. Use
|
|
<application>locate</application> to find the file if it is not in
|
|
either of those two places. The modified command would be as
|
|
follows:
|
|
</para>
|
|
<screen>
|
|
<prompt>bash$ </prompt><command>jade -t xml -i html \
|
|
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
|
|
/usr/lib/sgml/declaration/xml.dcl <replaceable>HOWTO.xml</replaceable></command>
|
|
</screen>
|
|
</note>
|
|
|
|
<para>
|
|
If you would like to create print-friendly files instead of HTML files,
|
|
simply change the style sheet that you are using. In the file name
|
|
above, note <quote>html/ldp.dsl</quote> at the end. Change this to
|
|
<quote>print/docbook.dsl</quote>, or if you want XHTML output, instead
|
|
of HTML, change the file name to <quote>xhtml/docbook.dsl</quote>.
|
|
</para>
|
|
|
|
<section id="dsssl-css">
|
|
<title>Changing CSS Files</title>
|
|
<para>If you want your HTML files to use a specific
|
|
<acronym>CSS</acronym> stylesheet, you will need to edit
|
|
<filename>ldp.dsl</filename>. Immediately after
|
|
<literal>;; End of $verbatim-display$ redefinition</literal>
|
|
add the following lines:</para>
|
|
|
|
<screen format="linespecific">
|
|
(define %stylesheet-type%
|
|
;; The type of the stylesheet to use
|
|
"text/css")
|
|
|
|
(define %stylesheet%
|
|
;; Name of the css stylesheet to use, use value #f if you don't want to
|
|
;; use css stylesheets
|
|
"base.css")
|
|
</screen>
|
|
|
|
<para>
|
|
Replace <filename>base.css</filename> with the name of the
|
|
<acronym>CSS</acronym> file you would like to use.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<!--Emma: I found that all these thingies you were talking about were way too difficult, no wonder people are objecting. I've never bothered setting any variable at all, for instance, using the docbook-utils. I took the liberty of adding a section about them. -->
|
|
<section id="docbook-utils"><title>The docbook-utils Package</title>
|
|
<para>The <application>docbook-utils</application> provide commands like <command>db2html</command>, <command>db2pdf</command> and <command>db2ps</command>, based on the <command>jw</command> scripts, that is a front-end to <application>Jade</application>. These tools ease the everyday management of documentation and add comfortable features.</para>
|
|
<para>The package, originally created by RedHat and available from <ulink url="http://sources.redhat.com/docbook-tools/" /> can be installed on most systems.</para>
|
|
|
|
<example id="ex-htmloutput">
|
|
<title>Example creating HTML output</title>
|
|
<para>After validating your document, simply issue the command
|
|
<command>db2html <filename>mydoc.xml</filename></command> to create (a)
|
|
HTML file(s). You can also use the
|
|
<application>docbook-utils</application> as validation tools. Remember: when errors occur, always start by solving only the first problem. The rest of the problems may be fixed when you fix the first error.</para>
|
|
<para>
|
|
If you get errors about a function name, please read <xref linkend="dcl-errors" />.
|
|
</para>
|
|
</example>
|
|
|
|
<section id="stylesheets"><title>Using CSS and DSL for pretty output</title>
|
|
<para>You can define your own additional DSL instructions, which can
|
|
include a pointer to a personalized CSS file. Sample DSL and CSS files are
|
|
provided in <xref linkend="templates" />.</para>
|
|
|
|
<para>The sample DSL file will create a table of contents, and have all
|
|
HTML files start with the prefix <filename>intro2linux-</filename> and end
|
|
with a suffix of <filename>.html</filename>. The
|
|
<varname>%stylesheet%</varname> variable points to the CSS file which
|
|
should be called by your HTML file.</para>
|
|
|
|
<para>To use a specific DSL style sheet the following command should be
|
|
used:</para>
|
|
<cmdsynopsis><command>db2html <option>-d</option> <filename>mystyle.dsl</filename> <filename>mydoc.xml</filename></command></cmdsynopsis>
|
|
<para>You can compare the result here: <ulink url="http://tille.soti.org/training/unix/" /> is a book formatted with the standard tools; <ulink url="http://tille.soti.org/training/tldp/" /> is one using personalized DSL and CSS files. Soft tones and special effects, for instance in buttons, were used to achieve maximum effect.</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="xsl">
|
|
<title>XSL</title>
|
|
<para>
|
|
There are alternatives to DSSSL and Jade/OpenJade.</para>
|
|
|
|
<para>When working with DocBook XML, the LDP offers a series of
|
|
XSL<footnote><para>In truth, "XSL" is actually comprised of three
|
|
components: the <emphasis>XSLT</emphasis> transformation language,
|
|
the <emphasis>XPath</emphasis> expression language (used by XSLT),
|
|
and XSL Formatting Objects (FO) that are used for describing a page.
|
|
The style sheets are actually written in XSLT and generate either HTML
|
|
or (for print output) FO. The FO file is then run through a FO processor
|
|
to create the actual print (PDF or PostScript) output. See the
|
|
<ulink url="http://www.w3.org/Style/XSL/WhatIsXSL.html">W3C web
|
|
site</ulink> for more information.</para></footnote>
|
|
style sheets to process documents into HTML. These style
|
|
sheets create
|
|
output files using the XML tool set that are similar to those produced by
|
|
the SGML tools using <link linkend="dsssl">ldp.dsl</link>.
|
|
</para>
|
|
|
|
<para>The major difference between using <filename>ldp.dsl</filename>
|
|
and the XSL style sheets is the way that the generation of multiple
|
|
files is handled, such as the creation of a separate file for each chapter,
|
|
section and appendix. With the SGML tools, such as
|
|
<application>jade</application> or
|
|
<application>openjade</application>, the tool
|
|
itself was responsible for generating the separate files. Because of
|
|
this, only a single file, <filename>ldp.dsl</filename> was necessary as
|
|
a customization layer for the standard DocBook DSSSL style sheets.
|
|
</para>
|
|
<para>With the DocBook XSL style sheets, generation of multiple files is
|
|
controlled <emphasis>by the style sheet</emphasis>. If you want to
|
|
generate a single file, you call one style sheet. If you want to generate
|
|
multiple files, you call a different style sheet. For that reason the
|
|
LDP XSL style sheet distribution is comprised of four files:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><filename>tldp-html.xsl</filename> - style sheet called to generate
|
|
a <emphasis>single</emphasis> file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>tldp-html-chunk.xsl</filename><footnote><para>In XSL
|
|
terminology, the process of generating multiple files is referred to
|
|
as "chunking".</para></footnote> - style sheet called to generate
|
|
multiple files based on chapter, section and appendix elements.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>tldp-html-common.xsl</filename> - style sheet containing
|
|
the actual XSLT transformations. It is called by the other two HTML
|
|
style sheets and is <emphasis>never</emphasis> directly called.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>tldp-print.xsl</filename> - style sheet for generation of
|
|
XSL Formatting Objects for print output.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
You can find the latest copy of the files at <ulink
|
|
url="http://my.core.com/~dhorton/docbook/tldp-xsl/">http://my.core.com/~dhorton/docbook/tldp-xsl/</ulink>.
|
|
The package includes installation instructions which are duplicated
|
|
at <ulink
|
|
url="http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html"
|
|
/>. The short version of the install instructions is as follows:
|
|
Download and unzip the latest package from the web site. Take the
|
|
files from the <filename class="directory">html</filename>
|
|
directory of TLDP-XSL and put them in the
|
|
<filename class="directory">html</filename> directory of Norman Walsh's
|
|
stylesheets. Take the file from the TLDP-XSL <filename
|
|
class="directory">fo</filename> directory and put it in the Norman Walsh
|
|
<filename class="directory">fo</filename> directory.
|
|
</para>
|
|
|
|
<para>
|
|
Once you have installed these files you can use
|
|
<application>xsltproc</application> to generate HTML files from your
|
|
XML documents. To transform your XML file(s) into a single-page HTML
|
|
document use the following command:
|
|
</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>bash$</prompt> <command> xsltproc -o <replaceable>HOWTO.html</replaceable> /usr/local/sgml/stylesheets/tldp-html.xsl <replaceable>HOWTO.xml</replaceable></command>
|
|
</screen>
|
|
|
|
<para>To generate a set of linked HTML pages, with a separate page for each
|
|
<sgmltag>chapter</sgmltag>, <sgmltag>sect1</sgmltag> or
|
|
<sgmltag>appendix</sgmltag>, use the following
|
|
command:
|
|
</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>bash$ </prompt><command>xsltproc /usr/share/sgml/stylesheets/tldp-html-chunk.xsl <replaceable>HOWTO.xml</replaceable></command>
|
|
</screen>
|
|
|
|
<para>Note that you never directly call the style sheet
|
|
<filename>tldp-html-common.xsl</filename>. It is called by both of the
|
|
other two style sheets.
|
|
</para>
|
|
|
|
<section id="xsl-css">
|
|
<title>Changing CSS Files</title>
|
|
<para>If you want your HTML files to use a specific
|
|
<acronym>CSS</acronym> stylesheet, you will need to edit
|
|
<filename>tldp-html-common.xsl</filename>. Look for a line that
|
|
ressembles <literal><xsl:param name="html.stylesheet"
|
|
select="'style.css'"/></literal>.</para>
|
|
|
|
<para>
|
|
Replace <filename>style.css</filename> with the name of the
|
|
<acronym>CSS</acronym> file you would like to use.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="dtd">
|
|
<!-- not sure if this is in the right place.... -->
|
|
<title>DocBook DTD</title>
|
|
<para>
|
|
<indexterm><primary>DocBook DTD</primary></indexterm>
|
|
The DocBook DTD defines the structure of a DocBook
|
|
document. It contains rules about how the elements
|
|
may be used; and what the elements ought to be
|
|
describing. For example: it is the DocBook DTD
|
|
which states all <sgmltag>warning</sgmltag>s are to
|
|
<emphasis>warn</emphasis> the reader (this is the
|
|
definition of the element); and may not contain
|
|
plain text (this is the content model--and the
|
|
bit which forces you to wrap your warning text
|
|
in a <sgmltag>para</sgmltag> or perhaps a list).
|
|
</para>
|
|
|
|
<caution><title>Versions</title><para>
|
|
It is important that you download the
|
|
version(s) that match your document. You
|
|
may want to configure your system now to
|
|
deal with <quote>all</quote> DocBook DTDs
|
|
if you are going to be editing older LDP
|
|
documents. If you are a new author, you
|
|
only need the first one listed: XML DTD
|
|
for DocBook version 4.2.
|
|
</para></caution>
|
|
|
|
<para>The XML DTD is available from <ulink
|
|
url="http://www.oasis-open.org/docbook/xml/4.2">http://www.oasis-open.org/xml/4.2/</ulink>.
|
|
The LDP prefers this version of the DocBook DTD.
|
|
</para>
|
|
|
|
<para>
|
|
If you are going to be working with SGML
|
|
versions of DocBook you will need one
|
|
(or both) of:
|
|
<ulink
|
|
url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip</ulink>
|
|
or <ulink
|
|
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip</ulink>
|
|
</para>
|
|
|
|
<example id="ex-dtd">
|
|
<title><quote>Installing</quote> DocBook Document Type Definitions</title>
|
|
<para>Create a base directory to store everything such as <filename moreinfo="none"
|
|
class="directory">/opt/local/sgml/</filename>. Copy the DTDs
|
|
into a sub-directory named <filename class="directory">dtd</filename>.
|
|
</para>
|
|
</example>
|
|
|
|
<warning><title>Do not edit DTD files</title><para>
|
|
The DocBook standard is described in these
|
|
files. If you change these files, you are no longer working
|
|
with DocBook.
|
|
</para></warning>
|
|
</section>
|
|
|
|
<section id="doc-components">
|
|
<title>Formatting Documents</title>
|
|
<section id="toc-articles">
|
|
<title>Inserting a summary on the initial articles page</title>
|
|
|
|
<indexterm>
|
|
<primary>tools</primary> <secondary>articles</secondary>
|
|
<tertiary>summary</tertiary>
|
|
</indexterm>
|
|
|
|
<para>A feature that might be valuable in some cases is
|
|
the insertion of the summary on the initial page of an
|
|
article. DocBook articles do not include it as a standard
|
|
feature.</para>
|
|
|
|
<para>To enable this, it is necessary to modify the style
|
|
sheet file.</para>
|
|
|
|
<example>
|
|
<title>Style sheet to insert summaries in articles</title>
|
|
<programlisting>
|
|
&dsl-example;
|
|
</programlisting>
|
|
</example>
|
|
|
|
</section>
|
|
|
|
<section id="automatic-indexes">
|
|
<title>Inserting indexes automatically</title>
|
|
|
|
<indexterm>
|
|
<primary>tools</primary> <secondary>indexes</secondary>
|
|
<tertiary>automatic generation</tertiary> <seealso>edition,
|
|
index</seealso>
|
|
</indexterm>
|
|
|
|
<para>
|
|
Although DocBook has markups for the composition of
|
|
them, indexes are not generated automatically. The
|
|
<command>collateindex.pl</command> command allows indexes
|
|
to be generated from the source DocBook for inclusion into the
|
|
finished/transformed document.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Process the document with
|
|
<application>jade</application> using the style to
|
|
<glossterm><acronym>HTML</acronym></glossterm> with
|
|
the option <option>-V html-index</option>.</para>
|
|
<informalexample>
|
|
<screen>
|
|
<prompt>bash$</prompt> <command>jade</command> <option>-t sgml \
|
|
-d html/docbook.dsl -V html-index document.sgml</option>
|
|
</screen>
|
|
</informalexample>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Generate the <filename>index.sgml</filename> file with
|
|
<command>collateindex.pl</command>.
|
|
</para> <informalexample>
|
|
<screen>
|
|
<prompt>bash$ </prompt> <command>perl</command> <option>collateindex.pl \
|
|
-o index.sgml HTML.index</option>
|
|
</screen>
|
|
</informalexample>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>For the above example to work, it is necessary to define
|
|
an <glossterm>external entity</glossterm> by calling the
|
|
file <filename>index.sgml</filename>.</para>
|
|
|
|
<example id="ex-entity-external-index">
|
|
<title>Configuring an external entity to include the
|
|
index</title>
|
|
<programlisting>
|
|
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD
|
|
DocBook V3.1//EN" [
|
|
|
|
<!-- Insertion of the index --> <!entity index SYSTEM
|
|
"index.sgml"> ]</sgmltag>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>See also <xref linkend="encoding-index"/> for information
|
|
on how to
|
|
insert necessary information on the text.</para>
|
|
|
|
<note><title>Odd behavior generating indexes for print versions</title>
|
|
<para>Remember that if you're trying to get Tables of
|
|
Contents or Indexes on PS or PDF output you'll need to
|
|
run <application moreinfo="none">jadetex</application>
|
|
or <application moreinfo="none">pdfjadetex</application>
|
|
at least three times. This is required by <application
|
|
moreinfo="none">TeX</application> but not by DocBook or
|
|
related applications.</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|