diff options
| -rw-r--r-- | doc/src/sgml/Makefile | 8 | ||||
| -rw-r--r-- | doc/src/sgml/docguide.sgml | 88 | ||||
| -rw-r--r-- | doc/src/sgml/images/Makefile | 2 | ||||
| -rw-r--r-- | doc/src/sgml/meson.build | 8 |
4 files changed, 70 insertions, 36 deletions
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 4f0e39223c4..b96c7cbf223 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -41,11 +41,15 @@ endif XMLINCLUDE = --path . -ifndef XMLLINT +ifdef XMLLINT +XMLLINT := $(XMLLINT) --nonet +else XMLLINT = $(missing) xmllint endif -ifndef XSLTPROC +ifdef XSLTPROC +XSLTPROC := $(XSLTPROC) --nonet +else XSLTPROC = $(missing) xsltproc endif diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 787caef70d8..35c4afc81ad 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -136,6 +136,7 @@ <listitem> <para> 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. </para> </listitem> </varlistentry> @@ -151,25 +152,13 @@ here. </para> - <para> - You can get away with not installing DocBook XML and the DocBook XSLT - stylesheets locally, because the required files will be downloaded from the - Internet and cached locally. This may in fact be the preferred solution if - your operating system packages provide only an old version of these files, - or if no packages are available at all. - If you want to prevent any attempt to access the Internet while building - the documentation, you need to pass the <option>--nonet</option> option - to <command>xmllint</command> and <command>xsltproc</command>; see below - for an example. - </para> - <sect2 id="docguide-toolsets-inst-fedora-et-al"> <title>Installation on Fedora, RHEL, and Derivatives</title> <para> To install the required packages, use: <programlisting> -yum install docbook-dtds docbook-style-xsl fop libxslt +yum install docbook-dtds docbook-style-xsl libxslt fop </programlisting> </para> </sect2> @@ -180,7 +169,7 @@ yum install docbook-dtds docbook-style-xsl fop libxslt <para> To install the required packages with <command>pkg</command>, use: <programlisting> -pkg install docbook-xml docbook-xsl fop libxslt +pkg install docbook-xml docbook-xsl libxslt fop </programlisting> </para> @@ -199,7 +188,7 @@ pkg install docbook-xml docbook-xsl fop libxslt available for <productname>Debian GNU/Linux</productname>. To install, simply use: <programlisting> -apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc +apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop </programlisting> </para> </sect2> @@ -208,21 +197,37 @@ apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc <title>macOS</title> <para> - On macOS, you can build the HTML and man documentation without installing - anything extra. If you want to build PDFs or want to install a local copy - of DocBook, you can get those from your preferred package manager. + If you use MacPorts, the following will get you set up: +<programlisting> +sudo port install docbook-xml docbook-xsl-nons libxslt fop +</programlisting> + If you use Homebrew, use this: +<programlisting> +brew install docbook docbook-xsl libxslt fop +</programlisting> </para> <para> - If you use MacPorts, the following will get you set up: + The Homebrew-supplied programs require the following environment variable + to be set: <programlisting> -sudo port install docbook-xml-4.5 docbook-xsl fop +export XML_CATALOG_FILES=/usr/local/etc/xml/catalog </programlisting> - If you use Homebrew, use this: + Without it, <command>xsltproc</command> will throw errors like this: <programlisting> -brew install docbook docbook-xsl fop +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" +... </programlisting> </para> + + <para> + While it is possible to use the Apple-provided versions + of <command>xmllint</command> and <command>xsltproc</command> + 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. + </para> </sect2> <sect2 id="docguide-toolsets-configure"> @@ -254,18 +259,19 @@ checking for dbtoepub... dbtoepub <screen> ./configure ... XMLLINT=/opt/local/bin/xmllint ... </screen> - Also, if you want to ensure that <filename>xmllint</filename> - and <filename>xsltproc</filename> will not perform any network access, - you can do something like -<screen> -./configure ... XMLLINT="xmllint --nonet" XSLTPROC="xsltproc --nonet" ... -</screen> + </para> + + <para> + If you prefer to build <productname>PostgreSQL</productname> using + Meson, instead run <command>meson setup</command> as described in + <xref linkend="install-meson"/>, and then see + <xref linkend="docguide-build-meson"/>. </para> </sect2> </sect1> <sect1 id="docguide-build"> - <title>Building the Documentation</title> + <title>Building the Documentation with Make</title> <para> Once you have everything set up, change to the directory @@ -410,6 +416,30 @@ ADDITIONAL_FLAGS='-Xmx1500m' </sect1> + <sect1 id="docguide-build-meson"> + <title>Building the Documentation with Meson</title> + + <para> + Two options are provided for building the documentation using Meson. + Change to the <filename>build</filename> directory before running + one of these commands, or add <option>-C build</option> to the command. + </para> + + <para> + To build just the <acronym>HTML</acronym> version of the documentation: +<screen> +<prompt>build$ </prompt><userinput>ninja docs</userinput> +</screen> + To build all forms of the documentation: +<screen> +<prompt>build$ </prompt><userinput>ninja alldocs</userinput> +</screen> + The output appears in the + subdirectory <filename>build/doc/src/sgml</filename>. + </para> + </sect1> + + <sect1 id="docguide-authoring"> <title>Documentation Authoring</title> diff --git a/doc/src/sgml/images/Makefile b/doc/src/sgml/images/Makefile index f9e356348b2..645519095d0 100644 --- a/doc/src/sgml/images/Makefile +++ b/doc/src/sgml/images/Makefile @@ -9,7 +9,7 @@ ALL_IMAGES = \ DITAA = ditaa DOT = dot -XSLTPROC = xsltproc +XSLTPROC = xsltproc --nonet all: $(ALL_IMAGES) diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index b9f4c6a05b8..38f1b8e7b17 100644 --- a/doc/src/sgml/meson.build +++ b/doc/src/sgml/meson.build @@ -87,7 +87,8 @@ postgres_full_xml = custom_target('postgres-full.xml', input: 'postgres.sgml', output: 'postgres-full.xml', depfile: 'postgres-full.xml.d', - command: [xmllint, '--noent', '--valid', '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'], + command: [xmllint, '--nonet', '--noent', '--valid', + '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'], depends: doc_generated, build_by_default: false, ) @@ -100,6 +101,7 @@ alldocs += postgres_full_xml # if xsltproc_bin.found() xsltproc_flags = [ + '--nonet', '--stringparam', 'pg.version', pg_version, '--param', 'website.stylesheet', '1' ] @@ -205,9 +207,7 @@ if xsltproc_bin.found() command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'], build_by_default: false, ) - - # build by default as part of docs target - docs += man + alldocs += man endif |