<!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.4.12 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="2012-05-31T23:30:11"></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.4.12 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 I. 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" >I.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="AEN120820" >I.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 > To create a proper index, the build might process several identical stages. If you do not care about the index, and just want to proof-read the output, use <TT CLASS="LITERAL" >draft</TT >: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >doc/src/sgml$ </SAMP ><KBD CLASS="USERINPUT" >gmake draft</KBD ></PRE ><P> </P ><P > 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 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="AEN120837" >I.3.2. Manpages</A ></H2 ><P > We use the <SPAN CLASS="APPLICATION" >docbook2man-sgmlspl</SPAN > utility from the <SPAN CLASS="PRODUCTNAME" >DocBook2X</SPAN > project 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 pages, use the commands: </P><PRE CLASS="PROGRAMLISTING" >cd doc/src/sgml gmake man D2MDIR=<TT CLASS="REPLACEABLE" ><I >directory</I ></TT ></PRE ><P> Use the <TT CLASS="VARNAME" >D2MDIR</TT > variable to specify the name of the directory where the file <TT CLASS="FILENAME" >docbook2man-spec.pl</TT > from the <SPAN CLASS="APPLICATION" >docbook2man-sgmlspl</SPAN > package resides. There is no default for that. Since that package is not available or outdated in many packaging systems, you might want to just download the source code tarball and unpack it. No building is required. Then the path is something like <TT CLASS="LITERAL" >D2MDIR=/home/you/somewhere/docbook2man-sgmlspl-1.0/perl</TT >. You may get warnings like this: </P><PRE CLASS="SCREEN" >Warning: unrecognized SDATA '[scaron]': please add definition to docbook2man-spec.pl Warning: unrecognized SDATA '[ouml ]': please add definition to docbook2man-spec.pl</PRE ><P> which can ignore if (and only if) you are using the latest version of <TT CLASS="FILENAME" >docbook2man-spec.pl</TT > and you are not seeing any other SDATA warnings besides those. </P ><P > To create the man page package for a release, use the following commands: </P><PRE CLASS="PROGRAMLISTING" >cd doc/src gmake man.tar.gz D2MDIR=<TT CLASS="REPLACEABLE" ><I >directory</I ></TT ></PRE ><P> which will result in a tar file being generated in the <TT CLASS="FILENAME" >doc/src</TT > directory. </P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="AEN120857" >I.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 generate PostScript via <ACRONYM CLASS="ACRONYM" >DVI</ACRONYM > in A4 format: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >doc/src/sgml$ </SAMP ><KBD CLASS="USERINPUT" >gmake postgres-A4.ps</KBD ></PRE ><P> In U.S. letter format: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >doc/src/sgml$ </SAMP ><KBD CLASS="USERINPUT" >gmake postgres-US.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-A4.pdf</KBD ></PRE ><P> or: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >doc/src/sgml$ </SAMP ><KBD CLASS="USERINPUT" >gmake postgres-US.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 ><P > When using JadeTeX to build the PostgreSQL documentation, you will probably need to increase some of TeX's internal parameters. These can be set in the file <TT CLASS="FILENAME" >texmf.cnf</TT >. The following settings worked at the time of this writing: </P><PRE CLASS="PROGRAMLISTING" >hash_extra.jadetex = 200000 hash_extra.pdfjadetex = 200000 pool_size.jadetex = 2000000 pool_size.pdfjadetex = 2000000 string_vacancies.jadetex = 150000 string_vacancies.pdfjadetex = 150000 max_strings.jadetex = 300000 max_strings.pdfjadetex = 300000 save_size.jadetex = 15000 save_size.pdfjadetex = 15000</PRE ><P> </P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="AEN120886" >I.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 might 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="AEN120949" ></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="AEN121014" >I.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 15</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="AEN121032" >I.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 >