-<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.69 2007/01/31 20:56:17 momjian Exp $ -->
+<!-- doc/src/sgml/docguide.sgml -->
<appendix id="docguide">
<title>Documentation</title>
about presentation details. A document style defines how that
content is rendered into one of several final forms. DocBook is
maintained by the <ulink url="http://www.oasis-open.org">
- OASIS group</ulink>. The <ulink url="http://www.oasis-open.org/docbook">
+ OASIS group</ulink>. The <ulink url="http://www.oasis-open.org/docbook/">
official DocBook site</ulink> has good introductory and reference documentation and
a complete O'Reilly book for your online reading pleasure. The
<ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
<variablelist>
<varlistentry>
- <term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
+ <term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
<listitem>
<para>
This is the definition of DocBook itself. We currently use
- version 4.2; you cannot use later or earlier versions. Note
- that there is also an <acronym>XML</acronym> version of DocBook
- — do not use that.
+ version 4.2; you cannot use later or earlier versions. You
+ need the <acronym>SGML</acronym> variant of the DocBook DTD,
+ but to build man pages you also need the <acronym>XML</acronym>
+ variant of the same version.
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><ulink url="http://wiki.docbook.org/DocBookDssslStylesheetDocs">DocBook DSSSL Stylesheets</ulink></term>
+ <listitem>
+ <para>
+ These contain the processing instructions for converting the
+ DocBook sources to other formats, such as
+ <acronym>HTML</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://wiki.docbook.org/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
+ <listitem>
+ <para>
+ This is another stylesheet for converting DocBook to other
+ formats. We currently use this to produce man pages and
+ optionally HTMLHelp. You can also use this toolchain to
+ produce HTML or PDF output, but official PostgreSQL releases
+ use the DSSSL stylesheets for that.
+ </para>
+
+ <para>
+ The minimum required version is currently 1.74.0.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
<listitem>
</varlistentry>
<varlistentry>
- <term><ulink url="http://docbook.sourceforge.net/projects/dsssl/index.html">DocBook DSSSL Stylesheets</ulink></term>
+ <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
<listitem>
<para>
- These contain the processing instructions for converting the
- DocBook sources to other formats, such as
- <acronym>HTML</acronym>.
+ This library and the <command>xmllint</command> tool it contains are
+ used for processing XML. Many developers will already
+ have <application>Libxml2</application> installed, because it is also
+ used when building the PostgreSQL code. Note, however,
+ that <command>xmllint</command> might need to be installed from a
+ separate subpackage.
</para>
</listitem>
- </varlistentry>
+ </varlistentry>
<varlistentry>
- <term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
+ <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
<listitem>
<para>
- This optional package is used to create man pages. It has a
- number of prerequisite packages of its own. Check the web
- site.
+ This is the processing tool to use with the XSLT stylesheets
+ (like <command>jade</command> is the processing tool for DSSSL
+ stylesheets).
</para>
</listitem>
</varlistentry>
</para>
<sect2>
- <title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
+ <title>Installation on Fedora, RHEL, and Derivatives</title>
<para>
- Most vendors provide a complete RPM set for DocBook processing in
- their distribution. Look for an <quote>SGML</quote> option while
- installing, or the following packages:
- <filename>sgml-common</filename>, <filename>docbook</filename>,
- <filename>stylesheets</filename>, <filename>openjade</filename>
- (or <filename>jade</filename>). Possibly
- <filename>sgml-tools</filename> will be needed as well. If your
- distributor does not provide these then you should be able to make
- use of the packages from some other, reasonably compatible vendor.
+ To install the required packages, use:
+<programlisting>
+yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
+</programlisting>
</para>
</sect2>
<sect2>
- <title>FreeBSD Installation</title>
+ <title>Installation on FreeBSD</title>
<para>
The FreeBSD Documentation Project is itself a heavy user of
documentation on FreeBSD.
<itemizedlist>
<listitem>
- <para><filename>textproc/sp</filename></para>
+ <para><filename>textproc/docbook-sgml</filename></para>
</listitem>
<listitem>
- <para><filename>textproc/openjade</filename></para>
+ <para><filename>textproc/docbook-xml</filename></para>
</listitem>
<listitem>
- <para><filename>textproc/iso8879</filename></para>
+ <para><filename>textproc/docbook-xsl</filename></para>
</listitem>
<listitem>
<para><filename>textproc/dsssl-docbook-modular</filename></para>
</listitem>
<listitem>
- <para><filename>textproc/docbook-420</filename></para>
+ <para><filename>textproc/libxslt</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename>textproc/openjade</filename></para>
</listitem>
</itemizedlist>
</para>
also be of interest.
</para>
- <para>
- It's possible that the ports do not update the main catalog file
- in <filename>/usr/local/share/sgml/catalog.ports</filename> or order
- isn't proper . Be sure to have the following lines in begining of file:
-<programlisting>
-CATALOG "openjade/catalog"
-CATALOG "iso8879/catalog"
-CATALOG "docbook/dsssl/modular/catalog"
-CATALOG "docbook/4.2/catalog"
-</programlisting>
- If you do not want to edit the file you can also set the
- environment variable <envar>SGML_CATALOG_FILES</envar> to a
- colon-separated list of catalog files (such as the one above).
- </para>
-
<para>
More information about the FreeBSD documentation tools can be
found in the <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
available for <productname>Debian GNU/Linux</productname>.
To install, simply use:
<programlisting>
-apt-get install openjade1.3
-apt-get install docbook
-apt-get install docbook-dsssl
+apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc
+</programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>OS X</title>
+
+ <para>
+ If you use MacPorts, the following will get you set up:
+<programlisting>
+sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp
</programlisting>
- (The plain <literal>openjade</literal> package installs
- OpenJade 1.4, which seems not to work.)
</para>
</sect2>
<envar>SGML_CATALOG_FILES</envar> to point to the file
whenever you use <application>jade</application> later on.
(This method is also an option if OpenJade is already
- installed and you want to install the rest of the tool chain
+ installed and you want to install the rest of the toolchain
locally.)
</para>
+
+ <note>
+ <para>
+ Some users have reported encountering a segmentation fault using
+ OpenJade 1.4devel to build the PDFs, with a message like:
+<screen>
+openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted
+make: *** [postgres-A4.tex-pdf] Segmentation fault
+</screen>
+ Downgrading to OpenJade 1.3 should get rid of this error.
+ </para>
+ </note>
+
</step>
<step id="doc-openjade-install">
<step>
<para>
- Unpack the archive.
+ Unpack the archive:
<screen>
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
</screen>
<para>
Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
ISO 8879 character entities archive</ulink>, unpack it, and put the
- files in the same directory you put the DocBook files in.
+ files in the same directory you put the DocBook files in:
<screen>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V4.2... yes
-checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
-checking for sgmlspl... sgmlspl
+checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
+checking for collateindex.pl... /usr/bin/collateindex.pl
+checking for xsltproc... xsltproc
+checking for osx... osx
</computeroutput>
</screen>
If neither <filename>onsgmls</filename> nor
- <filename>nsgmls</filename> were found then you will not see the
- remaining 4 lines. <filename>nsgmls</filename> is part of the Jade
+ <filename>nsgmls</filename> were found then some of the following tests
+ will be skipped. <filename>nsgmls</filename> is part of the Jade
package. You can pass the environment variables
<envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
to the programs if they are not found automatically. If
<para>
To build the <acronym>HTML</acronym> version of the documentation:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
</screen>
- This is also the default target.
+ This is also the default target. The output appears in the
+ subdirectory <filename>html</filename>.
</para>
<para>
stages. If you do not care about the index, and just want to
proof-read the output, use <literal>draft</>:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake draft</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make draft</userinput>
</screen>
</para>
<para>
- To allow for easier handling in the final distribution, the files
- comprising the HTML documentation can be stored in a tar archive that
- is unpacked at installation time. To create the
- <acronym>HTML</acronym> documentation package, use the commands
-<programlisting>
-cd doc/src
-gmake postgres.tar.gz
-</programlisting>
- In the distribution, these archives live in the
- <filename>doc</filename> directory and are installed by default
- with <command>gmake install</command>.
- </para>
+ To build the documentation as a single HTML page, use:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres.html</userinput>
+</screen>
+ </para>
</sect2>
<sect2>
<title>Manpages</title>
<para>
- We use the <application>docbook2man</application> utility to
+ We use the DocBook XSL stylesheets to
convert <productname>DocBook</productname>
<sgmltag>refentry</sgmltag> pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive,
similar to the <acronym>HTML</acronym> version. To create the man
- page package, use the commands
+ pages, use the commands:
<programlisting>
-cd doc/src
-gmake man.tar.gz
+cd doc/src/sgml
+make man
</programlisting>
- which will result in a tar file being generated in the
- <filename>doc/src</filename> directory.
- </para>
-
- <para>
- To generate quality man pages, it might be necessary to use a
- hacked version of the conversion utility or do some manual
- postprocessing. All man pages should be manually inspected before
- distribution.
</para>
</sect2>
<para>
To generate PostScript via <acronym>DVI</acronym> in A4 format:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.ps</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.ps</userinput>
</screen>
In U.S. letter format:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.ps</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.ps</userinput>
</screen>
</para>
</listitem>
-
+
<listitem>
<para>
To make a <acronym>PDF</acronym>:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-A4.pdf</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
</screen>
- or
+ or:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres-US.pdf</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
</screen>
(Of course you can also make a <acronym>PDF</acronym> version
from the PostScript, but if you generate <acronym>PDF</acronym>
string_vacancies.pdfjadetex = 150000
max_strings.jadetex = 300000
max_strings.pdfjadetex = 300000
-save_size.jadetex = 10000
-save_size.pdfjadetex = 10000
+save_size.jadetex = 15000
+save_size.pdfjadetex = 15000
</programlisting>
</para>
+
+ </sect2>
+
+ <sect2>
+ <title>Overflow Text</title>
+
+ <para>
+ Occasionally text is too wide for the printed margins, and in
+ extreme cases, too wide for the printed page, e.g. non-wrapped
+ text, wide tables. Overly wide text generates <quote>Overfull
+ hbox</quote> messages in the TeX log output file, e.g.
+ <filename>postgres-US.log</> or <filename>postgres-A4.log</>.
+ There are 72 points in an inch so anything reported as over 72
+ points too wide will probably not fit on the printed page (assuming
+ one inch margins). To find the <acronym>SGML</acronym> text
+ causing the overflow, find the first page number mentioned above
+ the overflow message, e.g. <literal>[50 ###]</> (page 50), and
+ look at the page after that (e.g. page 51) in the <acronym>PDF</acronym>
+ file to see the overflow text and adjust the <acronym>SGML</acronym>
+ accordingly.
+ </para>
</sect2>
<sect2>
<para>
Generate the <acronym>RTF</acronym> version by typing:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres.rtf</userinput>
</screen>
</para>
</step>
following one. A utility, <command>fixrtf</command>, is
available in <filename>doc/src/sgml</filename> to accomplish
these repairs:
-
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
</screen>
<title>Plain Text Files</title>
<para>
- Several files are distributed as plain text, for reading during
- the installation process. The <filename>INSTALL</filename> file
+ The installation instructions are also distributed as plain text,
+ in case they are needed in a situation where better reading tools
+ are not available. The <filename>INSTALL</filename> file
corresponds to <xref linkend="installation">, with some minor
changes to account for the different context. To recreate the
file, change to the directory <filename>doc/src/sgml</filename>
- and enter <userinput>gmake INSTALL</userinput>. This will create
- a file <filename>INSTALL.html</filename> that can be saved as text
- with <productname>Netscape Navigator</productname> and put into
- the place of the existing file.
- <productname>Netscape</productname> seems to offer the best
- quality for <acronym>HTML</acronym> to text conversions (over
- <application>lynx</application> and
- <application>w3m</application>).
+ and enter <userinput>make INSTALL</userinput>.
</para>
<para>
- The file <filename>HISTORY</filename> can be created similarly,
- using the command <userinput>gmake HISTORY</userinput>. For the
- file <filename>src/test/regress/README</filename> the command is
- <userinput>gmake regress_README</userinput>.
+ In the past, the release notes and regression testing instructions
+ were also distributed as plain text, but this practice has been
+ discontinued.
</para>
</sect2>
method to just check the correct syntax of the documentation
files, which only takes a few seconds:
<screen>
-<prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
+<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
</screen>
</para>
</sect2>
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
-(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
-(setq sgml-ecat-files nil)
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>
</para>
<para>
- The <productname>PostgreSQL</productname> distribution includes a
- parsed DTD definitions file <filename>reference.ced</filename>.
You might find that when using <productname>PSGML</productname>, a
comfortable way of working with these separate files of book
parts is to insert a proper <literal>DOCTYPE</literal>
</sect2>
<sect2>
- <title>Other Emacs modes</title>
+ <title>Other Emacs Modes</title>
<para>
<productname>GNU Emacs</productname> ships with a different
<productname>PSGML</productname>, but it's less confusing and
lighter weight. Also, it offers syntax highlighting (font lock),
which can be very helpful.
+ <filename>src/tools/editors/emacs.samples</filename> contains
+ sample settings for this mode.
</para>
<para>
Norm Walsh offers a
<ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
- specifically for DocBook which also has font-lock and a number of features to
+ specifically for DocBook which also has font-lock and a number of features to
reduce typing.
</para>
</sect2>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Description</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Options</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Exit Status</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Usage</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Environment</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Files</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Diagnostics</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Notes</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Examples</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>History</term>
<listitem>
</para>
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>Author</term>
+ <listitem>
+ <para>
+ Author (only used in the contrib section)
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>See Also</term>
<listitem>
projects / postgresql / blobdiff