1 <!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.37 2001/12/08 03:24:22 thomas 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 Postscript, for printing
28 man pages, for quick reference.
33 Additionally, a number of plain-text README-type files can be found
34 throughout the <productname>PostgreSQL</productname> source tree,
35 documenting various implementation issues.
39 The documentation is organized into several <quote>books</quote>:
44 <citetitle>Tutorial</citetitle>: introduction for new users
49 <citetitle>User's Guide</citetitle>: documents the SQL implementation
54 <citetitle>Reference Manual</citetitle>: reference pages for programs and SQL commands
59 <citetitle>Administrator's Guide</citetitle>: installation and server maintenance
64 <citetitle>Programmer's Guide</citetitle>: programming client
65 applications and server extensions
70 <citetitle>Developer's Guide</citetitle>: assorted information
71 for developers of <productname>PostgreSQL</> proper
76 All books are available as HTML and Postscript. The
77 <citetitle>Reference Manual</citetitle> contains reference entries which
78 are also shipped as man pages.
82 <acronym>HTML</acronym> documentation and man pages are part of a
83 standard distribution and are installed by default. Postscript
84 format documentation is available separately for download.
88 <title>DocBook</title>
90 The documentation sources are written in
91 <firstterm>DocBook</firstterm>, which is a markup language
92 superficially similar to <acronym>HTML</acronym>. Both of these
93 languages are applications of the <firstterm>Standard Generalized
94 Markup Language</firstterm>, <acronym>SGML</acronym>, which is
95 essentially a language for describing other languages. In what
96 follows, the terms DocBook and SGML are both used, but technically
97 they are not interchangeable.
101 <productname>DocBook</productname> allows an author to specify the
102 structure and content of a technical document without worrying
103 about presentation details. A document style defines how that
104 content is rendered into one of several final forms. DocBook is
105 maintained by the <ulink
106 url="http://www.oasis-open.org">OASIS</ulink> group. The <ulink
107 url="http://www.oasis-open.org/docbook">official DocBook
108 site</ulink> has good introductory and reference documentation and
109 a complete O'Reilly book for your online reading pleasure. The
110 <ulink url="http://www.freebsd.org/docproj/docproj.html">FreeBSD
111 Documentation Project</ulink> also uses DocBook and has some good
112 information, including a number of style guidelines that might be
118 <sect1 id="doc-toolsets">
119 <title>Toolsets</title>
122 The following tools are used to process the documentation. Some
123 may be optional, as noted.
127 <term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
130 This is the definition of DocBook itself. We currently use
131 version 3.1; you cannot use later or earlier versions. Note
132 that there is also an <acronym>XML</acronym> version of DocBook
139 <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
142 These are required by DocBook but are distributed separately
143 because they are maintained by ISO.
149 <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
152 This is the base package of <acronym>SGML</acronym> processing.
153 It contains an <acronym>SGML</acronym> parser, a
154 <acronym>DSSSL</acronym> processor (that is, a program to
155 convert <acronym>SGML</acronym> to other formats using
156 <acronym>DSSSL</acronym> stylesheets), as well as a number of
157 related tools. <productname>Jade</productname> is now being
158 maintained by the OpenJade group, no longer by James Clark.
164 <term><ulink url="http://docbook.sourceforge.net/projects/dsssl/index.html">DocBook DSSSL Stylesheets</ulink></term>
167 These contain the processing instructions for converting the
168 DocBook sources to other formats, such as
169 <acronym>HTML</acronym>.
175 <term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
178 This optional package is used to create man pages. It has a
179 number of prerequisite packages of its own. Check the web
186 <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
189 If you want to, you can also install
190 <productname>JadeTeX</productname> to use
191 <productname>TeX</productname> as a formatting backend for
192 <productname>Jade</productname>.
193 <application>JadeTeX</application> can create Postscript or
194 <acronym>PDF</acronym> files (the latter with bookmarks).
198 However, the output from <application>JadeTeX</application> is
199 inferior to what you get from the <acronym>RTF</acronym>
200 backend. Particular problem areas are tables and various
201 artifacts of vertical and horizontal spacing. Also, there is
202 no opportunity to manually polish the results.
210 We have documented experience with several installation methods for
211 the various tools that are needed to process the documentation.
212 These will be described below. There may be some other packaged
213 distributions for these tools. Please report package status to the
214 docs mailing list and we will include that information here.
218 <title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
221 Many vendors provide a complete RPM set for DocBook processing in
222 their distribution, which is usually based on the <ulink
223 url="http://sources.redhat.com/docbook-tools/">docbook-tools</ulink>
224 effort at Red Hat Software. Look for an <quote>SGML</quote>
225 option while installing, or the following packages:
226 <filename>sgml-common</filename>, <filename>docbook</filename>,
227 <filename>stylesheets</filename>, <filename>openjade</filename>
228 (or <filename>jade</filename>). Possibly
229 <filename>sgml-tools</filename> will be needed as well. If your
230 distributor does not provide these then you should be able to make
231 use of the packages from some other, reasonably compatible vendor.
236 <title>FreeBSD Installation</title>
239 The FreeBSD Documentation Project is itself a heavy user of
240 DocBook, so it comes as no surprise that there is a full set of
241 <quote>ports</quote> of the documentation tools available on
242 FreeBSD. The following ports need to be installed to build the
243 documentation on FreeBSD.
246 <para><filename>textproc/sp</filename></para>
249 <para><filename>textproc/openjade</filename></para>
252 <para><filename>textproc/docbook-310</filename></para>
255 <para><filename>textproc/iso8879</filename></para>
258 <para><filename>textproc/dsssl-docbook-modular</filename></para>
261 A number of things from <filename>/usr/ports/print</filename>
262 (<filename>tex</filename>, <filename>jadetex</filename>) might
267 It's possible that the ports do not update the main catalog file
268 in <filename>/usr/local/share/sgml/catalog</filename>. Be sure to
269 have the following line in there:
271 CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
273 If you do not want to edit the file you can also set the
274 environment variable <envar>SGML_CATALOG_FILES</envar> to a
275 colon-separated list of catalog files (such as the one above).
279 More information about the FreeBSD documentation tools can be
281 url="http://www.freebsd.org/tutorials/docproj-primer/tools.html">FreeBSD
282 Documentation Project's instructions</ulink>.
287 <title>Debian Packages</title>
290 There is a full set of packages of the documentation tools
291 available for <productname>Debian GNU/Linux</productname>.
292 To install, simply use:
295 apt-get install docbook
296 apt-get install docbook-stylesheets
302 <title>Manual Installation from Source</title>
305 The manual installation process of the DocBook tools is somewhat
306 complex, so if you have pre-built packages available, use them.
307 We describe here only a standard setup, with reasonabley standard
308 installation paths, and no <quote>fancy</quote> features. For
309 details, you should study the documentation of the respective
310 package, and read <acronym>SGML</acronym> introductory material.
314 <title>Installing OpenJade</title>
319 The installation of OpenJade offers a GNU-style
320 <literal>./configure; make; make install</literal> build
321 process. Details can be found in the OpenJade source
322 distribution. In a nutshell:
324 ./configure --enable-default-catalog=/usr/local/share/sgml/catalog
328 Be sure to remember where you put the <quote>default
329 catalog</quote>; you will need it below. You can also leave
330 it off, but then you will have to set the environment variable
331 <envar>SGML_CATALOG_FILES</envar> to point to the file
332 whenever you use <application>jade</application> later on.
333 (This method is also an option if OpenJade is already
334 installed and you want to install the rest of the toolchain
339 <step id="doc-openjade-install">
341 Additionally, you should install the files
342 <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
343 <filename>style-sheet.dtd</filename>, and
344 <filename>catalog</filename> from the
345 <filename>dsssl</filename> directory somewhere, perhaps into
346 <filename>/usr/local/share/sgml/dsssl</filename>. It's
347 probably easiest to copy the entire directory:
349 cp -R dsssl /usr/local/share/sgml
356 Finally, create the file
357 <filename>/usr/local/share/sgml/catalog</filename> and add
360 CATALOG "dsssl/catalog"
362 (This is a relative path reference to the file installed in
363 <xref linkend="doc-openjade-install">. Be sure to adjust it
364 if you chose your installation layout differently.)
371 <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
377 url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">DocBook
378 V3.1</ulink> distribution.
385 <filename>/usr/local/share/sgml/docbook31</filename> and change
386 to it. (The exact location is irrelevant, but this one is
387 reasonable within the layout we are following here.)
389 <prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook31</userinput>
390 <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
399 <prompt>$ </prompt><userinput>unzip -a ...../docbk31.zip</userinput>
401 (The archive will unpack its files into the current directory.)
408 <filename>/usr/local/share/sgml/catalog</filename> (or whatever
409 you told jade during installation) and put a line like this
412 CATALOG "docbook31/docbook.cat"
419 Optionally, you can edit the file
420 <filename>docbook.cat</filename> and comment out or remove the
421 line containing <literal>DTDDECL</literal>. If you do not then
422 you will get warnings from <application>jade</application>, but
423 there is no further harm.
430 url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879
431 character entities</ulink> archive, unpack it, and put the
432 files in the same directory you put the DocBook files in.
434 <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
435 <prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
442 Run the following command in the directory with the DocBook and ISO files:
444 perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
446 (This fixes a mixup between the names used in the DocBook
447 catalog file and the actual names of the ISO character entity
455 <title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
458 To install the style sheets, unzip and untar the distribution and
459 move it to a suitable place, for example
460 <filename>/usr/local/share/sgml</filename>. (The archive will
461 automatically create a subdirectory.)
463 <prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
464 <prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
469 The usual catalog entry in
470 <filename>/usr/local/share/sgml/catalog</filename> can also be
473 CATALOG "docbook-dsssl--1.<replaceable>xx</>/catalog
475 Because stylesheets change rather often, and it's sometimes
476 beneficial to try out alternative versions,
477 <productname>PostgreSQL</productname> doesn't use this catalog
478 entry. See <xref linkend="doc-build"> for information about how
479 to select the stylesheets instead.
484 <title>Installing <productname>JadeTeX</productname></title>
487 To install and use <productname>JadeTeX</productname>, you will
488 need a working installation of <productname>TeX</productname> and
489 <productname>LaTeX2e</productname>, including the supported
490 <productname>tools</productname> and
491 <productname>graphics</productname> packages,
492 <productname>Babel</productname>,
493 <productname><acronym>AMS</acronym> fonts</productname> and
494 <productname>AMS-LaTeX</productname>, the
495 <productname><acronym>PSNFSS</acronym></productname> extension
496 and companion kit of <quote>the 35 fonts</quote>, the
497 <productname>dvips</productname> program for generating
498 <productname>PostScript</productname>, the macro packages
499 <productname>fancyhdr</productname>,
500 <productname>hyperref</productname>,
501 <productname>minitoc</productname>,
502 <productname>url</productname> and
503 <productname>ot2enc</productname>. All of these can be found on
504 your friendly neighborhood <ulink
505 url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> site.
506 The installation of the <application>TeX</application> base
507 system is far beyond the scope of this introduction. Binary
508 packages should be available for any system that can run
509 <application>TeX</application>.
513 Before you can use <application>JadeTeX</application> with the
514 <productname>PostgreSQL</productname> documentation sources, you
515 will need to increase the size of
516 <application>TeX</application>'s internal data structures.
517 Details on this can be found in the <application>JadeTeX</application>
518 installation insructions.
522 Once that is finished you can install <application>JadeTeX</application>:
524 <prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
525 <prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
526 <prompt>$</prompt> <userinput>cd jadetex</userinput>
527 <prompt>$</prompt> <userinput>make install</userinput>
528 <prompt>$</prompt> <userinput>mktexlsr</userinput>
530 The last two need to be done as <systemitem>root</systemitem>.
539 <sect1 id="doc-build">
540 <title>Building The Documentation</title>
543 Before you can build the documentation you need to run the
544 <filename>configure</filename> script as you would when building
545 the programs themselves. Check the output near the end of the run,
546 it should look something like this:
549 checking for onsgmls... onsgmls
550 checking for openjade... openjade
551 checking for DocBook V3.1... yes
552 checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
553 checking for sgmlspl... sgmlspl
556 If neither <filename>onsgmls</filename> nor
557 <filename>nsgmls</filename> were found then you will not see the
558 remaining 4 lines. <filename>nsgmls</filename> is part of the Jade
559 package. If <quote>DocBook V3.1</quote> was not found then you did
560 not install the DocBook DTD kit in a place where jade can find it,
561 or you have not set up the catalog files correctly. See the
562 installation hints above. The DocBook stylesheets are looked for
563 in a number of relatively standard places, but if you have them
564 some other place then you should set the environment variable
565 <envar>DOCBOOKSTYLE</envar> to the location and rerun
566 <filename>configure</filename> afterwards.
570 Once you have everything set up, change to the directory
571 <filename>doc/src/sgml</filename> and run one of the following
572 commands: (Remember to use GNU make.)
576 To build the <acronym>HTML</acronym> version of the
577 <citetitle>Administrator's Guide</citetitle>:
579 <prompt>doc/src/sgml$ </prompt><userinput>gmake admin.html</userinput>
586 For the RTF version of the same:
588 <prompt>doc/src/sgml$ </prompt><userinput>gmake admin.rtf</userinput>
595 To get a <acronym>DVI</acronym> version via
596 <productname>JadeTeX</productname>:
598 <prompt>doc/src/sgml$ </prompt><userinput>gmake admin.dvi</userinput>
605 And Postscript from the <acronym>DVI</acronym>:
607 <prompt>doc/src/sgml$ </prompt><userinput>gmake admin.ps</userinput>
612 The official Postscript format documentation is generated
613 differently. See <xref linkend="doc-hardcopy"> below.
619 The other books can be built with analogous commands by replacing
620 <literal>admin</literal> with one of <literal>developer</literal>,
621 <literal>programmer</literal>, <literal>tutorial</literal>, or
622 <literal>user</literal>. Using <literal>postgres</literal> builds
623 an integrated version of all 5 books, which is practical since the
624 browser interface makes it easy to move around all of the
625 documentation by just clicking.
632 When building <acronym>HTML</acronym> documentation in
633 <filename>doc/src/sgml</filename>, some of the resulting files
634 will possibly (or quite certainly) have conflicting names between
635 books. Therefore the files are not in that directory in the
636 regular distribution. Instead, the files belonging to each book
637 are stored in a tar archive that is unpacked at installation time.
638 To create a set of <acronym>HTML</acronym> documentation packages
642 gmake tutorial.tar.gz
645 gmake programmer.tar.gz
646 gmake postgres.tar.gz
649 In the distribution, these archives live in the
650 <filename>doc</filename> directory and are installed by default
651 with <command>gmake install</command>.
655 <sect2 id="doc-manpages">
656 <title>Manpages</title>
659 We use the <application>docbook2man</application> utility to
660 convert <productname>DocBook</productname>
661 <sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man
662 pages. The man pages are also distributed as a tar archive,
663 similar to the <acronym>HTML</acronym> version. To create the man page package, use the commands
668 which will result in a tar file being generated in the
669 <filename>doc/src</filename> directory.
673 The man build leaves a lot of confusing output, and special care
674 must be taken to produce quality results. There is still room for
675 improvement in this area.
679 <sect2 id="doc-hardcopy">
680 <title>Hardcopy Generation</title>
683 The hardcopy Postscript documentation is generated by converting the
684 <acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
685 importing into <productname>ApplixWare</productname>.
686 After a little cleanup (see the following
687 section) the output is <quote>printed</quote> to a postscript file.
692 Some figures were redrawn to avoid having bitmap
693 <acronym>GIF</acronym> files in the hardcopy documentation. One
694 figure, of the system catalogs, was sufficiently complex that there
695 was not time to redraw it. It was converted to fit using the
699 % convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
700 % convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
707 Several areas are addressed while generating Postscript
708 hardcopy, including RTF repair, ToC generation, and page break
713 <title>Applixware <acronym>RTF</acronym> Cleanup</title>
716 <application>jade</application>, an integral part of the
717 hardcopy procedure, omits specifying a default style for body
718 text. In the past, this undiagnosed problem led to a long process
719 of Table of Contents (ToC) generation. However, with great help
720 from the ApplixWare folks the symptom was diagnosed and a
721 workaround is available.
724 <step performance="required">
726 Generate the <acronym>RTF</acronym> input by typing (for example):
735 <step performance="required">
737 Repair the RTF file to correctly specify all
738 styles, in particular the default style. If the document
739 contains <sgmltag>REFENTRY</sgmltag> sections, one must also
740 replace formatting hints which tie a
741 <emphasis>preceeding</emphasis> paragraph to the current
742 paragraph, and instead tie the current paragraph to the
743 following one. A utility, <application>fixrtf</application> is
745 <filename>doc/src/sgml</filename> to accomplish these repairs:
749 % fixrtf tutorial.rtf
756 % fixrtf --refentry reference.rtf
761 The script adds <literal>{\s0 Normal;}</literal> as
762 the zero-th style in the document. According to ApplixWare, the
763 RTF standard would prohibit adding an implicit zero-th style,
764 though M$Word happens to handle this case. For repairing
765 <sgmltag>REFENTRY</sgmltag> sections, the script replaces
766 <literal>\keepn</literal> tags with <literal>\keep</literal>.
770 <step performance="required">
772 Open a new document in <productname>Applix Words</productname> and
773 then import the <acronym>RTF</acronym> file.
777 <step performance="required">
779 Generate a new ToC using ApplixWare.
785 Select the existing ToC lines, from the beginning of the first
786 character on the first line to the last character of the last
793 Build a new ToC using
794 <literal>Tools.BookBuilding.CreateToC</literal>. Select the
795 first three levels of headers for inclusion in the ToC.
797 replace the existing lines imported in the RTF with a native
804 Adjust the ToC formatting by using
805 <literal>Format.Style</literal>, selecting each of the three
806 ToC styles, and adjusting the indents for <literal>First</literal> and
807 <literal>Left</literal>. Use the following values:
810 <title>Indent Formatting for Table of Contents</title>
818 First Indent (inches)
829 <literal>TOC-Heading 1</literal>
832 <literal>0.4</literal>
835 <literal>0.4</literal>
841 <literal>TOC-Heading 2</literal>
844 <literal>0.8</literal>
847 <literal>0.8</literal>
853 <literal>TOC-Heading 3</literal>
856 <literal>1.2</literal>
859 <literal>1.2</literal>
870 <step performance="required">
872 Work through the document to:
883 Adjust table column widths.
889 Insert figures into the document. Center each figure on the page using
890 the centering margins button on the ApplixWare toolbar.
894 Not all documents have figures.
895 You can grep the <acronym>SGML</acronym> source files for
896 the string <literal>graphic</literal> to identify those parts of the
897 documentation that may have figures. A few figures are replicated in
898 various parts of the documentation.
907 <step performance="required">
909 Replace the right-justified page numbers in the Examples and
910 Figures portions of the ToC with
911 correct values. This only takes a few minutes per document.
916 Later stylesheets seem to not need this adjustment - thomas 2001-11-29
917 <step performance="required">
919 If a bibliography is present, remove the <firstterm>short
920 form</firstterm> reference title from each entry. The
921 <productname>DocBook</productname> stylesheets from Norm Walsh
922 seem to print these out, even though this is a subset of the
923 information immediately following.
928 <step performance="optional">
930 Delete the index section from the document if it is empty.
934 <step performance="required">
936 Regenerate and adjust the table of contents.
942 Select the ToC field.
949 <literal>Tools->Book Building->Create Table of
956 Unbind the ToC by selecting
957 <literal>Tools->Field Editing->Unprotect</literal>.
963 Delete the first line in the ToC, which is an entry for the
970 <step performance="required">
972 Save the document as native Applix Words format to allow easier last
973 minute editing later.
977 <step performance="required">
979 <quote>Print</quote> the document
980 to a file in Postscript format.
984 <step performance="required">
986 Compress the Postscript file using <application>gzip</application>.
987 Place the compressed file into the <filename>doc</filename> directory.
994 <title>Plain Text Files</title>
997 Several files are distributed as plain text, for reading during
998 the installation process. The <filename>INSTALL</filename> file
999 corresponds to the chapter in the <citetitle>Administrator's
1000 Guide</citetitle>, with some minor changes to account for the
1001 different context. To recreate the file, change to the directory
1002 <filename>doc/src/sgml</filename> and enter <userinput>gmake
1003 INSTALL</userinput>. This will create a file
1004 <filename>INSTALL.html</filename> that can be saved as text with
1005 <productname>Netscape Navigator</productname> and put into the
1006 place of the existing file. <productname>Netscape</productname>
1007 seems to offer the best quality for <acronym>HTML</acronym> to
1008 text conversions (over <application>lynx</application> and
1009 <application>w3m</application>).
1013 The file <filename>HISTORY</filename> can be created similarly,
1014 using the command <userinput>gmake HISTORY</userinput>. For the
1015 file <filename>src/test/regress/README</filename> the command is
1016 <userinput>gmake regress_README</userinput>.
1020 * This is how you can create text files via RTF and ApplixWare,
1021 * for historical reference.
1024 <title>Plain Text Generation</title>
1027 Both <filename>INSTALL</filename> and
1028 <filename>HISTORY</filename> are generated from existing
1029 <acronym>SGML</acronym> sources. They are extracted from the same
1030 intermediate <acronym>RTF</acronym> file.
1033 <step performance="required">
1035 Generate <acronym>RTF</acronym> by typing:
1038 % make installation.rtf
1043 <step performance="required">
1045 Import <filename>installation.rtf</filename> into
1046 <productname>Applix Words</productname>.
1050 <step performance="required">
1052 Set the page width and margins.
1056 <step performance="required">
1058 Adjust the page width in File.PageSetup to 10 inches.
1062 <step performance="required">
1065 Adjust the right margin using the ruler to 9.5 inches. This
1066 will give a maximum column width of 79 characters, within the
1067 80 columns upper limit goal.
1073 <step performance="required">
1075 Lop off the parts of the document that are not needed.
1079 For <filename>INSTALL</filename>, remove all release notes from
1080 the end of the text, except for those from the current release.
1081 For <filename>HISTORY</filename>, remove all text up to the
1082 release notes, preserving and modifying the title and ToC.
1086 <step performance="required">
1088 Export the result as <literal>ASCII Layout</literal>.
1092 <step performance="required">
1094 Using emacs or vi, clean up the tabular information in
1095 <filename>INSTALL</filename>. Remove the <literal>mailto</literal>
1096 <acronym>URLs</acronym> for the porting contributors to shrink
1107 <sect1 id="doc-sources">
1108 <title>Documentation Authoring</title>
1111 <acronym>SGML</acronym> and <productname>DocBook</productname> do
1112 not suffer from an oversupply of open-source authoring tools. The
1113 most common toolset is the
1114 <productname>Emacs</productname>/<productname>XEmacs</productname>
1115 editor with appropriate editing mode. On some systems
1116 these tools are provided in a typical full installation.
1120 <title>Emacs/PSGML</title>
1123 <productname>PSGML</productname> is the most common and most
1124 powerful mode for editing <acronym>SGML</acronym> documents.
1125 When properly configured, it will allow you to use
1126 <application>Emacs</application> to insert tags and check markup
1127 consistancy. You could use it for <acronym>HTML</acronym> as
1128 well. Check the <ulink
1129 url="http://www.lysator.liu.se/projects/about_psgml.html">PSGML
1130 web site</ulink> for downloads, installation instructions, and
1131 detailed documentation.
1135 There is one important thing to note with
1136 <productname>PSGML</productname>: its author assumed that your
1137 main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
1138 would be <filename>/usr/local/lib/sgml</filename>. If, as in the
1139 examples in this chapter, you use
1140 <filename>/usr/local/share/sgml</filename>, you have to
1141 compensate for this, either by setting
1142 <envar>SGML_CATALOG_FILES</envar> environment variable, or you
1143 can customize your <productname>PSGML</productname> installation
1144 (its manual tells you how).
1148 Put the following in your <filename>~/.emacs</filename>
1149 environment file (adjusting the path names to be appropriate for
1153 ; ********** for SGML mode (psgml)
1155 (setq sgml-omittag t)
1156 (setq sgml-shorttag t)
1157 (setq sgml-minimize-attributes nil)
1158 (setq sgml-always-quote-attributes t)
1159 (setq sgml-indent-step 1)
1160 (setq sgml-indent-data t)
1161 (setq sgml-parent-document nil)
1162 (setq sgml-default-dtd-file "./reference.ced")
1163 (setq sgml-exposed-tags nil)
1164 (setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
1165 (setq sgml-ecat-files nil)
1167 (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
1170 and in the same file add an entry for <acronym>SGML</acronym>
1171 into the (existing) definition for
1172 <varname>auto-mode-alist</varname>:
1176 '(("\\.sgml$" . sgml-mode)
1182 Currently, each <acronym>SGML</acronym> source file has the
1183 following block at the end of the file:
1186 <!-- Keep this comment at the end of the file
1191 sgml-minimize-attributes:nil
1192 sgml-always-quote-attributes:t
1195 sgml-parent-document:nil
1196 sgml-default-dtd-file:"./reference.ced"
1197 sgml-exposed-tags:nil
1198 sgml-local-catalogs:("/usr/lib/sgml/catalog")
1199 sgml-local-ecat-files:nil
1203 This will set up a number of editing mode parameters even if you
1204 do not set up your <filename>~/.emacs</filename> file, but it is
1205 a bit unfortunate, since if you followed the installation
1206 instructions above, then the catalog path will not match your
1207 location. Hence you might need to turn off local variables:
1209 (setq inhibit-local-variables t)
1214 The <productname>PostgreSQL</productname> distribution includes a
1215 parsed DTD definitions file <filename>reference.ced</filename>.
1216 You may find that when using PSGML, a comfortable way of working
1217 with these separate files of book parts is to insert a proper
1218 <literal>DOCTYPE</literal> declaration while you're editing them.
1219 If you are working on this source, for instance, it is an
1220 appendix chapter, so you would specify the document as an
1221 <quote>appendix</quote> instance of a DocBook document by making
1222 the first line look like this:
1225 <!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
1228 This means that anything and everything that reads
1229 <acronym>SGML</acronym> will get it right, and I can verify the
1230 document with <command>nsgmls -s docguide.sgml</command>. (But
1231 you need to take out that line before building the entire
1237 <title>Other Emacs modes</title>
1240 <productname>GNU Emacs</productname> ships with a different SGML
1241 mode, which is not quite as powerful as
1242 <productname>PSGML</productname>, but it's less confusing and
1243 lighter weight. Also, it offers syntax highlighting (font lock),
1244 which can be very helpful.
1248 Norm Walsh offers a major <ulink
1249 url="http://nwalsh.com/emacs/docbookide/index.html">mode
1250 specifically for DocBook</ulink> which also has font-lock and a
1251 number of features to reduce typing.
1259 <!-- Keep this comment at the end of the file
1264 sgml-minimize-attributes:nil
1265 sgml-always-quote-attributes:t
1268 sgml-parent-document:nil
1269 sgml-default-dtd-file:"./reference.ced"
1270 sgml-exposed-tags:nil
1271 sgml-local-catalogs:("/usr/lib/sgml/catalog")
1272 sgml-local-ecat-files:nil