<!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.0.11 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="2007-02-02T03:57:22"></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.0.11 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="AEN75059" >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="AEN75072" >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="AEN75082" >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="AEN75108" >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="AEN75171" ></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="AEN75236" >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="AEN75254" >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 >