J.3. Building The Documentation
Once you have everything set up, change to the directorydoc/src/sgml and run one of the commands described in the following subsections to build the documentation. (Remember to use GNU make.)
J.3.2. Manpages
We use the DocBook XSL stylesheets to convertDocBookrefentry pages to *roff output suitable for man pages. The man pages are also distributed as a tar archive, similar to theHTML version. To create the man pages, use the commands:cd doc/src/sgmlmake man
J.3.3. Print Output viaJadeTeX
If you want to useJadeTex to produce a printable rendition of the documentation, you can use one of the following commands:
To generate PostScript viaDVI in A4 format:
doc/src/sgml$make postgres-A4.psIn U.S. letter format:
doc/src/sgml$make postgres-US.psTo make aPDF:
doc/src/sgml$make postgres-A4.pdfor:
doc/src/sgml$make postgres-US.pdf(Of course you can also make aPDF version from the PostScript, but if you generatePDF directly, it will have hyperlinks and other enhanced features.)
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 filetexmf.cnf. The following settings worked at the time of this writing:
hash_extra.jadetex = 200000hash_extra.pdfjadetex = 200000pool_size.jadetex = 2000000pool_size.pdfjadetex = 2000000string_vacancies.jadetex = 150000string_vacancies.pdfjadetex = 150000max_strings.jadetex = 300000max_strings.pdfjadetex = 300000save_size.jadetex = 15000save_size.pdfjadetex = 15000
J.3.4. Overflow Text
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“Overfull hbox” messages in the TeX log output file, e.g.,postgres-US.log orpostgres-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 theSGML text causing the overflow, find the first page number mentioned above the overflow message, e.g.,[50 ###] (page 50), and look at the page after that (e.g., page 51) in thePDF file to see the overflow text and adjust theSGML accordingly.
J.3.5. Print Output viaRTF
You can also create a printable version of thePostgreSQL documentation by converting it toRTF 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 ofPDF. The procedure below illustrates this process usingApplixware. It appears that current versions of thePostgreSQL documentation trigger some bug in or exceed the size limit of OpenJade. If the build process of theRTF 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.) ApplixwareRTF Cleanup OpenJade 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 theApplixware folks the symptom was diagnosed and a workaround is available.Note
J.3.6. Plain Text Files
The installation instructions are also distributed as plain text, in case they are needed in a situation where better reading tools are not available. TheINSTALL file corresponds toChapter 15, with some minor changes to account for the different context. To recreate the file, change to the directorydoc/src/sgml and entermake INSTALL.
In the past, the release notes and regression testing instructions were also distributed as plain text, but this practice has been discontinued.
J.3.7. Syntax Check
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:
doc/src/sgml$make check