mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Repair markup for sgmltools writeup.

Browse Source 
Fix indenting and make other minor markup improvements.
This commit is contained in:
Thomas G. Lockhart 1999-10-09 02:29:15 +00:00
parent fc32c709b4
commit 70320b5bf7
1 changed files with 485 additions and 403 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

258
doc/src/sgml/docguide.sgml
View File

@ -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
@ -1289,7 +1289,8 @@ 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
@ -1315,82 +1316,131 @@ and related packages.
<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>
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> <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 If you install GNU m4, install it with the name gnum4 and
<productname>sgmltools</productname> will it. After the install, you will <productname>sgmltools</productname> will find it.
After the install, you will
have <productname>sgmltools</productname>, have <productname>sgmltools</productname>,
<productname>jade</productname>, and <productname>DocBook</productname> <productname>jade</productname>,
and Norm Walsh's <productname>DocBook</productname>
style sheets. The instructions below are for installing these tools style sheets. The instructions below are for installing these tools
separately. </para> separately.
<sect3><title>Prerequisites</title>
<para>What you need:
<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> </para>
<para>What you must fetch: <sect3>
<title>Prerequisites</title>
<para>
What you need:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><ulink url="ftp://ftp.jclark.com/pub/jade/"> <para>
James Clark's <productname>Jade</productname></ulink> A working installation of GCC 2.7.2
(version 1.1 in file <filename>jade1_1.zip</filename> was current at the time of writing) </para>
</para></listitem> </listitem>
<listitem> <listitem>
<para><ulink url="http://www.ora.com/davenport/docbook/current/docbk30.zip"> <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 must fetch:
<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> <productname>DocBook</productname> version 3.0</ulink>
</para></listitem> </para>
</listitem>
<listitem> <listitem>
<para><ulink url="http://nwalsh.com/docbook/dsssl/"> <para>
Norman Walsh's <productname>Modular Stylesheets</productname></ulink> <ulink url="http://nwalsh.com/docbook/dsssl/">Norman Walsh's <productname>Modular Stylesheets</productname></ulink>
(version 1.19 was used to produce these documents) (version 1.19 was originally used to produce these documents)
</para></listitem> </para>
</listitem>
<listitem> <listitem>
<para><ulink url="ftp://ftp.lysator.liu.se/pub/sgml/"> <para>
Lennart Staflin's <productname>PSGML</productname></ulink> <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) (version 1.0.1 in <filename>psgml-1.0.1.tar.gz</filename> was
</para></listitem> available at the time of writing)
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para> </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>
</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> </itemizedlist>
</para> </para>
</sect3> </sect3>
<sect3> <sect3>
@ -1417,27 +1467,33 @@ unzip -aU jade1_1.zip
</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
<productname>GNU autoconf</productname>, so you'll need to edit a
<filename>Makefile</filename> yourself. Since James Clark has been <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 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 build directory (named for your machine architecture, perhaps) under
the main directory of the <productname>Jade</productname> the main directory of the <productname>Jade</productname>
distribution, copy the file <filename>Makefile</filename> from the distribution, copy the file <filename>Makefile</filename> from the
main directory into it, edit it there, and then run main directory into it, edit it there, and then run
<command>make</command> there.</para> <command>make</command> there.
</para>
<para>However, the <filename>Makefile</filename> does need to be <para>
However, the <filename>Makefile</filename> does need to be
edited. There is a file called <filename>Makefile.jade</filename> in edited. There is a file called <filename>Makefile.jade</filename> in
the main directory, which is intended to be used with <command>make -f the main directory, which is intended to be used with <command>make -f
Makefile.jade</command> when building <productname>Jade</productname> Makefile.jade</command> when building <productname>Jade</productname>
(as opposed to just <productname>SP</productname>, the <acronym>SGML</acronym> parser kit (as opposed to just <productname>SP</productname>,
the <acronym>SGML</acronym> parser kit
that <productname>Jade</productname> is built upon). We suggest that 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 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 than what is in <filename>Makefile.jade</filename>, so you'd have to
edit one of them anyway.</para> edit one of them anyway.
</para>
<para>Go through the <filename>Makefile</filename>, reading James' <para>
Go through the <filename>Makefile</filename>, reading James'
instructions and editing as needed. There are various variables that instructions and editing as needed. There are various variables that
need to be set. Here is a collected summary of the most important need to be set. Here is a collected summary of the most important
ones, with typical values: ones, with typical values:
@ -1460,13 +1516,16 @@ doesn't need the above settings for the math library and the
</step> </step>
<step performance="required"> <step performance="required">
<para>Type <command>make</command> to build Jade and the various <para>
Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para> <productname>SP</productname> tools.</para>
</step> </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
do the obvious.
</para>
</step> </step>
</procedure> </procedure>
</sect3> </sect3>
@ -1478,7 +1537,8 @@ do the obvious.</para>
<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>
You'll want to place the files that make up the
<productname>DocBook</productname> <acronym>DTD</acronym> kit in the <productname>DocBook</productname> <acronym>DTD</acronym> kit in the
directory you built <productname>Jade</productname> to expect them in, directory you built <productname>Jade</productname> to expect them in,
which, if you followed our suggestion above, is which, if you followed our suggestion above, is
@ -1488,9 +1548,11 @@ actual <productname>DocBook</productname> files, you'll need to have a
document type specifications and external entity references to actual document type specifications and external entity references to actual
files in that directory. You'll also want the <acronym>ISO</acronym> files in that directory. You'll also want the <acronym>ISO</acronym>
character set mappings, and probably one or more versions of character set mappings, and probably one or more versions of
<acronym>HTML</acronym>.</para> <acronym>HTML</acronym>.
</para>
<para>One way to install the various <acronym>DTD</acronym> and <para>
One way to install the various <acronym>DTD</acronym> and
support files and set up the <filename>catalog</filename> file, is to support files and set up the <filename>catalog</filename> file, is to
collect them all into the above mentioned directory, use a single file collect them all into the above mentioned directory, use a single file
named <filename>CATALOG</filename> to describe them all, and then named <filename>CATALOG</filename> to describe them all, and then
@ -1556,12 +1618,15 @@ accompany the entity kit you fetch.
<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
URL.
</para>
</step> </step>
<step performance="required"> <step performance="required">
<para>To install Norman's style sheets, simply unzip the distribution <para>
To install Norman's style sheets, simply unzip the distribution
kit in a suitable place. A good place to dot this would be kit in a suitable place. A good place to dot this would be
<filename>/usr/local/share</filename>, which places the kit in a <filename>/usr/local/share</filename>, which places the kit in a
directory tree under <filename>/usr/local/share/docbook</filename>. directory tree under <filename>/usr/local/share/docbook</filename>.
@ -1573,7 +1638,8 @@ unzip -aU db119.zip
</step> </step>
<step performance="required"> <step performance="required">
<para>One way to test the installation is to build the <para>
One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the <acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
<citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>. <citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>.
</para> </para>
@ -1618,12 +1684,15 @@ jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgre
<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
URL.
</para>
</step> </step>
<step performance="required"> <step performance="required">
<para>Unpack the distribution file, run configure, make and make <para>
Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place. install to put the byte-compiled files and info library in place.
</para> </para>
</step> </step>
@ -1654,7 +1723,8 @@ If you want to use <productname>PSGML</productname> when editing
</step> </step>
<step performance="optional"> <step performance="optional">
<para>There is one important thing to note with <para>
There is one important thing to note with
<productname>PSGML</productname>: its author assumed that your main <productname>PSGML</productname>: its author assumed that your main
<acronym>SGML</acronym> <acronym>DTD</acronym> directory would be <acronym>SGML</acronym> <acronym>DTD</acronym> directory would be
<filename>/usr/local/lib/sgml</filename>. If, as in the examples in <filename>/usr/local/lib/sgml</filename>. If, as in the examples in
@ -1683,7 +1753,8 @@ manual tells you how).
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.
</para>
</step> </step>
</substeps> </substeps>
@ -1692,9 +1763,11 @@ match your own default.</para>
</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>
If you want to, you can also install
<productname>JadeTeX</productname> to use <productname>JadeTeX</productname> to use
<productname>TeX</productname> as a formatting backend for <productname>TeX</productname> as a formatting backend for
<productname>Jade</productname>. Note that this is still quite <productname>Jade</productname>. Note that this is still quite
@ -1703,9 +1776,11 @@ to what you get from the <acronym>RTF</acronym> backend. Still, it
works all right, especially for simpler documents that don't use works all right, especially for simpler documents that don't use
tables, and as both <productname>JadeTeX</productname> and the style tables, and as both <productname>JadeTeX</productname> and the style
sheets are under continuous improvement, it will certainly get better sheets are under continuous improvement, it will certainly get better
over time.</para> over time.
</para>
<para>To install and use <productname>JadeTeX</productname>, you will <para>
To install and use <productname>JadeTeX</productname>, you will
need a working installation of <productname>TeX</productname> and need a working installation of <productname>TeX</productname> and
<productname>LaTeX2e</productname>, including the supported <productname>LaTeX2e</productname>, including the supported
<productname>tools</productname> and <productname>tools</productname> and
@ -1720,16 +1795,20 @@ macro packages <productname>fancyhdr</productname>,
<productname>minitoc</productname>, <productname>url</productname> and <productname>minitoc</productname>, <productname>url</productname> and
<productname>ot2enc</productname>, and of course <productname>ot2enc</productname>, and of course
<productname>JadeTeX</productname> itself. All of these can be found <productname>JadeTeX</productname> itself. All of these can be found
on your friendly neighborhood <acronym>CTAN</acronym> site.</para> on your friendly neighborhood <acronym>CTAN</acronym> site.
</para>
<para><productname>JadeTeX</productname> does not at the time of <para>
<productname>JadeTeX</productname> does not at the time of
writing come with much of an installation guide, but there is a writing come with much of an installation guide, but there is a
<filename>makefile</filename> which shows what is needed. It also <filename>makefile</filename> which shows what is needed. It also
includes a directory <filename>cooked</filename>, wherein you'll find includes a directory <filename>cooked</filename>, wherein you'll find
some of the macro packages it needs, but not all, and not complete -- some of the macro packages it needs, but not all, and not complete --
at least last we looked.</para> at least last we looked.
</para>
<para>Before building the <filename>jadetex.fmt</filename> format <para>
Before building the <filename>jadetex.fmt</filename> format
file, you'll probably want to edit the file, you'll probably want to edit the
<filename>jadetex.ltx</filename> file, to change the configuration of <filename>jadetex.ltx</filename> file, to change the configuration of
<productname>Babel</productname> to suit your locality. The line to <productname>Babel</productname> to suit your locality. The line to
@ -1738,9 +1817,11 @@ change looks something like
\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>
With <productname>JadeTeX</productname> working, you should be
able to generate and format <productname>TeX</productname> output for able to generate and format <productname>TeX</productname> output for
the <productname>PostgreSQL</productname> manuals by giving the the <productname>PostgreSQL</productname> manuals by giving the
commands (as above, in the <filename>doc/src/sgml</filename> commands (as above, in the <filename>doc/src/sgml</filename>
@ -1751,6 +1832,7 @@ 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 Of course, when you do this, <productname>TeX</productname> will stop
during the second run, and tell you that its capacity has been 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 exceeded. This is, as far as we can tell, because of the way