Вся предоставленная на этом сервере информация собрана нами из разных источников. Если Вам кажется, что публикация каких-то документов нарушает чьи-либо авторские права, сообщите нам об этом.
We have documented experience with three installation methods for the
various tools that are needed to process the documentation. One is
installation from RPMs on
Linux, the second is installation from
FreeBSD port, and the last is a general installation
from original distributions of the individual tools. 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.
The simplest installation for a RedHat-compatible Linux system
uses the RPM set developed by Mark Galassi at
Cygnus. It should also be possible to install from sources, as
described in a subsequent section.
Install Norm Walsh's latest style sheets. Depending on the age
of the RPMs, the latest style sheets may be substantially
improved from those contained in the RPMs.
Update your src/Makefile.custom to include
HSTYLE and PSTYLE definitions pointing to the style sheets.
There is a full set of ports of the
documentation tools available on FreeBSD. In fact, postgresql.org,
on which documentation is automatically updated every evening, is
a FreeBSD machine.
Installing FreeBSD Ports
To build the documentation on FreeBSD a number of ports will need to
be installed.
% cd /usr/ports/devel/gmake && make install
% cd /usr/ports/textproc/docproj && make install
% cd /usr/ports/textproc/docbook && make install
% cd /usr/ports/textproc/dsssl-docbook-modular && make install
Set environment variables
to access the jade
toolset.
Note: This was not required for the FreeBSD machine at
postgresql.org, so you may not have to do this.
This is a brief run-through of the process of obtaining and
installing the software you'll need to edit DocBook source with Emacs
and process it with Norman Walsh's DSSSL style sheets to create
HTML and RTF.
The easiest way to obtain the SGML and DocBook tools may be to get
sgmltools from
sgmltools.
sgmltools requires the GNU version of
m4. To confirm that you have the
correct version of m4 available, try
gnum4 --version
If you install GNU m4, install it with the name gnum4 and
sgmltools will find it.
After the install, you will
have sgmltools,
jade,
and Norm Walsh's DocBook
style sheets. The instructions below are for installing these tools
separately.
Read the installation instructions at the above listed
URL.
Unzip the distribution kit in a suitable place. The command to do
this will be something like
unzip -aU jade1_1.zip
Jade is not built using
GNU autoconf, so you'll need to edit a
Makefile yourself. Since James Clark has been
good enough to prepare his kit for it, it is a good idea to make a
build directory (named for your machine architecture, perhaps) under
the main directory of the Jade
distribution, copy the file Makefile from the
main directory into it, edit it there, and then run
make there.
However, the Makefile does need to be
edited. There is a file called Makefile.jade in
the main directory, which is intended to be used with make -f
Makefile.jade when building Jade
(as opposed to just SP,
the SGML parser kit
that Jade is built upon). We suggest that
you don't do that, though, since there is more that you need to change
than what is in Makefile.jade, so you'd have to
edit one of them anyway.
Go through the Makefile, reading James'
instructions and editing as needed. There are various variables that
need to be set. Here is a collected summary of the most important
ones, with typical values:
Note the specification of where to find the default catalog of
SGML support files -- you may want to change that
to something more suitable for your own installation. If your system
doesn't need the above settings for the math library and the
ranlib command, leave them as they are in the
Makefile.
Type make to build Jade and the various
SP tools.
Once the software is built, make install will
do the obvious.
You'll want to place the files that make up the
DocBookDTD kit in the
directory you built Jade to expect them in,
which, if you followed our suggestion above, is
/usr/local/share/sgml/. In addition to the
actual DocBook files, you'll need to have a
catalog file in place, for the mapping of
document type specifications and external entity references to actual
files in that directory. You'll also want the ISO
character set mappings, and probably one or more versions of
HTML.
One way to install the various DTD and
support files and set up the catalog file, is to
collect them all into the above mentioned directory, use a single file
named CATALOG to describe them all, and then
create the file catalog as a catalog pointer to
the former, by giving it the single line of content:
CATALOG /usr/local/share/sgml/CATALOG
The CATALOG file should then contain three types
of lines. The first is the (optional) SGML
declaration, thus:
SGMLDECL docbook.dcl
Next, the various references to DTD and entity
files must be resolved. For the DocBook
files, these lines look like this:
PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
Of course, a file containing these comes with the
DocBook kit. Note that the last item on
each of these lines is a file name, given here without a path. You
can put the files in subdirectories of your main
SGML directory if you like, of course, and modify
the reference in the CATALOG file.
DocBook also references the
ISO character set entities, so you need to fetch
and install these (they are available from several sources, and are
easily found by way of the URLs listed above), along with catalog
entries for all of them, such as:
PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
Note how the file name here contains a directory name, showing that
we've placed the ISO entity files in a subdirectory
named ISO. Again, proper catalog entries should
accompany the entity kit you fetch.
Read the installation instructions at the above listed
URL.
To install Norman's style sheets, simply unzip the distribution
kit in a suitable place. A good place to dot this would be
/usr/local/share, which places the kit in a
directory tree under /usr/local/share/docbook.
The command will be something like
unzip -aU db119.zip
One way to test the installation is to build the
HTML and RTF forms of the
PostgreSQL User's Guide.
To build the HTML files,
go to the SGML source
directory, doc/src/sgml, and say
There is one important thing to note with
PSGML: its author assumed that your main
SGMLDTD directory would be
/usr/local/lib/sgml. If, as in the examples in
this chapter, you use /usr/local/share/sgml, you
have to compensate for this.
You can set the
SGML_CATALOG_FILES environment variable.
You can
customize your PSGML installation (its
manual tells you how).
You can even edit the source file
psgml.el before compiling and installing
PSGML, changing the hard-coded paths to
match your own default.
If you want to, you can also install
JadeTeX to use
TeX as a formatting backend for
Jade. Note that this is still quite
unpolished software, and will generate printed output that is inferior
to what you get from the RTF backend. Still, it
works all right, especially for simpler documents that don't use
tables, and as both JadeTeX and the style
sheets are under continuous improvement, it will certainly get better
over time.
To install and use JadeTeX, you will
need a working installation of TeX and
LaTeX2e, including the supported
tools and
graphics packages,
Babel, AMS
fonts and AMS-LaTeX, the
PSNFSS extension and
companion kit of "the 35 fonts", the dvips
program for generating PostScript, the
macro packages fancyhdr,
hyperref,
minitoc, url and
ot2enc, and of course
JadeTeX itself. All of these can be found
on your friendly neighborhood CTAN site.
JadeTeX does not at the time of
writing come with much of an installation guide, but there is a
makefile which shows what is needed. It also
includes a directory cooked, wherein you'll find
some of the macro packages it needs, but not all, and not complete --
at least last we looked.
Before building the jadetex.fmt format
file, you'll probably want to edit the
jadetex.ltx file, to change the configuration of
Babel to suit your locality. The line to
change looks something like
and you should obviously list only the languages you actually need,
and have configured Babel for.
With JadeTeX working, you should be
able to generate and format TeX output for
the PostgreSQL manuals by giving the
commands (as above, in the doc/src/sgml
directory)
Of course, when you do this, TeX 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
JadeTeX generates cross referencing
information. TeX can, of course, be
compiled with larger data structure sizes. The details of this will
vary according to your installation.
