mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-21 20:33:23 +02:00
1173 lines
36 KiB
Plaintext
1173 lines
36 KiB
Plaintext
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.29 2000/11/11 13:53:49 petere Exp $ -->
|
|
|
|
<appendix label="DG2" id="docguide">
|
|
<title>Documentation</title>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> has four primary documentation
|
|
formats:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Plain text, for pre-installation information
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<acronym>HTML</acronym>, for on-line browsing and reference
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Postscript, for printing
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
man pages, for quick reference.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Additionally, a number of plain-text README-type files can be found
|
|
throughout the <productname>PostgreSQL</productname> source tree,
|
|
documenting various implementation issues.
|
|
</para>
|
|
|
|
<para>
|
|
The documentation is organized into several <quote>books</quote>
|
|
with varyingly confusing names:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Tutorial</citetitle>: introduction for new users
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>User's Guide</citetitle>: documents the query language environment
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Administrator's Guide</citetitle>: installation and server maintenance
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Programmer's Guide</citetitle>: programming client
|
|
applications and server extensions
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<citetitle>Developer's Guide</citetitle>: assorted information
|
|
for developers of PostgreSQL proper
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
All five books are available as HTML and Postscript. The
|
|
<citetitle>User's Guide</citetitle> contains reference entries which
|
|
are also shipped as man pages.
|
|
</para>
|
|
|
|
<para>
|
|
<acronym>HTML</acronym> documentation and man pages are part of a
|
|
standard distribution and are installed by default. Postscript
|
|
format documentation is available separately for download.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>DocBook</title>
|
|
<para>
|
|
The documentation sources are written in
|
|
<firstterm>DocBook</firstterm>, which is a markup language
|
|
superficially similar to <acronym>HTML</acronym>. Both of these
|
|
languages are applications of the <firstterm>Standard Generalized
|
|
Markup Language</firstterm>, <acronym>SGML</acronym>, which is
|
|
essentially a language for describing other languages. In what
|
|
follows, the terms DocBook and SGML are both used, but technically
|
|
they are not interchangeable.
|
|
</para>
|
|
|
|
<para>
|
|
<productname>DocBook</productname> allows an author to specify the
|
|
structure and content of a technical document without worrying
|
|
about presentation details. A document style defines how that
|
|
content is rendered into one of several final forms. DocBook is
|
|
maintained by the <ulink
|
|
url="http://www.oasis-open.org">OASIS</ulink> group. The <ulink
|
|
url="http://www.oasis-open.org/docbook">official DocBook
|
|
site</ulink> has good introductory and reference documentation and
|
|
a complete O'Reilly book for your online reading pleasure. The
|
|
<ulink url="http://www.freebsd.org/docproj/docproj.html">FreeBSD
|
|
Documentation Project</ulink> also uses DocBook and has some good
|
|
information, including a number of style guidelines that might be
|
|
worth considering.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-toolsets">
|
|
<title>Toolsets</title>
|
|
|
|
<para>
|
|
The following tools are used to process the documentation. Some
|
|
may be optional, as noted.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is the definition of DocBook itself. We currently use
|
|
version 3.1; you cannot use later or earlier versions. Note
|
|
that there is also an <acronym>XML</acronym> version of DocBook
|
|
-- do not use that.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
These are required by DocBook but are distributed separately
|
|
because they are maintained by ISO.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://openjade.sourceforge.net">Jade</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This is the base package of <acronym>SGML</acronym> processing.
|
|
It contains an <acronym>SGML</acronym> parser, a
|
|
<acronym>DSSSL</acronym> processor (that is, a program to
|
|
convert <acronym>SGML</acronym> to other formats using
|
|
<acronym>DSSSL</acronym> stylesheets), as well as a number of
|
|
related tools. <productname>Jade</productname> is now being
|
|
maintained by the OpenJade group, no longer by James Clark.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://nwalsh.com/docbook/dsssl/index.html">Norm Walsh's Modular DocBook Stylesheets</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
These contain the processing instructions for converting the
|
|
DocBook sources to other formats, such as
|
|
<acronym>HTML</acronym>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
|
|
<listitem>
|
|
<para>
|
|
This optional package is used to create man pages. It has a
|
|
number of prerequisite packages of its own. Check the web
|
|
site.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>JadeTeX</term>
|
|
<listitem>
|
|
<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>. This will generate printed
|
|
output that is inferior to what you get from the
|
|
<acronym>RTF</acronym> backend. Tables are a particular
|
|
problem area. Also, there is no opportunity to manually polish
|
|
the results. 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>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
We have documented experience with several installation methods for
|
|
the various tools that are needed to process the documentation.
|
|
These will be described below. There may be some other packaged
|
|
distributions for these tools. Please report package status to the
|
|
docs mailing list and we will include that information here.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
|
|
|
|
<para>
|
|
Many vendors provide a complete RPM set for DocBook processing in
|
|
their distribution, which is usually based on the <ulink
|
|
url="http://sources.redhat.com/docbook-tools/">docbook-tools</ulink>
|
|
effort at Red Hat Software. Look for an <quote>SGML</quote>
|
|
option while installing, or the following packages:
|
|
<filename>sgml-common</filename>, <filename>docbook</filename>,
|
|
<filename>stylesheets</filename>, <filename>openjade</filename>
|
|
(or <filename>jade</filename>). Possibly
|
|
<filename>sgml-tools</filename> will be needed as well. If your
|
|
distributor does not provide these then you should be able to make
|
|
use of the packages from some large, reasonably compatible vendor.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>FreeBSD Installation</title>
|
|
|
|
<para>
|
|
The FreeBSD Documentation Project is itself a heavy user of
|
|
DocBook, so it comes as no surprise that there is a full set of
|
|
<quote>ports</quote> of the documentation tools available on
|
|
FreeBSD. The following ports need to be installed to build the
|
|
documentation on FreeBSD.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><filename>textproc/sp</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/openjade</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/docbook-310</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/iso8879</filename></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><filename>textproc/dsssl-docbook-modular</filename></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
A number of things from <filename>/usr/ports/print</filename>
|
|
(<filename>tex</filename>, <filename>jadetex</filename>) might
|
|
also be of interest.
|
|
</para>
|
|
|
|
<para>
|
|
It's possible that the ports do not update the main catalog file
|
|
in <filename>/usr/local/share/sgml/catalog</filename>. Be sure to
|
|
have the following line in there:
|
|
<programlisting>
|
|
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
|
|
</programlisting>
|
|
If you do not want to edit the file you can also set the
|
|
environment variable <envar>SGML_CATALOG_FILES</envar> to a
|
|
colon-separated list of catalog files (such as the one above).
|
|
</para>
|
|
|
|
<para>
|
|
More information about the FreeBSD documentation tools can be
|
|
found in the <ulink
|
|
url="http://www.freebsd.org/tutorials/docproj-primer/tools.html">FreeBSD
|
|
Documentation Project's instructions</ulink>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Debian Packages</title>
|
|
|
|
<para>
|
|
There is a full set of packages of the documentation tools
|
|
available for <productname>Debian GNU/Linux</productname>.
|
|
To install, simply use:
|
|
<programlisting>
|
|
apt-get install jade
|
|
apt-get install docbook
|
|
apt-get install docbook-stylesheets
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Manual Installation from Source</title>
|
|
|
|
<para>
|
|
The manual installation process of the DocBook tools is somewhat
|
|
complex, so if you have pre-built packages available, use them.
|
|
We describe here only a standard setup, with reasonabley standard
|
|
installation paths, and no <quote>fancy</quote> features. For
|
|
details, you should study the documentation of the respective
|
|
package, and read <acronym>SGML</acronym> introductory material.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title>Installing Jade</title>
|
|
|
|
<para>
|
|
The installation of OpenJade offers a GNU-style
|
|
<literal>./configure; make; make install</literal> build process.
|
|
Details can be found in the OpenJade source distribution. In a
|
|
nutshell:
|
|
<synopsis>
|
|
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
|
|
make
|
|
make install
|
|
</synopsis>
|
|
Be sure to remember where you put the <quote>default
|
|
catalog</quote>; you will need it below. You can also leave it
|
|
off, but then you will have to set the environment variable
|
|
<envar>SGML_CATALOG_FILES</envar> to point to the file whenever
|
|
you use <application>jade</application> later on.
|
|
</para>
|
|
|
|
<para>
|
|
Additionally, you should install the files
|
|
<filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
|
|
<filename>style-sheet.dtd</filename>, and
|
|
<filename>catalog</filename> from the <filename>dsssl</filename>
|
|
directory somewhere, perhaps into
|
|
<filename>/usr/local/share/sgml/dsssl</filename>. (Or just copy
|
|
the entire directory.)
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
Obtain the <ulink
|
|
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">DocBook
|
|
V3.1</ulink> distribution.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Unpack the archive.
|
|
<screen>
|
|
<prompt>$ </prompt><userinput>unzip -a docbk31.zip</userinput>
|
|
</screen>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Place the files into the directory
|
|
<filename>/usr/local/share/sgml/docbook31</filename>. (The
|
|
exact location is irrelevant, but this one is fairly standard.)
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Create a file
|
|
<filename>/usr/local/share/sgml/catalog</filename> (or whatever
|
|
you told jade during installation) and put a line like this
|
|
into it:
|
|
<programlisting>
|
|
CATALOG "docbook31/docbook.cat"
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Optionally, you can edit the file
|
|
<filename>docbook.cat</filename> and comment out or remove the
|
|
line containing <literal>DTDDECL</literal>. If you do not then
|
|
you will get warnings from <application>jade</application>, but
|
|
there is no further harm.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Download the <ulink
|
|
url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879
|
|
character entities</ulink> archive, unpack it, and put the
|
|
files in the same directory you put the DocBook files in.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
|
|
|
|
<para>
|
|
To install the style sheets, simply unzip the distribution kit in
|
|
a suitable place, for example
|
|
<filename>/usr/local/share/sgml/stylesheets</filename>. (The
|
|
archive will automatically create a <filename>docbook</filename>
|
|
subdirectory.)
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Installing <productname>JadeTeX</productname></title>
|
|
|
|
<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 <quote>the 35 fonts</quote>, 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 <ulink
|
|
url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> 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>
|
|
\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>
|
|
It is quite likely that when you use
|
|
<productname>JadeTeX</productname> with
|
|
<productname>PostgreSQL</productname> documentation sources, that
|
|
<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>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-build">
|
|
<title>Building The Documentation</title>
|
|
|
|
<para>
|
|
Before you can build the documentation you need to run the
|
|
<filename>configure</filename> script as you would when building
|
|
the programs themselves. Check the output near the end of the run,
|
|
it should look something like this:
|
|
<screen>
|
|
<computeroutput>
|
|
checking for onsgmls... onsgmls
|
|
checking for openjade... openjade
|
|
checking for DocBook V3.1... yes
|
|
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
|
|
checking for sgmlspl... sgmlspl
|
|
</computeroutput>
|
|
</screen>
|
|
If neither <filename>onsgmls</filename> nor
|
|
<filename>nsgmls</filename> were found then you will not see the
|
|
remaining 4 lines. <filename>nsgmls</filename> is part of the Jade
|
|
package. If <quote>DocBook V3.1</quote> was not found then you did
|
|
not install the DocBook DTD kit in a place where jade can find it,
|
|
or you have not set up the catalog files correctly. See the
|
|
installation hints above. The DocBook stylesheets are looked for
|
|
in a number of relatively standard places, but if you have them
|
|
some other place then you should set the environment variable
|
|
<envar>DOCBOOKSTYLE</envar> to the location and rerun
|
|
<filename>configure</filename> afterwards.
|
|
</para>
|
|
|
|
<para>
|
|
Once you have everything set up, change to the directory
|
|
<filename>doc/src/sgml</filename> and run one of the following
|
|
commands: (Remember to use GNU make.)
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
To build the <acronym>HTML</acronym> version of the
|
|
<citetitle>Administrator's Guide</citetitle>:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.html</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
For the RTF version of the same:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.rtf</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
To get a <acronym>DVI</acronym> version via
|
|
<productname>JadeTeX</productname>:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.dvi</userinput>
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
And Postscript from the <acronym>DVI</acronym>:
|
|
<screen>
|
|
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.ps</userinput>
|
|
</screen>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The official Postscript format documentation is generated
|
|
differently. See <xref linkend="doc-hardcopy"> below.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
The other books can be built with analogous commands by replacing
|
|
<literal>admin</literal> with one of <literal>developer</literal>,
|
|
<literal>programmer</literal>, <literal>tutorial</literal>, or
|
|
<literal>user</literal>. Using <literal>postgres</literal> builds
|
|
an integrated version of all 5 books, which is practical since the
|
|
browser interface makes it easy to move around all of the
|
|
documentation by just clicking.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>HTML</title>
|
|
|
|
<para>
|
|
When building <acronym>HTML</acronym> documentation in
|
|
<filename>doc/src/sgml</filename>, some of the resulting files
|
|
will possibly (or quite certainly) have conflicting names between
|
|
books. Therefore the files are not in that directory in the
|
|
regular distribution. Instead, the files belonging to each book
|
|
are stored in a tar archive that is unpacked at installation time.
|
|
To create a set of <acronym>HTML</acronym> documentation packages
|
|
use the commands
|
|
<programlisting>
|
|
cd doc/src
|
|
gmake tutorial.tar.gz
|
|
gmake user.tar.gz
|
|
gmake admin.tar.gz
|
|
gmake programmer.tar.gz
|
|
gmake postgres.tar.gz
|
|
gmake install
|
|
</programlisting>
|
|
In the distribution, these archives live in the
|
|
<filename>doc</filename> directory and are installed by default
|
|
with <command>gmake install</command>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="doc-manpages">
|
|
<title>Manpages</title>
|
|
|
|
<para>
|
|
We use the <application>docbook2man</application> utility to
|
|
convert <productname>DocBook</productname>
|
|
<sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man
|
|
pages. The man pages are also distributed as a tar archive,
|
|
similar to the <acronym>HTML</acronym> version. To create the man page package, use the commands
|
|
<programlisting>
|
|
cd doc/src
|
|
gmake man
|
|
</programlisting>
|
|
which will result in a tar file being generated in the
|
|
<filename>doc/src</filename> directory.
|
|
</para>
|
|
|
|
<para>
|
|
The man build leaves a lot of confusing output, and special care
|
|
must be taken to produce quality results. There is still room for
|
|
improvement in this area.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="doc-hardcopy">
|
|
<title>Hardcopy Generation</title>
|
|
|
|
<para>
|
|
The hardcopy Postscript documentation is generated by converting the
|
|
<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
|
|
importing into <productname>ApplixWare-4.4.1</productname>.
|
|
After a little cleanup (see the following
|
|
section) the output is "printed" to a postscript file.
|
|
</para>
|
|
|
|
<!--
|
|
<para>
|
|
Some figures were redrawn to avoid having bitmap
|
|
<acronym>GIF</acronym> files in the hardcopy documentation. One
|
|
figure, of the system catalogs, was sufficiently complex that there
|
|
was not time to redraw it. It was converted to fit using the
|
|
following commands:
|
|
|
|
<programlisting>
|
|
% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
|
|
% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
|
|
</programlisting>
|
|
|
|
</para>
|
|
-->
|
|
|
|
<para>
|
|
Several areas are addressed while generating Postscript
|
|
hardcopy, including RTF repair, ToC generation, and page break
|
|
adjustments.
|
|
</para>
|
|
|
|
<procedure>
|
|
<title>Applixware <acronym>RTF</acronym> Cleanup</title>
|
|
|
|
<para>
|
|
<application>jade</application>, an integral part of the
|
|
hardcopy procedure, omits specifying a default style for body
|
|
text. In the past, this undiagnosed problem led to a long process
|
|
of Table of Contents (ToC) generation. However, with great help
|
|
from the ApplixWare folks the symptom was diagnosed and a
|
|
workaround is available.
|
|
</para>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Generate the <acronym>RTF</acronym> input by typing (for example):
|
|
<programlisting>
|
|
% cd doc/src/sgml
|
|
% make tutorial.rtf
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Repair the RTF file to correctly specify all
|
|
styles, in particular the default style. The field can be added
|
|
using <application>vi</application> or the following small
|
|
<application>sed</application> procedure:
|
|
|
|
<programlisting>
|
|
#!/bin/sh
|
|
# fixrtf.sh
|
|
# Utility to repair slight damage in RTF files generated by jade
|
|
# Thomas Lockhart <lockhart@alumni.caltech.edu>
|
|
#
|
|
for i in $* ; do
|
|
mv $i $i.orig
|
|
cat $i.orig | sed 's#\\stylesheet#\\stylesheet{\\s0 Normal;}#' > $i
|
|
done
|
|
|
|
exit
|
|
</programlisting>
|
|
|
|
where the script is adding <literal>{\s0 Normal;}</literal> as
|
|
the zero-th style in the document. According to ApplixWare, the
|
|
RTF standard would prohibit adding an implicit zero-th style,
|
|
though M$Word happens to handle this case.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Open a new document in <productname>Applix Words</productname> and
|
|
then import the <acronym>RTF</acronym> file.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Generate a new ToC using ApplixWare.
|
|
</para>
|
|
|
|
<substeps>
|
|
<step>
|
|
<para>
|
|
Select the existing ToC lines, from the beginning of the first
|
|
character on the first line to the last character of the last
|
|
line.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Build a new ToC using
|
|
<literal>Tools.BookBuilding.CreateToC</literal>. Select the
|
|
first three levels of headers for inclusion in the ToC.
|
|
This will
|
|
replace the existing lines imported in the RTF with a native
|
|
ApplixWare ToC.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Adjust the ToC formatting by using
|
|
<literal>Format.Style</literal>, selecting each of the three
|
|
ToC styles, and adjusting the indents for <literal>First</literal> and
|
|
<literal>Left</literal>. Use the following values:
|
|
|
|
<table>
|
|
<title>Indent Formatting for Table of Contents</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
Style
|
|
</entry>
|
|
<entry>
|
|
First Indent (inches)
|
|
</entry>
|
|
<entry>
|
|
Left Indent (inches)
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<literal>TOC-Heading 1</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>0.6</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>0.6</literal>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<literal>TOC-Heading 2</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>1.0</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>1.0</literal>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<literal>TOC-Heading 3</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>1.4</literal>
|
|
</entry>
|
|
<entry>
|
|
<literal>1.4</literal>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Work through the document to:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Adjust page breaks.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Adjust table column widths.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Insert figures into the document. Center each figure on the page using
|
|
the centering margins button on the ApplixWare toolbar.
|
|
|
|
<note>
|
|
<para>
|
|
Not all documents have figures.
|
|
You can grep the <acronym>SGML</acronym> source files for
|
|
the string "<literal>graphic</literal>" to identify those parts of the
|
|
documentation which may have figures. A few figures are replicated in
|
|
various parts of the documentation.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Replace the right-justified page numbers in the Examples and
|
|
Figures portions of the ToC with
|
|
correct values. This only takes a few minutes per document.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
If a bibliography is present, remove the <firstterm>short
|
|
form</firstterm> reference title from each entry. The
|
|
<productname>DocBook</productname> stylesheets from Norm Walsh
|
|
seem to print these out, even though this is a subset of the
|
|
information immediately following.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Save the document as native Applix Words format to allow easier last
|
|
minute editing later.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
"Print" the document
|
|
to a file in Postscript format.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Compress the Postscript file using <application>gzip</application>.
|
|
Place the compressed file into the <filename>doc</filename> directory.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Plain Text Files</title>
|
|
|
|
<para>
|
|
Several files are distributed as plain text, for reading during
|
|
the installation process. The <filename>INSTALL</filename> file
|
|
corresponds to the chapter in the <citetitle>Administrator's
|
|
Guide</citetitle>, with some minor changes to account for the
|
|
different context. To recreate the file, change to the directory
|
|
<filename>doc/src/sgml</filename> and enter <userinput>gmake
|
|
INSTALL</userinput>. This will create a file
|
|
<filename>INSTALL.html</filename> that can be saved as text with
|
|
<productname>Netscape Navigator</productname> and put into the
|
|
place of the existing file. <productname>Netscape</productname>
|
|
seems to offer the best quality for <acronym>HTML</acronym> to
|
|
text conversions (over <application>lynx</application> and
|
|
<application>w3m</application>).
|
|
</para>
|
|
|
|
<para>
|
|
The file <filename>HISTORY</filename> can be created similarly,
|
|
using the command <userinput>gmake HISTORY</userinput>. The table
|
|
of contents should be removed manually from the resulting text
|
|
file.
|
|
</para>
|
|
|
|
<para>
|
|
Since it does not change very often, the generation of the file
|
|
<filename>src/test/regress/README</filename> is not fully
|
|
automated. After building the <acronym>HTML</acronym> version of
|
|
the <citetitle>Administrator's Guide</citetitle>, convert the
|
|
resulting files <filename>regress.htm</filename> and
|
|
<filename>regress-platform.htm</filename> to text, using
|
|
<productname>Netscape</productname>. Then paste the text files
|
|
together and edit them to taste (e.g., remove the navigation
|
|
bars, remove the references to other chapters).
|
|
</para>
|
|
|
|
<!--
|
|
* This is how you can create text files via RTF and ApplixWare,
|
|
* for historical reference.
|
|
|
|
<procedure>
|
|
<title>Plain Text Generation</title>
|
|
|
|
<para>
|
|
Both <filename>INSTALL</filename> and
|
|
<filename>HISTORY</filename> are generated from existing
|
|
<acronym>SGML</acronym> sources. They are extracted from the same
|
|
intermediate <acronym>RTF</acronym> file.
|
|
</para>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Generate <acronym>RTF</acronym> by typing:
|
|
<programlisting>
|
|
% cd doc/src/sgml
|
|
% make installation.rtf
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Import <filename>installation.rtf</filename> into
|
|
<productname>Applix Words</productname>.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Set the page width and margins.
|
|
</para>
|
|
|
|
<substeps>
|
|
<step performance="required">
|
|
<para>
|
|
Adjust the page width in File.PageSetup to 10 inches.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Select all text.
|
|
Adjust the right margin using the ruler to 9.5 inches. This
|
|
will give a maximum column width of 79 characters, within the
|
|
80 columns upper limit goal.
|
|
</para>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Lop off the parts of the document which are not needed.
|
|
</para>
|
|
|
|
<para>
|
|
For <filename>INSTALL</filename>, remove all release notes from
|
|
the end of the text, except for those from the current release.
|
|
For <filename>HISTORY</filename>, remove all text up to the
|
|
release notes, preserving and modifying the title and ToC.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Export the result as "ASCII Layout".
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
Using emacs or vi, clean up the tabular information in
|
|
<filename>INSTALL</filename>. Remove the "mailto"
|
|
<acronym>URLs</acronym> for the porting contributors to shrink
|
|
the column heights.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
-->
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="doc-sources">
|
|
<title>Documentation Authoring</title>
|
|
|
|
<para>
|
|
<acronym>SGML</acronym> and <productname>DocBook</productname> do
|
|
not suffer from an oversupply of open-source authoring tools. The
|
|
most common toolset is the
|
|
<productname>Emacs</productname>/<productname>XEmacs</productname>
|
|
editor with appropriate editing mode. On some systems
|
|
(e.g., RedHat Linux) these tools are provided in a typical full
|
|
installation.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Emacs/PSGML</title>
|
|
|
|
<para>
|
|
<productname>PSGML</productname> is the most common and most
|
|
powerful mode for editing <acronym>SGML</acronym> documents.
|
|
When properly configured, it will allow you to use
|
|
<application>Emacs</application> to insert tags and check markup
|
|
consistancy. You could use it for <acronym>HTML</acronym> as
|
|
well. Check the <ulink
|
|
url="http://www.lysator.liu.se/projects/about_psgml.html">PSGML
|
|
web site</ulink> for downloads, installation instructions, and
|
|
detailed documentation.
|
|
</para>
|
|
|
|
<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, either by setting
|
|
<envar>SGML_CATALOG_FILES</envar> environment variable, or you
|
|
can customize your <productname>PSGML</productname> installation
|
|
(its manual tells you how).
|
|
</para>
|
|
|
|
<para>
|
|
Put the following in your <filename>~/.emacs</filename>
|
|
environment file (adjusting the path names to be appropriate for
|
|
your system):
|
|
|
|
<programlisting>
|
|
; ********** for SGML mode (psgml)
|
|
|
|
(setq sgml-omittag t)
|
|
(setq sgml-shorttag t)
|
|
(setq sgml-minimize-attributes nil)
|
|
(setq sgml-always-quote-attributes t)
|
|
(setq sgml-indent-step 1)
|
|
(setq sgml-indent-data t)
|
|
(setq sgml-parent-document nil)
|
|
(setq sgml-default-dtd-file "./reference.ced")
|
|
(setq sgml-exposed-tags nil)
|
|
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
|
|
(setq sgml-ecat-files nil)
|
|
|
|
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
|
|
</programlisting>
|
|
|
|
and in the same file add an entry for <acronym>SGML</acronym>
|
|
into the (existing) definition for
|
|
<varname>auto-mode-alist</varname>:
|
|
<programlisting>
|
|
(setq
|
|
auto-mode-alist
|
|
'(("\\.sgml$" . sgml-mode)
|
|
))
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Currently, each <acronym>SGML</acronym> source file has the
|
|
following block at the end of the file:
|
|
|
|
<programlisting>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|
|
</programlisting>
|
|
This will set up a number of editing mode parameters even if you
|
|
do not set up your <filename>~/.emacs</filename> file, but it is
|
|
a bit unfortunate, since if you followed the installation
|
|
instructions above, then the catalog path will not match your
|
|
location. Hence you might need to turn off local variables:
|
|
<programlisting>
|
|
(setq inhibit-local-variables t)
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The <productname>PostgreSQL</productname> distribution includes a
|
|
parsed DTD definitions file <filename>reference.ced</filename>.
|
|
You may find that when using PSGML, a comfortable way of working
|
|
with these separate files of book parts is to insert a proper
|
|
<literal>DOCTYPE</literal> declaration while you're editing them.
|
|
If you are working on this source, for instance, it is an
|
|
appendix chapter, so you would specify the document as an
|
|
<quote>appendix</quote> instance of a DocBook document by making
|
|
the first line look like this:
|
|
|
|
<programlisting>
|
|
<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
|
</programlisting>
|
|
|
|
This means that anything and everything that reads
|
|
<acronym>SGML</acronym> will get it right, and I can verify the
|
|
document with <command>nsgmls -s docguide.sgml</command>. (But
|
|
you need to take out that line before building the entire
|
|
documentation set.)
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Other Emacs modes</title>
|
|
|
|
<para>
|
|
<productname>GNU Emacs</productname> ships with a different SGML
|
|
mode, which is not quite as powerful as
|
|
<productname>PSGML</productname>, but it's less confusing and
|
|
lighter weight. Also, it offers syntax highlighting (font lock),
|
|
which can be very helpful.
|
|
</para>
|
|
|
|
<para>
|
|
Norm Walsh offers a major <ulink
|
|
url="http://nwalsh.com/emacs/docbookide/index.html">mode
|
|
specifically for DocBook</ulink> which also has font-lock and a
|
|
number of features to reduce typing.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
</appendix>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode:sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|