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