- url="http://sources.redhat.com/docbook-tools/">docbook-tools
- effort at Red Hat Software. Look for an SGML
- option while installing, or the following packages:
+ Most vendors provide a complete RPM set for DocBook processing in
+ their distribution. Look for an SGML
option while
+ installing, or the following packages:
sgml-common, docbook,
stylesheets, openjade
(or jade). Possibly
Because stylesheets change rather often, and it's sometimes
beneficial to try out alternative versions,
PostgreSQL doesn't use this catalog
- entry. See -build"> for information about how
- to select the stylesheets instead.
+ entry. See guide-toolsets-configure"> for
+ information about how to select the stylesheets instead.
-
-
-
-
Building The Documentation
+
+
Detection by <command>configure</command>
Before you can build the documentation you need to run the
configure script as you would when building
- the programs themselves. Check the output near the end of the run,
- it should look something like this:
+ the PostgreSQL programs themselves. Check the output near the end
+ of the run, it should look something like this:
checking for onsgmls... onsgmls
configure afterwards.
+
+
+
+
+
Building The Documentation
+
Once you have everything set up, change to the directory
- doc/src/sgml and run one of the following
- commands: (Remember to use GNU make.)
-
-
- To build the
HTML version of the
- Administrator's Guide:
-
-
doc/src/sgml$ gmake admin.html-
-
-
-
-
- For the RTF version of the same:
-
-
doc/src/sgml$ gmake admin.rtf-
-
-
+ doc/src/sgml and run one of the commands
+ described in the following subsections to build the
+ documentation. (Remember to use GNU make.)
+
-
- To get a
DVI version via
-
-
doc/src/sgml$ gmake admin.dvi-
-
-
+
+
HTML
-
- And Postscript from the
DVI:
+ To build the
HTML version of the documentation:
-
doc/src/sgml$ gmake admin.ps+
doc/src/sgml$ gmake html
-
-
- The official Postscript format documentation is generated
- differently. See below.
-
-
-
-
-
- The other books can be built with analogous commands by replacing
- admin with one of developer,
- programmer, tutorial, or
- user. Using postgres 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.
-
+ This is also the default target.
+
-
-
HTML
+ When the HTML documentation is built, the process also generates
+ the linking information for the index entries. Thus, if you want
+ your documentation to have a concept index at the end, you need to
+ build the HTML documentation once, and then build the
+ documentation again in whatever format you like.
+
- When building
HTML documentation in
- doc/src/sgml, 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
HTML documentation packages
- use the commands
+ To allow for easier handling in the final distribution, the files
+ comprising the HTML documentation are stored in a tar archive that
+ is unpacked at installation time. To create the
+
HTML documentation package, use the commands
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
In the distribution, these archives live in the
doc directory and are installed by default
- id="doc-manpages">
+
Manpages
We use the
docbook2man utility to
- REFENTRY pages to *roff output suitable for man
+ refentry pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive,
- similar to the
HTML version. To create the man page package, use the commands
+ similar to the
HTML version. To create the man
+ page package, use the commands
cd doc/src
-gmake man
+gmake man.tar.gz
which will result in a tar file being generated in the
doc/src directory.
- 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.
+ To generate quality man pages, it might be necessary to use a
+ hacked version of the conversion utility or do some manual
+ postprocessing. All man pages should be manually inspected before
+ distribution.
- >
- Hardcopy Generation</span>
+ >
+ Print Output via <application>JadeTex</application></span>
- The hardcopy Postscript documentation is generated by converting the
-
SGML source code to
RTF, then
- importing into
Applixware.
- After a little cleanup (see the following
- section) the output is printed
to a postscript file.
-
+ If you want to use
JadeTex to produce a
+ printable rendition of the documentation, you can use one of the
+ following commands:
-
-
Delete the index section from the document if it is empty.
- Select the ToC field.
-
+ Select the ToC field.
+
- Select
- Tools->Book Building->Create Table of
- Contents.
-
+ Select ToolsBook
+ Building>Create Table of
+ Contents.
+
- Unbind the ToC by selecting
- Tools->Field Editing->Unprotect.
-
+ Unbind the ToC by selecting
+ ToolsField
+ EditingUnprotect.
+
- Delete the first line in the ToC, which is an entry for the
- ToC itself.
-
+ Delete the first line in the ToC, which is an entry for the
+ ToC itself.
+
- Save the document as native
Applixware Words format to allow easier last
- minute editing later.
+ Save the document as native
Applixware+ Words format to allow easier last minute editing
+ later.
to a file in Postscript format.
-
-
- Compress the Postscript file using
gzip.
- Place the compressed file into the doc directory.
-
-
Several files are distributed as plain text, for reading during
the installation process. The INSTALL file
- corresponds to the chapter in the Administrator's
- Guide, with some minor changes to account for the
- different context. To recreate the file, change to the directory
- doc/src/sgml and enter gmake
- INSTALL. This will create a file
- INSTALL.html that can be saved as text with
-
Netscape Navigator and put into the
- place of the existing file.
Netscape- seems to offer the best quality for
HTML to
-
text conversions (over lynx and
+ corresponds to , with some minor
+ changes to account for the different context. To recreate the
+ file, change to the directory doc/src/sgml
+ and enter gmake INSTALL. This will create
+ a file INSTALL.html that can be saved as text
+ with
Netscape Navigator and put into
+ the place of the existing file.
+
Netscape seems to offer the best
+ quality for
HTML to text conversions (over
file src/test/regress/README the command is
gmake regress_README.
+
-
+
+
Syntax Check
+ Building the documentation can take very long. But there is a
+ method to just check the correct syntax of the documentation
+ files, which only takes a few seconds:
+
+
doc/src/sgml$ gmake check+
+
- -sources">
+ guide-authoring">
Documentation Authoring
the first line look like this:
-<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
This means that anything and everything that reads
-
+ guide-style">
Style Guide
projects / postgresql.git / commitdiff