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/DocBookDssslStylesheetDocs">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/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>). You may also need <filename>sgml-tools</filename>
205 and either <filename>xsltproc</filename> or <filename>libxslt</>. 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 that the
248 order isn't proper. Be sure to have the following lines in the beginning
251 CATALOG "openjade/catalog"
252 CATALOG "iso8879/catalog"
253 CATALOG "docbook/dsssl/modular/catalog"
254 CATALOG "docbook/4.2/catalog"
256 If you do not want to edit the file you can also set the
257 environment variable <envar>SGML_CATALOG_FILES</envar> to a
258 colon-separated list of catalog files (such as the one above).
262 More information about the FreeBSD documentation tools can be
263 found in the <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
264 FreeBSD Documentation Project's instructions</ulink>.
269 <title>Debian Packages</title>
272 There is a full set of packages of the documentation tools
273 available for <productname>Debian GNU/Linux</productname>.
274 To install, simply use:
276 apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc
282 <title>Mac OS X</title>
285 If you use MacPorts, the following will get you set up:
287 sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp
293 <title>Manual Installation from Source</title>
296 The manual installation process of the DocBook tools is somewhat
297 complex, so if you have pre-built packages available, use them.
298 We describe here only a standard setup, with reasonably standard
299 installation paths, and no <quote>fancy</quote> features. For
300 details, you should study the documentation of the respective
301 package, and read <acronym>SGML</acronym> introductory material.
305 <title>Installing OpenJade</title>
310 The installation of OpenJade offers a GNU-style
311 <literal>./configure; make; make install</literal> build
312 process. Details can be found in the OpenJade source
313 distribution. In a nutshell:
315 ./configure --enable-default-catalog=/usr/local/share/sgml/catalog
319 Be sure to remember where you put the <quote>default
320 catalog</quote>; you will need it below. You can also leave
321 it off, but then you will have to set the environment variable
322 <envar>SGML_CATALOG_FILES</envar> to point to the file
323 whenever you use <application>jade</application> later on.
324 (This method is also an option if OpenJade is already
325 installed and you want to install the rest of the toolchain
331 Some users have reported encountering a segmentation fault using
332 OpenJade 1.4devel to build the PDFs, with a message like:
334 openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted
335 make: *** [postgres-A4.tex-pdf] Segmentation fault
337 Downgrading to OpenJade 1.3 should get rid of this error.
343 <step id="doc-openjade-install">
345 Additionally, you should install the files
346 <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
347 <filename>style-sheet.dtd</filename>, and
348 <filename>catalog</filename> from the
349 <filename>dsssl</filename> directory somewhere, perhaps into
350 <filename>/usr/local/share/sgml/dsssl</filename>. It's
351 probably easiest to copy the entire directory:
353 cp -R dsssl /usr/local/share/sgml
360 Finally, create the file
361 <filename>/usr/local/share/sgml/catalog</filename> and add
364 CATALOG "dsssl/catalog"
366 (This is a relative path reference to the file installed in
367 <xref linkend="doc-openjade-install">. Be sure to adjust it
368 if you chose your installation layout differently.)
375 <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
380 Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
381 DocBook V4.2 distribution</ulink>.
388 <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
389 to it. (The exact location is irrelevant, but this one is
390 reasonable within the layout we are following here.)
392 <prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
393 <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
402 <prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
404 (The archive will unpack its files into the current directory.)
411 <filename>/usr/local/share/sgml/catalog</filename> (or whatever
412 you told jade during installation) and put a line like this
415 CATALOG "docbook-4.2/docbook.cat"
422 Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
423 ISO 8879 character entities archive</ulink>, unpack it, and put the
424 files in the same directory you put the DocBook files in:
426 <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
427 <prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
434 Run the following command in the directory with the DocBook and ISO files:
436 perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
438 (This fixes a mixup between the names used in the DocBook
439 catalog file and the actual names of the ISO character entity
447 <title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
450 To install the style sheets, unzip and untar the distribution and
451 move it to a suitable place, for example
452 <filename>/usr/local/share/sgml</filename>. (The archive will
453 automatically create a subdirectory.)
455 <prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
456 <prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
461 The usual catalog entry in
462 <filename>/usr/local/share/sgml/catalog</filename> can also be
465 CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog"
467 Because stylesheets change rather often, and it's sometimes
468 beneficial to try out alternative versions,
469 <productname>PostgreSQL</productname> doesn't use this catalog
470 entry. See <xref linkend="docguide-toolsets-configure"> for
471 information about how to select the stylesheets instead.
476 <title>Installing <productname>JadeTeX</productname></title>
479 To install and use <productname>JadeTeX</productname>, you will
480 need a working installation of <productname>TeX</productname> and
481 <productname>LaTeX2e</productname>, including the supported
482 <productname>tools</productname> and
483 <productname>graphics</productname> packages,
484 <productname>Babel</productname>,
485 <productname><acronym>AMS</acronym> fonts</productname> and
486 <productname>AMS-LaTeX</productname>, the
487 <productname><acronym>PSNFSS</acronym></productname> extension
488 and companion kit of <quote>the 35 fonts</quote>, the
489 <productname>dvips</productname> program for generating
490 <productname>PostScript</productname>, the macro packages
491 <productname>fancyhdr</productname>,
492 <productname>hyperref</productname>,
493 <productname>minitoc</productname>,
494 <productname>url</productname> and
495 <productname>ot2enc</productname>. All of these can be found on
496 your friendly neighborhood <ulink url="http://www.ctan.org">
497 <acronym>CTAN</acronym> site</ulink>.
498 The installation of the <application>TeX</application> base
499 system is far beyond the scope of this introduction. Binary
500 packages should be available for any system that can run
501 <application>TeX</application>.
505 Before you can use <application>JadeTeX</application> with the
506 <productname>PostgreSQL</productname> documentation sources, you
507 will need to increase the size of
508 <application>TeX</application>'s internal data structures.
509 Details on this can be found in the <application>JadeTeX</application>
510 installation instructions.
514 Once that is finished you can install <application>JadeTeX</application>:
516 <prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
517 <prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
518 <prompt>$</prompt> <userinput>cd jadetex</userinput>
519 <prompt>$</prompt> <userinput>make install</userinput>
520 <prompt>$</prompt> <userinput>mktexlsr</userinput>
522 The last two need to be done as <systemitem>root</systemitem>.
529 <sect2 id="docguide-toolsets-configure">
530 <title>Detection by <command>configure</command></title>
533 Before you can build the documentation you need to run the
534 <filename>configure</filename> script as you would when building
535 the <productname>PostgreSQL</productname> programs themselves.
536 Check the output near the end of the run, it should look something
540 checking for onsgmls... onsgmls
541 checking for openjade... openjade
542 checking for DocBook V4.2... yes
543 checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
544 checking for collateindex.pl... /usr/bin/collateindex.pl
545 checking for xsltproc... xsltproc
546 checking for osx... osx
549 If neither <filename>onsgmls</filename> nor
550 <filename>nsgmls</filename> were found then some of the following tests
551 will be skipped. <filename>nsgmls</filename> is part of the Jade
552 package. You can pass the environment variables
553 <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
554 to the programs if they are not found automatically. If
555 <quote>DocBook V4.2</quote> was not found then you did not install
556 the DocBook DTD kit in a place where Jade can find it, or you have
557 not set up the catalog files correctly. See the installation hints
558 above. The DocBook stylesheets are looked for in a number of
559 relatively standard places, but if you have them some other place
560 then you should set the environment variable
561 <envar>DOCBOOKSTYLE</envar> to the location and rerun
562 <filename>configure</filename> afterwards.
568 <sect1 id="docguide-build">
569 <title>Building The Documentation</title>
572 Once you have everything set up, change to the directory
573 <filename>doc/src/sgml</filename> and run one of the commands
574 described in the following subsections to build the
575 documentation. (Remember to use GNU make.)
582 To build the <acronym>HTML</acronym> version of the documentation:
584 <prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
586 This is also the default target. The output appears in the
587 subdirectory <filename>html</filename>.
591 To create a proper index, the build might process several identical
592 stages. If you do not care about the index, and just want to
593 proof-read the output, use <literal>draft</>:
595 <prompt>doc/src/sgml$ </prompt><userinput>make draft</userinput>
600 To build the documentation as a single HTML page, use:
602 <prompt>doc/src/sgml$ </prompt><userinput>make postgres.html</userinput>
608 <title>Manpages</title>
611 We use the DocBook XSL stylesheets to
612 convert <productname>DocBook</productname>
613 <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
614 pages. The man pages are also distributed as a tar archive,
615 similar to the <acronym>HTML</acronym> version. To create the man
616 pages, use the commands:
625 <title>Print Output via <application>JadeTeX</application></title>
628 If you want to use <application>JadeTex</application> to produce a
629 printable rendition of the documentation, you can use one of the
635 To generate PostScript via <acronym>DVI</acronym> in A4 format:
637 <prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.ps</userinput>
639 In U.S. letter format:
641 <prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.ps</userinput>
648 To make a <acronym>PDF</acronym>:
650 <prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
654 <prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
656 (Of course you can also make a <acronym>PDF</acronym> version
657 from the PostScript, but if you generate <acronym>PDF</acronym>
658 directly, it will have hyperlinks and other enhanced features.)
665 When using JadeTeX to build the PostgreSQL documentation, you will
666 probably need to increase some of TeX's internal parameters. These
667 can be set in the file <filename>texmf.cnf</filename>. The following
668 settings worked at the time of this writing:
670 hash_extra.jadetex = 200000
671 hash_extra.pdfjadetex = 200000
672 pool_size.jadetex = 2000000
673 pool_size.pdfjadetex = 2000000
674 string_vacancies.jadetex = 150000
675 string_vacancies.pdfjadetex = 150000
676 max_strings.jadetex = 300000
677 max_strings.pdfjadetex = 300000
678 save_size.jadetex = 15000
679 save_size.pdfjadetex = 15000
686 <title>Overflow Text</title>
689 Occasionally text is too wide for the printed margins, and in
690 extreme cases, too wide for the printed page, e.g. non-wrapped
691 text, wide tables. Overly wide text generates <quote>Overfull
692 hbox</quote> messages in the TeX log output file, e.g.
693 <filename>postgres-US.log</> or <filename>postgres-A4.log</>.
694 There are 72 points in an inch so anything reported as over 72
695 points too wide will probably not fit on the printed page (assuming
696 one inch margins). To find the <acronym>SGML</acronym> text
697 causing the overflow, find the first page number mentioned above
698 the overflow message, e.g. <literal>[50 ###]</> (page 50), and
699 look at the page after that (e.g. page 51) in the <acronym>PDF</acronym>
700 file to see the overflow text and adjust the <acronym>SGML</acronym>
706 <title>Print Output via <acronym>RTF</acronym></title>
709 You can also create a printable version of the <productname>PostgreSQL</productname>
710 documentation by converting it to <acronym>RTF</acronym> and
711 applying minor formatting corrections using an office suite.
712 Depending on the capabilities of the particular office suite, you
713 can then convert the documentation to PostScript of
714 <acronym>PDF</acronym>. The procedure below illustrates this
715 process using <productname>Applixware</productname>.
720 It appears that current versions of the <productname>PostgreSQL</productname> documentation
721 trigger some bug in or exceed the size limit of OpenJade. If the
722 build process of the <acronym>RTF</acronym> version hangs for a
723 long time and the output file still has size 0, then you might have
724 hit that problem. (But keep in mind that a normal build takes 5
725 to 10 minutes, so don't abort too soon.)
730 <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
733 <application>OpenJade</application> omits specifying a default
734 style for body text. In the past, this undiagnosed problem led to
735 a long process of table of contents generation. However, with
736 great help from the <productname>Applixware</productname> folks
737 the symptom was diagnosed and a workaround is available.
740 <step performance="required">
742 Generate the <acronym>RTF</acronym> version by typing:
744 <prompt>doc/src/sgml$ </prompt><userinput>make postgres.rtf</userinput>
749 <step performance="required">
751 Repair the RTF file to correctly specify all styles, in
752 particular the default style. If the document contains
753 <sgmltag>refentry</sgmltag> sections, one must also replace
754 formatting hints which tie a preceding paragraph to the current
755 paragraph, and instead tie the current paragraph to the
756 following one. A utility, <command>fixrtf</command>, is
757 available in <filename>doc/src/sgml</filename> to accomplish
760 <prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
765 The script adds <literal>{\s0 Normal;}</literal> as the zeroth
766 style in the document. According to
767 <productname>Applixware</productname>, the RTF standard would
768 prohibit adding an implicit zeroth style, though Microsoft Word
769 happens to handle this case. For repairing
770 <sgmltag>refentry</sgmltag> sections, the script replaces
771 <literal>\keepn</literal> tags with <literal>\keep</literal>.
775 <step performance="required">
777 Open a new document in <productname>Applixware Words</productname> and
778 then import the <acronym>RTF</acronym> file.
782 <step performance="required">
784 Generate a new table of contents (ToC) using
785 <productname>Applixware</productname>.
791 Select the existing ToC lines, from the beginning of the first
792 character on the first line to the last character of the last
799 Build a new ToC using
800 <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
801 Building</guisubmenu><guimenuitem>Create Table of
802 Contents</guimenuitem></menuchoice>. Select the first three
803 levels of headers for inclusion in the ToC. This will replace
804 the existing lines imported in the RTF with a native
805 <productname>Applixware</productname> ToC.
811 Adjust the ToC formatting by using
812 <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
813 selecting each of the three ToC styles, and adjusting the
814 indents for <literal>First</literal> and
815 <literal>Left</literal>. Use the following values:
822 <entry>First Indent (inches)</entry>
823 <entry>Left Indent (inches)</entry>
829 <entry><literal>TOC-Heading 1</literal></entry>
830 <entry><literal>0.4</literal></entry>
831 <entry><literal>0.4</literal></entry>
835 <entry><literal>TOC-Heading 2</literal></entry>
836 <entry><literal>0.8</literal></entry>
837 <entry><literal>0.8</literal></entry>
841 <entry><literal>TOC-Heading 3</literal></entry>
842 <entry><literal>1.2</literal></entry>
843 <entry><literal>1.2</literal></entry>
853 <step performance="required">
855 Work through the document to:
866 Adjust table column widths.
873 <step performance="required">
875 Replace the right-justified page numbers in the Examples and
876 Figures portions of the ToC with correct values. This only takes
881 <step performance="optional">
883 Delete the index section from the document if it is empty.
887 <step performance="required">
889 Regenerate and adjust the table of contents.
895 Select the ToC field.
901 Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
902 Building</guisubmenu><guimenuitem>Create Table of
903 Contents</guimenuitem></menuchoice>.
909 Unbind the ToC by selecting
910 <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
911 Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
917 Delete the first line in the ToC, which is an entry for the
924 <step performance="required">
926 Save the document as native <productname>Applixware
927 Words</productname> format to allow easier last minute editing
932 <step performance="required">
934 <quote>Print</quote> the document
935 to a file in PostScript format.
942 <title>Plain Text Files</title>
945 The installation instructions are also distributed as plain text,
946 in case they are needed in a situation where better reading tools
947 are not available. The <filename>INSTALL</filename> file
948 corresponds to <xref linkend="installation">, with some minor
949 changes to account for the different context. To recreate the
950 file, change to the directory <filename>doc/src/sgml</filename>
951 and enter <userinput>make INSTALL</userinput>.
955 In the past, the release notes and regression testing instructions
956 were also distributed as plain text, but this practice has been
962 <title>Syntax Check</title>
965 Building the documentation can take very long. But there is a
966 method to just check the correct syntax of the documentation
967 files, which only takes a few seconds:
969 <prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
976 <sect1 id="docguide-authoring">
977 <title>Documentation Authoring</title>
980 <acronym>SGML</acronym> and <productname>DocBook</productname> do
981 not suffer from an oversupply of open-source authoring tools. The
982 most common tool set is the
983 <productname>Emacs</productname>/<productname>XEmacs</productname>
984 editor with appropriate editing mode. On some systems
985 these tools are provided in a typical full installation.
989 <title>Emacs/PSGML</title>
992 <productname>PSGML</productname> is the most common and most
993 powerful mode for editing <acronym>SGML</acronym> documents.
994 When properly configured, it will allow you to use
995 <application>Emacs</application> to insert tags and check markup
996 consistency. You could use it for <acronym>HTML</acronym> as
997 well. Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
998 PSGML web site</ulink> for downloads, installation instructions, and
999 detailed documentation.
1003 There is one important thing to note with
1004 <productname>PSGML</productname>: its author assumed that your
1005 main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
1006 would be <filename>/usr/local/lib/sgml</filename>. If, as in the
1007 examples in this chapter, you use
1008 <filename>/usr/local/share/sgml</filename>, you have to
1009 compensate for this, either by setting
1010 <envar>SGML_CATALOG_FILES</envar> environment variable, or you
1011 can customize your <productname>PSGML</productname> installation
1012 (its manual tells you how).
1016 Put the following in your <filename>~/.emacs</filename>
1017 environment file (adjusting the path names to be appropriate for
1021 ; ********** for SGML mode (psgml)
1023 (setq sgml-omittag t)
1024 (setq sgml-shorttag t)
1025 (setq sgml-minimize-attributes nil)
1026 (setq sgml-always-quote-attributes t)
1027 (setq sgml-indent-step 1)
1028 (setq sgml-indent-data t)
1029 (setq sgml-parent-document nil)
1030 (setq sgml-exposed-tags nil)
1031 (setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
1033 (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
1036 and in the same file add an entry for <acronym>SGML</acronym>
1037 into the (existing) definition for
1038 <varname>auto-mode-alist</varname>:
1042 '(("\\.sgml$" . sgml-mode)
1048 You might find that when using <productname>PSGML</productname>, a
1049 comfortable way of working with these separate files of book
1050 parts is to insert a proper <literal>DOCTYPE</literal>
1051 declaration while you're editing them. If you are working on
1052 this source, for instance, it is an appendix chapter, so you
1053 would specify the document as an <quote>appendix</quote> instance
1054 of a DocBook document by making the first line look like this:
1057 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
1060 This means that anything and everything that reads
1061 <acronym>SGML</acronym> will get it right, and I can verify the
1062 document with <command>nsgmls -s docguide.sgml</command>. (But
1063 you need to take out that line before building the entire
1069 <title>Other Emacs Modes</title>
1072 <productname>GNU Emacs</productname> ships with a different
1073 <acronym>SGML</acronym> mode, which is not quite as powerful as
1074 <productname>PSGML</productname>, but it's less confusing and
1075 lighter weight. Also, it offers syntax highlighting (font lock),
1076 which can be very helpful.
1077 <filename>src/tools/editors/emacs.samples</filename> contains
1078 sample settings for this mode.
1083 <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
1084 specifically for DocBook which also has font-lock and a number of features to
1092 <sect1 id="docguide-style">
1093 <title>Style Guide</title>
1096 <title>Reference Pages</title>
1099 Reference pages should follow a standard layout. This allows
1100 users to find the desired information more quickly, and it also
1101 encourages writers to document all relevant aspects of a command.
1102 Consistency is not only desired among
1103 <productname>PostgreSQL</productname> reference pages, but also
1104 with reference pages provided by the operating system and other
1105 packages. Hence the following guidelines have been developed.
1106 They are for the most part consistent with similar guidelines
1107 established by various operating systems.
1111 Reference pages that describe executable commands should contain
1112 the following sections, in this order. Sections that do not apply
1113 can be omitted. Additional top-level sections should only be used
1114 in special circumstances; often that information belongs in the
1115 <quote>Usage</quote> section.
1122 This section is generated automatically. It contains the
1123 command name and a half-sentence summary of its functionality.
1129 <term>Synopsis</term>
1132 This section contains the syntax diagram of the command. The
1133 synopsis should normally not list each command-line option;
1134 that is done below. Instead, list the major components of the
1135 command line, such as where input and output files go.
1141 <term>Description</term>
1144 Several paragraphs explaining what the command does.
1150 <term>Options</term>
1153 A list describing each command-line option. If there are a
1154 lot of options, subsections can be used.
1160 <term>Exit Status</term>
1163 If the program uses 0 for success and non-zero for failure,
1164 then you do not need to document it. If there is a meaning
1165 behind the different non-zero exit codes, list them here.
1174 Describe any sublanguage or run-time interface of the program.
1175 If the program is not interactive, this section can usually be
1176 omitted. Otherwise, this section is a catch-all for
1177 describing run-time features. Use subsections if appropriate.
1183 <term>Environment</term>
1186 List all environment variables that the program might use.
1187 Try to be complete; even seemingly trivial variables like
1188 <envar>SHELL</envar> might be of interest to the user.
1197 List any files that the program might access implicitly. That
1198 is, do not list input and output files that were specified on
1199 the command line, but list configuration files, etc.
1205 <term>Diagnostics</term>
1208 Explain any unusual output that the program might create.
1209 Refrain from listing every possible error message. This is a
1210 lot of work and has little use in practice. But if, say, the
1211 error messages have a standard format that the user can parse,
1212 this would be the place to explain it.
1221 Anything that doesn't fit elsewhere, but in particular bugs,
1222 implementation flaws, security considerations, compatibility
1229 <term>Examples</term>
1238 <term>History</term>
1241 If there were some major milestones in the history of the
1242 program, they might be listed here. Usually, this section can
1252 Author (only used in the contrib section)
1258 <term>See Also</term>
1261 Cross-references, listed in the following order: other
1262 <productname>PostgreSQL</productname> command reference pages,
1263 <productname>PostgreSQL</productname> SQL command reference
1264 pages, citation of <productname>PostgreSQL</productname>
1265 manuals, other reference pages (e.g., operating system, other
1266 packages), other documentation. Items in the same group are
1267 listed alphabetically.
1276 Reference pages describing SQL commands should contain the
1277 following sections: Name, Synopsis, Description, Parameters,
1278 Outputs, Notes, Examples, Compatibility, History, See
1279 Also. The Parameters section is like the Options section, but
1280 there is more freedom about which clauses of the command can be
1281 listed. The Outputs section is only needed if the command returns
1282 something other than a default command-completion tag. The Compatibility
1283 section should explain to what extent
1284 this command conforms to the SQL standard(s), or to which other
1285 database system it is compatible. The See Also section of SQL
1286 commands should list SQL commands before cross-references to