begriffs open source - ai-pg/blob - full-docs/txt/docguide-toolsets.txt

   1
   2 J.2. Tool Sets #
   3
   4    J.2.1. Installation on Fedora, RHEL, and Derivatives
   5    J.2.2. Installation on FreeBSD
   6    J.2.3. Debian Packages
   7    J.2.4. macOS
   8    J.2.5. Detection by configure
   9
  10    The following tools are used to process the documentation. Some might
  11    be optional, as noted.
  12
  13    DocBook DTD #
  14           This is the definition of DocBook itself. We currently use
  15           version 4.5; you cannot use later or earlier versions. You need
  16           the XML variant of the DocBook DTD, not the SGML variant.
  17
  18    DocBook XSL Stylesheets #
  19           These contain the processing instructions for converting the
  20           DocBook sources to other formats, such as HTML.
  21
  22           The minimum required version is currently 1.77.0, but it is
  23           recommended to use the latest available version for best
  24           results.
  25
  26    Libxml2 for xmllint #
  27           This library and the xmllint tool it contains are used for
  28           processing XML. Many developers will already have Libxml2
  29           installed, because it is also used when building the PostgreSQL
  30           code. Note, however, that xmllint might need to be installed
  31           from a separate subpackage.
  32
  33    Libxslt for xsltproc #
  34           xsltproc is an XSLT processor, that is, a program to convert XML
  35           to other formats using XSLT stylesheets.
  36
  37    FOP #
  38           This is a program for converting, among other things, XML to
  39           PDF. It is needed only if you want to build the documentation in
  40           PDF format.
  41
  42    We have documented experience with several installation methods for the
  43    various tools that are needed to process the documentation. These will
  44    be described below. There might be some other packaged distributions
  45    for these tools. Please report package status to the documentation
  46    mailing list, and we will include that information here.
  47
  48 J.2.1. Installation on Fedora, RHEL, and Derivatives #
  49
  50    To install the required packages, use:
  51 yum install docbook-dtds docbook-style-xsl libxslt fop
  52
  53 J.2.2. Installation on FreeBSD #
  54
  55    To install the required packages with pkg, use:
  56 pkg install docbook-xml docbook-xsl libxslt fop
  57
  58    When building the documentation from the doc directory you'll need to
  59    use gmake, because the makefile provided is not suitable for FreeBSD's
  60    make.
  61
  62 J.2.3. Debian Packages #
  63
  64    There is a full set of packages of the documentation tools available
  65    for Debian GNU/Linux. To install, simply use:
  66 apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
  67
  68 J.2.4. macOS #
  69
  70    If you use MacPorts, the following will get you set up:
  71 sudo port install docbook-xml docbook-xsl-nons libxslt fop
  72
  73    If you use Homebrew, use this:
  74 brew install docbook docbook-xsl libxslt fop
  75
  76    The Homebrew-supplied programs require the following environment
  77    variable to be set. For Intel based machines, use this:
  78 export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
  79
  80    On Apple Silicon based machines, use this:
  81 export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
  82
  83    Without it, xsltproc will throw errors like this:
  84 I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml
  85 /4.5/docbookx.dtd
  86 postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open
  87 .org/docbook/xml/4.5/docbookx.dtd"
  88 ...
  89
  90    While it is possible to use the Apple-provided versions of xmllint and
  91    xsltproc instead of those from MacPorts or Homebrew, you'll still need
  92    to install the DocBook DTD and stylesheets, and set up a catalog file
  93    that points to them.
  94
  95 J.2.5. Detection by configure #
  96
  97    Before you can build the documentation you need to run the configure
  98    script, as you would when building the PostgreSQL programs themselves.
  99    Check the output near the end of the run; it should look something like
 100    this:
 101 checking for xmllint... xmllint
 102 checking for xsltproc... xsltproc
 103 checking for fop... fop
 104 checking for dbtoepub... dbtoepub
 105
 106    If xmllint or xsltproc is not found, you will not be able to build any
 107    of the documentation. fop is only needed to build the documentation in
 108    PDF format. dbtoepub is only needed to build the documentation in EPUB
 109    format.
 110
 111    If necessary, you can tell configure where to find these programs, for
 112    example
 113 ./configure ... XMLLINT=/opt/local/bin/xmllint ...
 114
 115    If you prefer to build PostgreSQL using Meson, instead run meson setup
 116    as described in Section 17.4, and then see Section J.4.