diff options
Diffstat (limited to 'doc/src/sgml/html/docguide-toolsets.html')
| -rw-r--r-- | doc/src/sgml/html/docguide-toolsets.html | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/doc/src/sgml/html/docguide-toolsets.html b/doc/src/sgml/html/docguide-toolsets.html new file mode 100644 index 0000000..1b217ab --- /dev/null +++ b/doc/src/sgml/html/docguide-toolsets.html @@ -0,0 +1,115 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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" /></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 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-build.html" title="J.3. Building the Documentation">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</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.4">J.2.1. Installation on Fedora, RHEL, and Derivatives</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.5">J.2.2. Installation on FreeBSD</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.6">J.2.3. Debian Packages</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.7">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> + The following tools are used to process the documentation. Some + might be optional, as noted. + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a class="ulink" href="https://www.oasis-open.org/docbook/" target="_top">DocBook DTD</a></span></dt><dd><p> + This is the definition of DocBook itself. We currently use version + 4.5; you cannot use later or earlier versions. You need + the <acronym class="acronym">XML</acronym> variant of the DocBook DTD, not + the <acronym class="acronym">SGML</acronym> variant. + </p></dd><dt><span class="term"><a class="ulink" href="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets" target="_top">DocBook XSL Stylesheets</a></span></dt><dd><p> + These contain the processing instructions for converting the + DocBook sources to other formats, such as + <acronym class="acronym">HTML</acronym>. + </p><p> + The minimum required version is currently 1.77.0, but it is recommended + to use the latest available version for best results. + </p></dd><dt><span class="term"><a class="ulink" href="http://xmlsoft.org/" target="_top">Libxml2</a> for <code class="command">xmllint</code></span></dt><dd><p> + This library and the <code class="command">xmllint</code> tool it contains are + used for processing XML. Many developers will already + have <span class="application">Libxml2</span> installed, because it is also + used when building the PostgreSQL code. Note, however, + that <code class="command">xmllint</code> might need to be installed from a + separate subpackage. + </p></dd><dt><span class="term"><a class="ulink" href="http://xmlsoft.org/XSLT/" target="_top">Libxslt</a> for <code class="command">xsltproc</code></span></dt><dd><p> + <code class="command">xsltproc</code> is an XSLT processor, that is, a program to + convert XML to other formats using XSLT stylesheets. + </p></dd><dt><span class="term"><a class="ulink" href="https://xmlgraphics.apache.org/fop/" target="_top">FOP</a></span></dt><dd><p> + This is a program for converting, among other things, XML to PDF. + It is needed only if you want to build the documentation in PDF format. + </p></dd></dl></div><p> + </p><p> + 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. + </p><div class="sect2" id="id-1.11.11.5.4"><div class="titlepage"><div><div><h3 class="title">J.2.1. Installation on Fedora, RHEL, and Derivatives</h3></div></div></div><p> + To install the required packages, use: +</p><pre class="programlisting"> +yum install docbook-dtds docbook-style-xsl libxslt fop +</pre><p> + </p></div><div class="sect2" id="id-1.11.11.5.5"><div class="titlepage"><div><div><h3 class="title">J.2.2. Installation on FreeBSD</h3></div></div></div><p> + To install the required packages with <code class="command">pkg</code>, use: +</p><pre class="programlisting"> +pkg install docbook-xml docbook-xsl libxslt fop +</pre><p> + </p><p> + When building the documentation from the <code class="filename">doc</code> + directory you'll need to use <code class="command">gmake</code>, because the + makefile provided is not suitable for FreeBSD's <code class="command">make</code>. + </p></div><div class="sect2" id="id-1.11.11.5.6"><div class="titlepage"><div><div><h3 class="title">J.2.3. Debian Packages</h3></div></div></div><p> + There is a full set of packages of the documentation tools + available for <span class="productname">Debian GNU/Linux</span>. + To install, simply use: +</p><pre class="programlisting"> +apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop +</pre><p> + </p></div><div class="sect2" id="id-1.11.11.5.7"><div class="titlepage"><div><div><h3 class="title">J.2.4. macOS</h3></div></div></div><p> + If you use MacPorts, the following will get you set up: +</p><pre class="programlisting"> +sudo port install docbook-xml docbook-xsl-nons libxslt fop +</pre><p> + If you use Homebrew, use this: +</p><pre class="programlisting"> +brew install docbook docbook-xsl libxslt fop +</pre><p> + </p><p> + The Homebrew-supplied programs require the following environment variable + to be set. For Intel based machines, use this: +</p><pre class="programlisting"> +export XML_CATALOG_FILES=/usr/local/etc/xml/catalog +</pre><p> + On Apple Silicon based machines, use this: +</p><pre class="programlisting"> +export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog +</pre><p> + Without it, <code class="command">xsltproc</code> will throw errors like this: +</p><pre class="programlisting"> +I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd +postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +... +</pre><p> + </p><p> + While it is possible to use the Apple-provided versions + of <code class="command">xmllint</code> and <code class="command">xsltproc</code> + instead of those from MacPorts or Homebrew, you'll still need + to install the DocBook DTD and stylesheets, and set up a catalog + file that points to them. + </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></h3></div></div></div><p> + Before you can build the documentation you need to run the + <code class="filename">configure</code> script, as you would when building + the <span class="productname">PostgreSQL</span> programs themselves. + Check the output near the end of the run; it should look something + like this: +</p><pre class="screen"> +checking for xmllint... xmllint +checking for xsltproc... xsltproc +checking for fop... fop +checking for dbtoepub... dbtoepub +</pre><p> + If <code class="filename">xmllint</code> or <code class="filename">xsltproc</code> is not + found, you will not be able to build any of the documentation. + <code class="filename">fop</code> is only needed to build the documentation in + PDF format. + <code class="filename">dbtoepub</code> is only needed to build the documentation + in EPUB format. + </p><p> + If necessary, you can tell <code class="filename">configure</code> where to find + these programs, for example +</p><pre class="screen"> +./configure ... XMLLINT=/opt/local/bin/xmllint ... +</pre><p> + </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">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 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.3. Building the Documentation</td></tr></table></div></body></html>
\ No newline at end of file |