doc/src/sgml/docguide.sgml

   1 <!-- doc/src/sgml/docguide.sgml -->
   2
   3 <appendix id="docguide">
   4  <title>Documentation</title>
   5
   6  <para>
   7   <productname>PostgreSQL</productname> has four primary documentation
   8   formats:
   9
  10   <itemizedlist>
  11    <listitem>
  12     <para>
  13      Plain text, for pre-installation information
  14     </para>
  15    </listitem>
  16    <listitem>
  17     <para>
  18      <acronym>HTML</acronym>, for on-line browsing and reference
  19     </para>
  20    </listitem>
  21    <listitem>
  22     <para>
  23      PDF, for printing
  24     </para>
  25    </listitem>
  26    <listitem>
  27     <para>
  28      man pages, for quick reference.
  29     </para>
  30    </listitem>
  31   </itemizedlist>
  32
  33   Additionally, a number of plain-text <filename>README</filename> files can
  34   be found throughout the <productname>PostgreSQL</productname> source tree,
  35   documenting various implementation issues.
  36  </para>
  37
  38  <para>
  39   <acronym>HTML</acronym> documentation and man pages are part of a
  40   standard distribution and are installed by default.  PDF
  41   format documentation is available separately for
  42   download.
  43  </para>
  44
  45  <sect1 id="docguide-docbook">
  46   <title>DocBook</title>
  47   <para>
  48    The documentation sources are written in
  49    <firstterm>DocBook</firstterm>, which is a markup language
  50    defined in <acronym>XML</acronym>.  In what
  51    follows, the terms DocBook and <acronym>XML</acronym> are both
  52    used, but technically they are not interchangeable.
  53   </para>
  54
  55   <para>
  56   <productname>DocBook</productname> allows an author to specify the
  57    structure and content of a technical document without worrying
  58    about presentation details.  A document style defines how that
  59    content is rendered into one of several final forms.  DocBook is
  60    maintained by the <ulink url="https://www.oasis-open.org">
  61    OASIS group</ulink>.  The <ulink url="https://www.oasis-open.org/docbook/">
  62    official DocBook site</ulink> has good introductory and reference documentation and
  63    a complete O'Reilly book for your online reading pleasure.  The
  64    <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
  65    NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
  66    The <ulink url="https://www.freebsd.org/docproj/">
  67    FreeBSD Documentation Project</ulink> also uses DocBook and has some good
  68    information, including a number of style guidelines that might be
  69    worth considering.
  70   </para>
  71  </sect1>
  72
  73
  74  <sect1 id="docguide-toolsets">
  75   <title>Tool Sets</title>
  76
  77   <para>
  78    The following tools are used to process the documentation.  Some
  79    might be optional, as noted.
  80
  81    <variablelist>
  82     <varlistentry id="docguide-toolsets-docbook-dtd">
  83      <term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
  84      <listitem>
  85       <para>
  86        This is the definition of DocBook itself.  We currently use version
  87        4.5; you cannot use later or earlier versions.  You need
  88        the <acronym>XML</acronym> variant of the DocBook DTD, not
  89        the <acronym>SGML</acronym> variant.
  90       </para>
  91      </listitem>
  92     </varlistentry>
  93
  94     <varlistentry id="docguide-toolsets-docbook-xsl">
  95      <term><ulink url="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
  96      <listitem>
  97       <para>
  98        These contain the processing instructions for converting the
  99        DocBook sources to other formats, such as
 100        <acronym>HTML</acronym>.
 101       </para>
 102
 103       <para>
 104        The minimum required version is currently 1.77.0, but it is recommended
 105        to use the latest available version for best results.
 106       </para>
 107      </listitem>
 108     </varlistentry>
 109
 110     <varlistentry id="docguide-toolsets-libxml2">
 111      <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
 112      <listitem>
 113       <para>
 114        This library and the <command>xmllint</command> tool it contains are
 115        used for processing XML.  Many developers will already
 116        have <application>Libxml2</application> installed, because it is also
 117        used when building the PostgreSQL code.  Note, however,
 118        that <command>xmllint</command> might need to be installed from a
 119        separate subpackage.
 120       </para>
 121      </listitem>
 122      </varlistentry>
 123
 124     <varlistentry id="docguide-toolsets-libxslt">
 125      <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
 126      <listitem>
 127       <para>
 128        <command>xsltproc</command> is an XSLT processor, that is, a program to
 129        convert XML to other formats using XSLT stylesheets.
 130       </para>
 131      </listitem>
 132     </varlistentry>
 133
 134     <varlistentry id="docguide-toolsets-fop">
 135      <term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term>
 136      <listitem>
 137       <para>
 138        This is a program for converting, among other things, XML to PDF.
 139        It is needed only if you want to build the documentation in PDF format.
 140       </para>
 141      </listitem>
 142     </varlistentry>
 143    </variablelist>
 144   </para>
 145
 146   <para>
 147    We have documented experience with several installation methods for
 148    the various tools that are needed to process the documentation.
 149    These will be described below.  There might be some other packaged
 150    distributions for these tools. Please report package status to the
 151    documentation mailing list, and we will include that information
 152    here.
 153   </para>
 154
 155   <sect2 id="docguide-toolsets-inst-fedora-et-al">
 156    <title>Installation on Fedora, RHEL, and Derivatives</title>
 157
 158    <para>
 159     To install the required packages, use:
 160 <programlisting>
 161 yum install docbook-dtds docbook-style-xsl libxslt fop
 162 </programlisting>
 163    </para>
 164   </sect2>
 165
 166   <sect2 id="docguide-toolsets-inst-freebsd">
 167    <title>Installation on FreeBSD</title>
 168
 169    <para>
 170     To install the required packages with <command>pkg</command>, use:
 171 <programlisting>
 172 pkg install docbook-xml docbook-xsl libxslt fop
 173 </programlisting>
 174    </para>
 175
 176    <para>
 177     When building the documentation from the <filename>doc</filename>
 178     directory you'll need to use <command>gmake</command>, because the
 179     makefile provided is not suitable for FreeBSD's <command>make</command>.
 180    </para>
 181   </sect2>
 182
 183   <sect2 id="docguide-toolsets-inst-debian">
 184    <title>Debian Packages</title>
 185
 186    <para>
 187     There is a full set of packages of the documentation tools
 188     available for <productname>Debian GNU/Linux</productname>.
 189     To install, simply use:
 190 <programlisting>
 191 apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
 192 </programlisting>
 193    </para>
 194   </sect2>
 195
 196   <sect2 id="docguide-toolsets-inst-macos">
 197    <title>macOS</title>
 198
 199    <para>
 200     If you use MacPorts, the following will get you set up:
 201 <programlisting>
 202 sudo port install docbook-xml docbook-xsl-nons libxslt fop
 203 </programlisting>
 204     If you use Homebrew, use this:
 205 <programlisting>
 206 brew install docbook docbook-xsl libxslt fop
 207 </programlisting>
 208    </para>
 209
 210    <para>
 211     The Homebrew-supplied programs require the following environment variable
 212     to be set.  For Intel based machines, use this:
 213 <programlisting>
 214 export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
 215 </programlisting>
 216     On Apple Silicon based machines, use this:
 217 <programlisting>
 218 export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
 219 </programlisting>
 220     Without it, <command>xsltproc</command> will throw errors like this:
 221 <programlisting>
 222 I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
 223 postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
 224 ...
 225 </programlisting>
 226    </para>
 227
 228    <para>
 229     While it is possible to use the Apple-provided versions
 230     of <command>xmllint</command> and <command>xsltproc</command>
 231     instead of those from MacPorts or Homebrew, you'll still need
 232     to install the DocBook DTD and stylesheets, and set up a catalog
 233     file that points to them.
 234    </para>
 235   </sect2>
 236
 237   <sect2 id="docguide-toolsets-configure">
 238    <title>Detection by <command>configure</command></title>
 239
 240   <para>
 241    Before you can build the documentation you need to run the
 242    <filename>configure</filename> script, as you would when building
 243    the <productname>PostgreSQL</productname> programs themselves.
 244    Check the output near the end of the run; it should look something
 245    like this:
 246 <screen>
 247 checking for xmllint... xmllint
 248 checking for xsltproc... xsltproc
 249 checking for fop... fop
 250 checking for dbtoepub... dbtoepub
 251 </screen>
 252    If <filename>xmllint</filename> or <filename>xsltproc</filename> is not
 253    found, you will not be able to build any of the documentation.
 254    <filename>fop</filename> is only needed to build the documentation in
 255    PDF format.
 256    <filename>dbtoepub</filename> is only needed to build the documentation
 257    in EPUB format.
 258   </para>
 259
 260   <para>
 261    If necessary, you can tell <filename>configure</filename> where to find
 262    these programs, for example
 263 <screen>
 264 ./configure ... XMLLINT=/opt/local/bin/xmllint ...
 265 </screen>
 266   </para>
 267
 268   <para>
 269    If you prefer to build <productname>PostgreSQL</productname> using
 270    Meson, instead run <command>meson setup</command> as described in
 271    <xref linkend="install-meson"/>, and then see
 272    <xref linkend="docguide-build-meson"/>.
 273   </para>
 274   </sect2>
 275  </sect1>
 276
 277  <sect1 id="docguide-build">
 278   <title>Building the Documentation with Make</title>
 279
 280   <para>
 281    Once you have everything set up, change to the directory
 282    <filename>doc/src/sgml</filename> and run one of the commands
 283    described in the following subsections to build the
 284    documentation. (Remember to use GNU make.)
 285   </para>
 286
 287   <sect2 id="docguide-build-html">
 288    <title>HTML</title>
 289
 290    <para>
 291     To build the <acronym>HTML</acronym> version of the documentation:
 292 <screen>
 293 <prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
 294 </screen>
 295     This is also the default target.  The output appears in the
 296     subdirectory <filename>html</filename>.
 297    </para>
 298
 299    <para>
 300     To produce HTML documentation with the stylesheet used on <ulink
 301     url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> instead of the
 302     default simple style use:
 303 <screen>
 304 <prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput>
 305 </screen>
 306    </para>
 307
 308    <para>
 309     If the <literal>STYLE=website</literal> option is used, the generated HTML
 310     files include references to stylesheets hosted on <ulink
 311     url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> and
 312     require network access to view.
 313    </para>
 314  </sect2>
 315
 316  <sect2 id="docguide-build-manpages">
 317   <title>Manpages</title>
 318
 319   <para>
 320    We use the DocBook XSL stylesheets to
 321    convert <productname>DocBook</productname>
 322    <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
 323    pages.  To create the man pages, use the command:
 324 <screen>
 325 <prompt>doc/src/sgml$ </prompt><userinput>make man</userinput>
 326 </screen>
 327   </para>
 328  </sect2>
 329
 330   <sect2 id="docguide-build-pdf">
 331    <title>PDF</title>
 332
 333    <para>
 334     To produce a PDF rendition of the documentation
 335     using <productname>FOP</productname>, you can use one of the following
 336     commands, depending on the preferred paper format:
 337
 338     <itemizedlist>
 339      <listitem>
 340       <para>
 341        For A4 format:
 342 <screen>
 343 <prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
 344 </screen>
 345       </para>
 346      </listitem>
 347
 348      <listitem>
 349       <para>
 350        For U.S. letter format:
 351 <screen>
 352 <prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
 353 </screen>
 354       </para>
 355      </listitem>
 356     </itemizedlist>
 357    </para>
 358
 359    <para>
 360     Because the PostgreSQL documentation is fairly
 361     big, <productname>FOP</productname> will require a significant amount of
 362     memory.  Because of that, on some systems, the build will fail with a
 363     memory-related error message.  This can usually be fixed by configuring
 364     Java heap settings in the configuration
 365     file <filename>~/.foprc</filename>, for example:
 366 <programlisting>
 367 # FOP binary distribution
 368 FOP_OPTS='-Xmx1500m'
 369 # Debian
 370 JAVA_ARGS='-Xmx1500m'
 371 # Red Hat
 372 ADDITIONAL_FLAGS='-Xmx1500m'
 373 </programlisting>
 374     There is a minimum amount of memory that is required, and to some extent
 375     more memory appears to make things a bit faster.  On systems with very
 376     little memory (less than 1 GB), the build will either be very slow due to
 377     swapping or will not work at all.
 378    </para>
 379
 380    <para>
 381     In its default configuration <productname>FOP</productname> will emit an
 382     <literal>INFO</literal> message for each page. The log level can be
 383     changed via <filename>~/.foprc</filename>:
 384 <programlisting>
 385 LOGCHOICE=-Dorg.apache.commons.logging.Log=&zwsp;org.apache.commons.logging.impl.SimpleLog
 386 LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
 387 </programlisting>
 388    </para>
 389
 390    <para>
 391     Other XSL-FO processors can also be used manually, but the automated build
 392     process only supports FOP.
 393    </para>
 394   </sect2>
 395
 396   <sect2 id="docguide-build-syntax-check">
 397    <title>Syntax Check</title>
 398
 399    <para>
 400     Building the documentation can take very long.  But there is a
 401     method to just check the correct syntax of the documentation
 402     files, which only takes a few seconds:
 403 <screen>
 404 <prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
 405 </screen>
 406    </para>
 407   </sect2>
 408  </sect1>
 409
 410
 411  <sect1 id="docguide-build-meson">
 412   <title>Building the Documentation with Meson</title>
 413
 414    <para>
 415     To build the documentation using Meson, change to the
 416     <filename>build</filename> directory before running one of these commands,
 417     or add <option>-C build</option> to the command.
 418    </para>
 419
 420    <para>
 421     To build just the <acronym>HTML</acronym> version of the documentation:
 422 <screen>
 423 <prompt>build$ </prompt><userinput>ninja html</userinput>
 424 </screen>
 425     For a list of other documentation targets see
 426     <xref linkend="targets-meson-documentation"/>.
 427
 428     The output appears in the
 429     subdirectory <filename>build/doc/src/sgml</filename>.
 430    </para>
 431  </sect1>
 432
 433
 434  <sect1 id="docguide-authoring">
 435   <title>Documentation Authoring</title>
 436
 437    <para>
 438     The documentation sources are most conveniently modified with an editor
 439     that has a mode for editing XML, and even more so if it has some awareness
 440     of XML schema languages so that it can know about
 441     <productname>DocBook</productname> syntax specifically.
 442    </para>
 443
 444    <para>
 445     Note that for historical reasons the documentation source files are named
 446     with an extension <filename>.sgml</filename> even though they are now XML
 447     files.  So you might need to adjust your editor configuration to set the
 448     correct mode.
 449    </para>
 450
 451    <sect2 id="docguide-authoring-emacs">
 452     <title>Emacs</title>
 453
 454     <para>
 455      <productname>nXML Mode</productname>, which ships with
 456      <productname>Emacs</productname>, is the most common mode for editing
 457      <acronym>XML</acronym> documents with <productname>Emacs</productname>.
 458      It will allow you to use <application>Emacs</application> to insert tags
 459      and check markup consistency, and it supports
 460      <productname>DocBook</productname> out of the box.  Check the <ulink
 461      url="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html">
 462      nXML manual</ulink> for detailed documentation.
 463     </para>
 464
 465     <para>
 466      <filename>src/tools/editors/emacs.samples</filename> contains
 467      recommended settings for this mode.
 468     </para>
 469    </sect2>
 470
 471  </sect1>
 472
 473
 474  <sect1 id="docguide-style">
 475   <title>Style Guide</title>
 476
 477   <sect2 id="docguide-style-ref-pages">
 478    <title>Reference Pages</title>
 479
 480    <para>
 481     Reference pages should follow a standard layout.  This allows
 482     users to find the desired information more quickly, and it also
 483     encourages writers to document all relevant aspects of a command.
 484     Consistency is not only desired among
 485     <productname>PostgreSQL</productname> reference pages, but also
 486     with reference pages provided by the operating system and other
 487     packages.  Hence the following guidelines have been developed.
 488     They are for the most part consistent with similar guidelines
 489     established by various operating systems.
 490    </para>
 491
 492    <para>
 493     Reference pages that describe executable commands should contain
 494     the following sections, in this order.  Sections that do not apply
 495     can be omitted.  Additional top-level sections should only be used
 496     in special circumstances; often that information belongs in the
 497     <quote>Usage</quote> section.
 498
 499     <variablelist>
 500      <varlistentry id="docguide-style-ref-pages-name">
 501       <term>Name</term>
 502       <listitem>
 503        <para>
 504         This section is generated automatically.  It contains the
 505         command name and a half-sentence summary of its functionality.
 506        </para>
 507       </listitem>
 508      </varlistentry>
 509
 510      <varlistentry id="docguide-style-ref-pages-synopsis">
 511       <term>Synopsis</term>
 512       <listitem>
 513        <para>
 514         This section contains the syntax diagram of the command.  The
 515         synopsis should normally not list each command-line option;
 516         that is done below.  Instead, list the major components of the
 517         command line, such as where input and output files go.
 518        </para>
 519       </listitem>
 520      </varlistentry>
 521
 522      <varlistentry id="docguide-style-ref-pages-description">
 523       <term>Description</term>
 524       <listitem>
 525        <para>
 526         Several paragraphs explaining what the command does.
 527        </para>
 528       </listitem>
 529      </varlistentry>
 530
 531      <varlistentry id="docguide-style-ref-pages-options">
 532       <term>Options</term>
 533       <listitem>
 534        <para>
 535         A list describing each command-line option.  If there are a
 536         lot of options, subsections can be used.
 537        </para>
 538       </listitem>
 539      </varlistentry>
 540
 541      <varlistentry id="docguide-style-ref-pages-exit-status">
 542       <term>Exit Status</term>
 543       <listitem>
 544        <para>
 545         If the program uses 0 for success and non-zero for failure,
 546         then you do not need to document it.  If there is a meaning
 547         behind the different non-zero exit codes, list them here.
 548        </para>
 549       </listitem>
 550      </varlistentry>
 551
 552      <varlistentry id="docguide-style-ref-pages-usage">
 553       <term>Usage</term>
 554       <listitem>
 555        <para>
 556         Describe any sublanguage or run-time interface of the program.
 557         If the program is not interactive, this section can usually be
 558         omitted.  Otherwise, this section is a catch-all for
 559         describing run-time features.  Use subsections if appropriate.
 560        </para>
 561       </listitem>
 562      </varlistentry>
 563
 564      <varlistentry id="docguide-style-ref-pages-environment">
 565       <term>Environment</term>
 566       <listitem>
 567        <para>
 568         List all environment variables that the program might use.
 569         Try to be complete; even seemingly trivial variables like
 570         <envar>SHELL</envar> might be of interest to the user.
 571        </para>
 572       </listitem>
 573      </varlistentry>
 574
 575      <varlistentry id="docguide-style-ref-pages-files">
 576       <term>Files</term>
 577       <listitem>
 578        <para>
 579         List any files that the program might access implicitly.  That
 580         is, do not list input and output files that were specified on
 581         the command line, but list configuration files, etc.
 582        </para>
 583       </listitem>
 584      </varlistentry>
 585
 586      <varlistentry id="docguide-style-ref-pages-diagnostics">
 587       <term>Diagnostics</term>
 588       <listitem>
 589        <para>
 590         Explain any unusual output that the program might create.
 591         Refrain from listing every possible error message.  This is a
 592         lot of work and has little use in practice.  But if, say, the
 593         error messages have a standard format that the user can parse,
 594         this would be the place to explain it.
 595        </para>
 596       </listitem>
 597      </varlistentry>
 598
 599      <varlistentry id="docguide-style-ref-pages-notes">
 600       <term>Notes</term>
 601       <listitem>
 602        <para>
 603         Anything that doesn't fit elsewhere, but in particular bugs,
 604         implementation flaws, security considerations, compatibility
 605         issues.
 606        </para>
 607       </listitem>
 608      </varlistentry>
 609
 610      <varlistentry id="docguide-style-ref-pages-examples">
 611       <term>Examples</term>
 612       <listitem>
 613        <para>
 614         Examples
 615        </para>
 616       </listitem>
 617      </varlistentry>
 618
 619      <varlistentry id="docguide-style-ref-pages-history">
 620       <term>History</term>
 621       <listitem>
 622        <para>
 623         If there were some major milestones in the history of the
 624         program, they might be listed here.  Usually, this section can
 625         be omitted.
 626        </para>
 627       </listitem>
 628      </varlistentry>
 629
 630      <varlistentry id="docguide-style-ref-pages-author">
 631       <term>Author</term>
 632       <listitem>
 633        <para>
 634         Author (only used in the contrib section)
 635        </para>
 636       </listitem>
 637      </varlistentry>
 638
 639      <varlistentry id="docguide-style-ref-pages-see-also">
 640       <term>See Also</term>
 641       <listitem>
 642        <para>
 643         Cross-references, listed in the following order: other
 644         <productname>PostgreSQL</productname> command reference pages,
 645         <productname>PostgreSQL</productname> SQL command reference
 646         pages, citation of <productname>PostgreSQL</productname>
 647         manuals, other reference pages (e.g., operating system, other
 648         packages), other documentation.  Items in the same group are
 649         listed alphabetically.
 650        </para>
 651       </listitem>
 652      </varlistentry>
 653
 654     </variablelist>
 655    </para>
 656
 657    <para>
 658     Reference pages describing SQL commands should contain the
 659     following sections: Name, Synopsis, Description, Parameters,
 660     Outputs, Notes, Examples, Compatibility, History, See
 661     Also.  The Parameters section is like the Options section, but
 662     there is more freedom about which clauses of the command can be
 663     listed.  The Outputs section is only needed if the command returns
 664     something other than a default command-completion tag.  The Compatibility
 665     section should explain to what extent
 666     this command conforms to the SQL standard(s), or to which other
 667     database system it is compatible.  The See Also section of SQL
 668     commands should list SQL commands before cross-references to
 669     programs.
 670    </para>
 671   </sect2>
 672
 673  </sect1>
 674 </appendix>