1261 lines
22 KiB
HTML
1261 lines
22 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Transformations</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="LDP Author Guide"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="System Setup: Editors, Validation and
|
|
Transformations"
|
|
HREF="tools.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Validation"
|
|
HREF="tools-validate.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="DocBook DTD"
|
|
HREF="dtd.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>LDP Author Guide</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="tools-validate.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Appendix B. System Setup: Editors, Validation and
|
|
Transformations</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="dtd.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="transformations"
|
|
></A
|
|
>B.4. Transformations</H1
|
|
><DIV
|
|
CLASS="warning"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="warning"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/warning.gif"
|
|
HSPACE="5"
|
|
ALT="Warning"></TD
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="CENTER"
|
|
><B
|
|
>TLDP will convert your document</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> </TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>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 <EM
|
|
>skip this section</EM
|
|
>.</P
|
|
><P
|
|
> If you would like to transform your documents for
|
|
proofreading purposes, please use the <A
|
|
HREF="http://www.xml-dev.com/blog/xml2html.php"
|
|
TARGET="_top"
|
|
>XML to HTML on-line
|
|
converter</A
|
|
>. 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.
|
|
</P
|
|
><P
|
|
>Another easy-to-use package is
|
|
<SPAN
|
|
CLASS="application"
|
|
>xmlto</SPAN
|
|
>. It is a front-end for
|
|
<SPAN
|
|
CLASS="application"
|
|
>xsltproc</SPAN
|
|
>. It is available as a
|
|
RedHat, Debian (etc) package or can be downloaded from <A
|
|
HREF="http://cyberelk.net/tim/xmlto/"
|
|
TARGET="_top"
|
|
>http://cyberelk.net/tim/xmlto/</A
|
|
>. You can use it to convert
|
|
documents with:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash$ </TT
|
|
><TT
|
|
CLASS="userinput"
|
|
><B
|
|
>xmlto html <TT
|
|
CLASS="filename"
|
|
>mydoc.xml</TT
|
|
></B
|
|
></TT
|
|
>
|
|
<TT
|
|
CLASS="prompt"
|
|
>bash$ </TT
|
|
><TT
|
|
CLASS="userinput"
|
|
><B
|
|
>xmlto txt <TT
|
|
CLASS="filename"
|
|
>mydoc.xml</TT
|
|
></B
|
|
></TT
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> 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.
|
|
</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
> 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 <EM
|
|
>see</EM
|
|
>
|
|
your document before you release it to
|
|
the world.
|
|
</P
|
|
><P
|
|
> 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 <EM
|
|
>one</EM
|
|
> of these
|
|
methods. For more information about DSSSL read: <A
|
|
HREF="transformations.html#dsssl"
|
|
>Section B.4.1</A
|
|
>, for more information about XSLT read: <A
|
|
HREF="transformations.html#xsl"
|
|
>Section B.4.3</A
|
|
>.
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="dsssl"
|
|
></A
|
|
>B.4.1. DSSSL</H2
|
|
><P
|
|
> There are three basic requirements to transform a document using DSSSL:
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> The Document Style and Semantics Specification Language files
|
|
(these are plain text files). <A
|
|
HREF="transformations.html#dsssl-files"
|
|
>Section B.4.1.1</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> The Document Type Definition file
|
|
which matches the DOCTYPE of your
|
|
document (this is a plain text file).
|
|
<A
|
|
HREF="dtd.html"
|
|
>Section B.5</A
|
|
>
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> A processor to do the actual work. <A
|
|
HREF="transformations.html#dsssl-processors"
|
|
>Section B.4.1.2</A
|
|
>
|
|
</P
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="dsssl-files"
|
|
></A
|
|
>B.4.1.1. The Style Sheets</H3
|
|
><P
|
|
>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.</P
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>Norman Walsh DSSSL <A
|
|
HREF="http://docbook.sourceforge.net/projects/dsssl/"
|
|
TARGET="_top"
|
|
>http://docbook.sourceforge.net/projects/dsssl/</A
|
|
>. </B
|
|
>The
|
|
|
|
Document Style Semantics and Specification Language tells
|
|
Jade (see <A
|
|
HREF="transformations.html#dsssl-processors"
|
|
>Section B.4.1.2</A
|
|
>) how to render
|
|
a DocBook document into print or on-line
|
|
form. The DSSSL is what converts a
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>title</TT
|
|
> 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).</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>LDP DSSSL <A
|
|
HREF="http://www.tldp.org/authors/tools/ldp.dsl"
|
|
TARGET="_top"
|
|
>http://www.tldp.org/authors/tools/ldp.dsl</A
|
|
>. </B
|
|
>The LDP DSSSL requires the Norman Walsh version (see
|
|
above) but is a slightly modified DSSSL to provide things
|
|
like a table of contents.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="example"
|
|
><A
|
|
NAME="ex-dsssl"
|
|
></A
|
|
><P
|
|
><B
|
|
>Example B-5. <SPAN
|
|
CLASS="QUOTE"
|
|
>"Installing"</SPAN
|
|
> DSSSL style sheets</B
|
|
></P
|
|
><P
|
|
>Create a base directory to store everything such as <TT
|
|
CLASS="filename"
|
|
>/usr/share/sgml/</TT
|
|
>. Copy the DSSSL
|
|
style sheets into a sub-directory named
|
|
<TT
|
|
CLASS="filename"
|
|
>dsssl</TT
|
|
>.
|
|
</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="dsssl-processors"
|
|
></A
|
|
>B.4.1.2. DSSSL Processors</H3
|
|
><P
|
|
>
|
|
There are two versions of the <SPAN
|
|
CLASS="application"
|
|
>Jade</SPAN
|
|
> processor: the
|
|
original version by James Clark; and an open-source
|
|
version of approximately the same program, <SPAN
|
|
CLASS="application"
|
|
>OpenJade</SPAN
|
|
>.
|
|
You only need <EM
|
|
>one</EM
|
|
> of these programs. It should
|
|
be installed <EM
|
|
>after</EM
|
|
> the DTD
|
|
and DSSSL have been <SPAN
|
|
CLASS="QUOTE"
|
|
>"installed."</SPAN
|
|
>
|
|
</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><P
|
|
><B
|
|
>DSSSL Transformation Tools</B
|
|
></P
|
|
><DL
|
|
><DT
|
|
>Jade</DT
|
|
><DD
|
|
><P
|
|
> <A
|
|
HREF="ftp://ftp.jclark.com/pub/jade/"
|
|
TARGET="_top"
|
|
>ftp://ftp.jclark.com/pub/jade/</A
|
|
></P
|
|
><P
|
|
>Currently, the latest version of the package is <TT
|
|
CLASS="filename"
|
|
>jade-1.2.1.tar.gz</TT
|
|
>.</P
|
|
><P
|
|
>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.</P
|
|
></DD
|
|
><DT
|
|
>OpenJade</DT
|
|
><DD
|
|
><P
|
|
><A
|
|
HREF="http://openjade.sourceforge.net/"
|
|
TARGET="_top"
|
|
>http://openjade.sourceforge.net/</A
|
|
></P
|
|
><P
|
|
>An extension of Jade written by the DSSSL
|
|
community. Some applications require jade, but are being
|
|
updated to support either software package.</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="dsssl-setup"
|
|
></A
|
|
>B.4.1.3. System Setup for DSSSL Transformations</H3
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> 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 <A
|
|
HREF="tools-validate.html#ex-catalog-files"
|
|
>Example B-1</A
|
|
>.
|
|
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Download the DSSSL and DTD files and copy them into your working
|
|
directory. You can find an example of how to do this in <A
|
|
HREF="transformations.html#ex-dsssl"
|
|
>Example B-5</A
|
|
> and <A
|
|
HREF="dtd.html#ex-dtd"
|
|
>Example B-7</A
|
|
>.
|
|
</P
|
|
></LI
|
|
></OL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="usingjade"
|
|
></A
|
|
>B.4.1.4. Transformations with DSSSL</H3
|
|
><P
|
|
> Once your system is configured (see the previous section), you should
|
|
be able to start using <SPAN
|
|
CLASS="application"
|
|
>jade</SPAN
|
|
> to transform
|
|
your files from XML to XHTML.
|
|
</P
|
|
><P
|
|
> To create individual HTML files, point <SPAN
|
|
CLASS="application"
|
|
>jade</SPAN
|
|
>
|
|
at the correct DSL (style sheet). The following example uses the LDP
|
|
style sheet.
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash$ </TT
|
|
><B
|
|
CLASS="command"
|
|
>jade -t xml -i html \
|
|
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
|
|
<TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>HOWTO.xml</I
|
|
></TT
|
|
></B
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> If you would like to produce a single-file HTML page, add the
|
|
<TT
|
|
CLASS="parameter"
|
|
><I
|
|
>-V nochunks</I
|
|
></TT
|
|
> parameter. You can specify the
|
|
name of the final HTML file by appending the command with <TT
|
|
CLASS="parameter"
|
|
><I
|
|
> > <TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>output.html</I
|
|
></TT
|
|
></I
|
|
></TT
|
|
>.
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash$ </TT
|
|
><B
|
|
CLASS="command"
|
|
>jade -t xml -i html -V nochunks \
|
|
-d /usr/local/sgml/dsssl/stylesheets/ldp.dsl#html \
|
|
<TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>HOWTO.sgml</I
|
|
></TT
|
|
> > output.html</B
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><DIV
|
|
CLASS="note"
|
|
><A
|
|
NAME="dcl-errors"
|
|
></A
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="CENTER"
|
|
><B
|
|
><EM
|
|
>Not a function name</EM
|
|
> errors</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> </TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
> If you get an error about <SPAN
|
|
CLASS="QUOTE"
|
|
>"is not a function name"</SPAN
|
|
>, you
|
|
will need to add a pointer to <TT
|
|
CLASS="filename"
|
|
>xml.dcl</TT
|
|
>. It has
|
|
to be listed immediately before the pointer to your XML
|
|
document. Try one of the following locations:
|
|
<TT
|
|
CLASS="filename"
|
|
>/usr/lib/sgml/declaration/xml.dcl</TT
|
|
>, or
|
|
<TT
|
|
CLASS="filename"
|
|
>/usr/share/sgml/declaration/xml.dcl</TT
|
|
>. Use
|
|
<SPAN
|
|
CLASS="application"
|
|
>locate</SPAN
|
|
> to find the file if it is not in
|
|
either of those two places. The modified command would be as
|
|
follows:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash$ </TT
|
|
><B
|
|
CLASS="command"
|
|
>jade -t xml -i html \
|
|
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
|
|
/usr/lib/sgml/declaration/xml.dcl <TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>HOWTO.xml</I
|
|
></TT
|
|
></B
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
> 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 <SPAN
|
|
CLASS="QUOTE"
|
|
>"html/ldp.dsl"</SPAN
|
|
> at the end. Change this to
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"print/docbook.dsl"</SPAN
|
|
>, or if you want XHTML output, instead
|
|
of HTML, change the file name to <SPAN
|
|
CLASS="QUOTE"
|
|
>"xhtml/docbook.dsl"</SPAN
|
|
>.
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H4
|
|
CLASS="section"
|
|
><A
|
|
NAME="dsssl-css"
|
|
></A
|
|
>B.4.1.4.1. Changing CSS Files</H4
|
|
><P
|
|
>If you want your HTML files to use a specific
|
|
<SPAN
|
|
CLASS="acronym"
|
|
>CSS</SPAN
|
|
> stylesheet, you will need to edit
|
|
<TT
|
|
CLASS="filename"
|
|
>ldp.dsl</TT
|
|
>. Immediately after
|
|
<TT
|
|
CLASS="literal"
|
|
>;; End of $verbatim-display$ redefinition</TT
|
|
>
|
|
add the following lines:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> (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")
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> Replace <TT
|
|
CLASS="filename"
|
|
>base.css</TT
|
|
> with the name of the
|
|
<SPAN
|
|
CLASS="acronym"
|
|
>CSS</SPAN
|
|
> file you would like to use.
|
|
</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="docbook-utils"
|
|
></A
|
|
>B.4.2. The docbook-utils Package</H2
|
|
><P
|
|
>The <SPAN
|
|
CLASS="application"
|
|
>docbook-utils</SPAN
|
|
> provide commands like <B
|
|
CLASS="command"
|
|
>db2html</B
|
|
>, <B
|
|
CLASS="command"
|
|
>db2pdf</B
|
|
> and <B
|
|
CLASS="command"
|
|
>db2ps</B
|
|
>, based on the <B
|
|
CLASS="command"
|
|
>jw</B
|
|
> scripts, that is a front-end to <SPAN
|
|
CLASS="application"
|
|
>Jade</SPAN
|
|
>. These tools ease the everyday management of documentation and add comfortable features.</P
|
|
><P
|
|
>The package, originally created by RedHat and available from <A
|
|
HREF="http://sources.redhat.com/docbook-tools/"
|
|
TARGET="_top"
|
|
>http://sources.redhat.com/docbook-tools/</A
|
|
> can be installed on most systems.</P
|
|
><DIV
|
|
CLASS="example"
|
|
><A
|
|
NAME="ex-htmloutput"
|
|
></A
|
|
><P
|
|
><B
|
|
>Example B-6. Example creating HTML output</B
|
|
></P
|
|
><P
|
|
>After validating your document, simply issue the command
|
|
<B
|
|
CLASS="command"
|
|
>db2html <TT
|
|
CLASS="filename"
|
|
>mydoc.xml</TT
|
|
></B
|
|
> to create (a)
|
|
HTML file(s). You can also use the
|
|
<SPAN
|
|
CLASS="application"
|
|
>docbook-utils</SPAN
|
|
> 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.</P
|
|
><P
|
|
> If you get errors about a function name, please read .
|
|
</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="stylesheets"
|
|
></A
|
|
>B.4.2.1. Using CSS and DSL for pretty output</H3
|
|
><P
|
|
>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 <A
|
|
HREF="templates.html"
|
|
>Appendix A</A
|
|
>.</P
|
|
><P
|
|
>The sample DSL file will create a table of contents, and have all
|
|
HTML files start with the prefix <TT
|
|
CLASS="filename"
|
|
>intro2linux-</TT
|
|
> and end
|
|
with a suffix of <TT
|
|
CLASS="filename"
|
|
>.html</TT
|
|
>. The
|
|
<TT
|
|
CLASS="varname"
|
|
>%stylesheet%</TT
|
|
> variable points to the CSS file which
|
|
should be called by your HTML file.</P
|
|
><P
|
|
>To use a specific DSL style sheet the following command should be
|
|
used:</P
|
|
><P
|
|
><B
|
|
CLASS="command"
|
|
>db2html <TT
|
|
CLASS="option"
|
|
>-d</TT
|
|
> <TT
|
|
CLASS="filename"
|
|
>mystyle.dsl</TT
|
|
> <TT
|
|
CLASS="filename"
|
|
>mydoc.xml</TT
|
|
></B
|
|
> </P
|
|
><P
|
|
>You can compare the result here: <A
|
|
HREF="http://tille.xalasys.com/training/unix/"
|
|
TARGET="_top"
|
|
>http://tille.xalasys.com/training/unix/</A
|
|
> is a book formatted with the standard tools; <A
|
|
HREF="http://tille.xalasys.com/training/tldp/"
|
|
TARGET="_top"
|
|
>http://tille.xalasys.com/training/tldp/</A
|
|
> is one using personalized DSL and CSS files. Soft tones and special effects, for instance in buttons, were used to achieve maximum effect.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="xsl"
|
|
></A
|
|
>B.4.3. XSL</H2
|
|
><P
|
|
> There are alternatives to DSSSL and Jade/OpenJade.</P
|
|
><P
|
|
>When working with DocBook XML, the LDP offers a series of
|
|
XSL<A
|
|
NAME="AEN2259"
|
|
HREF="#FTN.AEN2259"
|
|
><SPAN
|
|
CLASS="footnote"
|
|
>[1]</SPAN
|
|
></A
|
|
>
|
|
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 <A
|
|
HREF="transformations.html#dsssl"
|
|
>ldp.dsl</A
|
|
>.
|
|
</P
|
|
><P
|
|
>The major difference between using <TT
|
|
CLASS="filename"
|
|
>ldp.dsl</TT
|
|
>
|
|
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
|
|
<SPAN
|
|
CLASS="application"
|
|
>jade</SPAN
|
|
> or
|
|
<SPAN
|
|
CLASS="application"
|
|
>openjade</SPAN
|
|
>, the tool
|
|
itself was responsible for generating the separate files. Because of
|
|
this, only a single file, <TT
|
|
CLASS="filename"
|
|
>ldp.dsl</TT
|
|
> was necessary as
|
|
a customization layer for the standard DocBook DSSSL style sheets.
|
|
</P
|
|
><P
|
|
>With the DocBook XSL style sheets, generation of multiple files is
|
|
controlled <EM
|
|
>by the style sheet</EM
|
|
>. 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:
|
|
</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="filename"
|
|
>tldp-html.xsl</TT
|
|
> - style sheet called to generate
|
|
a <EM
|
|
>single</EM
|
|
> file.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="filename"
|
|
>tldp-html-chunk.xsl</TT
|
|
><A
|
|
NAME="AEN2280"
|
|
HREF="#FTN.AEN2280"
|
|
><SPAN
|
|
CLASS="footnote"
|
|
>[2]</SPAN
|
|
></A
|
|
> - style sheet called to generate
|
|
multiple files based on chapter, section and appendix elements.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="filename"
|
|
>tldp-html-common.xsl</TT
|
|
> - style sheet containing
|
|
the actual XSLT transformations. It is called by the other two HTML
|
|
style sheets and is <EM
|
|
>never</EM
|
|
> directly called.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="filename"
|
|
>tldp-print.xsl</TT
|
|
> - style sheet for generation of
|
|
XSL Formatting Objects for print output.
|
|
</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
> You can find the latest copy of the files at <A
|
|
HREF="http://my.core.com/~dhorton/docbook/tldp-xsl/"
|
|
TARGET="_top"
|
|
>http://my.core.com/~dhorton/docbook/tldp-xsl/</A
|
|
>.
|
|
The package includes installation instructions which are duplicated
|
|
at <A
|
|
HREF="http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html"
|
|
TARGET="_top"
|
|
>http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html</A
|
|
>. 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 <TT
|
|
CLASS="filename"
|
|
>html</TT
|
|
>
|
|
directory of TLDP-XSL and put them in the
|
|
<TT
|
|
CLASS="filename"
|
|
>html</TT
|
|
> directory of Norman Walsh's
|
|
stylesheets. Take the file from the TLDP-XSL <TT
|
|
CLASS="filename"
|
|
>fo</TT
|
|
> directory and put it in the Norman Walsh
|
|
<TT
|
|
CLASS="filename"
|
|
>fo</TT
|
|
> directory.
|
|
</P
|
|
><P
|
|
> Once you have installed these files you can use
|
|
<SPAN
|
|
CLASS="application"
|
|
>xsltproc</SPAN
|
|
> to generate HTML files from your
|
|
XML documents. To transform your XML file(s) into a single-page HTML
|
|
document use the following command:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash$</TT
|
|
> <B
|
|
CLASS="command"
|
|
> xsltproc -o <TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>HOWTO.html</I
|
|
></TT
|
|
> /usr/local/sgml/stylesheets/tldp-html.xsl <TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>HOWTO.xml</I
|
|
></TT
|
|
></B
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>To generate a set of linked HTML pages, with a separate page for each
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>chapter</TT
|
|
>, <TT
|
|
CLASS="sgmltag"
|
|
>sect1</TT
|
|
> or
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>appendix</TT
|
|
>, use the following
|
|
command:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash$ </TT
|
|
><B
|
|
CLASS="command"
|
|
>xsltproc /usr/share/sgml/stylesheets/tldp-html-chunk.xsl <TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>HOWTO.xml</I
|
|
></TT
|
|
></B
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>Note that you never directly call the style sheet
|
|
<TT
|
|
CLASS="filename"
|
|
>tldp-html-common.xsl</TT
|
|
>. It is called by both of the
|
|
other two style sheets.
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="xsl-css"
|
|
></A
|
|
>B.4.3.1. Changing CSS Files</H3
|
|
><P
|
|
>If you want your HTML files to use a specific
|
|
<SPAN
|
|
CLASS="acronym"
|
|
>CSS</SPAN
|
|
> stylesheet, you will need to edit
|
|
<TT
|
|
CLASS="filename"
|
|
>tldp-html-common.xsl</TT
|
|
>. Look for a line that
|
|
ressembles <TT
|
|
CLASS="literal"
|
|
><xsl:param name="html.stylesheet"
|
|
select="'style.css'"/></TT
|
|
>.</P
|
|
><P
|
|
> Replace <TT
|
|
CLASS="filename"
|
|
>style.css</TT
|
|
> with the name of the
|
|
<SPAN
|
|
CLASS="acronym"
|
|
>CSS</SPAN
|
|
> file you would like to use.
|
|
</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><H3
|
|
CLASS="FOOTNOTES"
|
|
>Notes</H3
|
|
><TABLE
|
|
BORDER="0"
|
|
CLASS="FOOTNOTES"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
WIDTH="5%"
|
|
><A
|
|
NAME="FTN.AEN2259"
|
|
HREF="transformations.html#AEN2259"
|
|
><SPAN
|
|
CLASS="footnote"
|
|
>[1]</SPAN
|
|
></A
|
|
></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
WIDTH="95%"
|
|
><P
|
|
>In truth, "XSL" is actually comprised of three
|
|
components: the <EM
|
|
>XSLT</EM
|
|
> transformation language,
|
|
the <EM
|
|
>XPath</EM
|
|
> 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
|
|
<A
|
|
HREF="http://www.w3.org/Style/XSL/WhatIsXSL.html"
|
|
TARGET="_top"
|
|
>W3C web
|
|
site</A
|
|
> for more information.</P
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
WIDTH="5%"
|
|
><A
|
|
NAME="FTN.AEN2280"
|
|
HREF="transformations.html#AEN2280"
|
|
><SPAN
|
|
CLASS="footnote"
|
|
>[2]</SPAN
|
|
></A
|
|
></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
WIDTH="95%"
|
|
><P
|
|
>In XSL
|
|
terminology, the process of generating multiple files is referred to
|
|
as "chunking".</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="tools-validate.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="dtd.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Validation</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="tools.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>DocBook DTD</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |