docguide.sgml 41.1 KB
Newer Older
1
<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.51 2004/11/15 06:32:13 neilc 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 41 42
  standard distribution and are installed by default.  PDF and
  Postscript format documentation is available separately for
  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 63 64 65 66 67 68 69 70 71
  <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="http://www.oasis-open.org">OASIS</ulink> group.  The <ulink
   url="http://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://www.freebsd.org/docproj/docproj.html">FreeBSD
   Documentation Project</ulink> also uses DocBook and has some good
   information, including a number of style guidelines that might be
   worth considering.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
72 73 74 75
  </para>
 </sect1>


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

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

Peter Eisentraut's avatar
Peter Eisentraut committed
83 84 85 86 87 88
   <variablelist>
    <varlistentry>
     <term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
     <listitem>
      <para>
       This is the definition of DocBook itself.  We currently use
89
       version 4.2; you cannot use later or earlier versions.  Note
Peter Eisentraut's avatar
Peter Eisentraut committed
90
       that there is also an <acronym>XML</acronym> version of DocBook
91
       &mdash; do not use that.
Peter Eisentraut's avatar
Peter Eisentraut committed
92 93 94
      </para>
     </listitem>
    </varlistentry>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
95

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

Peter Eisentraut's avatar
Peter Eisentraut committed
106
    <varlistentry>
107
     <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
108 109 110 111 112 113 114 115 116 117 118 119
     <listitem>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
120

Peter Eisentraut's avatar
Peter Eisentraut committed
121
    <varlistentry>
122
     <term><ulink url="http://docbook.sourceforge.net/projects/dsssl/index.html">DocBook DSSSL Stylesheets</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
123 124 125 126 127 128 129 130
     <listitem>
      <para>
       These contain the processing instructions for converting the
       DocBook sources to other formats, such as
       <acronym>HTML</acronym>.
      </para>
     </listitem>
    </varlistentry>
131

Peter Eisentraut's avatar
Peter Eisentraut committed
132 133 134 135 136 137 138 139 140 141
    <varlistentry>
     <term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
     <listitem>
      <para>
       This optional package is used to create man pages.  It has a
       number of prerequisite packages of its own.  Check the web
       site.
      </para>
     </listitem>
    </varlistentry>
142

Peter Eisentraut's avatar
Peter Eisentraut committed
143
    <varlistentry>
144
     <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
Peter Eisentraut's avatar
Peter Eisentraut committed
145 146 147 148 149
     <listitem>
      <para>
       If you want to, you can also install
       <productname>JadeTeX</productname> to use
       <productname>TeX</productname> as a formatting backend for
150 151 152 153 154 155 156 157 158 159 160
       <productname>Jade</productname>.
       <application>JadeTeX</application> can create Postscript or
       <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
161 162 163 164
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
165
  </para>
166

167
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
168 169 170 171
   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 may be some other packaged
   distributions for these tools. Please report package status to the
172 173
   documentation mailing list, and we will include that information
   here.
174
  </para>
175

176
  <sect2>
Peter Eisentraut's avatar
Peter Eisentraut committed
177
   <title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
178

179
   <para>
180 181 182
    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
183 184 185 186 187
    <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
188
    use of the packages from some other, reasonably compatible vendor.
189
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
190
  </sect2>
191

192
  <sect2>
Peter Eisentraut's avatar
Peter Eisentraut committed
193
   <title>FreeBSD Installation</title>
194 195

   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
    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>
    </itemizedlist>
215 216 217 218 219
    Apparently, there is no port for the DocBook V4.2 SGML DTD
    available right now.  You will need to install it manually.
   </para>

   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
220 221 222
    A number of things from <filename>/usr/ports/print</filename>
    (<filename>tex</filename>, <filename>jadetex</filename>) might
    also be of interest.
223
   </para>
224

Peter Eisentraut's avatar
Peter Eisentraut committed
225 226 227 228 229
   <para>
    It's possible that the ports do not update the main catalog file
    in <filename>/usr/local/share/sgml/catalog</filename>.  Be sure to
    have the following line in there:
<programlisting>
230
CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"
Peter Eisentraut's avatar
Peter Eisentraut committed
231 232 233 234 235 236 237 238 239
</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
    found in the <ulink
240
    url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">FreeBSD
Peter Eisentraut's avatar
Peter Eisentraut committed
241 242
    Documentation Project's instructions</ulink>.
   </para>
243
  </sect2>
244

245
  <sect2>
Peter Eisentraut's avatar
Peter Eisentraut committed
246
   <title>Debian Packages</title>
247

248
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
249 250 251 252 253 254 255 256
    There is a full set of packages of the documentation tools
    available for <productname>Debian GNU/Linux</productname>.
    To install, simply use:
<programlisting>
apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets
</programlisting>
257
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
258 259 260 261
  </sect2>

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

263
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
264 265
    The manual installation process of the DocBook tools is somewhat
    complex, so if you have pre-built packages available, use them.
266
    We describe here only a standard setup, with reasonably standard
Peter Eisentraut's avatar
Peter Eisentraut committed
267 268 269
    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.
270
   </para>
271

272
   <sect3>
273
    <title>Installing OpenJade</title>
274

275 276 277 278 279 280 281
    <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
282 283 284 285 286
<synopsis>
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
</synopsis>
287 288 289 290 291 292 293 294 295 296
        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
        installed and you want to install the rest of the toolchain
        locally.)
       </para>
      </step>
297

298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
      <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
327
   </sect3>
328

Peter Eisentraut's avatar
Peter Eisentraut committed
329 330
   <sect3>
    <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
331

Peter Eisentraut's avatar
Peter Eisentraut committed
332 333 334 335
    <procedure>
     <step>
      <para>
       Obtain the <ulink
336 337
       url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">DocBook
       V4.2</ulink> distribution.
Peter Eisentraut's avatar
Peter Eisentraut committed
338 339
      </para>
     </step>
340

Peter Eisentraut's avatar
Peter Eisentraut committed
341 342
     <step>
      <para>
343
       Create the directory
344
       <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
345 346
       to it. (The exact location is irrelevant, but this one is
       reasonable within the layout we are following here.)
Peter Eisentraut's avatar
Peter Eisentraut committed
347
<screen>
348 349
<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
350 351 352
</screen>
      </para>
     </step>
353

Peter Eisentraut's avatar
Peter Eisentraut committed
354 355
     <step>
      <para>
356 357
       Unpack the archive.
<screen>
358
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
359 360
</screen>
       (The archive will unpack its files into the current directory.)
Peter Eisentraut's avatar
Peter Eisentraut committed
361 362
      </para>
     </step>
363

Peter Eisentraut's avatar
Peter Eisentraut committed
364 365
     <step>
      <para>
366
       Edit the file
Peter Eisentraut's avatar
Peter Eisentraut committed
367 368 369 370
       <filename>/usr/local/share/sgml/catalog</filename> (or whatever
       you told jade during installation) and put a line like this
       into it:
<programlisting>
371
CATALOG "docbook-4.2/docbook.cat"
Peter Eisentraut's avatar
Peter Eisentraut committed
372 373
</programlisting>
      </para>
374
     </step>
375

Peter Eisentraut's avatar
Peter Eisentraut committed
376 377 378 379 380 381
     <step>
      <para>
       Download the <ulink
       url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879
       character entities</ulink> archive, unpack it, and put the
       files in the same directory you put the DocBook files in.
382
<screen>
383
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
384 385 386 387 388 389 390 391 392 393 394 395 396 397
<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
398 399 400 401 402 403
      </para>
     </step>
    </procedure>
   </sect3>

   <sect3>
404 405 406 407 408 409 410 411 412 413 414 415
    <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
     automatically create a subdirectory.)
<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
416 417

    <para>
418 419 420 421
     The usual catalog entry in
     <filename>/usr/local/share/sgml/catalog</filename> can also be
     made:
<programlisting>
422
CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog
423 424 425 426
</programlisting>
     Because stylesheets change rather often, and it's sometimes
     beneficial to try out alternative versions,
     <productname>PostgreSQL</productname> doesn't use this catalog
427 428
     entry.  See <xref linkend="docguide-toolsets-configure"> for
     information about how to select the stylesheets instead.
429
    </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
430 431 432 433
   </sect3>

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

435
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451
     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
452 453
     <productname>ot2enc</productname>.  All of these can be found on
     your friendly neighborhood <ulink
Peter Eisentraut's avatar
Peter Eisentraut committed
454
     url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> site.
455 456 457 458
     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
459 460 461
    </para>

    <para>
462 463 464 465 466
     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>
467
     installation instructions.
Peter Eisentraut's avatar
Peter Eisentraut committed
468 469 470
    </para>

    <para>
471 472 473 474 475 476 477 478 479
     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>.
480
    </para>
481

482
   </sect3>
Peter Eisentraut's avatar
Peter Eisentraut committed
483

484
  </sect2>
485

486 487
  <sect2 id="docguide-toolsets-configure">
   <title>Detection by <command>configure</command></title>
488

489
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
490 491
   Before you can build the documentation you need to run the
   <filename>configure</filename> script as you would when building
492 493 494
   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
495 496 497 498
<screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for openjade... openjade
499
checking for DocBook V4.2... yes
Peter Eisentraut's avatar
Peter Eisentraut committed
500 501 502 503 504 505 506
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
</computeroutput>
</screen>
   If neither <filename>onsgmls</filename> nor
   <filename>nsgmls</filename> were found then you will not see the
   remaining 4 lines.  <filename>nsgmls</filename> is part of the Jade
507
   package.  If <quote>DocBook V4.2</quote> was not found then you did
Peter Eisentraut's avatar
Peter Eisentraut committed
508 509 510 511 512 513 514
   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
   <envar>DOCBOOKSTYLE</envar> to the location and rerun
   <filename>configure</filename> afterwards.
515
  </para>
516

517 518 519 520 521 522
  </sect2>
 </sect1>

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

523
  <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
524
   Once you have everything set up, change to the directory
525 526 527 528
   <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
529

530 531
  <sect2>
   <title>HTML</title>
Peter Eisentraut's avatar
Peter Eisentraut committed
532

533 534
   <para>
    To build the <acronym>HTML</acronym> version of the documentation:
Peter Eisentraut's avatar
Peter Eisentraut committed
535
<screen>
536
<prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
Peter Eisentraut's avatar
Peter Eisentraut committed
537
</screen>
538 539
    This is also the default target.
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
540

541 542 543 544 545 546 547
   <para>
    When the HTML documentation is built, the process also generates
    the linking information for the index entries.  Thus, if you want
    your documentation to have a concept index at the end, you need to
    build the HTML documentation once, and then build the
    documentation again in whatever format you like.
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
548 549

   <para>
550 551 552 553
    To allow for easier handling in the final distribution, the files
    comprising the HTML documentation are stored in a tar archive that
    is unpacked at installation time.  To create the
    <acronym>HTML</acronym> documentation package, use the commands
Peter Eisentraut's avatar
Peter Eisentraut committed
554 555 556 557 558 559 560 561 562
<programlisting>
cd doc/src
gmake postgres.tar.gz
</programlisting>
    In the distribution, these archives live in the
    <filename>doc</filename> directory and are installed by default
    with <command>gmake install</command>.
  </para>
 </sect2>
563

564
 <sect2>
565 566 567 568 569
  <title>Manpages</title>

  <para>
   We use the <application>docbook2man</application> utility to
   convert <productname>DocBook</productname>
570
   <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
Peter Eisentraut's avatar
Peter Eisentraut committed
571
   pages.  The man pages are also distributed as a tar archive,
572 573
   similar to the <acronym>HTML</acronym> version.  To create the man
   page package, use the commands
Peter Eisentraut's avatar
Peter Eisentraut committed
574 575
<programlisting>
cd doc/src
576
gmake man.tar.gz
Peter Eisentraut's avatar
Peter Eisentraut committed
577
</programlisting>
578 579 580 581
   which will result in a tar file being generated in the
   <filename>doc/src</filename> directory.
  </para>

Peter Eisentraut's avatar
Peter Eisentraut committed
582
  <para>
583 584 585 586
   To generate quality man pages, it might be necessary to use a
   hacked version of the conversion utility or do some manual
   postprocessing.  All man pages should be manually inspected before
   distribution.
Peter Eisentraut's avatar
Peter Eisentraut committed
587
  </para>
588
 </sect2>
589

590 591
  <sect2>
   <title>Print Output via <application>JadeTex</application></title>
592

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

598 599 600 601 602 603 604 605 606
    <itemizedlist>
     <listitem>
      <para>
       To make a <acronym>DVI</acronym> version:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.dvi</userinput>
</screen>
      </para>
     </listitem>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
607

608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630
     <listitem>
      <para>
       To generate Postscript from the <acronym>DVI</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.ps</userinput>
</screen>
      </para>
     </listitem>
  
     <listitem>
      <para>
       To make a <acronym>PDF</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.pdf</userinput>
</screen>
       (Of course you can also make a <acronym>PDF</acronym> version
       from the Postscript, but if you generate <acronym>PDF</acronym>
       directly, it will have hyperlinks and other enhanced features.)
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect2>
631

632 633
  <sect2>
   <title>Print Output via <acronym>RTF</acronym></title>
634

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
635
   <para>
636
    You can also create a printable version of the <productname>PostgreSQL</productname>
637 638 639 640 641 642
    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
    can then convert the documentation to Postscript of
    <acronym>PDF</acronym>.  The procedure below illustrates this
    process using <productname>Applixware</productname>.
643
   </para>
644

645 646
   <note>
    <para>
647
     It appears that current versions of the <productname>PostgreSQL</productname> documentation
648 649 650 651 652 653 654 655
     trigger some bug in or exceed the size limit of OpenJade.  If the
     build process of the <acronym>RTF</acronym> version hangs for a
     long time and the output file still has size 0, then you may have
     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
656
   <procedure>
657
    <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
658

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
659
    <para>
660 661 662 663 664
     <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.
665
    </para>
666

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
667 668
    <step performance="required">
     <para>
669 670 671 672
      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
673 674 675 676 677
     </para>
    </step>

    <step performance="required">
     <para>
678 679 680 681 682 683 684 685
      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:
686

687 688 689 690 691 692 693 694 695 696 697 698 699
<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
700 701 702 703 704
     </para>
    </step>

    <step performance="required">
     <para>
705
      Open a new document in <productname>Applixware Words</productname> and
706
      then import the <acronym>RTF</acronym> file.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
707 708 709 710 711
     </para>
    </step>

    <step performance="required">
     <para>
712 713
      Generate a new table of contents (ToC) using
      <productname>Applixware</productname>.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
714
     </para>
715 716 717 718

     <substeps>
      <step>
       <para>
719 720 721
        Select the existing ToC lines, from the beginning of the first
        character on the first line to the last character of the last
        line.
722 723 724 725 726
       </para>
      </step>

      <step>
       <para>
727 728 729 730 731 732 733
        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.
734 735 736 737 738
       </para>
      </step>

      <step>
       <para>
739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775
        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>
776 777 778
       </para>
      </step>
     </substeps>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
779 780 781 782
    </step>

    <step performance="required">
     <para>
783 784 785 786
      Work through the document to:

      <itemizedlist>
       <listitem>
787 788 789
        <para>
         Adjust page breaks.
        </para>
790 791 792
       </listitem>

       <listitem>
793 794 795
        <para>
         Adjust table column widths.
        </para>
796 797
       </listitem>
      </itemizedlist>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
798 799 800 801 802
     </para>
    </step>

    <step performance="required">
     <para>
803
      Replace the right-justified page numbers in the Examples and
804 805
      Figures portions of the ToC with correct values. This only takes
      a few minutes.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
806 807
     </para>
    </step>
808 809 810 811 812 813 814 815 816 817 818 819 820 821

    <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>
822 823 824
        <para>
         Select the ToC field.
        </para>
825 826 827
       </step>

       <step>
828 829 830 831 832
        <para>
         Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
         Building</guisubmenu><guimenuitem>Create Table of
         Contents</guimenuitem></menuchoice>.
        </para>
833 834 835
       </step>

       <step>
836 837 838 839 840
        <para>
         Unbind the ToC by selecting
         <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
         Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
        </para>
841 842 843
       </step>

       <step>
844 845 846 847
        <para>
         Delete the first line in the ToC, which is an entry for the
         ToC itself.
        </para>
848 849 850
       </step>
      </substeps>
    </step>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
851 852 853

    <step performance="required">
     <para>
854 855 856
      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
857 858 859 860 861
     </para>
    </step>

    <step performance="required">
     <para>
862
      <quote>Print</quote> the document
863
      to a file in Postscript format.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
864 865 866
     </para>
    </step>
   </procedure>
867 868 869 870 871 872 873 874
  </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
875 876 877 878 879 880 881 882 883 884
    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
885 886 887 888 889
    <application>w3m</application>).
   </para>

   <para>
    The file <filename>HISTORY</filename> can be created similarly,
890 891 892
    using the command <userinput>gmake HISTORY</userinput>.  For the
    file <filename>src/test/regress/README</filename> the command is
    <userinput>gmake regress_README</userinput>.
893
   </para>
894
  </sect2>
895

896 897
  <sect2>
   <title>Syntax Check</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
898

899 900 901 902 903 904 905 906
   <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
907
  </sect2>
908
 </sect1>
909

910

911
 <sect1 id="docguide-authoring">
Peter Eisentraut's avatar
Peter Eisentraut committed
912
  <title>Documentation Authoring</title>
913

914
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
915 916
    <acronym>SGML</acronym> and <productname>DocBook</productname> do
    not suffer from an oversupply of open-source authoring tools. The
917
    most common tool set is the
Peter Eisentraut's avatar
Peter Eisentraut committed
918 919
    <productname>Emacs</productname>/<productname>XEmacs</productname>
    editor with appropriate editing mode.  On some systems
920
    these tools are provided in a typical full installation.
921
   </para>
922

Peter Eisentraut's avatar
Peter Eisentraut committed
923 924
   <sect2>
    <title>Emacs/PSGML</title>
925

926
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
927 928 929 930
     <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
931
     consistency.  You could use it for <acronym>HTML</acronym> as
Peter Eisentraut's avatar
Peter Eisentraut committed
932 933 934 935
     well.  Check the <ulink
     url="http://www.lysator.liu.se/projects/about_psgml.html">PSGML
     web site</ulink> for downloads, installation instructions, and
     detailed documentation.
936
    </para>
937

938
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
939 940 941 942 943 944 945 946 947 948
     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).
949
    </para>
950

951
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
952 953 954
     Put the following in your <filename>~/.emacs</filename>
     environment file (adjusting the path names to be appropriate for
     your system):
955

Peter Eisentraut's avatar
Peter Eisentraut committed
956 957
<programlisting>
; ********** for SGML mode (psgml)
958

Peter Eisentraut's avatar
Peter Eisentraut committed
959 960 961 962 963 964 965 966 967 968 969
(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)
970

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

Peter Eisentraut's avatar
Peter Eisentraut committed
974 975 976 977 978 979 980 981 982
     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>
983
    </para>
984

985
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014
     Currently, each <acronym>SGML</acronym> source file has the
     following block at the end of the file:

<programlisting>
&lt;!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--&gt;
</programlisting>
     This will set up a number of editing mode parameters even if you
     do not set up your <filename>~/.emacs</filename> file, but it is
     a bit unfortunate, since if you followed the installation
     instructions above, then the catalog path will not match your
     location.  Hence you might need to turn off local variables:
<programlisting>
(setq inhibit-local-variables t)
</programlisting>
1015
    </para>
1016

1017
    <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
1018 1019
     The <productname>PostgreSQL</productname> distribution includes a
     parsed DTD definitions file <filename>reference.ced</filename>.
1020 1021 1022 1023 1024 1025 1026
     You may find that when using <productname>PSGML</productname>, a
     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
1027 1028

<programlisting>
1029
&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"&gt;
Peter Eisentraut's avatar
Peter Eisentraut committed
1030 1031 1032 1033 1034 1035 1036
</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.)
1037
    </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
1038 1039 1040 1041
   </sect2>

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

1043
    <para>
1044 1045
     <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
1046 1047 1048
     <productname>PSGML</productname>, but it's less confusing and
     lighter weight.  Also, it offers syntax highlighting (font lock),
     which can be very helpful.
1049 1050 1051
    </para>

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

1059
 </sect1>
1060

1061

1062
 <sect1 id="docguide-style">
1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 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 1126 1127 1128 1129 1130 1131 1132 1133
  <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
    may be omitted.  Additional top-level sections should only be used
    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
        lot of options, subsections may be used.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Exit Status</term>
      <listitem>
       <para>
        If the program uses 0 for success and non-zero for failure,
1134
        then you do not need to document it.  If there is a meaning
1135 1136 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
        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,
1239
    Outputs, Notes, Examples, Compatibility, History, See
1240 1241
    Also.  The Parameters section is like the Options section, but
    there is more freedom about which clauses of the command can be
1242 1243 1244
    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
1245 1246 1247 1248 1249 1250 1251 1252
    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>
1253
</appendix>
1254

1255 1256
<!-- Keep this comment at the end of the file
Local variables:
1257
mode:sgml
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
1258
sgml-omittag:nil
1259 1260 1261 1262 1263 1264 1265 1266
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
1267
sgml-local-catalogs:("/usr/lib/sgml/catalog")
1268 1269 1270
sgml-local-ecat-files:nil
End:
-->