begriffs open source - ai-pg/blob - full-docs/src/sgml/html/docguide-toolsets.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.2. Tool Sets</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-docbook.html" title="J.1. DocBook" /><link rel="next" href="docguide-build.html" title="J.3. Building the Documentation with Make" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.2. Tool Sets</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-docbook.html" title="J.1. DocBook">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-build.html" title="J.3. Building the Documentation with Make">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-TOOLSETS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.2. Tool Sets <a href="#DOCGUIDE-TOOLSETS" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-INST-FEDORA-ET-AL">J.2.1. Installation on Fedora, RHEL, and Derivatives</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-INST-FREEBSD">J.2.2. Installation on FreeBSD</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-INST-DEBIAN">J.2.3. Debian Packages</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-INST-MACOS">J.2.4. macOS</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-CONFIGURE">J.2.5. Detection by <code class="command">configure</code></a></span></dt></dl></div><p>
   3    The following tools are used to process the documentation.  Some
   4    might be optional, as noted.
   5
   6    </p><div class="variablelist"><dl class="variablelist"><dt id="DOCGUIDE-TOOLSETS-DOCBOOK-DTD"><span class="term"><a class="ulink" href="https://www.oasis-open.org/docbook/" target="_top">DocBook DTD</a></span> <a href="#DOCGUIDE-TOOLSETS-DOCBOOK-DTD" class="id_link">#</a></dt><dd><p>
   7        This is the definition of DocBook itself.  We currently use version
   8        4.5; you cannot use later or earlier versions.  You need
   9        the <acronym class="acronym">XML</acronym> variant of the DocBook DTD, not
  10        the <acronym class="acronym">SGML</acronym> variant.
  11       </p></dd><dt id="DOCGUIDE-TOOLSETS-DOCBOOK-XSL"><span class="term"><a class="ulink" href="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets" target="_top">DocBook XSL Stylesheets</a></span> <a href="#DOCGUIDE-TOOLSETS-DOCBOOK-XSL" class="id_link">#</a></dt><dd><p>
  12        These contain the processing instructions for converting the
  13        DocBook sources to other formats, such as
  14        <acronym class="acronym">HTML</acronym>.
  15       </p><p>
  16        The minimum required version is currently 1.77.0, but it is recommended
  17        to use the latest available version for best results.
  18       </p></dd><dt id="DOCGUIDE-TOOLSETS-LIBXML2"><span class="term"><a class="ulink" href="http://xmlsoft.org/" target="_top">Libxml2</a> for <code class="command">xmllint</code></span> <a href="#DOCGUIDE-TOOLSETS-LIBXML2" class="id_link">#</a></dt><dd><p>
  19        This library and the <code class="command">xmllint</code> tool it contains are
  20        used for processing XML.  Many developers will already
  21        have <span class="application">Libxml2</span> installed, because it is also
  22        used when building the PostgreSQL code.  Note, however,
  23        that <code class="command">xmllint</code> might need to be installed from a
  24        separate subpackage.
  25       </p></dd><dt id="DOCGUIDE-TOOLSETS-LIBXSLT"><span class="term"><a class="ulink" href="http://xmlsoft.org/XSLT/" target="_top">Libxslt</a> for <code class="command">xsltproc</code></span> <a href="#DOCGUIDE-TOOLSETS-LIBXSLT" class="id_link">#</a></dt><dd><p>
  26        <code class="command">xsltproc</code> is an XSLT processor, that is, a program to
  27        convert XML to other formats using XSLT stylesheets.
  28       </p></dd><dt id="DOCGUIDE-TOOLSETS-FOP"><span class="term"><a class="ulink" href="https://xmlgraphics.apache.org/fop/" target="_top">FOP</a></span> <a href="#DOCGUIDE-TOOLSETS-FOP" class="id_link">#</a></dt><dd><p>
  29        This is a program for converting, among other things, XML to PDF.
  30        It is needed only if you want to build the documentation in PDF format.
  31       </p></dd></dl></div><p>
  32   </p><p>
  33    We have documented experience with several installation methods for
  34    the various tools that are needed to process the documentation.
  35    These will be described below.  There might be some other packaged
  36    distributions for these tools. Please report package status to the
  37    documentation mailing list, and we will include that information
  38    here.
  39   </p><div class="sect2" id="DOCGUIDE-TOOLSETS-INST-FEDORA-ET-AL"><div class="titlepage"><div><div><h3 class="title">J.2.1. Installation on Fedora, RHEL, and Derivatives <a href="#DOCGUIDE-TOOLSETS-INST-FEDORA-ET-AL" class="id_link">#</a></h3></div></div></div><p>
  40     To install the required packages, use:
  41 </p><pre class="programlisting">
  42 yum install docbook-dtds docbook-style-xsl libxslt fop
  43 </pre><p>
  44    </p></div><div class="sect2" id="DOCGUIDE-TOOLSETS-INST-FREEBSD"><div class="titlepage"><div><div><h3 class="title">J.2.2. Installation on FreeBSD <a href="#DOCGUIDE-TOOLSETS-INST-FREEBSD" class="id_link">#</a></h3></div></div></div><p>
  45     To install the required packages with <code class="command">pkg</code>, use:
  46 </p><pre class="programlisting">
  47 pkg install docbook-xml docbook-xsl libxslt fop
  48 </pre><p>
  49    </p><p>
  50     When building the documentation from the <code class="filename">doc</code>
  51     directory you'll need to use <code class="command">gmake</code>, because the
  52     makefile provided is not suitable for FreeBSD's <code class="command">make</code>.
  53    </p></div><div class="sect2" id="DOCGUIDE-TOOLSETS-INST-DEBIAN"><div class="titlepage"><div><div><h3 class="title">J.2.3. Debian Packages <a href="#DOCGUIDE-TOOLSETS-INST-DEBIAN" class="id_link">#</a></h3></div></div></div><p>
  54     There is a full set of packages of the documentation tools
  55     available for <span class="productname">Debian GNU/Linux</span>.
  56     To install, simply use:
  57 </p><pre class="programlisting">
  58 apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
  59 </pre><p>
  60    </p></div><div class="sect2" id="DOCGUIDE-TOOLSETS-INST-MACOS"><div class="titlepage"><div><div><h3 class="title">J.2.4. macOS <a href="#DOCGUIDE-TOOLSETS-INST-MACOS" class="id_link">#</a></h3></div></div></div><p>
  61     If you use MacPorts, the following will get you set up:
  62 </p><pre class="programlisting">
  63 sudo port install docbook-xml docbook-xsl-nons libxslt fop
  64 </pre><p>
  65     If you use Homebrew, use this:
  66 </p><pre class="programlisting">
  67 brew install docbook docbook-xsl libxslt fop
  68 </pre><p>
  69    </p><p>
  70     The Homebrew-supplied programs require the following environment variable
  71     to be set.  For Intel based machines, use this:
  72 </p><pre class="programlisting">
  73 export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
  74 </pre><p>
  75     On Apple Silicon based machines, use this:
  76 </p><pre class="programlisting">
  77 export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
  78 </pre><p>
  79     Without it, <code class="command">xsltproc</code> will throw errors like this:
  80 </p><pre class="programlisting">
  81 I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
  82 postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
  83 ...
  84 </pre><p>
  85    </p><p>
  86     While it is possible to use the Apple-provided versions
  87     of <code class="command">xmllint</code> and <code class="command">xsltproc</code>
  88     instead of those from MacPorts or Homebrew, you'll still need
  89     to install the DocBook DTD and stylesheets, and set up a catalog
  90     file that points to them.
  91    </p></div><div class="sect2" id="DOCGUIDE-TOOLSETS-CONFIGURE"><div class="titlepage"><div><div><h3 class="title">J.2.5. Detection by <code class="command">configure</code> <a href="#DOCGUIDE-TOOLSETS-CONFIGURE" class="id_link">#</a></h3></div></div></div><p>
  92    Before you can build the documentation you need to run the
  93    <code class="filename">configure</code> script, as you would when building
  94    the <span class="productname">PostgreSQL</span> programs themselves.
  95    Check the output near the end of the run; it should look something
  96    like this:
  97 </p><pre class="screen">
  98 checking for xmllint... xmllint
  99 checking for xsltproc... xsltproc
 100 checking for fop... fop
 101 checking for dbtoepub... dbtoepub
 102 </pre><p>
 103    If <code class="filename">xmllint</code> or <code class="filename">xsltproc</code> is not
 104    found, you will not be able to build any of the documentation.
 105    <code class="filename">fop</code> is only needed to build the documentation in
 106    PDF format.
 107    <code class="filename">dbtoepub</code> is only needed to build the documentation
 108    in EPUB format.
 109   </p><p>
 110    If necessary, you can tell <code class="filename">configure</code> where to find
 111    these programs, for example
 112 </p><pre class="screen">
 113 ./configure ... XMLLINT=/opt/local/bin/xmllint ...
 114 </pre><p>
 115   </p><p>
 116    If you prefer to build <span class="productname">PostgreSQL</span> using
 117    Meson, instead run <code class="command">meson setup</code> as described in
 118    <a class="xref" href="install-meson.html" title="17.4. Building and Installation with Meson">Section 17.4</a>, and then see
 119    <a class="xref" href="docguide-build-meson.html" title="J.4. Building the Documentation with Meson">Section J.4</a>.
 120   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-docbook.html" title="J.1. DocBook">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide-build.html" title="J.3. Building the Documentation with Make">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.1. DocBook </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.3. Building the Documentation with Make</td></tr></table></div></body></html>