LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

Note: absolute and relative URIs are accepted for the on-line 

transformation tool.
This commit is contained in:
emmajane 2003-12-07 21:15:32 +00:00
parent 20c2c7e128
commit 6368b451af
1 changed files with 379 additions and 388 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

767
LDP/guide/docbook/LDP-Author-Guide/tools-transform.xml
View File

@ -17,407 +17,393 @@
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.
</para>
<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
setup 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. [Editor's note: Dare
I say it's virtually a requirement for any sane Editor?]
transformed into a beautiful (and legible)
HTML document. External files are supported. You may use
either absolute or relative URIs.
</para>
<para>
There are currently two ways to transform your
document: Document Style and Semantics
Specification Language (DSSSL); and XML Style sheets
(XSLT) [TODO: check this expansion]. Although the LDP web site uses DSSSL to
convert documents you can use XSLT if you want.
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 setup 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. [Editor's note: Dare I say it's
virtually a requirement for any sane Editor?]
</para>
<para>
There are currently two ways to transform
your document: Document Style and Semantics
Specification Language (DSSSL); and XML
Style sheets (XSLT) [TODO: check this
expansion]. Although the LDP web site uses
DSSSL to convert documents you can use XSLT
if you want.
</para>
<section id="dtd">
<title>DocBook DTD</title>
<para>
<indexterm><primary>DocBook DTD</primary></indexterm>
The DocBook DTD defines the structure of a DocBook
<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
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).
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><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.
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:
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/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>
</para>
<warning><para>
Please feel free to look at the DTD files, but do NOT edit
them.
Please feel free to look at the DTD files,
but do NOT edit them.
</para></warning>
</section>
<section id="dsssl">
<title>DSSSL</title>
<para>
There are three basic requirements to transform a
document using DSSSL:
</para>
<itemizedlist>
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).
The Document Style and Semantics
Specification Language files
(these are plain text files).
<xref linkend="dsssl" />
</para></listitem>
<listitem><para>
The Document Type Definition file which matches
the DOCTYPE of your document (this is a plain
text file).
</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>
</para></listitem> <listitem><para>
A processor to do the actual work.
<xref linkend="jade" />
</para></listitem>
</itemizedlist>
<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>
</itemizedlist> <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>
<section id="nwdsssl">
<title>Norman Walsh DSSSL</title>
<para><ulink
url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink></para>
<para>The
<indexterm><primary>DSSSL</primary></indexterm>
Document Style Semantics and Specification Language
tells Jade (see <xref linkend="jade"/>) how to render
<title>Norman Walsh DSSSL</title> <para><ulink
url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink></para>
<para>The
<indexterm><primary>DSSSL</primary></indexterm>
Document Style Semantics and Specification Language tells
Jade (see <xref linkend="jade"/>) how to render
a DocBook document into print or on-line
form. The DSSSL is what converts a
form. The DSSSL is what converts a
<sgmltag>title</sgmltag> tag into an
&lt;h1&gt; 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>
&lt;h1&gt; 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>
</section>
<section id="ldpdsssl">
<title>LDP DSSSL</title>
<para><ulink
url="http://www.tldp.org/authors/tools/ldp.dsl">http://www.tldp.org/authors/tools/ldp.dsl</ulink></para>
<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>
<title>LDP DSSSL</title> <para><ulink
url="http://www.tldp.org/authors/tools/ldp.dsl">http://www.tldp.org/authors/tools/ldp.dsl</ulink></para>
<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>
</section>
<!-- duplicated from elsewhere in the guide -->
&ldp-dsssl;
<section id="processors">
<title>DSSSL Processors</title>
<!-- duplicated from elsewhere in the guide --> &ldp-dsssl;
<section id="processors"> <title>DSSSL Processors</title>
<section id="jade">
<title>Jade</title>
<para>
<indexterm><primary>jade</primary></indexterm>
There are two versions of the Jade processor: the
<title>Jade</title> <para>
<indexterm><primary>jade</primary></indexterm> There are
two versions of the Jade processor: the
original version by James Clark; and an open-source
version of approximately the same program.
You only need one
of these programs. It should be installed
<emphasis>after</emphasis> the DTD and DSSSL have
been <quote>installed.</quote>
</para>
version of approximately the same program.
You only need one of these programs. It should
be installed <emphasis>after</emphasis> the DTD
and DSSSL have been <quote>installed.</quote>
</para>
<section>
<title>Jade</title>
<para><ulink
url="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz</ulink></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>
<section id="usingjade">
<title>Using Jade</title>
<para>This is the quick and dirty way that should work for all
distributions, no matter what one you are using.
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Create a base directory to store everything such as
<filename moreinfo="none"
class="directory">/usr/local/sgml/</filename>. We'll call
this <envar>$_toolroot</envar> from here on.</para>
</listitem>
<listitem>
<para>Install Jade, DocBook DTD, and DSSSL such that the
base of each is under <envar>$_toolroot</envar>, creating:
</para>
<itemizedlist>
<listitem>
<para><filename class="directory">$_toolroot/jade-1.2.1</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dtd</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dsssl</filename>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>You'll need to set the
<envar>SGML_CATALOG_FILES</envar> environment variable to
the catalogs that you have under<filename moreinfo="none"
class="directory">$_toolroot</filename>. You can do this
with the command:
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command moreinfo="none">export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
<title>Jade</title> <para><ulink
url="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz</ulink></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> <section id="usingjade">
<title>Using Jade</title>
<para>This is the quick and dirty way that should work
for all
distributions, no matter what one you are using.
</para> <orderedlist inheritnum="ignore"
continuation="restarts"> <listitem>
<para>Create a base directory to store
everything such as <filename moreinfo="none"
class="directory">/usr/local/sgml/</filename>. We'll
call this <envar>$_toolroot</envar> from here
on.</para>
</listitem> <listitem>
<para>Install Jade, DocBook DTD, and DSSSL such that
the base of each is under <envar>$_toolroot</envar>,
creating: </para> <itemizedlist>
<listitem>
<para><filename
class="directory">$_toolroot/jade-1.2.1</filename>
</para>
</listitem> <listitem>
<para><filename
class="directory">$_toolroot/dtd</filename> </para>
</listitem> <listitem>
<para><filename
class="directory">$_toolroot/dsssl</filename>
</para>
</listitem>
</itemizedlist>
</listitem> <listitem>
<para>You'll need to set the
<envar>SGML_CATALOG_FILES</envar>
environment variable to the catalogs that
you have under<filename moreinfo="none"
class="directory">$_toolroot</filename>. You can do
this with the command: <screen format="linespecific">
<prompt moreinfo="none">bash$</prompt>
<command moreinfo="none">export
SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog</command>
</screen>
</para>
</listitem>
<listitem>
<para>Now you can start using Jade. To create individual
HTML files: </para>
<screen format="linespecific">
<command moreinfo="none">$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \
-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml</command>
</screen>
</listitem>
<listitem>
<para>To create one large HTML file, add <emphasis>-V
nochunks</emphasis> to the jade command.</para>
</listitem>
</orderedlist>
</section>
<section id="jadexml">
<title>Jade in XML mode</title>
<para>
Once configured for XML, jade and openjade will work
the same way as for SGML DocBook.
</para>
<para>
After extracting the XML DTD, you will want to make
a symlink from the docbook.cat file to "catalog", the
default filename for jade/openjade catalogs. Replace
$_xml_root with the location of your XML DTD.
</para>
<informalexample>
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command>cd $_xml_root</command>
<prompt moreinfo="none">bash$</prompt> <command>ln -s docbook.cat catalog</command>
<prompt moreinfo="none">bash$</prompt> <command>export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\
$_toolroot/dtd/docbook/catalog</command> <co id="export"/>
<prompt moreinfo="none">bash$</prompt> <command>jade -t sgml -i html -d <replaceable>style</replaceable> $_jade_path/pubtext/xml.dcl foo.xml</command> <co id="jadexmlcmd"/>
</screen>
<calloutlist>
<callout arearefs="export">
<para>
You'll need the catalogs for XML, the DSSSL, and DocBook,
respectively. $_toolroot was defined above.
</para>
</callout>
<callout arearefs="jadexmlcmd">
<para>
Replace <replaceable>style</replaceable> with the DSSSL
(ldp.dsl) you wish to use. The pointer to xml.dcl is
required for jade to work, and it has to be listed
immediately before the pointer to your XML document.
This file may be in a different directory.
Check your distribution.
</para>
<para>
You may get the following warnings when processing XML
documents. They don't impact the output, and the cause
is being looked into.
</para>
<screen>
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name
</screen>
</callout>
</calloutlist>
</informalexample>
<para>
If you want to convert your existing SGML DocBook into
XML docbook, use this as your declaration (the lines at the
very start of your document).
</para>
<screen>
&lt;?xml version='1.0' encoding='ISO-8859-1'?&gt;
&lt;!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'&gt;
</screen>
<para>
If you have followed LDP guidelines, there should be no
other changes required to your document. Note that there
are changes between DocBook 3.x and 4.x that you may
also have to take into account. You can get more information
at this in <xref linkend="differences3040"/>.
</para>
</section>
</screen> </para>
</listitem> <listitem>
<para>Now you can start using Jade. To
create individual HTML files: </para> <screen
format="linespecific">
<command moreinfo="none">$_toolroot/jade-1.2.1/jade/jade -t
sgml -i html \ -d $_toolroot/dsssl/docbook/html/docbook.dsl
howto.sgml</command>
</screen>
</listitem> <listitem>
<para>To create one large HTML file, add <emphasis>-V
nochunks</emphasis> to the jade command.</para>
</listitem>
</orderedlist>
</section> <section id="jadexml">
<title>Jade in XML mode</title> <para>
Once configured for XML, jade and openjade will work
the same way as for SGML DocBook.
</para> <para>
After extracting the XML DTD, you will want to make
a symlink from the docbook.cat file to "catalog",
the default filename for jade/openjade catalogs.
Replace $_xml_root with the location of your XML DTD.
</para> <informalexample>
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command>cd
$_xml_root</command> <prompt moreinfo="none">bash$</prompt>
<command>ln -s docbook.cat catalog</command>
<prompt moreinfo="none">bash$</prompt> <command>export
SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\
$_toolroot/dtd/docbook/catalog</command> <co id="export"/> <prompt
moreinfo="none">bash$</prompt> <command>jade -t sgml -i html
-d <replaceable>style</replaceable> $_jade_path/pubtext/xml.dcl
foo.xml</command> <co id="jadexmlcmd"/>
</screen> <calloutlist> <callout arearefs="export">
<para>
You'll need the catalogs for XML, the DSSSL, and
DocBook, respectively. $_toolroot was defined above.
</para>
</callout> <callout arearefs="jadexmlcmd">
<para>
Replace <replaceable>style</replaceable> with the
DSSSL (ldp.dsl) you wish to use. The pointer to
xml.dcl is required for jade to work, and it has to
be listed immediately before the pointer to your XML
document. This file may be in a different directory.
Check your distribution.
</para> <para>
You may get the following warnings when processing
XML documents. They don't impact the output,
and the cause is being looked into.
</para> <screen>
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:119:18:E: "X0176" is not
a function name &lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:120:17:E:
"X0178" is not a function name
</screen>
</callout> </calloutlist>
</informalexample> <para>
If you want to convert your existing SGML DocBook into
XML docbook, use this as your declaration (the lines
at the very start of your document).
</para> <screen>
&lt;?xml version='1.0' encoding='ISO-8859-1'?&gt; &lt;!DOCTYPE
article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'&gt;
</screen> <para>
If you have followed LDP guidelines, there should be
no other changes required to your document. Note that
there are changes between DocBook 3.x and 4.x that you
may also have to take into account. You can get more
information at this in <xref linkend="differences3040"/>.
</para>
</section>
</section>
<section id="openjade">
<title>OpenJade</title>
<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>
<title>OpenJade</title> <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>
</section>
</section>
<section id="jadewrappers">
<title>Jade wrappers</title>
<para>These tools are optional and may be installed after Jade,
the DSSSL, and DTD have been installed.</para>
<title>Jade wrappers</title> <para>These tools are optional
and may be installed after Jade, the DSSSL, and DTD have
been installed.</para>
<section id="sgmltools-lite">
<title>sgmltools-lite</title>
<para><ulink
url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink></para>
<para>This is the successor to the sgmltools project, which
has been officially disbanded for over a year. Since then,
Cees de Groot has created a slightly different project, which
acts as a wrapper to the jade SGML processor. It hides much of
the ugliness of the syntax. This author was able to install the
old sgmltools package followed by the sgmltools-lite and could
format this document quite easily. There's even a man page for
sgmltools showing syntax.</para>
<title>sgmltools-lite</title> <para><ulink
url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink></para>
<para>This is the successor to the sgmltools project, which
has been officially disbanded for over a year. Since then,
Cees de Groot has created a slightly different project,
which acts as a wrapper to the jade SGML processor. It
hides much of the ugliness of the syntax. This author
was able to install the old sgmltools package followed by
the sgmltools-lite and could format this document quite
easily. There's even a man page for sgmltools showing
syntax.</para>
</section>
<section id="cygnus">
<title>Cygnus DocBook Tools</title>
<para>May be Red Hat specific - <ulink
url="http://www.redhat.com/">http://www.redhat.com/</ulink></para>
<para>
<indexterm><primary>Cygnus Tools</primary></indexterm>
Red Hat distributes three packages, starting with the
6.2 release, that include DocBook support and some tools. The
tools are easily installed, allowing you to focus more on
writing than wrestling with the tools. TeTex, Jade, and
JadeTeX must be installed first. All three of these packages
are available on the installation CD.
</para>
<section id="usingcygnus">
<title>Using the Cygnus Tools</title>
<para> These tools are provided with Red Hat 6.2. Make sure
the following packages are installed: </para>
<itemizedlist>
<listitem><para> sgml-common-0.1-8.noarch </para></listitem>
<listitem><para> docbook-3.1-4.noarch </para></listitem>
<listitem><para> stylesheets-1.54.13rh-1.noarch </para></listitem>
</itemizedlist>
<para> Red Hat has the latest version on their web site:
<ulink
url="http://www.redhat.com/support/errata/RHBA-2000022-01.html">http://www.redhat.com/support/errata/RHBA-2000022-01.html</ulink>.</para>
<para>Download/get/sneaker-net the RPMs to your machine and
install in the usual manner (become root, then <command
moreinfo="none">rpm -Uvh filename</command>). Once the RPMs
are installed, you can use the following commands to render
DocBook: </para>
<screen>
<prompt>bash$</prompt> <command>db2html</command> <option>filename</option>
</screen>
<para> Renders DocBook into HTML. A subdirectory with the
filename (minus the .sgml extension) is created and the HTML
files are placed there. </para>
<screen>
<prompt>bash$</prompt> <command>db2pdf</command> <option>filename</option>
</screen>
<para>Renders DocBook into a PDF file. Note that there is currently a
problem with db2pdf, and pd2ps caused by JadeTeX. This has been
<ulink url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670">
registered as a bug with RedHat</ulink>.</para>
</section> <!-- cygnus -->
<title>Cygnus DocBook Tools</title>
<para>May be Red Hat specific - <ulink
url="http://www.redhat.com/">http://www.redhat.com/</ulink></para>
<para>
<indexterm><primary>Cygnus Tools</primary></indexterm>
Red Hat distributes three packages, starting with the 6.2
release, that include DocBook support and some tools. The
tools are easily installed, allowing you to focus more
on writing than wrestling with the tools. TeTex, Jade,
and JadeTeX must be installed first. All three of these
packages are available on the installation CD.
</para> <section id="usingcygnus">
<title>Using the Cygnus Tools</title> <para> These tools
are provided with Red Hat 6.2. Make sure the following
packages are installed: </para> <itemizedlist>
<listitem><para> sgml-common-0.1-8.noarch
</para></listitem> <listitem><para>
docbook-3.1-4.noarch </para></listitem> <listitem><para>
stylesheets-1.54.13rh-1.noarch </para></listitem>
</itemizedlist> <para> Red Hat has the latest version on
their web site: <ulink
url="http://www.redhat.com/support/errata/RHBA-2000022-01.html">http://www.redhat.com/support/errata/RHBA-2000022-01.html</ulink>.</para>
<para>Download/get/sneaker-net the RPMs to your machine and
install in the usual manner (become root, then <command
moreinfo="none">rpm -Uvh filename</command>). Once the
RPMs are installed, you can use the following commands
to render DocBook: </para> <screen>
<prompt>bash$</prompt> <command>db2html</command>
<option>filename</option> </screen>
<para> Renders DocBook into HTML. A subdirectory with
the filename (minus the .sgml extension) is created and
the HTML files are placed there. </para> <screen>
<prompt>bash$</prompt> <command>db2pdf</command>
<option>filename</option> </screen>
<para>Renders DocBook into a PDF file. Note
that there is currently a problem with db2pdf,
and pd2ps caused by JadeTeX. This has been <ulink
url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670">
registered as a bug with RedHat</ulink>.</para>
</section> <!-- cygnus -->
</section> <!-- jadewrappers -->
</section> <!-- jade -->
</section> <!-- dsssl -->
</section> <!-- jade --> </section> <!-- dsssl -->
<section id="libxslt">
<title>libxslt</title>
<para>There are alternatives to DSSSL and Jade/OpenJade.</para>
<!-- moved from another part of the guide -->
&ldp-xsl;
<section id="libxslt"> <title>libxslt</title> <para>There
are alternatives to DSSSL and Jade/OpenJade.</para>
<!-- moved from another part of the guide --> &ldp-xsl;
</section>
</section> <!-- processors -->
<section id="tools-compile">
<title>Compiling the sources</title>
<indexterm>
<primary>tools</primary>
<secondary>compiling the sources</secondary>
<secondary>compiling the sources</secondary>
</indexterm>
<para>The <command>compiles-sgml</command> script is a set of grouped
commands. As parameters, use the
<glossterm><acronym>SGML</acronym></glossterm> file and the output
format you want.
</para>
<para>The <command>compiles-sgml</command> script is a set
of grouped
commands. As parameters, use the
<glossterm><acronym>SGML</acronym></glossterm> file and
the output format you want.
</para>
<para>The script included below supports the following formats:
<glossterm><acronym>XML</acronym></glossterm>,
<glossterm><acronym>HTML</acronym></glossterm>, TeX,
<glossterm><acronym>RTF</acronym></glossterm>,
<glossterm>PS</glossterm>, <glossterm>DVI</glossterm> and mirrored PS,
ideal for the creation of photo lithographs.</para>
<para>The script included below supports the following
formats: <glossterm><acronym>XML</acronym></glossterm>,
<glossterm><acronym>HTML</acronym></glossterm>,
TeX, <glossterm><acronym>RTF</acronym></glossterm>,
<glossterm>PS</glossterm>, <glossterm>DVI</glossterm>
and mirrored PS, ideal for the creation of photo
lithographs.</para>
<para>The generation of the index is made automatically by the script
<filename>collateindex.pl</filename><footnote>
<para>More information about indexes are available at <ulink
url="http://nwalsh.com/docbook/dsssl/doc/indexing.html">the page about
index of Norman Walsh</ulink>.</para> </footnote>, which should be
installed in your system. </para>
<para>The generation of the index is made automatically by
the script <filename>collateindex.pl</filename><footnote>
<para>More information about indexes are available
at <ulink
url="http://nwalsh.com/docbook/dsssl/doc/indexing.html">the
page about index of Norman Walsh</ulink>.</para> </footnote>,
which should be installed in your system. </para>
<para>Besides the commands below, which generate the outputs in different
formats, there are other tools from <trademark>Cygnus</trademark> for making
the direct conversion. The tools can be obtained from <ulink
url="http://sourceware.cygnus.com/docbook-tools/">Cygnus</ulink>.</para>
<para>Besides the commands below, which generate the
outputs in different formats, there are other tools from
<trademark>Cygnus</trademark> for making the direct
conversion. The tools can be obtained from <ulink
url="http://sourceware.cygnus.com/docbook-tools/">Cygnus</ulink>.</para>
<para>You can <ulink
url="compiles-sgml">download the compile script</ulink> as well
@ -425,14 +411,14 @@ $_toolroot/dtd/docbook/catalog</command> <co id="export"/>
url="collateindex.pl"><filename>collateindex.pl</filename></ulink>.</para>
<indexterm>
<primary>tools</primary>
<secondary>compiling sources</secondary>
<tertiary>compile-sgml</tertiary>
<primary>tools</primary> <secondary>compiling
sources</secondary> <tertiary>compile-sgml</tertiary>
</indexterm>
<para>A similar script can be modified by creating a
<filename>Makefile</filename> and optimizing some functions.</para>
<para>A similar script can be modified by creating
a <filename>Makefile</filename> and optimizing some
functions.</para>
</section>
@ -440,22 +426,23 @@ $_toolroot/dtd/docbook/catalog</command> <co id="export"/>
<title>Inserting a summary on the initial articles page</title>
<indexterm>
<primary>tools</primary>
<secondary>articles</secondary>
<tertiary>summary</tertiary>
<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>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>
<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>
<title>Style sheet to insert summaries in articles</title>
<programlisting>
&dsl-example;
</programlisting>
</programlisting>
</example>
</section>
@ -464,65 +451,69 @@ $_toolroot/dtd/docbook/catalog</command> <co id="export"/>
<title>Inserting indexes automatically</title>
<indexterm>
<primary>tools</primary>
<secondary>indexes</secondary>
<tertiary>automatic generation</tertiary>
<seealso>edition, index</seealso>
<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 automatically.
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 automatically.
</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>$</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>$</prompt> <command>perl</command> <option>collateindex.pl -o index.sgml HTML.index</option></screen>
</informalexample>
</listitem>
<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>$</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>$</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's necessary to define an
<glossterm>external entity</glossterm> by calling the file
<filename>index.sgml</filename>.</para>
<para>For the above example to work, it's 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" [
<title>Configuring an external entity to include the
index</title>
<programlisting>
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD
DocBook V3.1//EN" [
&lt;!-- Insertion of the index --&gt;
&lt;!entity index SYSTEM "index.sgml"&gt;
]</sgmltag>
</programlisting>
&lt;!-- Insertion of the index --&gt; &lt;!entity index SYSTEM
"index.sgml"&gt; ]</sgmltag>
</programlisting>
</example>
<para>See also <xref linkend="encoding-index"/> for information on how to
insert necessary information on the text.</para>
<para>See also <xref linkend="encoding-index"/> for information
on how to
insert necessary information on the text.</para>
<note>
<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>
<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>