docguide.sgml 41.6 KB
Newer Older
1
<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.82 2010/05/31 22:14:20 momjian Exp $ -->
2

3
<appendix id="docguide">
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
4 5 6
 <title>Documentation</title>

 <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
  <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>
23
     PDF or PostScript, for printing
Peter Eisentraut's avatar
Peter Eisentraut committed
24 25 26 27 28 29 30 31 32
    </para>
   </listitem>
   <listitem>
    <para>
     man pages, for quick reference.
    </para>
   </listitem>
  </itemizedlist>

33 34
  Additionally, a number of plain-text <filename>README</filename> files can
  be found throughout the <productname>PostgreSQL</productname> source tree,
Peter Eisentraut's avatar
Peter Eisentraut committed
35
  documenting various implementation issues.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
36 37
 </para>

Peter Eisentraut's avatar
Peter Eisentraut committed
38 39
 <para>
  <acronym>HTML</acronym> documentation and man pages are part of a
40
  standard distribution and are installed by default.  PDF and
41
  PostScript format documentation is available separately for
42
  download.
Peter Eisentraut's avatar
Peter Eisentraut committed
43
 </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
44

45
 <sect1 id="docguide-docbook">
Peter Eisentraut's avatar
Peter Eisentraut committed
46
  <title>DocBook</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
47
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
48 49 50 51 52 53
   The documentation sources are written in
   <firstterm>DocBook</firstterm>, which is a markup language
   superficially similar to <acronym>HTML</acronym>.  Both of these
   languages are applications of the <firstterm>Standard Generalized
   Markup Language</firstterm>, <acronym>SGML</acronym>, which is
   essentially a language for describing other languages.  In what
54 55
   follows, the terms DocBook and <acronym>SGML</acronym> are both
   used, but technically they are not interchangeable.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
56 57 58
  </para>

  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
59 60 61 62
  <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
63
   maintained by the <ulink url="http://www.oasis-open.org">
64
   OASIS group</ulink>.  The <ulink url="http://www.oasis-open.org/docbook/">
65
   official DocBook site</ulink> has good introductory and reference documentation and
Peter Eisentraut's avatar
Peter Eisentraut committed
66
   a complete O'Reilly book for your online reading pleasure.  The
67
   <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
68 69 70
   NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
   The <ulink url="http://www.freebsd.org/docproj/docproj.html">
   FreeBSD Documentation Project</ulink> also uses DocBook and has some good
Peter Eisentraut's avatar
Peter Eisentraut committed
71 72
   information, including a number of style guidelines that might be
   worth considering.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
73 74 75 76
  </para>
 </sect1>


77
 <sect1 id="docguide-toolsets">
78
  <title>Tool Sets</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
79 80

  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
81
   The following tools are used to process the documentation.  Some
82
   might be optional, as noted.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
83

Peter Eisentraut's avatar
Peter Eisentraut committed
84 85
   <variablelist>
    <varlistentry>
86
     <term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
87 88 89
     <listitem>
      <para>
       This is the definition of DocBook itself.  We currently use
90 91 92 93
       version 4.2; you cannot use later or earlier versions.  You
       need the <acronym>SGML</acronym> variant of the DocBook DTD,
       but to build man pages you also need the <acronym>XML</acronym>
       variant of the same version.
Peter Eisentraut's avatar
Peter Eisentraut committed
94 95 96
      </para>
     </listitem>
    </varlistentry>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
97

Peter Eisentraut's avatar
Peter Eisentraut committed
98
    <varlistentry>
99
     <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
100 101 102 103 104 105 106
     <listitem>
      <para>
       These are required by DocBook but are distributed separately
       because they are maintained by ISO.
      </para>
     </listitem>
    </varlistentry>
107

Peter Eisentraut's avatar
Peter Eisentraut committed
108
    <varlistentry>
109
     <term><ulink url="http://wiki.docbook.org/topic/DocBookDssslStylesheets">DocBook DSSSL Stylesheets</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
110 111
     <listitem>
      <para>
112 113 114
       These contain the processing instructions for converting the
       DocBook sources to other formats, such as
       <acronym>HTML</acronym>.
Peter Eisentraut's avatar
Peter Eisentraut committed
115 116 117
      </para>
     </listitem>
    </varlistentry>
118

Peter Eisentraut's avatar
Peter Eisentraut committed
119
    <varlistentry>
120
     <term><ulink url="http://wiki.docbook.org/topic/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
121 122
     <listitem>
      <para>
123 124 125 126 127
       This is another stylesheet for converting DocBook to other
       formats.  We currently use this to produce man pages and
       optionally HTMLHelp.  You can also use this toolchain to
       produce HTML or PDF output, but official PostgreSQL releases
       use the DSSSL stylesheets for that.
Peter Eisentraut's avatar
Peter Eisentraut committed
128 129 130
      </para>
     </listitem>
    </varlistentry>
131

Peter Eisentraut's avatar
Peter Eisentraut committed
132
    <varlistentry>
133
     <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
134 135
     <listitem>
      <para>
136 137 138 139 140 141 142
       This is the base package of <acronym>SGML</acronym> processing.
       It contains an <acronym>SGML</acronym> parser, a
       <acronym>DSSSL</acronym> processor (that is, a program to
       convert <acronym>SGML</acronym> to other formats using
       <acronym>DSSSL</acronym> stylesheets), as well as a number of
       related tools.  <productname>Jade</productname> is now being
       maintained by the OpenJade group, no longer by James Clark.
143 144 145 146 147
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
148
     <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
149 150
     <listitem>
      <para>
151 152 153
       This is the processing tool to use with the XSLT stylesheets
       (like <command>jade</command> is the processing tool for DSSSL
       stylesheets).
Peter Eisentraut's avatar
Peter Eisentraut committed
154 155 156
      </para>
     </listitem>
    </varlistentry>
157

Peter Eisentraut's avatar
Peter Eisentraut committed
158
    <varlistentry>
159
     <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
160 161 162 163 164
     <listitem>
      <para>
       If you want to, you can also install
       <productname>JadeTeX</productname> to use
       <productname>TeX</productname> as a formatting backend for
165
       <productname>Jade</productname>.
166
       <application>JadeTeX</application> can create PostScript or
167 168 169 170 171 172 173 174 175
       <acronym>PDF</acronym> files (the latter with bookmarks).
      </para>

      <para>
       However, the output from <application>JadeTeX</application> is
       inferior to what you get from the <acronym>RTF</acronym>
       backend.  Particular problem areas are tables and various
       artifacts of vertical and horizontal spacing.  Also, there is
       no opportunity to manually polish the results.
Peter Eisentraut's avatar
Peter Eisentraut committed
176 177 178 179
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
180
  </para>
181

182
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
183 184
   We have documented experience with several installation methods for
   the various tools that are needed to process the documentation.
185
   These will be described below.  There might be some other packaged
Peter Eisentraut's avatar
Peter Eisentraut committed
186
   distributions for these tools. Please report package status to the
187 188
   documentation mailing list, and we will include that information
   here.
189
  </para>
190

191
  <sect2>
Peter Eisentraut's avatar
Peter Eisentraut committed
192
   <title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
193

194
   <para>
195 196 197
    Most vendors provide a complete RPM set for DocBook processing in
    their distribution.  Look for an <quote>SGML</quote> option while
    installing, or the following packages:
Peter Eisentraut's avatar
Peter Eisentraut committed
198 199 200 201 202
    <filename>sgml-common</filename>, <filename>docbook</filename>,
    <filename>stylesheets</filename>, <filename>openjade</filename>
    (or <filename>jade</filename>).  Possibly
    <filename>sgml-tools</filename> will be needed as well.  If your
    distributor does not provide these then you should be able to make
203
    use of the packages from some other, reasonably compatible vendor.
204
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
205
  </sect2>
206

207
  <sect2>
Peter Eisentraut's avatar
Peter Eisentraut committed
208
   <title>FreeBSD Installation</title>
209 210

   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228
    The FreeBSD Documentation Project is itself a heavy user of
    DocBook, so it comes as no surprise that there is a full set of
    <quote>ports</quote> of the documentation tools available on
    FreeBSD.  The following ports need to be installed to build the
    documentation on FreeBSD.
    <itemizedlist>
     <listitem>
      <para><filename>textproc/sp</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/openjade</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/iso8879</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/dsssl-docbook-modular</filename></para>
     </listitem>
229 230 231
     <listitem>
      <para><filename>textproc/docbook-420</filename></para>
     </listitem>
Peter Eisentraut's avatar
Peter Eisentraut committed
232
    </itemizedlist>
233 234 235
   </para>

   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
236 237 238
    A number of things from <filename>/usr/ports/print</filename>
    (<filename>tex</filename>, <filename>jadetex</filename>) might
    also be of interest.
239
   </para>
240

Peter Eisentraut's avatar
Peter Eisentraut committed
241 242
   <para>
    It's possible that the ports do not update the main catalog file
243
    in <filename>/usr/local/share/sgml/catalog.ports</filename> or order 
244
    isn't proper .  Be sure to have the following lines in begining of file:
Peter Eisentraut's avatar
Peter Eisentraut committed
245
<programlisting>
246 247 248 249
CATALOG "openjade/catalog"
CATALOG "iso8879/catalog"
CATALOG "docbook/dsssl/modular/catalog"
CATALOG "docbook/4.2/catalog"
Peter Eisentraut's avatar
Peter Eisentraut committed
250 251 252 253 254 255 256 257
</programlisting>
    If you do not want to edit the file you can also set the
    environment variable <envar>SGML_CATALOG_FILES</envar> to a
    colon-separated list of catalog files (such as the one above).
   </para>

   <para>
    More information about the FreeBSD documentation tools can be
258 259
    found in the <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
    FreeBSD Documentation Project's instructions</ulink>.
Peter Eisentraut's avatar
Peter Eisentraut committed
260
   </para>
261
  </sect2>
262

263
  <sect2>
Peter Eisentraut's avatar
Peter Eisentraut committed
264
   <title>Debian Packages</title>
265

266
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
267 268 269 270
    There is a full set of packages of the documentation tools
    available for <productname>Debian GNU/Linux</productname>.
    To install, simply use:
<programlisting>
271
apt-get install docbook docbook-dsssl docbook-xsl openjade xsltproc
Peter Eisentraut's avatar
Peter Eisentraut committed
272
</programlisting>
273
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
274 275 276 277
  </sect2>

  <sect2>
   <title>Manual Installation from Source</title>
278

279
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
280 281
    The manual installation process of the DocBook tools is somewhat
    complex, so if you have pre-built packages available, use them.
282
    We describe here only a standard setup, with reasonably standard
Peter Eisentraut's avatar
Peter Eisentraut committed
283 284 285
    installation paths, and no <quote>fancy</quote> features.  For
    details, you should study the documentation of the respective
    package, and read <acronym>SGML</acronym> introductory material.
286
   </para>
287

288
   <sect3>
289
    <title>Installing OpenJade</title>
290

291 292 293 294 295 296 297
    <procedure>
      <step>
       <para>
        The installation of OpenJade offers a GNU-style
        <literal>./configure; make; make install</literal> build
        process.  Details can be found in the OpenJade source
        distribution. In a nutshell:
Peter Eisentraut's avatar
Peter Eisentraut committed
298 299 300 301 302
<synopsis>
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
</synopsis>
303 304 305 306 307 308
        Be sure to remember where you put the <quote>default
        catalog</quote>; you will need it below.  You can also leave
        it off, but then you will have to set the environment variable
        <envar>SGML_CATALOG_FILES</envar> to point to the file
        whenever you use <application>jade</application> later on.
        (This method is also an option if OpenJade is already
Peter Eisentraut's avatar
Peter Eisentraut committed
309
        installed and you want to install the rest of the tool chain
310 311 312
        locally.)
       </para>
      </step>
313

314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
      <step id="doc-openjade-install">
       <para>
        Additionally, you should install the files
        <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
        <filename>style-sheet.dtd</filename>, and
        <filename>catalog</filename> from the
        <filename>dsssl</filename> directory somewhere, perhaps into
        <filename>/usr/local/share/sgml/dsssl</filename>.  It's
        probably easiest to copy the entire directory:
<synopsis>
cp -R dsssl /usr/local/share/sgml
</synopsis>
       </para>
      </step>

      <step>
       <para>
        Finally, create the file
        <filename>/usr/local/share/sgml/catalog</filename> and add
        this line to it:
<programlisting>
CATALOG "dsssl/catalog"
</programlisting>
        (This is a relative path reference to the file installed in
        <xref linkend="doc-openjade-install">.  Be sure to adjust it
        if you chose your installation layout differently.)
       </para>
      </step>
     </procedure>
Peter Eisentraut's avatar
Peter Eisentraut committed
343
   </sect3>
344

Peter Eisentraut's avatar
Peter Eisentraut committed
345 346
   <sect3>
    <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
347

Peter Eisentraut's avatar
Peter Eisentraut committed
348 349 350
    <procedure>
     <step>
      <para>
351 352
       Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
       DocBook V4.2 distribution</ulink>.
Peter Eisentraut's avatar
Peter Eisentraut committed
353 354
      </para>
     </step>
355

Peter Eisentraut's avatar
Peter Eisentraut committed
356 357
     <step>
      <para>
358
       Create the directory
359
       <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
360
       to it. (The exact location is irrelevant, but this one is
361
       reasonable within the layout we are following here.)
Peter Eisentraut's avatar
Peter Eisentraut committed
362
<screen>
363 364
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
Peter Eisentraut's avatar
Peter Eisentraut committed
365 366 367
</screen>
      </para>
     </step>
368

Peter Eisentraut's avatar
Peter Eisentraut committed
369 370
     <step>
      <para>
371
       Unpack the archive:
372
<screen>
373
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
374 375
</screen>
       (The archive will unpack its files into the current directory.)
Peter Eisentraut's avatar
Peter Eisentraut committed
376 377
      </para>
     </step>
378

Peter Eisentraut's avatar
Peter Eisentraut committed
379 380
     <step>
      <para>
381
       Edit the file
Peter Eisentraut's avatar
Peter Eisentraut committed
382 383 384 385
       <filename>/usr/local/share/sgml/catalog</filename> (or whatever
       you told jade during installation) and put a line like this
       into it:
<programlisting>
386
CATALOG "docbook-4.2/docbook.cat"
Peter Eisentraut's avatar
Peter Eisentraut committed
387 388
</programlisting>
      </para>
389
     </step>
390

Peter Eisentraut's avatar
Peter Eisentraut committed
391 392
     <step>
      <para>
393 394
       Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
       ISO 8879 character entities archive</ulink>, unpack it, and put the
395
       files in the same directory you put the DocBook files in:
396
<screen>
397
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
398 399 400 401 402 403 404 405 406 407 408 409 410 411
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
</screen>
      </para>
     </step>

     <step>
      <para>
       Run the following command in the directory with the DocBook and ISO files:
<programlisting>
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
       (This fixes a mixup between the names used in the DocBook
       catalog file and the actual names of the ISO character entity
       files.)
Peter Eisentraut's avatar
Peter Eisentraut committed
412 413 414 415 416 417
      </para>
     </step>
    </procedure>
   </sect3>

   <sect3>
418 419 420 421 422 423
    <title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>

    <para>
     To install the style sheets, unzip and untar the distribution and
     move it to a suitable place, for example
     <filename>/usr/local/share/sgml</filename>.  (The archive will
424
     automatically create a subdirectory.)
425 426 427 428 429
<screen>
<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
</screen>
    </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
430 431

    <para>
432 433 434 435
     The usual catalog entry in
     <filename>/usr/local/share/sgml/catalog</filename> can also be
     made:
<programlisting>
Tom Lane's avatar
Tom Lane committed
436
CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog"
437 438 439 440
</programlisting>
     Because stylesheets change rather often, and it's sometimes
     beneficial to try out alternative versions,
     <productname>PostgreSQL</productname> doesn't use this catalog
441 442
     entry.  See <xref linkend="docguide-toolsets-configure"> for
     information about how to select the stylesheets instead.
443
    </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
444 445 446 447
   </sect3>

   <sect3>
    <title>Installing <productname>JadeTeX</productname></title>
448

449
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465
     To install and use <productname>JadeTeX</productname>, you will
     need a working installation of <productname>TeX</productname> and
     <productname>LaTeX2e</productname>, including the supported
     <productname>tools</productname> and
     <productname>graphics</productname> packages,
     <productname>Babel</productname>,
     <productname><acronym>AMS</acronym> fonts</productname> and
     <productname>AMS-LaTeX</productname>, the
     <productname><acronym>PSNFSS</acronym></productname> extension
     and companion kit of <quote>the 35 fonts</quote>, the
     <productname>dvips</productname> program for generating
     <productname>PostScript</productname>, the macro packages
     <productname>fancyhdr</productname>,
     <productname>hyperref</productname>,
     <productname>minitoc</productname>,
     <productname>url</productname> and
466
     <productname>ot2enc</productname>.  All of these can be found on
467
     your friendly neighborhood <ulink url="http://www.ctan.org">
468
     <acronym>CTAN</acronym> site</ulink>.
469 470 471 472
     The installation of the <application>TeX</application> base
     system is far beyond the scope of this introduction.  Binary
     packages should be available for any system that can run
     <application>TeX</application>.
Peter Eisentraut's avatar
Peter Eisentraut committed
473 474 475
    </para>

    <para>
476 477 478 479 480
     Before you can use <application>JadeTeX</application> with the
     <productname>PostgreSQL</productname> documentation sources, you
     will need to increase the size of
     <application>TeX</application>'s internal data structures.
     Details on this can be found in the <application>JadeTeX</application>
481
     installation instructions.
Peter Eisentraut's avatar
Peter Eisentraut committed
482 483 484
    </para>

    <para>
485 486 487 488 489 490 491 492 493
     Once that is finished you can install <application>JadeTeX</application>:
<screen>
<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
<prompt>$</prompt> <userinput>cd jadetex</userinput>
<prompt>$</prompt> <userinput>make install</userinput>
<prompt>$</prompt> <userinput>mktexlsr</userinput>
</screen>
     The last two need to be done as <systemitem>root</systemitem>.
494
    </para>
495

496
   </sect3>
Peter Eisentraut's avatar
Peter Eisentraut committed
497

498
  </sect2>
499

500 501
  <sect2 id="docguide-toolsets-configure">
   <title>Detection by <command>configure</command></title>
502

503
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
504 505
   Before you can build the documentation you need to run the
   <filename>configure</filename> script as you would when building
506 507 508
   the <productname>PostgreSQL</productname> programs themselves.
   Check the output near the end of the run, it should look something
   like this:
Peter Eisentraut's avatar
Peter Eisentraut committed
509 510 511 512
<screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for openjade... openjade
513
checking for DocBook V4.2... yes
514 515 516 517
checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
checking for collateindex.pl... /usr/bin/collateindex.pl
checking for xsltproc... xsltproc
checking for osx... osx
Peter Eisentraut's avatar
Peter Eisentraut committed
518 519 520
</computeroutput>
</screen>
   If neither <filename>onsgmls</filename> nor
521 522
   <filename>nsgmls</filename> were found then some of the following tests
   will be skipped.  <filename>nsgmls</filename> is part of the Jade
523 524 525 526 527 528 529 530 531
   package.  You can pass the environment variables
   <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
   to the programs if they are not found automatically.  If
   <quote>DocBook V4.2</quote> was not found then you did not install
   the DocBook DTD kit in a place where Jade can find it, or you have
   not set up the catalog files correctly.  See the installation hints
   above.  The DocBook stylesheets are looked for in a number of
   relatively standard places, but if you have them some other place
   then you should set the environment variable
Peter Eisentraut's avatar
Peter Eisentraut committed
532 533
   <envar>DOCBOOKSTYLE</envar> to the location and rerun
   <filename>configure</filename> afterwards.
534
  </para>
535

536 537 538 539 540 541
  </sect2>
 </sect1>

 <sect1 id="docguide-build">
  <title>Building The Documentation</title>

542
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
543
   Once you have everything set up, change to the directory
544 545 546 547
   <filename>doc/src/sgml</filename> and run one of the commands
   described in the following subsections to build the
   documentation. (Remember to use GNU make.)
  </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
548

549 550
  <sect2>
   <title>HTML</title>
Peter Eisentraut's avatar
Peter Eisentraut committed
551

552 553
   <para>
    To build the <acronym>HTML</acronym> version of the documentation:
Peter Eisentraut's avatar
Peter Eisentraut committed
554
<screen>
555
<prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
Peter Eisentraut's avatar
Peter Eisentraut committed
556
</screen>
557 558
    This is also the default target.  The output appears in the
    subdirectory <filename>html</filename>.
559
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
560

561
   <para>
562
    To create a proper index, the build might process several identical
563
    stages.  If you do not care about the index, and just want to
564 565
    proof-read the output, use <literal>draft</>:
<screen>
566
<prompt>doc/src/sgml$ </prompt><userinput>gmake draft</userinput>
567
</screen>
568
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
569
 </sect2>
570

571
 <sect2>
572 573 574
  <title>Manpages</title>

  <para>
575
   We use the DocBook XSL stylesheets to
576
   convert <productname>DocBook</productname>
577
   <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
Peter Eisentraut's avatar
Peter Eisentraut committed
578
   pages.  The man pages are also distributed as a tar archive,
579
   similar to the <acronym>HTML</acronym> version.  To create the man
580
   pages, use the commands:
Peter Eisentraut's avatar
Peter Eisentraut committed
581
<programlisting>
582
cd doc/src/sgml
583
gmake man
Peter Eisentraut's avatar
Peter Eisentraut committed
584
</programlisting>
585
  </para>
586
 </sect2>
587

588
  <sect2>
589
   <title>Print Output via <application>JadeTeX</application></title>
590

591 592
   <para>
    If you want to use <application>JadeTex</application> to produce a
593
    printable rendition of the documentation, you can use one of the
594
    following commands:
595

596 597 598
    <itemizedlist>
     <listitem>
      <para>
599
       To generate PostScript via <acronym>DVI</acronym> in A4 format:
600
<screen>
601
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.ps</userinput>
602
</screen>
603
       In U.S. letter format:
604
<screen>
605
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.ps</userinput>
606 607 608 609 610 611 612 613
</screen>
      </para>
     </listitem>
  
     <listitem>
      <para>
       To make a <acronym>PDF</acronym>:
<screen>
614 615
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.pdf</userinput>
</screen>
616
       or:
617 618
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.pdf</userinput>
619 620
</screen>
       (Of course you can also make a <acronym>PDF</acronym> version
621
       from the PostScript, but if you generate <acronym>PDF</acronym>
622 623 624 625 626
       directly, it will have hyperlinks and other enhanced features.)
      </para>
     </listitem>
    </itemizedlist>
   </para>
627 628 629 630 631 632 633 634 635 636 637 638 639 640 641

   <para>
    When using JadeTeX to build the PostgreSQL documentation, you will
    probably need to increase some of TeX's internal parameters.  These
    can be set in the file <filename>texmf.cnf</filename>.  The following
    settings worked at the time of this writing:
<programlisting>
hash_extra.jadetex  = 200000
hash_extra.pdfjadetex  = 200000
pool_size.jadetex = 2000000
pool_size.pdfjadetex = 2000000
string_vacancies.jadetex = 150000
string_vacancies.pdfjadetex = 150000
max_strings.jadetex = 300000
max_strings.pdfjadetex = 300000
642 643
save_size.jadetex = 15000
save_size.pdfjadetex = 15000
644 645
</programlisting>
   </para>
646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665

  </sect2>

  <sect2>
   <title>Overflow Text</title>

   <para>
    Occasionally text is too wide for the printed margins, and in
    extreme cases, too wide for the printed page, e.g.  non-wrapped
    text, wide tables.  Overly wide text generates <quote>Overfull
    hbox</quote> messages in the TeX log output file, e.g.
    <filename>postgres-US.log</> or <filename>postgres-A4.log</>.
    There are 72 points in an inch so anything reported as over 72
    points too wide will probably not fit on the printed page (assuming
    one inch margins).  To find the <acronym>SGML</acronym> text
    causing the overflow, find the first page number mentioned above
    the overflow message, e.g.  <literal>[50 XXX]</> (page 50), and look
    at that page in the <acronym>PDF</acronym> file to see the overflow
    text and adjust the <acronym>SGML</acronym> accordingly.
   </para>
666
  </sect2>
667

668 669
  <sect2>
   <title>Print Output via <acronym>RTF</acronym></title>
670

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
671
   <para>
672
    You can also create a printable version of the <productname>PostgreSQL</productname>
673 674 675
    documentation by converting it to <acronym>RTF</acronym> and
    applying minor formatting corrections using an office suite.
    Depending on the capabilities of the particular office suite, you
676
    can then convert the documentation to PostScript of
677 678
    <acronym>PDF</acronym>.  The procedure below illustrates this
    process using <productname>Applixware</productname>.
679
   </para>
680

681 682
   <note>
    <para>
683
     It appears that current versions of the <productname>PostgreSQL</productname> documentation
684 685
     trigger some bug in or exceed the size limit of OpenJade.  If the
     build process of the <acronym>RTF</acronym> version hangs for a
686
     long time and the output file still has size 0, then you might have
687 688 689 690 691
     hit that problem.  (But keep in mind that a normal build takes 5
     to 10 minutes, so don't abort too soon.)
    </para>
   </note>

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
692
   <procedure>
693
    <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
694

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
695
    <para>
696 697 698 699 700
     <application>OpenJade</application> omits specifying a default
     style for body text. In the past, this undiagnosed problem led to
     a long process of table of contents generation. However, with
     great help from the <productname>Applixware</productname> folks
     the symptom was diagnosed and a workaround is available.
701
    </para>
702

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
703 704
    <step performance="required">
     <para>
705 706 707 708
      Generate the <acronym>RTF</acronym> version by typing:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
</screen>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
709 710 711 712 713
     </para>
    </step>

    <step performance="required">
     <para>
714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734
      Repair the RTF file to correctly specify all styles, in
      particular the default style. If the document contains
      <sgmltag>refentry</sgmltag> sections, one must also replace
      formatting hints which tie a preceding paragraph to the current
      paragraph, and instead tie the current paragraph to the
      following one. A utility, <command>fixrtf</command>, is
      available in <filename>doc/src/sgml</filename> to accomplish
      these repairs:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
</screen>
     </para>

     <para>
      The script adds <literal>{\s0 Normal;}</literal> as the zeroth
      style in the document. According to
      <productname>Applixware</productname>, the RTF standard would
      prohibit adding an implicit zeroth style, though Microsoft Word
      happens to handle this case. For repairing
      <sgmltag>refentry</sgmltag> sections, the script replaces
      <literal>\keepn</literal> tags with <literal>\keep</literal>.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
735 736 737 738 739
     </para>
    </step>

    <step performance="required">
     <para>
740
      Open a new document in <productname>Applixware Words</productname> and
741
      then import the <acronym>RTF</acronym> file.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
742 743 744 745 746
     </para>
    </step>

    <step performance="required">
     <para>
747 748
      Generate a new table of contents (ToC) using
      <productname>Applixware</productname>.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
749
     </para>
750 751 752 753

     <substeps>
      <step>
       <para>
754 755 756
        Select the existing ToC lines, from the beginning of the first
        character on the first line to the last character of the last
        line.
757 758 759 760 761
       </para>
      </step>

      <step>
       <para>
762 763 764 765 766 767 768
        Build a new ToC using
        <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
        Building</guisubmenu><guimenuitem>Create Table of
        Contents</guimenuitem></menuchoice>. Select the first three
        levels of headers for inclusion in the ToC. This will replace
        the existing lines imported in the RTF with a native
        <productname>Applixware</productname> ToC.
769 770 771 772 773
       </para>
      </step>

      <step>
       <para>
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810
        Adjust the ToC formatting by using
        <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
        selecting each of the three ToC styles, and adjusting the
        indents for <literal>First</literal> and
        <literal>Left</literal>. Use the following values:

        <informaltable>
         <tgroup cols="3">
          <thead>
           <row>
            <entry>Style</entry>
            <entry>First Indent (inches)</entry>
            <entry>Left Indent (inches)</entry>
           </row>
          </thead>

          <tbody>
           <row>
            <entry><literal>TOC-Heading 1</literal></entry>
            <entry><literal>0.4</literal></entry>
            <entry><literal>0.4</literal></entry>
           </row>

           <row>
            <entry><literal>TOC-Heading 2</literal></entry>
            <entry><literal>0.8</literal></entry>
            <entry><literal>0.8</literal></entry>
           </row>

           <row>
            <entry><literal>TOC-Heading 3</literal></entry>
            <entry><literal>1.2</literal></entry>
            <entry><literal>1.2</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </informaltable>
811 812 813
       </para>
      </step>
     </substeps>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
814 815 816 817
    </step>

    <step performance="required">
     <para>
818 819 820 821
      Work through the document to:

      <itemizedlist>
       <listitem>
822 823 824
        <para>
         Adjust page breaks.
        </para>
825 826 827
       </listitem>

       <listitem>
828 829 830
        <para>
         Adjust table column widths.
        </para>
831 832
       </listitem>
      </itemizedlist>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
833 834 835 836 837
     </para>
    </step>

    <step performance="required">
     <para>
838
      Replace the right-justified page numbers in the Examples and
839 840
      Figures portions of the ToC with correct values. This only takes
      a few minutes.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
841 842
     </para>
    </step>
843 844 845 846 847 848 849 850 851 852 853 854 855 856

    <step performance="optional">
     <para>
       Delete the index section from the document if it is empty.
     </para>
    </step>

    <step performance="required">
     <para>
       Regenerate and adjust the table of contents.
     </para>

      <substeps>
       <step>
857 858 859
        <para>
         Select the ToC field.
        </para>
860 861 862
       </step>

       <step>
863 864 865 866 867
        <para>
         Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
         Building</guisubmenu><guimenuitem>Create Table of
         Contents</guimenuitem></menuchoice>.
        </para>
868 869 870
       </step>

       <step>
871 872 873 874 875
        <para>
         Unbind the ToC by selecting
         <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
         Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
        </para>
876 877 878
       </step>

       <step>
879 880 881 882
        <para>
         Delete the first line in the ToC, which is an entry for the
         ToC itself.
        </para>
883 884 885
       </step>
      </substeps>
    </step>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
886 887 888

    <step performance="required">
     <para>
889 890 891
      Save the document as native <productname>Applixware
      Words</productname> format to allow easier last minute editing
      later.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
892 893 894 895 896
     </para>
    </step>

    <step performance="required">
     <para>
897
      <quote>Print</quote> the document
898
      to a file in PostScript format.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
899 900 901
     </para>
    </step>
   </procedure>
902 903 904 905 906 907 908 909
  </sect2>

  <sect2>
   <title>Plain Text Files</title>

   <para>
    Several files are distributed as plain text, for reading during
    the installation process. The <filename>INSTALL</filename> file
910 911 912 913 914 915 916 917 918 919
    corresponds to <xref linkend="installation">, with some minor
    changes to account for the different context.  To recreate the
    file, change to the directory <filename>doc/src/sgml</filename>
    and enter <userinput>gmake INSTALL</userinput>.  This will create
    a file <filename>INSTALL.html</filename> that can be saved as text
    with <productname>Netscape Navigator</productname> and put into
    the place of the existing file.
    <productname>Netscape</productname> seems to offer the best
    quality for <acronym>HTML</acronym> to text conversions (over
    <application>lynx</application> and
920 921 922 923 924
    <application>w3m</application>).
   </para>

   <para>
    The file <filename>HISTORY</filename> can be created similarly,
925 926 927
    using the command <userinput>gmake HISTORY</userinput>.  For the
    file <filename>src/test/regress/README</filename> the command is
    <userinput>gmake regress_README</userinput>.
928
   </para>
929
  </sect2>
930

931 932
  <sect2>
   <title>Syntax Check</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
933

934 935 936 937 938 939 940 941
   <para>
    Building the documentation can take very long.  But there is a
    method to just check the correct syntax of the documentation
    files, which only takes a few seconds:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
</screen>
   </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
942
  </sect2>
943
 </sect1>
944

945

946
 <sect1 id="docguide-authoring">
Peter Eisentraut's avatar
Peter Eisentraut committed
947
  <title>Documentation Authoring</title>
948

949
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
950 951
    <acronym>SGML</acronym> and <productname>DocBook</productname> do
    not suffer from an oversupply of open-source authoring tools. The
952
    most common tool set is the
Peter Eisentraut's avatar
Peter Eisentraut committed
953 954
    <productname>Emacs</productname>/<productname>XEmacs</productname>
    editor with appropriate editing mode.  On some systems
955
    these tools are provided in a typical full installation.
956
   </para>
957

Peter Eisentraut's avatar
Peter Eisentraut committed
958 959
   <sect2>
    <title>Emacs/PSGML</title>
960

961
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
962 963 964 965
     <productname>PSGML</productname> is the most common and most
     powerful mode for editing <acronym>SGML</acronym> documents.
     When properly configured, it will allow you to use
     <application>Emacs</application> to insert tags and check markup
966
     consistency.  You could use it for <acronym>HTML</acronym> as
967 968
     well.  Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
     PSGML web site</ulink> for downloads, installation instructions, and
Peter Eisentraut's avatar
Peter Eisentraut committed
969
     detailed documentation.
970
    </para>
971

972
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
973 974 975 976 977 978 979 980 981 982
     There is one important thing to note with
     <productname>PSGML</productname>: its author assumed that your
     main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
     would be <filename>/usr/local/lib/sgml</filename>.  If, as in the
     examples in this chapter, you use
     <filename>/usr/local/share/sgml</filename>, you have to
     compensate for this, either by setting
     <envar>SGML_CATALOG_FILES</envar> environment variable, or you
     can customize your <productname>PSGML</productname> installation
     (its manual tells you how).
983
    </para>
984

985
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
986 987 988
     Put the following in your <filename>~/.emacs</filename>
     environment file (adjusting the path names to be appropriate for
     your system):
989

Peter Eisentraut's avatar
Peter Eisentraut committed
990 991
<programlisting>
; ********** for SGML mode (psgml)
992

Peter Eisentraut's avatar
Peter Eisentraut committed
993 994 995 996 997 998 999 1000 1001 1002 1003
(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)
1004

Peter Eisentraut's avatar
Peter Eisentraut committed
1005 1006
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>
1007

Peter Eisentraut's avatar
Peter Eisentraut committed
1008 1009 1010 1011 1012 1013 1014 1015 1016
     and in the same file add an entry for <acronym>SGML</acronym>
     into the (existing) definition for
     <varname>auto-mode-alist</varname>:
<programlisting>
(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))
</programlisting>
1017
    </para>
1018

1019
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
1020 1021
     The <productname>PostgreSQL</productname> distribution includes a
     parsed DTD definitions file <filename>reference.ced</filename>.
1022
     You might find that when using <productname>PSGML</productname>, a
1023 1024 1025 1026 1027 1028
     comfortable way of working with these separate files of book
     parts is to insert a proper <literal>DOCTYPE</literal>
     declaration while you're editing them.  If you are working on
     this source, for instance, it is an appendix chapter, so you
     would specify the document as an <quote>appendix</quote> instance
     of a DocBook document by making the first line look like this:
Peter Eisentraut's avatar
Peter Eisentraut committed
1029 1030

<programlisting>
1031
&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"&gt;
Peter Eisentraut's avatar
Peter Eisentraut committed
1032 1033 1034 1035 1036 1037 1038
</programlisting>

     This means that anything and everything that reads
     <acronym>SGML</acronym> will get it right, and I can verify the
     document with <command>nsgmls -s docguide.sgml</command>.  (But
     you need to take out that line before building the entire
     documentation set.)
1039
    </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
1040 1041 1042 1043
   </sect2>

   <sect2>
    <title>Other Emacs modes</title>
1044

1045
    <para>
1046 1047
     <productname>GNU Emacs</productname> ships with a different
     <acronym>SGML</acronym> mode, which is not quite as powerful as
Peter Eisentraut's avatar
Peter Eisentraut committed
1048 1049 1050
     <productname>PSGML</productname>, but it's less confusing and
     lighter weight.  Also, it offers syntax highlighting (font lock),
     which can be very helpful.
1051 1052 1053
    </para>

    <para>
1054 1055 1056 1057
     Norm Walsh offers a
     <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
     specifically for DocBook which also has font-lock and a number of features to 
     reduce typing.
1058
    </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
1059
   </sect2>
1060

1061
 </sect1>
1062

1063

1064
 <sect1 id="docguide-style">
1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084
  <title>Style Guide</title>

  <sect2>
   <title>Reference Pages</title>

   <para>
    Reference pages should follow a standard layout.  This allows
    users to find the desired information more quickly, and it also
    encourages writers to document all relevant aspects of a command.
    Consistency is not only desired among
    <productname>PostgreSQL</productname> reference pages, but also
    with reference pages provided by the operating system and other
    packages.  Hence the following guidelines have been developed.
    They are for the most part consistent with similar guidelines
    established by various operating systems.
   </para>

   <para>
    Reference pages that describe executable commands should contain
    the following sections, in this order.  Sections that do not apply
1085
    can be omitted.  Additional top-level sections should only be used
1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125
    in special circumstances; often that information belongs in the
    <quote>Usage</quote> section.

    <variablelist>
     <varlistentry>
      <term>Name</term>
      <listitem>
       <para>
        This section is generated automatically.  It contains the
        command name and a half-sentence summary of its functionality.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Synopsis</term>
      <listitem>
       <para>
        This section contains the syntax diagram of the command.  The
        synopsis should normally not list each command-line option;
        that is done below.  Instead, list the major components of the
        command line, such as where input and output files go.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Description</term>
      <listitem>
       <para>
        Several paragraphs explaining what the command does.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Options</term>
      <listitem>
       <para>
        A list describing each command-line option.  If there are a
1126
        lot of options, subsections can be used.
1127 1128 1129 1130 1131 1132 1133 1134 1135
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Exit Status</term>
      <listitem>
       <para>
        If the program uses 0 for success and non-zero for failure,
1136
        then you do not need to document it.  If there is a meaning
1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240
        behind the different non-zero exit codes, list them here.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Usage</term>
      <listitem>
       <para>
        Describe any sublanguage or run-time interface of the program.
        If the program is not interactive, this section can usually be
        omitted.  Otherwise, this section is a catch-all for
        describing run-time features.  Use subsections if appropriate.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Environment</term>
      <listitem>
       <para>
        List all environment variables that the program might use.
        Try to be complete; even seemingly trivial variables like
        <envar>SHELL</envar> might be of interest to the user.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Files</term>
      <listitem>
       <para>
        List any files that the program might access implicitly.  That
        is, do not list input and output files that were specified on
        the command line, but list configuration files, etc.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Diagnostics</term>
      <listitem>
       <para>
        Explain any unusual output that the program might create.
        Refrain from listing every possible error message.  This is a
        lot of work and has little use in practice.  But if, say, the
        error messages have a standard format that the user can parse,
        this would be the place to explain it.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Notes</term>
      <listitem>
       <para>
        Anything that doesn't fit elsewhere, but in particular bugs,
        implementation flaws, security considerations, compatibility
        issues.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Examples</term>
      <listitem>
       <para>
        Examples
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>History</term>
      <listitem>
       <para>
        If there were some major milestones in the history of the
        program, they might be listed here.  Usually, this section can
        be omitted.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>See Also</term>
      <listitem>
       <para>
        Cross-references, listed in the following order: other
        <productname>PostgreSQL</productname> command reference pages,
        <productname>PostgreSQL</productname> SQL command reference
        pages, citation of <productname>PostgreSQL</productname>
        manuals, other reference pages (e.g., operating system, other
        packages), other documentation.  Items in the same group are
        listed alphabetically.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    Reference pages describing SQL commands should contain the
    following sections: Name, Synopsis, Description, Parameters,
1241
    Outputs, Notes, Examples, Compatibility, History, See
1242 1243
    Also.  The Parameters section is like the Options section, but
    there is more freedom about which clauses of the command can be
1244 1245 1246
    listed.  The Outputs section is only needed if the command returns
    something other than a default command-completion tag.  The Compatibility
    section should explain to what extent
1247 1248 1249 1250 1251 1252 1253 1254
    this command conforms to the SQL standard(s), or to which other
    database system it is compatible.  The See Also section of SQL
    commands should list SQL commands before cross-references to
    programs.
   </para>
  </sect2>

 </sect1>
1255
</appendix>