<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Building The Documentation</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 8.2.14 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Tool Sets"
HREF="docguide-toolsets.html"><LINK
REL="NEXT"
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2009-09-04T05:25:47"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL 8.2.14 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-toolsets.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide.html"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Appendix G. Documentation</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide-authoring.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOCGUIDE-BUILD"
>G.3. Building The Documentation</A
></H1
><P
> Once you have everything set up, change to the directory
<TT
CLASS="FILENAME"
>doc/src/sgml</TT
> and run one of the commands
described in the following subsections to build the
documentation. (Remember to use GNU make.)
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN90920"
>G.3.1. HTML</A
></H2
><P
> To build the <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> version of the documentation:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake html</KBD
></PRE
><P>
This is also the default target.
</P
><P
> When the HTML documentation is built, the process also generates
the linking information for the index entries. Thus, if you want
your documentation to have a concept index at the end, you need to
build the HTML documentation once, and then build the
documentation again in whatever format you like.
</P
><P
> To allow for easier handling in the final distribution, the files
comprising the HTML documentation are stored in a tar archive that
is unpacked at installation time. To create the
<ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> documentation package, use the commands
</P><PRE
CLASS="PROGRAMLISTING"
>cd doc/src
gmake postgres.tar.gz</PRE
><P>
In the distribution, these archives live in the
<TT
CLASS="FILENAME"
>doc</TT
> directory and are installed by default
with <TT
CLASS="COMMAND"
>gmake install</TT
>.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN90933"
>G.3.2. Manpages</A
></H2
><P
> We use the <SPAN
CLASS="APPLICATION"
>docbook2man</SPAN
> utility to
convert <SPAN
CLASS="PRODUCTNAME"
>DocBook</SPAN
>
<CODE
CLASS="SGMLTAG"
>refentry</CODE
> pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive,
similar to the <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> version. To create the man
page package, use the commands
</P><PRE
CLASS="PROGRAMLISTING"
>cd doc/src
gmake man.tar.gz</PRE
><P>
which will result in a tar file being generated in the
<TT
CLASS="FILENAME"
>doc/src</TT
> directory.
</P
><P
> 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.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN90943"
>G.3.3. Print Output via <SPAN
CLASS="APPLICATION"
>JadeTex</SPAN
></A
></H2
><P
> If you want to use <SPAN
CLASS="APPLICATION"
>JadeTex</SPAN
> to produce a
printable rendition of the documentation, you can use one of the
following commands:
<P
></P
></P><UL
><LI
><P
> To make a <ACRONYM
CLASS="ACRONYM"
>DVI</ACRONYM
> version:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres.dvi</KBD
></PRE
><P>
</P
></LI
><LI
><P
> To generate Postscript from the <ACRONYM
CLASS="ACRONYM"
>DVI</ACRONYM
>:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres.ps</KBD
></PRE
><P>
</P
></LI
><LI
><P
> To make a <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres.pdf</KBD
></PRE
><P>
(Of course you can also make a <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
> version
from the Postscript, but if you generate <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>
directly, it will have hyperlinks and other enhanced features.)
</P
></LI
></UL
><P>
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN90969"
>G.3.4. Print Output via <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
></A
></H2
><P
> You can also create a printable version of the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
documentation by converting it to <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> and
applying minor formatting corrections using an office suite.
Depending on the capabilities of the particular office suite, you
can then convert the documentation to Postscript of
<ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>. The procedure below illustrates this
process using <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
>.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> It appears that current versions of the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> documentation
trigger some bug in or exceed the size limit of OpenJade. If the
build process of the <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> version hangs for a
long time and the output file still has size 0, then you may have
hit that problem. (But keep in mind that a normal build takes 5
to 10 minutes, so don't abort too soon.)
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="PROCEDURE"
><P
><B
><SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
> <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> Cleanup</B
></P
><P
> <SPAN
CLASS="APPLICATION"
>OpenJade</SPAN
> omits specifying a default
style for body text. In the past, this undiagnosed problem led to
a long process of table of contents generation. However, with
great help from the <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
> folks
the symptom was diagnosed and a workaround is available.
</P
><OL
TYPE="1"
><LI
CLASS="STEP"
><P
> Generate the <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> version by typing:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres.rtf</KBD
></PRE
><P>
</P
></LI
><LI
CLASS="STEP"
><P
> Repair the RTF file to correctly specify all styles, in
particular the default style. If the document contains
<CODE
CLASS="SGMLTAG"
>refentry</CODE
> sections, one must also replace
formatting hints which tie a preceding paragraph to the current
paragraph, and instead tie the current paragraph to the
following one. A utility, <TT
CLASS="COMMAND"
>fixrtf</TT
>, is
available in <TT
CLASS="FILENAME"
>doc/src/sgml</TT
> to accomplish
these repairs:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>./fixrtf --refentry postgres.rtf</KBD
></PRE
><P>
</P
><P
> The script adds <TT
CLASS="LITERAL"
>{\s0 Normal;}</TT
> as the zeroth
style in the document. According to
<SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
>, the RTF standard would
prohibit adding an implicit zeroth style, though Microsoft Word
happens to handle this case. For repairing
<CODE
CLASS="SGMLTAG"
>refentry</CODE
> sections, the script replaces
<TT
CLASS="LITERAL"
>\keepn</TT
> tags with <TT
CLASS="LITERAL"
>\keep</TT
>.
</P
></LI
><LI
CLASS="STEP"
><P
> Open a new document in <SPAN
CLASS="PRODUCTNAME"
>Applixware Words</SPAN
> and
then import the <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> file.
</P
></LI
><LI
CLASS="STEP"
><P
> Generate a new table of contents (ToC) using
<SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
>.
</P
><OL
CLASS="SUBSTEPS"
TYPE="a"
><LI
CLASS="STEP"
><P
> Select the existing ToC lines, from the beginning of the first
character on the first line to the last character of the last
line.
</P
></LI
><LI
CLASS="STEP"
><P
> Build a new ToC using
<SPAN
CLASS="GUIMENU"
>Tools</SPAN
>-><SPAN
CLASS="GUISUBMENU"
>Book
Building</SPAN
>-><SPAN
CLASS="GUIMENUITEM"
>Create Table of
Contents</SPAN
>. Select the first three
levels of headers for inclusion in the ToC. This will replace
the existing lines imported in the RTF with a native
<SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
> ToC.
</P
></LI
><LI
CLASS="STEP"
><P
> Adjust the ToC formatting by using
<SPAN
CLASS="GUIMENU"
>Format</SPAN
>-><SPAN
CLASS="GUIMENUITEM"
>Style</SPAN
>,
selecting each of the three ToC styles, and adjusting the
indents for <TT
CLASS="LITERAL"
>First</TT
> and
<TT
CLASS="LITERAL"
>Left</TT
>. Use the following values:
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN91032"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>Style</TH
><TH
>First Indent (inches)</TH
><TH
>Left Indent (inches)</TH
></TR
></THEAD
><TBODY
><TR
><TD
><TT
CLASS="LITERAL"
>TOC-Heading 1</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.4</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.4</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>TOC-Heading 2</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.8</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.8</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>TOC-Heading 3</TT
></TD
><TD
><TT
CLASS="LITERAL"
>1.2</TT
></TD
><TD
><TT
CLASS="LITERAL"
>1.2</TT
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></LI
></OL
></LI
><LI
CLASS="STEP"
><P
> Work through the document to:
<P
></P
></P><UL
><LI
><P
> Adjust page breaks.
</P
></LI
><LI
><P
> Adjust table column widths.
</P
></LI
></UL
><P>
</P
></LI
><LI
CLASS="STEP"
><P
> Replace the right-justified page numbers in the Examples and
Figures portions of the ToC with correct values. This only takes
a few minutes.
</P
></LI
><LI
CLASS="STEP"
><P
> Delete the index section from the document if it is empty.
</P
></LI
><LI
CLASS="STEP"
><P
> Regenerate and adjust the table of contents.
</P
><OL
CLASS="SUBSTEPS"
TYPE="a"
><LI
CLASS="STEP"
><P
> Select the ToC field.
</P
></LI
><LI
CLASS="STEP"
><P
> Select <SPAN
CLASS="GUIMENU"
>Tools</SPAN
>-><SPAN
CLASS="GUISUBMENU"
>Book
Building</SPAN
>-><SPAN
CLASS="GUIMENUITEM"
>Create Table of
Contents</SPAN
>.
</P
></LI
><LI
CLASS="STEP"
><P
> Unbind the ToC by selecting
<SPAN
CLASS="GUIMENU"
>Tools</SPAN
>-><SPAN
CLASS="GUISUBMENU"
>Field
Editing</SPAN
>-><SPAN
CLASS="GUIMENUITEM"
>Unprotect</SPAN
>.
</P
></LI
><LI
CLASS="STEP"
><P
> Delete the first line in the ToC, which is an entry for the
ToC itself.
</P
></LI
></OL
></LI
><LI
CLASS="STEP"
><P
> Save the document as native <SPAN
CLASS="PRODUCTNAME"
>Applixware
Words</SPAN
> format to allow easier last minute editing
later.
</P
></LI
><LI
CLASS="STEP"
><P
> <SPAN
CLASS="QUOTE"
>"Print"</SPAN
> the document
to a file in Postscript format.
</P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN91097"
>G.3.5. Plain Text Files</A
></H2
><P
> Several files are distributed as plain text, for reading during
the installation process. The <TT
CLASS="FILENAME"
>INSTALL</TT
> file
corresponds to <A
HREF="installation.html"
>Chapter 14</A
>, with some minor
changes to account for the different context. To recreate the
file, change to the directory <TT
CLASS="FILENAME"
>doc/src/sgml</TT
>
and enter <KBD
CLASS="USERINPUT"
>gmake INSTALL</KBD
>. This will create
a file <TT
CLASS="FILENAME"
>INSTALL.html</TT
> that can be saved as text
with <SPAN
CLASS="PRODUCTNAME"
>Netscape Navigator</SPAN
> and put into
the place of the existing file.
<SPAN
CLASS="PRODUCTNAME"
>Netscape</SPAN
> seems to offer the best
quality for <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> to text conversions (over
<SPAN
CLASS="APPLICATION"
>lynx</SPAN
> and
<SPAN
CLASS="APPLICATION"
>w3m</SPAN
>).
</P
><P
> The file <TT
CLASS="FILENAME"
>HISTORY</TT
> can be created similarly,
using the command <KBD
CLASS="USERINPUT"
>gmake HISTORY</KBD
>. For the
file <TT
CLASS="FILENAME"
>src/test/regress/README</TT
> the command is
<KBD
CLASS="USERINPUT"
>gmake regress_README</KBD
>.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN91115"
>G.3.6. Syntax Check</A
></H2
><P
> Building the documentation can take very long. But there is a
method to just check the correct syntax of the documentation
files, which only takes a few seconds:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake check</KBD
></PRE
><P>
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-toolsets.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide-authoring.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Tool Sets</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Documentation Authoring</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a866202fe868538f89a755dbcabc378b
>
files
>
127
