Skip to content

P
Postgres FD Implementation
Commit 70320b5b authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Repair markup for sgmltools writeup. 

Fix indenting and make other minor markup improvements.
parent fc32c709
Hide whitespace changes
Inline Side-by-side
Showing with 527 additions and 445 deletions
doc/src/sgml/docguide.sgml
View file @ 70320b5b
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.21 1999/10/05 18:55:45 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.22 1999/10/09 02:29:15 thomas Exp $
Documentation Guide
Thomas Lockhart
......@@ -1278,170 +1278,226 @@ $ make man
</procedure>
</sect2>
</sect1>
<sect1>
<title>Toolsets</title>
<para>
We have documented experience with two installation methods for the
various tools that are needed to process the documentation. One is
installation from <acronym>RPM</acronym>s on
<productname>Linux</productname>, the other is a general installation
from original distributions of the individual tools. Both will be
described below.</para>
<para>
We understand that there are some other packaged distributions for
these tools. <productname>FreeBSD</productname> seems to have them
available. Please report package status to the docs mailing list and
we will include that information here.
</para>
<sect2>
<title><acronym>RPM</acronym> installation on
<productname>Linux</productname></title>
<para>
Install <ulink url="ftp://ftp.cygnus.com/pub/home/rosalia/">
<acronym>RPM</acronym>s</ulink> for <productname>Jade</productname>
and related packages.
</para>
</sect2>
<sect2>
<title>Manual installation of tools</title>
</sect1>
<para>
This is a brief run-through of the process of obtaining and
installing the software you'll need to edit DocBook source with Emacs
and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym>
and <acronym>RTF</acronym>.
</para>
<sect1>
<title>Toolsets</title>
<para>
The easiest way is to fetch the SGML and DocBook tools is to get
<application>sgmltools</application> from <ulink
url="http://www.sgmltools.org/"><productname>sgmltools</productname></u
link>. <productname>sgmltools</productname> requires the GNU version of
<productname>m4</productname>. <programlisting>gnum4
--version</programlisting> will show you if your m4 is the GNU version.
If you install GNU m4, install it with the name gnum4 and
<productname>sgmltools</productname> will it. After the install, you will
have <productname>sgmltools</productname>,
<productname>jade</productname>, and <productname>DocBook</productname>
style sheets. The instructions below are for installing these tools
separately. </para>
<para>
We have documented experience with two installation methods for the
various tools that are needed to process the documentation. One is
installation from <acronym>RPM</acronym>s on
<productname>Linux</productname>, the other is a general installation
from original distributions of the individual tools. Both will be
described below.
</para>
<sect3><title>Prerequisites</title>
<para>
We understand that there are some other packaged distributions for
these tools. <productname>FreeBSD</productname> seems to have them
available. Please report package status to the docs mailing list and
we will include that information here.
</para>
<para>What you need:
<sect2>
<title><acronym>RPM</acronym> installation on
<productname>Linux</productname></title>
<itemizedlist>
<listitem><para>A working installation of GCC 2.7.2</para></listitem>
<listitem><para>A working installation of Emacs 19.19 or later</para></listitem>
<listitem><para>An unzip program for Unix to unpack things</para></listitem>
</itemizedlist>
<para>
Install <ulink url="ftp://ftp.cygnus.com/pub/home/rosalia/">
<acronym>RPM</acronym>s</ulink> for <productname>Jade</productname>
and related packages.
</para>
</sect2>
</para>
<sect2>
<title>Manual installation of tools</title>
<para>What you must fetch:
<para>
This is a brief run-through of the process of obtaining and
installing the software you'll need to edit DocBook source with Emacs
and process it with Norman Walsh's DSSSL style sheets to create
<acronym>HTML</acronym> and <acronym>RTF</acronym>.
</para>
<itemizedlist>
<listitem>
<para><ulink url="ftp://ftp.jclark.com/pub/jade/">
James Clark's <productname>Jade</productname></ulink>
(version 1.1 in file <filename>jade1_1.zip</filename> was current at the time of writing)
</para></listitem>
<listitem>
<para><ulink url="http://www.ora.com/davenport/docbook/current/docbk30.zip">
<productname>DocBook</productname> version 3.0</ulink>
</para></listitem>
<listitem>
<para><ulink url="http://nwalsh.com/docbook/dsssl/">
Norman Walsh's <productname>Modular Stylesheets</productname></ulink>
(version 1.19 was used to produce these documents)
</para></listitem>
<listitem>
<para><ulink url="ftp://ftp.lysator.liu.se/pub/sgml/">
Lennart Staflin's <productname>PSGML</productname></ulink>
(version 1.0.1 in <filename>psgml-1.0.1.tar.gz</filename> was available at the time of writing)
</para></listitem>
</itemizedlist>
<para>
The easiest way to obtain the SGML and DocBook tools may be to get
<application>sgmltools</application> from
<ulink url="http://www.sgmltools.org/"><productname>sgmltools</productname></ulink>.
<productname>sgmltools</productname> requires the GNU version of
<productname>m4</productname>. To confirm that you have the
correct version of m4 available, try
<programlisting>
gnum4 --version
</programlisting>
</para>
</para>
<para>
If you install GNU m4, install it with the name gnum4 and
<productname>sgmltools</productname> will find it.
After the install, you will
have <productname>sgmltools</productname>,
<productname>jade</productname>,
and Norm Walsh's <productname>DocBook</productname>
style sheets. The instructions below are for installing these tools
separately.
</para>
<para>Important URLs:
<sect3>
<title>Prerequisites</title>
<itemizedlist>
<listitem><para><ulink url="http://www.jclark.com/jade/">
The <productname>Jade</productname> web page</ulink></para></listitem>
<listitem><para><ulink url="http://www.ora.com/davenport/">
The <productname>DocBook</productname> web page</ulink></para></listitem>
<listitem><para><ulink url="http://nwalsh.com/docbook/dsssl/">
The <productname>Modular Stylesheets</productname> web page</ulink>
</para></listitem>
<listitem><para>
<ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
The <productname>PSGML</productname> web page</ulink></para></listitem>
<listitem><para><ulink url="http://www.infotek.no/sgmltool/guide.htm">
Steve Pepper's Whirlwind Guide</ulink></para></listitem>
<listitem><para><ulink url="http://www.sil.org/sgml/publicSW.html">
Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
</itemizedlist>
</para>
<para>
What you need:
</sect3>
<itemizedlist>
<listitem>
<para>
A working installation of GCC 2.7.2
</para>
</listitem>
<listitem>
<para>
A working installation of Emacs 19.19 or later
</para>
</listitem>
<listitem>
<para>
An unzip program for Unix to unpack things
</para>
</listitem>
</itemizedlist>
</para>
<sect3>
<title>Installing Jade</title>
<para>
What you must fetch:
<procedure>
<title>Installing Jade</title>
<itemizedlist>
<listitem>
<para>
<ulink url="ftp://ftp.jclark.com/pub/jade/">James Clark's <productname>Jade</productname></ulink>
(version 1.1 in file <filename>jade1_1.zip</filename> was
current at the time of writing)
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.ora.com/davenport/docbook/current/docbk30.zip">
<productname>DocBook</productname> version 3.0</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://nwalsh.com/docbook/dsssl/">Norman Walsh's <productname>Modular Stylesheets</productname></ulink>
(version 1.19 was originally used to produce these documents)
</para>
</listitem>
<listitem>
<para>
<ulink url="ftp://ftp.lysator.liu.se/pub/sgml/">Lennart Staflin's <productname>PSGML</productname></ulink>
(version 1.0.1 in <filename>psgml-1.0.1.tar.gz</filename> was
available at the time of writing)
</para>
</listitem>
</itemizedlist>
</para>
<step performance="required">
<para>
Read the installation instructions at the above listed
URL.
</para>
</step>
<para>
Important URLs:
<step performance="required">
<para>
Unzip the distribution kit in a suitable place. The command to do
this will be something like
<programlisting>
<itemizedlist>
<listitem>
<para>
<ulink url="http://www.jclark.com/jade/">The <productname>Jade</productname> web page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.ora.com/davenport/">The <productname>DocBook</productname> web page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://nwalsh.com/docbook/dsssl/">The <productname>Modular Stylesheets</productname> web page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.lysator.liu.se/projects/about_psgml.html">The <productname>PSGML</productname> web page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.infotek.no/sgmltool/guide.htm">Steve
Pepper's Whirlwind Guide</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.sil.org/sgml/publicSW.html">
Robin Cover's database of <acronym>SGML</acronym>
software</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</sect3>
<sect3>
<title>Installing Jade</title>
<procedure>
<title>Installing Jade</title>
<step performance="required">
<para>
Read the installation instructions at the above listed
URL.
</para>
</step>
<step performance="required">
<para>
Unzip the distribution kit in a suitable place. The command to do
this will be something like
<programlisting>
unzip -aU jade1_1.zip
</programlisting>
</para>
</step>
<step performance="required">
<para><productname>Jade</productname> is not built using
<productname>GNU Autoconf</productname>, so you'll need to edit a
<filename>Makefile</filename> yourself. Since James Clark has been
good enough to prepare his kit for it, it is a good idea to make a
build directory (named for your machine architecture, perhaps) under
the main directory of the <productname>Jade</productname>
distribution, copy the file <filename>Makefile</filename> from the
main directory into it, edit it there, and then run
<command>make</command> there.</para>
<para>However, the <filename>Makefile</filename> does need to be
edited. There is a file called <filename>Makefile.jade</filename> in
the main directory, which is intended to be used with <command>make -f
Makefile.jade</command> when building <productname>Jade</productname>
(as opposed to just <productname>SP</productname>, the <acronym>SGML</acronym> parser kit
that <productname>Jade</productname> is built upon). We suggest that
you don't do that, though, since there is more that you need to change
than what is in <filename>Makefile.jade</filename>, so you'd have to
edit one of them anyway.</para>
<para>Go through the <filename>Makefile</filename>, reading James'
instructions and editing as needed. There are various variables that
need to be set. Here is a collected summary of the most important
ones, with typical values:
<programlisting>
</programlisting>
</para>
</step>
<step performance="required">
<para>
<productname>Jade</productname> is not built using
<productname>GNU autoconf</productname>, so you'll need to edit a
<filename>Makefile</filename> yourself. Since James Clark has been
good enough to prepare his kit for it, it is a good idea to make a
build directory (named for your machine architecture, perhaps) under
the main directory of the <productname>Jade</productname>
distribution, copy the file <filename>Makefile</filename> from the
main directory into it, edit it there, and then run
<command>make</command> there.
</para>
<para>
However, the <filename>Makefile</filename> does need to be
edited. There is a file called <filename>Makefile.jade</filename> in
the main directory, which is intended to be used with <command>make -f
Makefile.jade</command> when building <productname>Jade</productname>
(as opposed to just <productname>SP</productname>,
the <acronym>SGML</acronym> parser kit
that <productname>Jade</productname> is built upon). We suggest that
you don't do that, though, since there is more that you need to change
than what is in <filename>Makefile.jade</filename>, so you'd have to
edit one of them anyway.
</para>
<para>
Go through the <filename>Makefile</filename>, reading James'
instructions and editing as needed. There are various variables that
need to be set. Here is a collected summary of the most important
ones, with typical values:
<programlisting>
prefix = /usr/local
XDEFINES = -DSGML_CATALOG_FILES_DEFAULT=\"/usr/local/share/sgml/catalog\"
XLIBS = -lm
......@@ -1449,332 +1505,358 @@ RANLIB = ranlib
srcdir = ..
XLIBDIRS = grove spgrove style
XPROGDIRS = jade
</programlisting>
Note the specification of where to find the default catalog of
<acronym>SGML</acronym> support files -- you may want to change that
to something more suitable for your own installation. If your system
doesn't need the above settings for the math library and the
<command>ranlib</command> command, leave them as they are in the
<filename>Makefile</filename>.
</para>
</step>
<step performance="required">
<para>Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para>
</step>
<step performance="required">
<para>Once the software is built, <command>make install</command> will
do the obvious.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<procedure>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<step performance="required">
<para>You'll want to place the files that make up the
<productname>DocBook</productname> <acronym>DTD</acronym> kit in the
directory you built <productname>Jade</productname> to expect them in,
which, if you followed our suggestion above, is
<filename>/usr/local/share/sgml/</filename>. In addition to the
actual <productname>DocBook</productname> files, you'll need to have a
<filename>catalog</filename> file in place, for the mapping of
document type specifications and external entity references to actual
files in that directory. You'll also want the <acronym>ISO</acronym>
character set mappings, and probably one or more versions of
<acronym>HTML</acronym>.</para>
<para>One way to install the various <acronym>DTD</acronym> and
support files and set up the <filename>catalog</filename> file, is to
collect them all into the above mentioned directory, use a single file
named <filename>CATALOG</filename> to describe them all, and then
create the file <filename>catalog</filename> as a catalog pointer to
the former, by giving it the single line of content:
<programlisting>
</programlisting>
Note the specification of where to find the default catalog of
<acronym>SGML</acronym> support files -- you may want to change that
to something more suitable for your own installation. If your system
doesn't need the above settings for the math library and the
<command>ranlib</command> command, leave them as they are in the
<filename>Makefile</filename>.
</para>
</step>
<step performance="required">
<para>
Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para>
</step>
<step performance="required">
<para>
Once the software is built, <command>make install</command> will
do the obvious.
</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<procedure>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<step performance="required">
<para>
You'll want to place the files that make up the
<productname>DocBook</productname> <acronym>DTD</acronym> kit in the
directory you built <productname>Jade</productname> to expect them in,
which, if you followed our suggestion above, is
<filename>/usr/local/share/sgml/</filename>. In addition to the
actual <productname>DocBook</productname> files, you'll need to have a
<filename>catalog</filename> file in place, for the mapping of
document type specifications and external entity references to actual
files in that directory. You'll also want the <acronym>ISO</acronym>
character set mappings, and probably one or more versions of
<acronym>HTML</acronym>.
</para>
<para>
One way to install the various <acronym>DTD</acronym> and
support files and set up the <filename>catalog</filename> file, is to
collect them all into the above mentioned directory, use a single file
named <filename>CATALOG</filename> to describe them all, and then
create the file <filename>catalog</filename> as a catalog pointer to
the former, by giving it the single line of content:
<programlisting>
CATALOG /usr/local/share/sgml/CATALOG
</programlisting>
</para>
</step>
<step performance="required">
<para>
The <filename>CATALOG</filename> file should then contain three types
of lines. The first is the (optional) <acronym>SGML</acronym>
declaration, thus:
<programlisting>
</programlisting>
</para>
</step>
<step performance="required">
<para>
The <filename>CATALOG</filename> file should then contain three types
of lines. The first is the (optional) <acronym>SGML</acronym>
declaration, thus:
<programlisting>
SGMLDECL docbook.dcl
</programlisting>
Next, the various references to <acronym>DTD</acronym> and entity
files must be resolved. For the <productname>DocBook</productname>
files, these lines look like this:
<programlisting>
</programlisting>
Next, the various references to <acronym>DTD</acronym> and entity
files must be resolved. For the <productname>DocBook</productname>
files, these lines look like this:
<programlisting>
PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
</programlisting>
</para>
</step>
<step performance="required">
<para>
Of course, a file containing these comes with the
<productname>DocBook</productname> kit. Note that the last item on
each of these lines is a file name, given here without a path. You
can put the files in subdirectories of your main
<acronym>SGML</acronym> directory if you like, of course, and modify
the reference in the <filename>CATALOG</filename> file.
<productname>DocBook</productname> also references the
<acronym>ISO</acronym> character set entities, so you need to fetch
and install these (they are available from several sources, and are
easily found by way of the URLs listed above), along with catalog
entries for all of them, such as:
<programlisting>
</programlisting>
</para>
</step>
<step performance="required">
<para>
Of course, a file containing these comes with the
<productname>DocBook</productname> kit. Note that the last item on
each of these lines is a file name, given here without a path. You
can put the files in subdirectories of your main
<acronym>SGML</acronym> directory if you like, of course, and modify
the reference in the <filename>CATALOG</filename> file.
<productname>DocBook</productname> also references the
<acronym>ISO</acronym> character set entities, so you need to fetch
and install these (they are available from several sources, and are
easily found by way of the URLs listed above), along with catalog
entries for all of them, such as:
<programlisting>
PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
</programlisting>
Note how the file name here contains a directory name, showing that
we've placed the <acronym>ISO</acronym> entity files in a subdirectory
named <filename>ISO</filename>. Again, proper catalog entries should
accompany the entity kit you fetch.
</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<procedure>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<step performance="required">
<para>Read the installation instructions at the above listed
URL.</para>
</step>
<step performance="required">
<para>To install Norman's style sheets, simply unzip the distribution
kit in a suitable place. A good place to dot this would be
<filename>/usr/local/share</filename>, which places the kit in a
directory tree under <filename>/usr/local/share/docbook</filename>.
The command will be something like
<programlisting>
</programlisting>
Note how the file name here contains a directory name, showing that
we've placed the <acronym>ISO</acronym> entity files in a subdirectory
named <filename>ISO</filename>. Again, proper catalog entries should
accompany the entity kit you fetch.
</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<procedure>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<step performance="required">
<para>
Read the installation instructions at the above listed
URL.
</para>
</step>
<step performance="required">
<para>
To install Norman's style sheets, simply unzip the distribution
kit in a suitable place. A good place to dot this would be
<filename>/usr/local/share</filename>, which places the kit in a
directory tree under <filename>/usr/local/share/docbook</filename>.
The command will be something like
<programlisting>
unzip -aU db119.zip
</programlisting>
</para>
</step>
<step performance="required">
<para>One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
<citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>.
</para>
<substeps>
<step performance="required">
<para>
To build the <acronym>HTML</acronym> files,
go to the <acronym>SGML</acronym> source
directory, <filename>doc/src/sgml</filename>, and say
<programlisting>
</programlisting>
</para>
</step>
<step performance="required">
<para>
One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
<citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>.
</para>
<substeps>
<step performance="required">
<para>
To build the <acronym>HTML</acronym> files,
go to the <acronym>SGML</acronym> source
directory, <filename>doc/src/sgml</filename>, and say
<programlisting>
jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
</para>
<para>
<filename>book1.htm</filename> is the top level node of the output..
</para>
</step>
<step performance="required">
<para>
To generate the <acronym>RTF</acronym> output, ready for importing
into your favorite word processing system and printing, type:
<programlisting>
</programlisting>
</para>
<para>
<filename>book1.htm</filename> is the top level node of the output..
</para>
</step>
<step performance="required">
<para>
To generate the <acronym>RTF</acronym> output, ready for importing
into your favorite word processing system and printing, type:
<programlisting>
jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
</para>
</step>
</substeps>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing <productname>PSGML</productname></title>
<procedure>
<title>Installing <productname>PSGML</productname></title>
<step performance="required">
<para>Read the installation instructions at the above listed
URL.</para>
</step>
<step performance="required">
<para>Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place.
</para>
</step>
<step performance="required" id="psgml-setup">
<para>
Then add the following lines to your
<filename>/usr/local/share/emacs/site-lisp/site-start.el</filename>
file to make <productname>Emacs</productname> properly load
<productname>PSGML</productname> when needed:
<programlisting>
</programlisting>
</para>
</step>
</substeps>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing <productname>PSGML</productname></title>
<procedure>
<title>Installing <productname>PSGML</productname></title>
<step performance="required">
<para>
Read the installation instructions at the above listed
URL.
</para>
</step>
<step performance="required">
<para>
Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place.
</para>
</step>
<step performance="required" id="psgml-setup">
<para>
Then add the following lines to your
<filename>/usr/local/share/emacs/site-lisp/site-start.el</filename>
file to make <productname>Emacs</productname> properly load
<productname>PSGML</productname> when needed:
<programlisting>
(setq load-path
(cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
</programlisting>
</para>
</step>
<step performance="optional">
<para>
If you want to use <productname>PSGML</productname> when editing
<acronym>HTML</acronym> too, also add this:
<programlisting>
</programlisting>
</para>
</step>
<step performance="optional">
<para>
If you want to use <productname>PSGML</productname> when editing
<acronym>HTML</acronym> too, also add this:
<programlisting>
(setq auto-mode-alist
(cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
</programlisting>
</para>
</step>
<step performance="optional">
<para>There is one important thing to note with
<productname>PSGML</productname>: its author assumed that your main
<acronym>SGML</acronym> <acronym>DTD</acronym> directory would be
<filename>/usr/local/lib/sgml</filename>. If, as in the examples in
this chapter, you use <filename>/usr/local/share/sgml</filename>, you
have to compensate for this.
</para>
</programlisting>
</para>
</step>
<step performance="optional">
<para>
There is one important thing to note with
<productname>PSGML</productname>: its author assumed that your main
<acronym>SGML</acronym> <acronym>DTD</acronym> directory would be
<filename>/usr/local/lib/sgml</filename>. If, as in the examples in
this chapter, you use <filename>/usr/local/share/sgml</filename>, you
have to compensate for this.
</para>
<substeps>
<step performance="optional">
<para>
You can set the
<filename>SGML_CATALOG_FILES</filename> environment variable.
</para>
</step>
<step performance="optional">
<para>
You can
customize your <productname>PSGML</productname> installation (its
manual tells you how).
</para>
</step>
<step performance="optional">
<para>
You can even edit the source file
<filename>psgml.el</filename> before compiling and installing
<productname>PSGML</productname>, changing the hard-coded paths to
match your own default.
</para>
</step>
</substeps>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing <productname>JadeTeX</productname></title>
<substeps>
<step performance="optional">
<para>
You can set the
<filename>SGML_CATALOG_FILES</filename> environment variable.
</para>
</step>
<step performance="optional">
<para>
You can
customize your <productname>PSGML</productname> installation (its
manual tells you how).
</para>
</step>
<step performance="optional">
<para>
You can even edit the source file
<filename>psgml.el</filename> before compiling and installing
<productname>PSGML</productname>, changing the hard-coded paths to
match your own default.</para>
</step>
<para>
If you want to, you can also install
<productname>JadeTeX</productname> to use
<productname>TeX</productname> as a formatting backend for
<productname>Jade</productname>. Note that this is still quite
unpolished software, and will generate printed output that is inferior
to what you get from the <acronym>RTF</acronym> backend. Still, it
works all right, especially for simpler documents that don't use
tables, and as both <productname>JadeTeX</productname> and the style
sheets are under continuous improvement, it will certainly get better
over time.
</para>
</substeps>
</step>
<para>
To install and use <productname>JadeTeX</productname>, you will
need a working installation of <productname>TeX</productname> and
<productname>LaTeX2e</productname>, including the supported
<productname>tools</productname> and
<productname>graphics</productname> packages,
<productname>Babel</productname>, <productname><acronym>AMS</acronym>
fonts</productname> and <productname>AMS-LaTeX</productname>, the
<productname><acronym>PSNFSS</acronym></productname> extension and
companion kit of "the 35 fonts", the <productname>dvips</productname>
program for generating <productname>PostScript</productname>, the
macro packages <productname>fancyhdr</productname>,
<productname>hyperref</productname>,
<productname>minitoc</productname>, <productname>url</productname> and
<productname>ot2enc</productname>, and of course
<productname>JadeTeX</productname> itself. All of these can be found
on your friendly neighborhood <acronym>CTAN</acronym> site.
</para>
</procedure>
</sect3>
<para>
<productname>JadeTeX</productname> does not at the time of
writing come with much of an installation guide, but there is a
<filename>makefile</filename> which shows what is needed. It also
includes a directory <filename>cooked</filename>, wherein you'll find
some of the macro packages it needs, but not all, and not complete --
at least last we looked.
</para>
<sect3><title>Installing <productname>JadeTeX</productname></title>
<para>If you want to, you can also install
<productname>JadeTeX</productname> to use
<productname>TeX</productname> as a formatting backend for
<productname>Jade</productname>. Note that this is still quite
unpolished software, and will generate printed output that is inferior
to what you get from the <acronym>RTF</acronym> backend. Still, it
works all right, especially for simpler documents that don't use
tables, and as both <productname>JadeTeX</productname> and the style
sheets are under continuous improvement, it will certainly get better
over time.</para>
<para>To install and use <productname>JadeTeX</productname>, you will
need a working installation of <productname>TeX</productname> and
<productname>LaTeX2e</productname>, including the supported
<productname>tools</productname> and
<productname>graphics</productname> packages,
<productname>Babel</productname>, <productname><acronym>AMS</acronym>
fonts</productname> and <productname>AMS-LaTeX</productname>, the
<productname><acronym>PSNFSS</acronym></productname> extension and
companion kit of "the 35 fonts", the <productname>dvips</productname>
program for generating <productname>PostScript</productname>, the
macro packages <productname>fancyhdr</productname>,
<productname>hyperref</productname>,
<productname>minitoc</productname>, <productname>url</productname> and
<productname>ot2enc</productname>, and of course
<productname>JadeTeX</productname> itself. All of these can be found
on your friendly neighborhood <acronym>CTAN</acronym> site.</para>
<para><productname>JadeTeX</productname> does not at the time of
writing come with much of an installation guide, but there is a
<filename>makefile</filename> which shows what is needed. It also
includes a directory <filename>cooked</filename>, wherein you'll find
some of the macro packages it needs, but not all, and not complete --
at least last we looked.</para>
<para>Before building the <filename>jadetex.fmt</filename> format
file, you'll probably want to edit the
<filename>jadetex.ltx</filename> file, to change the configuration of
<productname>Babel</productname> to suit your locality. The line to
change looks something like
<programlisting>
<para>
Before building the <filename>jadetex.fmt</filename> format
file, you'll probably want to edit the
<filename>jadetex.ltx</filename> file, to change the configuration of
<productname>Babel</productname> to suit your locality. The line to
change looks something like
<programlisting>
\RequirePackage[german,french,english]{babel}[1997/01/23]
</programlisting>
and you should obviously list only the languages you actually need,
and have configured <productname>Babel</productname> for.</para>
<para>With <productname>JadeTeX</productname> working, you should be
able to generate and format <productname>TeX</productname> output for
the <productname>PostgreSQL</productname> manuals by giving the
commands (as above, in the <filename>doc/src/sgml</filename>
directory)
<programlisting>
</programlisting>
and you should obviously list only the languages you actually need,
and have configured <productname>Babel</productname> for.
</para>
<para>
With <productname>JadeTeX</productname> working, you should be
able to generate and format <productname>TeX</productname> output for
the <productname>PostgreSQL</productname> manuals by giving the
commands (as above, in the <filename>doc/src/sgml</filename>
directory)
<programlisting>
jade -t tex -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
jadetex postgres.tex
jadetex postgres.tex
dvips postgres.dvi
</programlisting>
Of course, when you do this, <productname>TeX</productname> will stop
during the second run, and tell you that its capacity has been
exceeded. This is, as far as we can tell, because of the way
<productname>JadeTeX</productname> generates cross referencing
information. <productname>TeX</productname> can, of course, be
compiled with larger data structure sizes. The details of this will
vary according to your installation.
</para>
</programlisting>
Of course, when you do this, <productname>TeX</productname> will stop
during the second run, and tell you that its capacity has been
exceeded. This is, as far as we can tell, because of the way
<productname>JadeTeX</productname> generates cross referencing
information. <productname>TeX</productname> can, of course, be
compiled with larger data structure sizes. The details of this will
vary according to your installation.
</para>
</sect3>
</sect3>
</sect2>
</sect1>
</sect2>
</sect1>
<sect1>
<title>Alternate Toolsets</title>
<sect1>
<title>Alternate Toolsets</title>
<para>
<productname>sgml-tools</productname> v2.x
now supports <application>jade</application>
and <productname>DocBook</productname>. It may be the preferred toolset
for working with <acronym>SGML</acronym> but we have not had a chance to
evaluate the new package.
</para>
<para>
<productname>sgml-tools</productname> v2.x
now supports <application>jade</application>
and <productname>DocBook</productname>. It may be the preferred toolset
for working with <acronym>SGML</acronym> but we have not had a chance to
evaluate the new package.
</para>
<!--
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment