1 <!-- doc/src/sgml/docguide.sgml -->
3 <appendix id="docguide">
4 <title>Documentation</title>
7 <productname>PostgreSQL</productname> has four primary documentation
13 Plain text, for pre-installation information
18 <acronym>HTML</acronym>, for on-line browsing and reference
23 PDF or PostScript, for printing
28 man pages, for quick reference.
33 Additionally, a number of plain-text <filename>README</filename> files can
34 be found throughout the <productname>PostgreSQL</productname> source tree,
35 documenting various implementation issues.
39 <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
45 <sect1 id="docguide-docbook">
46 <title>DocBook</title>
48 The documentation sources are written in
49 <firstterm>DocBook</firstterm>, which is a markup language
50 superficially similar to <acronym>HTML</acronym>. Both of these
51 languages are applications of the <firstterm>Standard Generalized
52 Markup Language</firstterm>, <acronym>SGML</acronym>, which is
53 essentially a language for describing other languages. In what
54 follows, the terms DocBook and <acronym>SGML</acronym> are both
55 used, but technically they are not interchangeable.
59 <productname>DocBook</productname> allows an author to specify the
60 structure and content of a technical document without worrying
61 about presentation details. A document style defines how that
62 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
66 a complete O'Reilly book for your online reading pleasure. The
67 <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
68 NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
69 The <ulink url="http://www.freebsd.org/docproj/docproj.html">
70 FreeBSD Documentation Project</ulink> also uses DocBook and has some good
71 information, including a number of style guidelines that might be
77 <sect1 id="docguide-toolsets">
78 <title>Tool Sets</title>
81 The following tools are used to process the documentation. Some
82 might be optional, as noted.
86 <term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
89 This is the definition of DocBook itself. We currently use
90 version 4.2; you cannot use later or earlier versions. You
91 need the <acronym>SGML</acronym> variant of the DocBook DTD,
92 but to build man pages you also need the <acronym>XML</acronym>
93 variant of the same version.
99 <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
102 These are required by DocBook but are distributed separately
103 because they are maintained by ISO.
109 <term><ulink url="http://wiki.docbook.org/topic/DocBookDssslStylesheets">DocBook DSSSL Stylesheets</ulink></term>
112 These contain the processing instructions for converting the
113 DocBook sources to other formats, such as
114 <acronym>HTML</acronym>.
120 <term><ulink url="http://wiki.docbook.org/topic/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
123 This is another stylesheet for converting DocBook to other
124 formats. We currently use this to produce man pages and
125 optionally HTMLHelp. You can also use this toolchain to
126 produce HTML or PDF output, but official PostgreSQL releases
127 use the DSSSL stylesheets for that.
131 The minimum required version is currently 1.74.0.
137 <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
140 This is the base package of <acronym>SGML</acronym> processing.
141 It contains an <acronym>SGML</acronym> parser, a
142 <acronym>DSSSL</acronym> processor (that is, a program to
143 convert <acronym>SGML</acronym> to other formats using
144 <acronym>DSSSL</acronym> stylesheets), as well as a number of
145 related tools. <productname>Jade</productname> is now being
146 maintained by the OpenJade group, no longer by James Clark.
152 <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
155 This is the processing tool to use with the XSLT stylesheets
156 (like <command>jade</command> is the processing tool for DSSSL
163 <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
166 If you want to, you can also install
167 <productname>JadeTeX</productname> to use
168 <productname>TeX</productname> as a formatting backend for
169 <productname>Jade</productname>.
170 <application>JadeTeX</application> can create PostScript or
171 <acronym>PDF</acronym> files (the latter with bookmarks).
175 However, the output from <application>JadeTeX</application> is
176 inferior to what you get from the <acronym>RTF</acronym>
177 backend. Particular problem areas are tables and various
178 artifacts of vertical and horizontal spacing. Also, there is
179 no opportunity to manually polish the results.
187 We have documented experience with several installation methods for
188 the various tools that are needed to process the documentation.
189 These will be described below. There might be some other packaged
190 distributions for these tools. Please report package status to the
191 documentation mailing list, and we will include that information
196 <title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
199 Most vendors provide a complete RPM set for DocBook processing in
200 their distribution. Look for an <quote>SGML</quote> option while
201 installing, or the following packages:
202 <filename>sgml-common</filename>, <filename>docbook</filename>,
203 <filename>stylesheets</filename>, <filename>openjade</filename>
204 (or <filename>jade</filename>). Possibly
205 <filename>sgml-tools</filename> will be needed as well. If your
206 distributor does not provide these then you should be able to make
207 use of the packages from some other, reasonably compatible vendor.
212 <title>FreeBSD Installation</title>
215 The FreeBSD Documentation Project is itself a heavy user of
216 DocBook, so it comes as no surprise that there is a full set of
217 <quote>ports</quote> of the documentation tools available on
218 FreeBSD. The following ports need to be installed to build the
219 documentation on FreeBSD.
222 <para><filename>textproc/sp</filename></para>
225 <para><filename>textproc/openjade</filename></para>
228 <para><filename>textproc/iso8879</filename></para>
231 <para><filename>textproc/dsssl-docbook-modular</filename></para>
234 <para><filename>textproc/docbook-420</filename></para>
240 A number of things from <filename>/usr/ports/print</filename>
241 (<filename>tex</filename>, <filename>jadetex</filename>) might
246 It's possible that the ports do not update the main catalog file
247 in <filename>/usr/local/share/sgml/catalog.ports</filename> or order
248 isn't proper . Be sure to have the following lines in beginning of file:
250 CATALOG "openjade/catalog"
251 CATALOG "iso8879/catalog"
252 CATALOG "docbook/dsssl/modular/catalog"
253 CATALOG "docbook/4.2/catalog"
255 If you do not want to edit the file you can also set the
256 environment variable <envar>SGML_CATALOG_FILES</envar> to a
257 colon-separated list of catalog files (such as the one above).
261 More information about the FreeBSD documentation tools can be
262 found in the <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
263 FreeBSD Documentation Project's instructions</ulink>.
268 <title>Debian Packages</title>
271 There is a full set of packages of the documentation tools
272 available for <productname>Debian GNU/Linux</productname>.
273 To install, simply use:
275 apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc
281 <title>Manual Installation from Source</title>
284 The manual installation process of the DocBook tools is somewhat
285 complex, so if you have pre-built packages available, use them.
286 We describe here only a standard setup, with reasonably standard
287 installation paths, and no <quote>fancy</quote> features. For
288 details, you should study the documentation of the respective
289 package, and read <acronym>SGML</acronym> introductory material.
293 <title>Installing OpenJade</title>
298 The installation of OpenJade offers a GNU-style
299 <literal>./configure; make; make install</literal> build
300 process. Details can be found in the OpenJade source
301 distribution. In a nutshell:
303 ./configure --enable-default-catalog=/usr/local/share/sgml/catalog
307 Be sure to remember where you put the <quote>default
308 catalog</quote>; you will need it below. You can also leave
309 it off, but then you will have to set the environment variable
310 <envar>SGML_CATALOG_FILES</envar> to point to the file
311 whenever you use <application>jade</application> later on.
312 (This method is also an option if OpenJade is already
313 installed and you want to install the rest of the toolchain
319 Some users have reported encountering a segmentation fault using
320 OpenJade 1.4devel to build the PDFs, with a message like:
322 openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted
323 make: *** [postgres-A4.tex-pdf] Segmentation fault
325 Downgrading to OpenJade 1.3 should get rid of this error.
331 <step id="doc-openjade-install">
333 Additionally, you should install the files
334 <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
335 <filename>style-sheet.dtd</filename>, and
336 <filename>catalog</filename> from the
337 <filename>dsssl</filename> directory somewhere, perhaps into
338 <filename>/usr/local/share/sgml/dsssl</filename>. It's
339 probably easiest to copy the entire directory:
341 cp -R dsssl /usr/local/share/sgml
348 Finally, create the file
349 <filename>/usr/local/share/sgml/catalog</filename> and add
352 CATALOG "dsssl/catalog"
354 (This is a relative path reference to the file installed in
355 <xref linkend="doc-openjade-install">. Be sure to adjust it
356 if you chose your installation layout differently.)
363 <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
368 Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
369 DocBook V4.2 distribution</ulink>.
376 <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
377 to it. (The exact location is irrelevant, but this one is
378 reasonable within the layout we are following here.)
380 <prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
381 <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
390 <prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
392 (The archive will unpack its files into the current directory.)
399 <filename>/usr/local/share/sgml/catalog</filename> (or whatever
400 you told jade during installation) and put a line like this
403 CATALOG "docbook-4.2/docbook.cat"
410 Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
411 ISO 8879 character entities archive</ulink>, unpack it, and put the
412 files in the same directory you put the DocBook files in:
414 <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
415 <prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
422 Run the following command in the directory with the DocBook and ISO files:
424 perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
426 (This fixes a mixup between the names used in the DocBook
427 catalog file and the actual names of the ISO character entity
435 <title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
438 To install the style sheets, unzip and untar the distribution and
439 move it to a suitable place, for example
440 <filename>/usr/local/share/sgml</filename>. (The archive will
441 automatically create a subdirectory.)
443 <prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
444 <prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
449 The usual catalog entry in
450 <filename>/usr/local/share/sgml/catalog</filename> can also be
453 CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog"
455 Because stylesheets change rather often, and it's sometimes
456 beneficial to try out alternative versions,
457 <productname>PostgreSQL</productname> doesn't use this catalog
458 entry. See <xref linkend="docguide-toolsets-configure"> for
459 information about how to select the stylesheets instead.
464 <title>Installing <productname>JadeTeX</productname></title>
467 To install and use <productname>JadeTeX</productname>, you will
468 need a working installation of <productname>TeX</productname> and
469 <productname>LaTeX2e</productname>, including the supported
470 <productname>tools</productname> and
471 <productname>graphics</productname> packages,
472 <productname>Babel</productname>,
473 <productname><acronym>AMS</acronym> fonts</productname> and
474 <productname>AMS-LaTeX</productname>, the
475 <productname><acronym>PSNFSS</acronym></productname> extension
476 and companion kit of <quote>the 35 fonts</quote>, the
477 <productname>dvips</productname> program for generating
478 <productname>PostScript</productname>, the macro packages
479 <productname>fancyhdr</productname>,
480 <productname>hyperref</productname>,
481 <productname>minitoc</productname>,
482 <productname>url</productname> and
483 <productname>ot2enc</productname>. All of these can be found on
484 your friendly neighborhood <ulink url="http://www.ctan.org">
485 <acronym>CTAN</acronym> site</ulink>.
486 The installation of the <application>TeX</application> base
487 system is far beyond the scope of this introduction. Binary
488 packages should be available for any system that can run
489 <application>TeX</application>.
493 Before you can use <application>JadeTeX</application> with the
494 <productname>PostgreSQL</productname> documentation sources, you
495 will need to increase the size of
496 <application>TeX</application>'s internal data structures.
497 Details on this can be found in the <application>JadeTeX</application>
498 installation instructions.
502 Once that is finished you can install <application>JadeTeX</application>:
504 <prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
505 <prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
506 <prompt>$</prompt> <userinput>cd jadetex</userinput>
507 <prompt>$</prompt> <userinput>make install</userinput>
508 <prompt>$</prompt> <userinput>mktexlsr</userinput>
510 The last two need to be done as <systemitem>root</systemitem>.
517 <sect2 id="docguide-toolsets-configure">
518 <title>Detection by <command>configure</command></title>
521 Before you can build the documentation you need to run the
522 <filename>configure</filename> script as you would when building
523 the <productname>PostgreSQL</productname> programs themselves.
524 Check the output near the end of the run, it should look something
528 checking for onsgmls... onsgmls
529 checking for openjade... openjade
530 checking for DocBook V4.2... yes
531 checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
532 checking for collateindex.pl... /usr/bin/collateindex.pl
533 checking for xsltproc... xsltproc
534 checking for osx... osx
537 If neither <filename>onsgmls</filename> nor
538 <filename>nsgmls</filename> were found then some of the following tests
539 will be skipped. <filename>nsgmls</filename> is part of the Jade
540 package. You can pass the environment variables
541 <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
542 to the programs if they are not found automatically. If
543 <quote>DocBook V4.2</quote> was not found then you did not install
544 the DocBook DTD kit in a place where Jade can find it, or you have
545 not set up the catalog files correctly. See the installation hints
546 above. The DocBook stylesheets are looked for in a number of
547 relatively standard places, but if you have them some other place
548 then you should set the environment variable
549 <envar>DOCBOOKSTYLE</envar> to the location and rerun
550 <filename>configure</filename> afterwards.
556 <sect1 id="docguide-build">
557 <title>Building The Documentation</title>
560 Once you have everything set up, change to the directory
561 <filename>doc/src/sgml</filename> and run one of the commands
562 described in the following subsections to build the
563 documentation. (Remember to use GNU make.)
570 To build the <acronym>HTML</acronym> version of the documentation:
572 <prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
574 This is also the default target. The output appears in the
575 subdirectory <filename>html</filename>.
579 To create a proper index, the build might process several identical
580 stages. If you do not care about the index, and just want to
581 proof-read the output, use <literal>draft</>:
583 <prompt>doc/src/sgml$ </prompt><userinput>gmake draft</userinput>
588 To build the documentation as a single HTML page, use:
590 <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.html</userinput>
596 <title>Manpages</title>
599 We use the DocBook XSL stylesheets to
600 convert <productname>DocBook</productname>
601 <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
602 pages. The man pages are also distributed as a tar archive,
603 similar to the <acronym>HTML</acronym> version. To create the man
604 pages, use the commands:
613 <title>Print Output via <application>JadeTeX</application></title>
616 If you want to use <application>JadeTex</application> to produce a
617 printable rendition of the documentation, you can use one of the
623 To generate PostScript via <acronym>DVI</acronym> in A4 format:
625 <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.ps</userinput>
627 In U.S. letter format:
629 <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.ps</userinput>
636 To make a <acronym>PDF</acronym>:
638 <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.pdf</userinput>
642 <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.pdf</userinput>
644 (Of course you can also make a <acronym>PDF</acronym> version
645 from the PostScript, but if you generate <acronym>PDF</acronym>
646 directly, it will have hyperlinks and other enhanced features.)
653 When using JadeTeX to build the PostgreSQL documentation, you will
654 probably need to increase some of TeX's internal parameters. These
655 can be set in the file <filename>texmf.cnf</filename>. The following
656 settings worked at the time of this writing:
658 hash_extra.jadetex = 200000
659 hash_extra.pdfjadetex = 200000
660 pool_size.jadetex = 2000000
661 pool_size.pdfjadetex = 2000000
662 string_vacancies.jadetex = 150000
663 string_vacancies.pdfjadetex = 150000
664 max_strings.jadetex = 300000
665 max_strings.pdfjadetex = 300000
666 save_size.jadetex = 15000
667 save_size.pdfjadetex = 15000
674 <title>Overflow Text</title>
677 Occasionally text is too wide for the printed margins, and in
678 extreme cases, too wide for the printed page, e.g. non-wrapped
679 text, wide tables. Overly wide text generates <quote>Overfull
680 hbox</quote> messages in the TeX log output file, e.g.
681 <filename>postgres-US.log</> or <filename>postgres-A4.log</>.
682 There are 72 points in an inch so anything reported as over 72
683 points too wide will probably not fit on the printed page (assuming
684 one inch margins). To find the <acronym>SGML</acronym> text
685 causing the overflow, find the first page number mentioned above
686 the overflow message, e.g. <literal>[50 ###]</> (page 50), and
687 look at the page after that (e.g. page 51) in the <acronym>PDF</acronym>
688 file to see the overflow text and adjust the <acronym>SGML</acronym>
694 <title>Print Output via <acronym>RTF</acronym></title>
697 You can also create a printable version of the <productname>PostgreSQL</productname>
698 documentation by converting it to <acronym>RTF</acronym> and
699 applying minor formatting corrections using an office suite.
700 Depending on the capabilities of the particular office suite, you
701 can then convert the documentation to PostScript of
702 <acronym>PDF</acronym>. The procedure below illustrates this
703 process using <productname>Applixware</productname>.
708 It appears that current versions of the <productname>PostgreSQL</productname> documentation
709 trigger some bug in or exceed the size limit of OpenJade. If the
710 build process of the <acronym>RTF</acronym> version hangs for a
711 long time and the output file still has size 0, then you might have
712 hit that problem. (But keep in mind that a normal build takes 5
713 to 10 minutes, so don't abort too soon.)
718 <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
721 <application>OpenJade</application> omits specifying a default
722 style for body text. In the past, this undiagnosed problem led to
723 a long process of table of contents generation. However, with
724 great help from the <productname>Applixware</productname> folks
725 the symptom was diagnosed and a workaround is available.
728 <step performance="required">
730 Generate the <acronym>RTF</acronym> version by typing:
732 <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
737 <step performance="required">
739 Repair the RTF file to correctly specify all styles, in
740 particular the default style. If the document contains
741 <sgmltag>refentry</sgmltag> sections, one must also replace
742 formatting hints which tie a preceding paragraph to the current
743 paragraph, and instead tie the current paragraph to the
744 following one. A utility, <command>fixrtf</command>, is
745 available in <filename>doc/src/sgml</filename> to accomplish
748 <prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
753 The script adds <literal>{\s0 Normal;}</literal> as the zeroth
754 style in the document. According to
755 <productname>Applixware</productname>, the RTF standard would
756 prohibit adding an implicit zeroth style, though Microsoft Word
757 happens to handle this case. For repairing
758 <sgmltag>refentry</sgmltag> sections, the script replaces
759 <literal>\keepn</literal> tags with <literal>\keep</literal>.
763 <step performance="required">
765 Open a new document in <productname>Applixware Words</productname> and
766 then import the <acronym>RTF</acronym> file.
770 <step performance="required">
772 Generate a new table of contents (ToC) using
773 <productname>Applixware</productname>.
779 Select the existing ToC lines, from the beginning of the first
780 character on the first line to the last character of the last
787 Build a new ToC using
788 <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
789 Building</guisubmenu><guimenuitem>Create Table of
790 Contents</guimenuitem></menuchoice>. Select the first three
791 levels of headers for inclusion in the ToC. This will replace
792 the existing lines imported in the RTF with a native
793 <productname>Applixware</productname> ToC.
799 Adjust the ToC formatting by using
800 <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
801 selecting each of the three ToC styles, and adjusting the
802 indents for <literal>First</literal> and
803 <literal>Left</literal>. Use the following values:
810 <entry>First Indent (inches)</entry>
811 <entry>Left Indent (inches)</entry>
817 <entry><literal>TOC-Heading 1</literal></entry>
818 <entry><literal>0.4</literal></entry>
819 <entry><literal>0.4</literal></entry>
823 <entry><literal>TOC-Heading 2</literal></entry>
824 <entry><literal>0.8</literal></entry>
825 <entry><literal>0.8</literal></entry>
829 <entry><literal>TOC-Heading 3</literal></entry>
830 <entry><literal>1.2</literal></entry>
831 <entry><literal>1.2</literal></entry>
841 <step performance="required">
843 Work through the document to:
854 Adjust table column widths.
861 <step performance="required">
863 Replace the right-justified page numbers in the Examples and
864 Figures portions of the ToC with correct values. This only takes
869 <step performance="optional">
871 Delete the index section from the document if it is empty.
875 <step performance="required">
877 Regenerate and adjust the table of contents.
883 Select the ToC field.
889 Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
890 Building</guisubmenu><guimenuitem>Create Table of
891 Contents</guimenuitem></menuchoice>.
897 Unbind the ToC by selecting
898 <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
899 Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
905 Delete the first line in the ToC, which is an entry for the
912 <step performance="required">
914 Save the document as native <productname>Applixware
915 Words</productname> format to allow easier last minute editing
920 <step performance="required">
922 <quote>Print</quote> the document
923 to a file in PostScript format.
930 <title>Plain Text Files</title>
933 Several files are distributed as plain text, for reading during
934 the installation process. The <filename>INSTALL</filename> file
935 corresponds to <xref linkend="installation">, with some minor
936 changes to account for the different context. To recreate the
937 file, change to the directory <filename>doc/src/sgml</filename>
938 and enter <userinput>gmake INSTALL</userinput>. This will create
939 a file <filename>INSTALL.html</filename> that can be saved as text
940 with <productname>Netscape Navigator</productname> and put into
941 the place of the existing file.
942 <productname>Netscape</productname> seems to offer the best
943 quality for <acronym>HTML</acronym> to text conversions (over
944 <application>lynx</application> and
945 <application>w3m</application>).
949 The file <filename>HISTORY</filename> can be created similarly,
950 using the command <userinput>gmake HISTORY</userinput>. For the
951 file <filename>src/test/regress/README</filename> the command is
952 <userinput>gmake regress_README</userinput>.
957 <title>Syntax Check</title>
960 Building the documentation can take very long. But there is a
961 method to just check the correct syntax of the documentation
962 files, which only takes a few seconds:
964 <prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
971 <sect1 id="docguide-authoring">
972 <title>Documentation Authoring</title>
975 <acronym>SGML</acronym> and <productname>DocBook</productname> do
976 not suffer from an oversupply of open-source authoring tools. The
977 most common tool set is the
978 <productname>Emacs</productname>/<productname>XEmacs</productname>
979 editor with appropriate editing mode. On some systems
980 these tools are provided in a typical full installation.
984 <title>Emacs/PSGML</title>
987 <productname>PSGML</productname> is the most common and most
988 powerful mode for editing <acronym>SGML</acronym> documents.
989 When properly configured, it will allow you to use
990 <application>Emacs</application> to insert tags and check markup
991 consistency. You could use it for <acronym>HTML</acronym> as
992 well. Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
993 PSGML web site</ulink> for downloads, installation instructions, and
994 detailed documentation.
998 There is one important thing to note with
999 <productname>PSGML</productname>: its author assumed that your
1000 main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
1001 would be <filename>/usr/local/lib/sgml</filename>. If, as in the
1002 examples in this chapter, you use
1003 <filename>/usr/local/share/sgml</filename>, you have to
1004 compensate for this, either by setting
1005 <envar>SGML_CATALOG_FILES</envar> environment variable, or you
1006 can customize your <productname>PSGML</productname> installation
1007 (its manual tells you how).
1011 Put the following in your <filename>~/.emacs</filename>
1012 environment file (adjusting the path names to be appropriate for
1016 ; ********** for SGML mode (psgml)
1018 (setq sgml-omittag t)
1019 (setq sgml-shorttag t)
1020 (setq sgml-minimize-attributes nil)
1021 (setq sgml-always-quote-attributes t)
1022 (setq sgml-indent-step 1)
1023 (setq sgml-indent-data t)
1024 (setq sgml-parent-document nil)
1025 (setq sgml-exposed-tags nil)
1026 (setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
1028 (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
1031 and in the same file add an entry for <acronym>SGML</acronym>
1032 into the (existing) definition for
1033 <varname>auto-mode-alist</varname>:
1037 '(("\\.sgml$" . sgml-mode)
1043 You might find that when using <productname>PSGML</productname>, a
1044 comfortable way of working with these separate files of book
1045 parts is to insert a proper <literal>DOCTYPE</literal>
1046 declaration while you're editing them. If you are working on
1047 this source, for instance, it is an appendix chapter, so you
1048 would specify the document as an <quote>appendix</quote> instance
1049 of a DocBook document by making the first line look like this:
1052 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
1055 This means that anything and everything that reads
1056 <acronym>SGML</acronym> will get it right, and I can verify the
1057 document with <command>nsgmls -s docguide.sgml</command>. (But
1058 you need to take out that line before building the entire
1064 <title>Other Emacs Modes</title>
1067 <productname>GNU Emacs</productname> ships with a different
1068 <acronym>SGML</acronym> mode, which is not quite as powerful as
1069 <productname>PSGML</productname>, but it's less confusing and
1070 lighter weight. Also, it offers syntax highlighting (font lock),
1071 which can be very helpful.
1072 <filename>src/tools/editors/emacs.samples</filename> contains
1073 sample settings for this mode.
1078 <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
1079 specifically for DocBook which also has font-lock and a number of features to
1087 <sect1 id="docguide-style">
1088 <title>Style Guide</title>
1091 <title>Reference Pages</title>
1094 Reference pages should follow a standard layout. This allows
1095 users to find the desired information more quickly, and it also
1096 encourages writers to document all relevant aspects of a command.
1097 Consistency is not only desired among
1098 <productname>PostgreSQL</productname> reference pages, but also
1099 with reference pages provided by the operating system and other
1100 packages. Hence the following guidelines have been developed.
1101 They are for the most part consistent with similar guidelines
1102 established by various operating systems.
1106 Reference pages that describe executable commands should contain
1107 the following sections, in this order. Sections that do not apply
1108 can be omitted. Additional top-level sections should only be used
1109 in special circumstances; often that information belongs in the
1110 <quote>Usage</quote> section.
1117 This section is generated automatically. It contains the
1118 command name and a half-sentence summary of its functionality.
1124 <term>Synopsis</term>
1127 This section contains the syntax diagram of the command. The
1128 synopsis should normally not list each command-line option;
1129 that is done below. Instead, list the major components of the
1130 command line, such as where input and output files go.
1136 <term>Description</term>
1139 Several paragraphs explaining what the command does.
1145 <term>Options</term>
1148 A list describing each command-line option. If there are a
1149 lot of options, subsections can be used.
1155 <term>Exit Status</term>
1158 If the program uses 0 for success and non-zero for failure,
1159 then you do not need to document it. If there is a meaning
1160 behind the different non-zero exit codes, list them here.
1169 Describe any sublanguage or run-time interface of the program.
1170 If the program is not interactive, this section can usually be
1171 omitted. Otherwise, this section is a catch-all for
1172 describing run-time features. Use subsections if appropriate.
1178 <term>Environment</term>
1181 List all environment variables that the program might use.
1182 Try to be complete; even seemingly trivial variables like
1183 <envar>SHELL</envar> might be of interest to the user.
1192 List any files that the program might access implicitly. That
1193 is, do not list input and output files that were specified on
1194 the command line, but list configuration files, etc.
1200 <term>Diagnostics</term>
1203 Explain any unusual output that the program might create.
1204 Refrain from listing every possible error message. This is a
1205 lot of work and has little use in practice. But if, say, the
1206 error messages have a standard format that the user can parse,
1207 this would be the place to explain it.
1216 Anything that doesn't fit elsewhere, but in particular bugs,
1217 implementation flaws, security considerations, compatibility
1224 <term>Examples</term>
1233 <term>History</term>
1236 If there were some major milestones in the history of the
1237 program, they might be listed here. Usually, this section can
1247 Author (only used in the contrib section)
1253 <term>See Also</term>
1256 Cross-references, listed in the following order: other
1257 <productname>PostgreSQL</productname> command reference pages,
1258 <productname>PostgreSQL</productname> SQL command reference
1259 pages, citation of <productname>PostgreSQL</productname>
1260 manuals, other reference pages (e.g., operating system, other
1261 packages), other documentation. Items in the same group are
1262 listed alphabetically.
1271 Reference pages describing SQL commands should contain the
1272 following sections: Name, Synopsis, Description, Parameters,
1273 Outputs, Notes, Examples, Compatibility, History, See
1274 Also. The Parameters section is like the Options section, but
1275 there is more freedom about which clauses of the command can be
1276 listed. The Outputs section is only needed if the command returns
1277 something other than a default command-completion tag. The Compatibility
1278 section should explain to what extent
1279 this command conforms to the SQL standard(s), or to which other
1280 database system it is compatible. The See Also section of SQL
1281 commands should list SQL commands before cross-references to