1
<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.51 2004-11-15 06:32:13 neilc Exp $ -->
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
64
url="http://www.oasis-open.org">OASIS</ulink> group. The <ulink
65
url="http://www.oasis-open.org/docbook">official DocBook
66
site</ulink> has good introductory and reference documentation and
67
a complete O'Reilly book for your online reading pleasure. The
68
<ulink url="http://www.freebsd.org/docproj/docproj.html">FreeBSD
69
Documentation Project</ulink> also uses DocBook and has some good
70
information, including a number of style guidelines that might be
76
<sect1 id="docguide-toolsets">
77
<title>Tool Sets</title>
80
The following tools are used to process the documentation. Some
81
may be optional, as noted.
85
<term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
88
This is the definition of DocBook itself. We currently use
89
version 4.2; you cannot use later or earlier versions. Note
90
that there is also an <acronym>XML</acronym> version of DocBook
91
— do not use that.
97
<term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
100
These are required by DocBook but are distributed separately
101
because they are maintained by ISO.
107
<term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
110
This is the base package of <acronym>SGML</acronym> processing.
111
It contains an <acronym>SGML</acronym> parser, a
112
<acronym>DSSSL</acronym> processor (that is, a program to
113
convert <acronym>SGML</acronym> to other formats using
114
<acronym>DSSSL</acronym> stylesheets), as well as a number of
115
related tools. <productname>Jade</productname> is now being
116
maintained by the OpenJade group, no longer by James Clark.
122
<term><ulink url="http://docbook.sourceforge.net/projects/dsssl/index.html">DocBook DSSSL Stylesheets</ulink></term>
125
These contain the processing instructions for converting the
126
DocBook sources to other formats, such as
127
<acronym>HTML</acronym>.
133
<term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
136
This optional package is used to create man pages. It has a
137
number of prerequisite packages of its own. Check the web
144
<term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
147
If you want to, you can also install
148
<productname>JadeTeX</productname> to use
149
<productname>TeX</productname> as a formatting backend for
150
<productname>Jade</productname>.
151
<application>JadeTeX</application> can create Postscript or
152
<acronym>PDF</acronym> files (the latter with bookmarks).
156
However, the output from <application>JadeTeX</application> is
157
inferior to what you get from the <acronym>RTF</acronym>
158
backend. Particular problem areas are tables and various
159
artifacts of vertical and horizontal spacing. Also, there is
160
no opportunity to manually polish the results.
168
We have documented experience with several installation methods for
169
the various tools that are needed to process the documentation.
170
These will be described below. There may be some other packaged
171
distributions for these tools. Please report package status to the
172
documentation mailing list, and we will include that information
177
<title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
180
Most vendors provide a complete RPM set for DocBook processing in
181
their distribution. Look for an <quote>SGML</quote> option while
182
installing, or the following packages:
183
<filename>sgml-common</filename>, <filename>docbook</filename>,
184
<filename>stylesheets</filename>, <filename>openjade</filename>
185
(or <filename>jade</filename>). Possibly
186
<filename>sgml-tools</filename> will be needed as well. If your
187
distributor does not provide these then you should be able to make
188
use of the packages from some other, reasonably compatible vendor.
193
<title>FreeBSD Installation</title>
196
The FreeBSD Documentation Project is itself a heavy user of
197
DocBook, so it comes as no surprise that there is a full set of
198
<quote>ports</quote> of the documentation tools available on
199
FreeBSD. The following ports need to be installed to build the
200
documentation on FreeBSD.
203
<para><filename>textproc/sp</filename></para>
206
<para><filename>textproc/openjade</filename></para>
209
<para><filename>textproc/iso8879</filename></para>
212
<para><filename>textproc/dsssl-docbook-modular</filename></para>
215
Apparently, there is no port for the DocBook V4.2 SGML DTD
216
available right now. You will need to install it manually.
220
A number of things from <filename>/usr/ports/print</filename>
221
(<filename>tex</filename>, <filename>jadetex</filename>) might
226
It's possible that the ports do not update the main catalog file
227
in <filename>/usr/local/share/sgml/catalog</filename>. Be sure to
228
have the following line in there:
230
CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"
232
If you do not want to edit the file you can also set the
233
environment variable <envar>SGML_CATALOG_FILES</envar> to a
234
colon-separated list of catalog files (such as the one above).
238
More information about the FreeBSD documentation tools can be
240
url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">FreeBSD
241
Documentation Project's instructions</ulink>.
246
<title>Debian Packages</title>
249
There is a full set of packages of the documentation tools
250
available for <productname>Debian GNU/Linux</productname>.
251
To install, simply use:
254
apt-get install docbook
255
apt-get install docbook-stylesheets
261
<title>Manual Installation from Source</title>
264
The manual installation process of the DocBook tools is somewhat
265
complex, so if you have pre-built packages available, use them.
266
We describe here only a standard setup, with reasonably standard
267
installation paths, and no <quote>fancy</quote> features. For
268
details, you should study the documentation of the respective
269
package, and read <acronym>SGML</acronym> introductory material.
273
<title>Installing OpenJade</title>
278
The installation of OpenJade offers a GNU-style
279
<literal>./configure; make; make install</literal> build
280
process. Details can be found in the OpenJade source
281
distribution. In a nutshell:
283
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
287
Be sure to remember where you put the <quote>default
288
catalog</quote>; you will need it below. You can also leave
289
it off, but then you will have to set the environment variable
290
<envar>SGML_CATALOG_FILES</envar> to point to the file
291
whenever you use <application>jade</application> later on.
292
(This method is also an option if OpenJade is already
293
installed and you want to install the rest of the toolchain
298
<step id="doc-openjade-install">
300
Additionally, you should install the files
301
<filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
302
<filename>style-sheet.dtd</filename>, and
303
<filename>catalog</filename> from the
304
<filename>dsssl</filename> directory somewhere, perhaps into
305
<filename>/usr/local/share/sgml/dsssl</filename>. It's
306
probably easiest to copy the entire directory:
308
cp -R dsssl /usr/local/share/sgml
315
Finally, create the file
316
<filename>/usr/local/share/sgml/catalog</filename> and add
319
CATALOG "dsssl/catalog"
321
(This is a relative path reference to the file installed in
322
<xref linkend="doc-openjade-install">. Be sure to adjust it
323
if you chose your installation layout differently.)
330
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
336
url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">DocBook
337
V4.2</ulink> distribution.
344
<filename>/usr/local/share/sgml/docbook-4.2</filename> and change
345
to it. (The exact location is irrelevant, but this one is
346
reasonable within the layout we are following here.)
348
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
349
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
358
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
360
(The archive will unpack its files into the current directory.)
367
<filename>/usr/local/share/sgml/catalog</filename> (or whatever
368
you told jade during installation) and put a line like this
371
CATALOG "docbook-4.2/docbook.cat"
379
url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879
380
character entities</ulink> archive, unpack it, and put the
381
files in the same directory you put the DocBook files in.
383
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
384
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
391
Run the following command in the directory with the DocBook and ISO files:
393
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
395
(This fixes a mixup between the names used in the DocBook
396
catalog file and the actual names of the ISO character entity
404
<title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
407
To install the style sheets, unzip and untar the distribution and
408
move it to a suitable place, for example
409
<filename>/usr/local/share/sgml</filename>. (The archive will
410
automatically create a subdirectory.)
412
<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
413
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
418
The usual catalog entry in
419
<filename>/usr/local/share/sgml/catalog</filename> can also be
422
CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog
424
Because stylesheets change rather often, and it's sometimes
425
beneficial to try out alternative versions,
426
<productname>PostgreSQL</productname> doesn't use this catalog
427
entry. See <xref linkend="docguide-toolsets-configure"> for
428
information about how to select the stylesheets instead.
433
<title>Installing <productname>JadeTeX</productname></title>
436
To install and use <productname>JadeTeX</productname>, you will
437
need a working installation of <productname>TeX</productname> and
438
<productname>LaTeX2e</productname>, including the supported
439
<productname>tools</productname> and
440
<productname>graphics</productname> packages,
441
<productname>Babel</productname>,
442
<productname><acronym>AMS</acronym> fonts</productname> and
443
<productname>AMS-LaTeX</productname>, the
444
<productname><acronym>PSNFSS</acronym></productname> extension
445
and companion kit of <quote>the 35 fonts</quote>, the
446
<productname>dvips</productname> program for generating
447
<productname>PostScript</productname>, the macro packages
448
<productname>fancyhdr</productname>,
449
<productname>hyperref</productname>,
450
<productname>minitoc</productname>,
451
<productname>url</productname> and
452
<productname>ot2enc</productname>. All of these can be found on
453
your friendly neighborhood <ulink
454
url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> site.
455
The installation of the <application>TeX</application> base
456
system is far beyond the scope of this introduction. Binary
457
packages should be available for any system that can run
458
<application>TeX</application>.
462
Before you can use <application>JadeTeX</application> with the
463
<productname>PostgreSQL</productname> documentation sources, you
464
will need to increase the size of
465
<application>TeX</application>'s internal data structures.
466
Details on this can be found in the <application>JadeTeX</application>
467
installation instructions.
471
Once that is finished you can install <application>JadeTeX</application>:
473
<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
474
<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
475
<prompt>$</prompt> <userinput>cd jadetex</userinput>
476
<prompt>$</prompt> <userinput>make install</userinput>
477
<prompt>$</prompt> <userinput>mktexlsr</userinput>
479
The last two need to be done as <systemitem>root</systemitem>.
486
<sect2 id="docguide-toolsets-configure">
487
<title>Detection by <command>configure</command></title>
490
Before you can build the documentation you need to run the
491
<filename>configure</filename> script as you would when building
492
the <productname>PostgreSQL</productname> programs themselves.
493
Check the output near the end of the run, it should look something
497
checking for onsgmls... onsgmls
498
checking for openjade... openjade
499
checking for DocBook V4.2... yes
500
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
501
checking for sgmlspl... sgmlspl
504
If neither <filename>onsgmls</filename> nor
505
<filename>nsgmls</filename> were found then you will not see the
506
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
508
not install the DocBook DTD kit in a place where jade can find it,
509
or you have not set up the catalog files correctly. See the
510
installation hints above. The DocBook stylesheets are looked for
511
in a number of relatively standard places, but if you have them
512
some other place then you should set the environment variable
513
<envar>DOCBOOKSTYLE</envar> to the location and rerun
514
<filename>configure</filename> afterwards.
520
<sect1 id="docguide-build">
521
<title>Building The Documentation</title>
524
Once you have everything set up, change to the directory
525
<filename>doc/src/sgml</filename> and run one of the commands
526
described in the following subsections to build the
527
documentation. (Remember to use GNU make.)
534
To build the <acronym>HTML</acronym> version of the documentation:
536
<prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
538
This is also the default target.
542
When the HTML documentation is built, the process also generates
543
the linking information for the index entries. Thus, if you want
544
your documentation to have a concept index at the end, you need to
545
build the HTML documentation once, and then build the
546
documentation again in whatever format you like.
550
To allow for easier handling in the final distribution, the files
551
comprising the HTML documentation are stored in a tar archive that
552
is unpacked at installation time. To create the
553
<acronym>HTML</acronym> documentation package, use the commands
556
gmake postgres.tar.gz
558
In the distribution, these archives live in the
559
<filename>doc</filename> directory and are installed by default
560
with <command>gmake install</command>.
565
<title>Manpages</title>
568
We use the <application>docbook2man</application> utility to
569
convert <productname>DocBook</productname>
570
<sgmltag>refentry</sgmltag> pages to *roff output suitable for man
571
pages. The man pages are also distributed as a tar archive,
572
similar to the <acronym>HTML</acronym> version. To create the man
573
page package, use the commands
578
which will result in a tar file being generated in the
579
<filename>doc/src</filename> directory.
583
To generate quality man pages, it might be necessary to use a
584
hacked version of the conversion utility or do some manual
585
postprocessing. All man pages should be manually inspected before
591
<title>Print Output via <application>JadeTex</application></title>
594
If you want to use <application>JadeTex</application> to produce a
595
printable rendition of the documentation, you can use one of the
601
To make a <acronym>DVI</acronym> version:
603
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.dvi</userinput>
610
To generate Postscript from the <acronym>DVI</acronym>:
612
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.ps</userinput>
619
To make a <acronym>PDF</acronym>:
621
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.pdf</userinput>
623
(Of course you can also make a <acronym>PDF</acronym> version
624
from the Postscript, but if you generate <acronym>PDF</acronym>
625
directly, it will have hyperlinks and other enhanced features.)
633
<title>Print Output via <acronym>RTF</acronym></title>
636
You can also create a printable version of the <productname>PostgreSQL</productname>
637
documentation by converting it to <acronym>RTF</acronym> and
638
applying minor formatting corrections using an office suite.
639
Depending on the capabilities of the particular office suite, you
640
can then convert the documentation to Postscript of
641
<acronym>PDF</acronym>. The procedure below illustrates this
642
process using <productname>Applixware</productname>.
647
It appears that current versions of the <productname>PostgreSQL</productname> documentation
648
trigger some bug in or exceed the size limit of OpenJade. If the
649
build process of the <acronym>RTF</acronym> version hangs for a
650
long time and the output file still has size 0, then you may have
651
hit that problem. (But keep in mind that a normal build takes 5
652
to 10 minutes, so don't abort too soon.)
657
<title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
660
<application>OpenJade</application> omits specifying a default
661
style for body text. In the past, this undiagnosed problem led to
662
a long process of table of contents generation. However, with
663
great help from the <productname>Applixware</productname> folks
664
the symptom was diagnosed and a workaround is available.
667
<step performance="required">
669
Generate the <acronym>RTF</acronym> version by typing:
671
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
676
<step performance="required">
678
Repair the RTF file to correctly specify all styles, in
679
particular the default style. If the document contains
680
<sgmltag>refentry</sgmltag> sections, one must also replace
681
formatting hints which tie a preceding paragraph to the current
682
paragraph, and instead tie the current paragraph to the
683
following one. A utility, <command>fixrtf</command>, is
684
available in <filename>doc/src/sgml</filename> to accomplish
688
<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
693
The script adds <literal>{\s0 Normal;}</literal> as the zeroth
694
style in the document. According to
695
<productname>Applixware</productname>, the RTF standard would
696
prohibit adding an implicit zeroth style, though Microsoft Word
697
happens to handle this case. For repairing
698
<sgmltag>refentry</sgmltag> sections, the script replaces
699
<literal>\keepn</literal> tags with <literal>\keep</literal>.
703
<step performance="required">
705
Open a new document in <productname>Applixware Words</productname> and
706
then import the <acronym>RTF</acronym> file.
710
<step performance="required">
712
Generate a new table of contents (ToC) using
713
<productname>Applixware</productname>.
719
Select the existing ToC lines, from the beginning of the first
720
character on the first line to the last character of the last
727
Build a new ToC using
728
<menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
729
Building</guisubmenu><guimenuitem>Create Table of
730
Contents</guimenuitem></menuchoice>. Select the first three
731
levels of headers for inclusion in the ToC. This will replace
732
the existing lines imported in the RTF with a native
733
<productname>Applixware</productname> ToC.
739
Adjust the ToC formatting by using
740
<menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
741
selecting each of the three ToC styles, and adjusting the
742
indents for <literal>First</literal> and
743
<literal>Left</literal>. Use the following values:
750
<entry>First Indent (inches)</entry>
751
<entry>Left Indent (inches)</entry>
757
<entry><literal>TOC-Heading 1</literal></entry>
758
<entry><literal>0.4</literal></entry>
759
<entry><literal>0.4</literal></entry>
763
<entry><literal>TOC-Heading 2</literal></entry>
764
<entry><literal>0.8</literal></entry>
765
<entry><literal>0.8</literal></entry>
769
<entry><literal>TOC-Heading 3</literal></entry>
770
<entry><literal>1.2</literal></entry>
771
<entry><literal>1.2</literal></entry>
781
<step performance="required">
783
Work through the document to:
794
Adjust table column widths.
801
<step performance="required">
803
Replace the right-justified page numbers in the Examples and
804
Figures portions of the ToC with correct values. This only takes
809
<step performance="optional">
811
Delete the index section from the document if it is empty.
815
<step performance="required">
817
Regenerate and adjust the table of contents.
823
Select the ToC field.
829
Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
830
Building</guisubmenu><guimenuitem>Create Table of
831
Contents</guimenuitem></menuchoice>.
837
Unbind the ToC by selecting
838
<menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
839
Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
845
Delete the first line in the ToC, which is an entry for the
852
<step performance="required">
854
Save the document as native <productname>Applixware
855
Words</productname> format to allow easier last minute editing
860
<step performance="required">
862
<quote>Print</quote> the document
863
to a file in Postscript format.
870
<title>Plain Text Files</title>
873
Several files are distributed as plain text, for reading during
874
the installation process. The <filename>INSTALL</filename> file
875
corresponds to <xref linkend="installation">, with some minor
876
changes to account for the different context. To recreate the
877
file, change to the directory <filename>doc/src/sgml</filename>
878
and enter <userinput>gmake INSTALL</userinput>. This will create
879
a file <filename>INSTALL.html</filename> that can be saved as text
880
with <productname>Netscape Navigator</productname> and put into
881
the place of the existing file.
882
<productname>Netscape</productname> seems to offer the best
883
quality for <acronym>HTML</acronym> to text conversions (over
884
<application>lynx</application> and
885
<application>w3m</application>).
889
The file <filename>HISTORY</filename> can be created similarly,
890
using the command <userinput>gmake HISTORY</userinput>. For the
891
file <filename>src/test/regress/README</filename> the command is
892
<userinput>gmake regress_README</userinput>.
897
<title>Syntax Check</title>
900
Building the documentation can take very long. But there is a
901
method to just check the correct syntax of the documentation
902
files, which only takes a few seconds:
904
<prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
911
<sect1 id="docguide-authoring">
912
<title>Documentation Authoring</title>
915
<acronym>SGML</acronym> and <productname>DocBook</productname> do
916
not suffer from an oversupply of open-source authoring tools. The
917
most common tool set is the
918
<productname>Emacs</productname>/<productname>XEmacs</productname>
919
editor with appropriate editing mode. On some systems
920
these tools are provided in a typical full installation.
924
<title>Emacs/PSGML</title>
927
<productname>PSGML</productname> is the most common and most
928
powerful mode for editing <acronym>SGML</acronym> documents.
929
When properly configured, it will allow you to use
930
<application>Emacs</application> to insert tags and check markup
931
consistency. You could use it for <acronym>HTML</acronym> as
932
well. Check the <ulink
933
url="http://www.lysator.liu.se/projects/about_psgml.html">PSGML
934
web site</ulink> for downloads, installation instructions, and
935
detailed documentation.
939
There is one important thing to note with
940
<productname>PSGML</productname>: its author assumed that your
941
main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
942
would be <filename>/usr/local/lib/sgml</filename>. If, as in the
943
examples in this chapter, you use
944
<filename>/usr/local/share/sgml</filename>, you have to
945
compensate for this, either by setting
946
<envar>SGML_CATALOG_FILES</envar> environment variable, or you
947
can customize your <productname>PSGML</productname> installation
948
(its manual tells you how).
952
Put the following in your <filename>~/.emacs</filename>
953
environment file (adjusting the path names to be appropriate for
957
; ********** for SGML mode (psgml)
959
(setq sgml-omittag t)
960
(setq sgml-shorttag t)
961
(setq sgml-minimize-attributes nil)
962
(setq sgml-always-quote-attributes t)
963
(setq sgml-indent-step 1)
964
(setq sgml-indent-data t)
965
(setq sgml-parent-document nil)
966
(setq sgml-default-dtd-file "./reference.ced")
967
(setq sgml-exposed-tags nil)
968
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
969
(setq sgml-ecat-files nil)
971
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
974
and in the same file add an entry for <acronym>SGML</acronym>
975
into the (existing) definition for
976
<varname>auto-mode-alist</varname>:
980
'(("\\.sgml$" . sgml-mode)
986
Currently, each <acronym>SGML</acronym> source file has the
987
following block at the end of the file:
990
<!-- Keep this comment at the end of the file
995
sgml-minimize-attributes:nil
996
sgml-always-quote-attributes:t
999
sgml-parent-document:nil
1000
sgml-default-dtd-file:"./reference.ced"
1001
sgml-exposed-tags:nil
1002
sgml-local-catalogs:("/usr/lib/sgml/catalog")
1003
sgml-local-ecat-files:nil
1007
This will set up a number of editing mode parameters even if you
1008
do not set up your <filename>~/.emacs</filename> file, but it is
1009
a bit unfortunate, since if you followed the installation
1010
instructions above, then the catalog path will not match your
1011
location. Hence you might need to turn off local variables:
1013
(setq inhibit-local-variables t)
1018
The <productname>PostgreSQL</productname> distribution includes a
1019
parsed DTD definitions file <filename>reference.ced</filename>.
1020
You may find that when using <productname>PSGML</productname>, a
1021
comfortable way of working with these separate files of book
1022
parts is to insert a proper <literal>DOCTYPE</literal>
1023
declaration while you're editing them. If you are working on
1024
this source, for instance, it is an appendix chapter, so you
1025
would specify the document as an <quote>appendix</quote> instance
1026
of a DocBook document by making the first line look like this:
1029
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
1032
This means that anything and everything that reads
1033
<acronym>SGML</acronym> will get it right, and I can verify the
1034
document with <command>nsgmls -s docguide.sgml</command>. (But
1035
you need to take out that line before building the entire
1041
<title>Other Emacs modes</title>
1044
<productname>GNU Emacs</productname> ships with a different
1045
<acronym>SGML</acronym> mode, which is not quite as powerful as
1046
<productname>PSGML</productname>, but it's less confusing and
1047
lighter weight. Also, it offers syntax highlighting (font lock),
1048
which can be very helpful.
1052
Norm Walsh offers a major <ulink
1053
url="http://nwalsh.com/emacs/docbookide/index.html">mode
1054
specifically for DocBook</ulink> which also has font-lock and a
1055
number of features to reduce typing.
1062
<sect1 id="docguide-style">
1063
<title>Style Guide</title>
1066
<title>Reference Pages</title>
1069
Reference pages should follow a standard layout. This allows
1070
users to find the desired information more quickly, and it also
1071
encourages writers to document all relevant aspects of a command.
1072
Consistency is not only desired among
1073
<productname>PostgreSQL</productname> reference pages, but also
1074
with reference pages provided by the operating system and other
1075
packages. Hence the following guidelines have been developed.
1076
They are for the most part consistent with similar guidelines
1077
established by various operating systems.
1081
Reference pages that describe executable commands should contain
1082
the following sections, in this order. Sections that do not apply
1083
may be omitted. Additional top-level sections should only be used
1084
in special circumstances; often that information belongs in the
1085
<quote>Usage</quote> section.
1092
This section is generated automatically. It contains the
1093
command name and a half-sentence summary of its functionality.
1099
<term>Synopsis</term>
1102
This section contains the syntax diagram of the command. The
1103
synopsis should normally not list each command-line option;
1104
that is done below. Instead, list the major components of the
1105
command line, such as where input and output files go.
1111
<term>Description</term>
1114
Several paragraphs explaining what the command does.
1120
<term>Options</term>
1123
A list describing each command-line option. If there are a
1124
lot of options, subsections may be used.
1130
<term>Exit Status</term>
1133
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
behind the different non-zero exit codes, list them here.
1144
Describe any sublanguage or run-time interface of the program.
1145
If the program is not interactive, this section can usually be
1146
omitted. Otherwise, this section is a catch-all for
1147
describing run-time features. Use subsections if appropriate.
1153
<term>Environment</term>
1156
List all environment variables that the program might use.
1157
Try to be complete; even seemingly trivial variables like
1158
<envar>SHELL</envar> might be of interest to the user.
1167
List any files that the program might access implicitly. That
1168
is, do not list input and output files that were specified on
1169
the command line, but list configuration files, etc.
1175
<term>Diagnostics</term>
1178
Explain any unusual output that the program might create.
1179
Refrain from listing every possible error message. This is a
1180
lot of work and has little use in practice. But if, say, the
1181
error messages have a standard format that the user can parse,
1182
this would be the place to explain it.
1191
Anything that doesn't fit elsewhere, but in particular bugs,
1192
implementation flaws, security considerations, compatibility
1199
<term>Examples</term>
1208
<term>History</term>
1211
If there were some major milestones in the history of the
1212
program, they might be listed here. Usually, this section can
1219
<term>See Also</term>
1222
Cross-references, listed in the following order: other
1223
<productname>PostgreSQL</productname> command reference pages,
1224
<productname>PostgreSQL</productname> SQL command reference
1225
pages, citation of <productname>PostgreSQL</productname>
1226
manuals, other reference pages (e.g., operating system, other
1227
packages), other documentation. Items in the same group are
1228
listed alphabetically.
1237
Reference pages describing SQL commands should contain the
1238
following sections: Name, Synopsis, Description, Parameters,
1239
Outputs, Notes, Examples, Compatibility, History, See
1240
Also. The Parameters section is like the Options section, but
1241
there is more freedom about which clauses of the command can be
1242
listed. The Outputs section is only needed if the command returns
1243
something other than a default command-completion tag. The Compatibility
1244
section should explain to what extent
1245
this command conforms to the SQL standard(s), or to which other
1246
database system it is compatible. The See Also section of SQL
1247
commands should list SQL commands before cross-references to
1255
<!-- Keep this comment at the end of the file
1260
sgml-minimize-attributes:nil
1261
sgml-always-quote-attributes:t
1264
sgml-parent-document:nil
1265
sgml-default-dtd-file:"./reference.ced"
1266
sgml-exposed-tags:nil
1267
sgml-local-catalogs:("/usr/lib/sgml/catalog")
1268
sgml-local-ecat-files:nil
added
removed
doc/src/sgml/docguide.sgml
