PostgreSQL 9.4.1 Documentation
Prev	Up	Appendix J. Documentation	Next

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.1. HTML

To build theHTML version of the documentation:

doc/src/sgml$make html

This is also the default target. The output appears in the subdirectoryhtml.

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, usedraft:

doc/src/sgml$make draft

To build the documentation as a single HTML page, use:

doc/src/sgml$make postgres.html

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.ps
```
In U.S. letter format:
```
doc/src/sgml$make postgres-US.ps
```
To make a PDF:
```
doc/src/sgml$make postgres-A4.pdf
```
or:
```
doc/src/sgml$make postgres-US.pdf
```
(Of course you can also make a PDF version from the PostScript, but if you generate PDF 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 the PDF file to see the overflow text and adjust the SGML accordingly.

J.3.5. Print Output via RTF

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 of PDF. The procedure below illustrates this process usingApplixware.

Note: It appears that current versions of thePostgreSQL documentation trigger some bug in or exceed the size limit of OpenJade. If the build process of the RTF 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.

Generate the RTF version by typing:
```
doc/src/sgml$make postgres.rtf
```
Repair the RTF file to correctly specify all styles, in particular the default style. If the document containsrefentry 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,fixrtf, is available indoc/src/sgml to accomplish these repairs:
```
doc/src/sgml$./fixrtf --refentry postgres.rtf
```
The script adds{\s0 Normal;} as the zeroth style in the document. According toApplixware, the RTF standard would prohibit adding an implicit zeroth style, though Microsoft Word happens to handle this case. For repairingrefentry sections, the script replaces\keepn tags with\keep.
Open a new document inApplixware Words and then import the RTF file.
Generate a new table of contents (ToC) usingApplixware.
1. Select the existing ToC lines, from the beginning of the first character on the first line to the last character of the last line.
2. Build a new ToC usingTools->Book Building->Create Table of Contents. Select the first three levels of headers for inclusion in the ToC. This will replace the existing lines imported in the RTF with a nativeApplixware ToC.
3. Adjust the ToC formatting by usingFormat->Style, selecting each of the three ToC styles, and adjusting the indents forFirst andLeft. Use the following values:
  Style First Indent (inches) Left Indent (inches)
  TOC-Heading 1 0.4 0.4
  TOC-Heading 2 0.8 0.8
  TOC-Heading 3 1.2 1.2
Work through the document to:
- Adjust page breaks.
- Adjust table column widths.
Replace the right-justified page numbers in the Examples and Figures portions of the ToC with correct values. This only takes a few minutes.
Delete the index section from the document if it is empty.
Regenerate and adjust the table of contents.
1. Select the ToC field.
2. SelectTools->Book Building->Create Table of Contents.
3. Unbind the ToC by selectingTools->Field Editing->Unprotect.
4. Delete the first line in the ToC, which is an entry for the ToC itself.
Save the document as nativeApplixware Words format to allow easier last minute editing later.
"Print" the document to a file in PostScript format.

Style	First Indent (inches)	Left Indent (inches)
`TOC-Heading 1`	`0.4`	`0.4`
`TOC-Heading 2`	`0.8`	`0.8`
`TOC-Heading 3`	`1.2`	`1.2`

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

Prev	Home	Next
Tool Sets	Up	Documentation Authoring

Movatterモバイル変換