<!-- doc/src/sgml/docguide.sgml -->

<appendix id="docguide">
 <title>Documentation</title>

 <para>
  <productname>PostgreSQL</productname> has four primary documentation
  formats:

  <itemizedlist>
   <listitem>
    <para>
     Plain text, for pre-installation information
    </para>
   </listitem>
   <listitem>
    <para>
     <acronym>HTML</acronym>, for on-line browsing and reference
    </para>
   </listitem>
   <listitem>
    <para>
     PDF, for printing
    </para>
   </listitem>
   <listitem>
    <para>
     man pages, for quick reference.
    </para>
   </listitem>
  </itemizedlist>

  Additionally, a number of plain-text <filename>README</filename> files can
  be found throughout the <productname>PostgreSQL</productname> source tree,
  documenting various implementation issues.
 </para>

 <para>
  <acronym>HTML</acronym> documentation and man pages are part of a
  standard distribution and are installed by default.  PDF
  format documentation is available separately for
  download.
 </para>

 <sect1 id="docguide-docbook">
  <title>DocBook</title>
  <para>
   The documentation sources are written in
   <firstterm>DocBook</firstterm>, which is a markup language
   defined in <acronym>XML</acronym>.  In what
   follows, the terms DocBook and <acronym>XML</acronym> are both
   used, but technically they are not interchangeable.
  </para>

  <para>
  <productname>DocBook</productname> allows an author to specify the
   structure and content of a technical document without worrying
   about presentation details.  A document style defines how that
   content is rendered into one of several final forms.  DocBook is
   maintained by the <ulink url="https://www.oasis-open.org">
   OASIS group</ulink>.  The <ulink url="https://www.oasis-open.org/docbook/">
   official DocBook site</ulink> has good introductory and reference documentation and
   a complete O'Reilly book for your online reading pleasure.  The
   <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
   NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
   The <ulink url="https://www.freebsd.org/docproj/">
   FreeBSD Documentation Project</ulink> also uses DocBook and has some good
   information, including a number of style guidelines that might be
   worth considering.
  </para>
 </sect1>


 <sect1 id="docguide-toolsets">
  <title>Tool Sets</title>

  <para>
   The following tools are used to process the documentation.  Some
   might be optional, as noted.

   <variablelist>
    <varlistentry id="docguide-toolsets-docbook-dtd">
     <term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
     <listitem>
      <para>
       This is the definition of DocBook itself.  We currently use version
       4.5; you cannot use later or earlier versions.  You need
       the <acronym>XML</acronym> variant of the DocBook DTD, not
       the <acronym>SGML</acronym> variant.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="docguide-toolsets-docbook-xsl">
     <term><ulink url="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
     <listitem>
      <para>
       These contain the processing instructions for converting the
       DocBook sources to other formats, such as
       <acronym>HTML</acronym>.
      </para>

      <para>
       The minimum required version is currently 1.77.0, but it is recommended
       to use the latest available version for best results.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="docguide-toolsets-libxml2">
     <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
     <listitem>
      <para>
       This library and the <command>xmllint</command> tool it contains are
       used for processing XML.  Many developers will already
       have <application>Libxml2</application> installed, because it is also
       used when building the PostgreSQL code.