From 2c93861f7cef99b4613abd37ed7e4c15a95754b4 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Fri, 6 Jun 2003 14:17:08 +0000 Subject: [PATCH] Update documentation build instructions. --- doc/src/sgml/docguide.sgml | 677 +++++++++++++------------------------ 1 file changed, 244 insertions(+), 433 deletions(-) diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index e52653ed146..a1199d66ae4 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ - + Documentation @@ -20,7 +20,7 @@ - Postscript, for printing + PDF or Postscript, for printing @@ -35,56 +35,14 @@ documenting various implementation issues. - - The documentation is organized into several books: - - - - - Tutorial: introduction for new users - - - - - User's Guide: documents the SQL implementation - - - - - Reference Manual: reference pages for programs and SQL commands - - - - - Administrator's Guide: installation and server maintenance - - - - - Programmer's Guide: programming client - applications and server extensions - - - - - Developer's Guide: assorted information - for developers of PostgreSQL proper - - - - - All books are available as HTML and Postscript. The - Reference Manual contains reference entries which - are also shipped as man pages. - - HTML documentation and man pages are part of a - standard distribution and are installed by default. Postscript - format documentation is available separately for download. + standard distribution and are installed by default. PDF and + Postscript format documentation is available separately for + download. - + DocBook The documentation sources are written in @@ -115,7 +73,7 @@ - + Tool Sets @@ -211,18 +169,17 @@ the various tools that are needed to process the documentation. These will be described below. There may be some other packaged distributions for these tools. Please report package status to the - docs mailing list and we will include that information here. + documentation mailing list, and we will include that information + here. <productname>Linux</productname> <acronym>RPM</acronym> Installation - Many vendors provide a complete RPM set for DocBook processing in - their distribution, which is usually based on the docbook-tools - effort at Red Hat Software. Look for an SGML - option while installing, or the following packages: + Most vendors provide a complete RPM set for DocBook processing in + their distribution. Look for an SGML option while + installing, or the following packages: sgml-common, docbook, stylesheets, openjade (or jade). Possibly @@ -475,8 +432,8 @@ CATALOG "docbook-dsssl--1.xx/catalog Because stylesheets change rather often, and it's sometimes beneficial to try out alternative versions, PostgreSQL doesn't use this catalog - entry. See for information about how - to select the stylesheets instead. + entry. See for + information about how to select the stylesheets instead. @@ -533,17 +490,15 @@ CATALOG "docbook-dsssl--1.xx/catalog - - - - Building The Documentation + + Detection by <command>configure</command> Before you can build the documentation you need to run the configure script as you would when building - the programs themselves. Check the output near the end of the run, - it should look something like this: + the PostgreSQL programs themselves. Check the output near the end + of the run, it should look something like this: checking for onsgmls... onsgmls @@ -566,85 +521,46 @@ checking for sgmlspl... sgmlspl configure afterwards. + + + + + Building The Documentation + Once you have everything set up, change to the directory - doc/src/sgml and run one of the following - commands: (Remember to use GNU make.) - - - - To build the HTML version of the - Administrator's Guide: - -doc/src/sgml$ gmake admin.html - - - - - - - For the RTF version of the same: - -doc/src/sgml$ gmake admin.rtf - - - - - - - To get a DVI version via - JadeTeX: - -doc/src/sgml$ gmake admin.dvi - - - - - - - And Postscript from the DVI: - -doc/src/sgml$ gmake admin.ps - - - - - The official Postscript format documentation is generated - differently. See below. - - - - - - The other books can be built with analogous commands by replacing - admin with one of developer, - programmer, tutorial, or - user. Using postgres builds - an integrated version of all 5 books, which is practical since the - browser interface makes it easy to move around all of the - documentation by just clicking. + doc/src/sgml and run one of the commands + described in the following subsections to build the + documentation. (Remember to use GNU make.) HTML - When building HTML documentation in - doc/src/sgml, some of the resulting files - will possibly (or quite certainly) have conflicting names between - books. Therefore the files are not in that directory in the - regular distribution. Instead, the files belonging to each book - are stored in a tar archive that is unpacked at installation time. - To create a set of HTML documentation packages - use the commands + To build the HTML version of the documentation: + +doc/src/sgml$ gmake html + + This is also the default target. + + + + 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. + + + + 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 + HTML documentation package, use the commands cd doc/src -gmake tutorial.tar.gz -gmake user.tar.gz -gmake admin.tar.gz -gmake programmer.tar.gz gmake postgres.tar.gz -gmake install In the distribution, these archives live in the doc directory and are installed by default @@ -652,118 +568,142 @@ gmake install - + Manpages We use the docbook2man utility to convert DocBook - REFENTRY pages to *roff output suitable for man + refentry pages to *roff output suitable for man pages. The man pages are also distributed as a tar archive, - similar to the HTML version. To create the man page package, use the commands + similar to the HTML version. To create the man + page package, use the commands cd doc/src -gmake man +gmake man.tar.gz which will result in a tar file being generated in the doc/src directory. - The man build leaves a lot of confusing output, and special care - must be taken to produce quality results. There is still room for - improvement in this area. + 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. - - Hardcopy Generation - - - The hardcopy Postscript documentation is generated by converting the - SGML source code to RTF, then - importing into Applixware. - After a little cleanup (see the following - section) the output is printed to a postscript file. - - - + + Print Output via <application>JadeTex</application> - Several areas are addressed while generating Postscript - hardcopy, including RTF repair, ToC generation, and page break - adjustments. + If you want to use JadeTex to produce a + printable rendition of the documentation, you can use one of the + following commands: + + + + + To make a DVI version: + +doc/src/sgml$ gmake postgres.dvi + + + + + + + To generate Postscript from the DVI: + +doc/src/sgml$ gmake postgres.ps + + + + + + + To make a PDF: + +doc/src/sgml$ gmake postgres.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.) + + + + + + + Print Output via <acronym>RTF</acronym> + + + You can also create a printable version of the PostgreSQL + documentation by converting it to RTF 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 using Applixware. + + + + + It appears that current versions of the PostgreSQL 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 may have + hit that problem. (But keep in mind that a normal build takes 5 + to 10 minutes, so don't abort too soon.) + + <productname>Applixware</productname> <acronym>RTF</acronym> Cleanup - jade, an integral part of the - hardcopy procedure, omits specifying a default style for body - text. In the past, this undiagnosed problem led to a long process - of Table of Contents (ToC) generation. However, with great help - from the Applixware folks the symptom was diagnosed and a - workaround is available. + 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 the Applixware folks + the symptom was diagnosed and a workaround is available. - Generate the RTF input by typing (for example): - -% cd doc/src/sgml -% make tutorial.rtf - + Generate the RTF version by typing: + +doc/src/sgml$ gmake postgres.rtf + - - Repair the RTF file to correctly specify all - styles, in particular the default style. If the document - contains REFENTRY 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 in - doc/src/sgml to accomplish these repairs: + Repair the RTF file to correctly specify all styles, in + particular the default style. If the document contains + refentry 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 in doc/src/sgml to accomplish + these repairs: - -% cd doc/src/sgml -% fixrtf tutorial.rtf - + +doc/src/sgml$ ./fixrtf --refentry postgres.rtf + + - or - - -% cd doc/src/sgml -% fixrtf --refentry reference.rtf - - - - - The script adds {\s0 Normal;} as - the zero-th style in the document. According to Applixware, the - RTF standard would prohibit adding an implicit zero-th style, - though M$Word happens to handle this case. For repairing - REFENTRY sections, the script replaces - \keepn tags with \keep. + + The script adds {\s0 Normal;} as the zeroth + style in the document. According to + Applixware, the RTF standard would + prohibit adding an implicit zeroth style, though Microsoft Word + happens to handle this case. For repairing + refentry sections, the script replaces + \keepn tags with \keep. @@ -776,92 +716,70 @@ gmake man - Generate a new ToC using Applixware. + Generate a new table of contents (ToC) using + Applixware. - Select the existing ToC lines, from the beginning of the first - character on the first line to the last character of the last - line. + Select the existing ToC lines, from the beginning of the first + character on the first line to the last character of the last + line. - Build a new ToC using - Tools.BookBuilding.CreateToC. 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 - Applixware ToC. + Build a new ToC using + ToolsBook + BuildingCreate 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 native + Applixware ToC. - Adjust the ToC formatting by using - Format.Style, selecting each of the three - ToC styles, and adjusting the indents for First and - Left. Use the following values: + Adjust the ToC formatting by using + FormatStyle, + selecting each of the three ToC styles, and adjusting the + indents for First and + Left. Use the following values: - - Indent Formatting for Table of Contents - - - - - Style - - - First Indent (inches) - - - Left Indent (inches) - - - + + + + + Style + First Indent (inches) + Left Indent (inches) + + - - - - TOC-Heading 1 - - - 0.4 - - - 0.4 - - + + + TOC-Heading 1 + 0.4 + 0.4 + - - - TOC-Heading 2 - - - 0.8 - - - 0.8 - - + + TOC-Heading 2 + 0.8 + 0.8 + - - - TOC-Heading 3 - - - 1.2 - - - 1.2 - - - - -
+ + TOC-Heading 3 + 1.2 + 1.2 + + + + @@ -873,32 +791,15 @@ gmake man - - Adjust page breaks. - + + Adjust page breaks. + - - Adjust table column widths. - - - - - - Insert figures into the document. Center each figure on the page using - the centering margins button on the Applixware toolbar. - - - - Not all documents have figures. - You can grep the SGML source files for - the string graphic to identify those parts of the - documentation that may have figures. A few figures are replicated in - various parts of the documentation. - - - + + Adjust table column widths. + @@ -907,24 +808,11 @@ gmake man Replace the right-justified page numbers in the Examples and - Figures portions of the ToC with - correct values. This only takes a few minutes per document. + 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. @@ -938,39 +826,41 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29 - - Select the ToC field. - + + Select the ToC field. + - - Select - Tools->Book Building->Create Table of - Contents. - + + Select ToolsBook + BuildingCreate Table of + Contents. + - - Unbind the ToC by selecting - Tools->Field Editing->Unprotect. - + + Unbind the ToC by selecting + ToolsField + EditingUnprotect. + - - Delete the first line in the ToC, which is an entry for the - ToC itself. - + + Delete the first line in the ToC, which is an entry for the + ToC itself. + - Save the document as native Applixware Words format to allow easier last - minute editing later. + Save the document as native Applixware + Words format to allow easier last minute editing + later. @@ -980,13 +870,6 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29 to a file in Postscript format. - - - - Compress the Postscript file using gzip. - Place the compressed file into the doc directory. - - @@ -996,16 +879,16 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29 Several files are distributed as plain text, for reading during the installation process. The INSTALL file - corresponds to the chapter in the Administrator's - Guide, with some minor changes to account for the - different context. To recreate the file, change to the directory - doc/src/sgml and enter gmake - INSTALL. This will create a file - INSTALL.html that can be saved as text with - Netscape Navigator and put into the - place of the existing file. Netscape - seems to offer the best quality for HTML to - text conversions (over lynx and + corresponds to , with some minor + changes to account for the different context. To recreate the + file, change to the directory doc/src/sgml + and enter gmake INSTALL. This will create + a file INSTALL.html that can be saved as text + with Netscape Navigator and put into + the place of the existing file. + Netscape seems to offer the best + quality for HTML to text conversions (over + lynx and w3m). @@ -1015,96 +898,24 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29 file src/test/regress/README the command is gmake regress_README. + - + + 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$ gmake check + + - + Documentation Authoring @@ -1222,7 +1033,7 @@ End: the first line look like this: -<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> This means that anything and everything that reads @@ -1255,7 +1066,7 @@ End: - + Style Guide