PostgreSQL: Documentation: 9.1: Tool Sets

PostgreSQL: Documentation: 9.1: Tool Sets

时间:2015-07-10 21:52来源:网络整理 作者:KKWL 点击:
I.2. Tool Sets The following tools are used to process the documentation. Some might be optional, as noted. DocBook DTD This is the definition of DocBook itself. We currentlyuse version 4.2; you cannot use later or earlier versions.You need

I.2. Tool Sets

The following tools are used to process the documentation. Some might be optional, as noted.

DocBook DTD

This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need the SGML variant of the DocBook DTD, but to build man pages you also need the XML variant of the same version.

ISO 8879 character entities

These are required by DocBook but are distributed separately because they are maintained by ISO.

DocBook DSSSL Stylesheets

These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.

DocBook XSL Stylesheets

This is another stylesheet for converting DocBook to other formats. We currently use this to produce man pages and optionally HTMLHelp. You can also use this toolchain to produce HTML or PDF output, but official PostgreSQL releases use the DSSSL stylesheets for that.

OpenJade

This is the base package of SGML processing. It contains an SGML parser, a DSSSL processor (that is, a program to convert SGML to other formats using DSSSL stylesheets), as well as a number of related tools. Jade is now being maintained by the OpenJade group, no longer by James Clark.

Libxslt for xsltproc

This is the processing tool to use with the XSLT stylesheets (like jade is the processing tool for DSSSL stylesheets).

JadeTeX

If you want to, you can also install JadeTeX to use TeX as a formatting backend for Jade. JadeTeX can create PostScript or PDF files (the latter with bookmarks).

However, the output from JadeTeX is inferior to what you get from the RTF backend. Particular problem areas are tables and various artifacts of vertical and horizontal spacing. Also, there is no opportunity to manually polish the results.

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 might be some other packaged distributions for these tools. Please report package status to the documentation mailing list, and we will include that information here.

I.2.1. Linux RPM Installation

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 sgml-tools 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 other, reasonably compatible vendor.

I.2.2. FreeBSD Installation

The FreeBSD Documentation Project is itself a heavy user of DocBook, so it comes as no surprise that there is a full set of "ports" of the documentation tools available on FreeBSD. The following ports need to be installed to build the documentation on FreeBSD.

  • textproc/sp

  • textproc/openjade

  • textproc/iso8879

  • textproc/dsssl-docbook-modular

  • textproc/docbook-420

  • A number of things from /usr/ports/print (tex, jadetex) might also be of interest.

    It's possible that the ports do not update the main catalog file in /usr/local/share/sgml/catalog.ports or that the order isn't proper. Be sure to have the following lines in the beginning of the file:

    CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"

    If you do not want to edit the file you can also set the environment variable SGML_CATALOG_FILES to a colon-separated list of catalog files (such as the one above).

    More information about the FreeBSD documentation tools can be found in the FreeBSD Documentation Project's instructions.

    I.2.3. Debian Packages

    There is a full set of packages of the documentation tools available for Debian GNU/Linux. To install, simply use:

    apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 xsltproc

    I.2.4. Manual Installation from Source

    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 reasonably standard installation paths, and no "fancy" features. For details, you should study the documentation of the respective package, and read SGML introductory material.

    I.2.4.1. Installing OpenJade

  • The installation of OpenJade offers a GNU-style ./configure; make; make install build process. Details can be found in the OpenJade source distribution. In a nutshell:

    ./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
  • ------分隔线----------------------------