Reference_Manual

Postgres-XC Reference Manual Preparation

(April 7th, Koichi Suzuki)

Because Postgres-XC inherits most of the spec from PostgreSQL, it is reasonable to prepare the reference manual using original PostgreSQL SGML files.

With PostgreSQL document resource, we can build the following documents:

1. PDF (A4 and US Legal size)
2. man
3. html docs

Target should be as follows:

1. postgres-A4.pdf or postgres-US.pdf
2. man
3. html

In the case of 3), we can embedd international characters like Japanese.

We should be careful to make it easier to merge with later version of PostgreSQL SGML files. To do this, we can embed special "TAG" to distinguish what is common, what is PostgreSQL-specific and what is Postgres-XC specific. Also, we may want to distinguish translation to different languages.

To make it easier to handle as an external tool, we can build dedicated (but somewhat general) tool to select what tags to be included. At present, the format is

   ...
   <para>
   </para>

You can nest this tag. With the nest, you can include multiple translations in a single file.

This can be handled by a command makesgml, which will be placed at postgres-xc/doc/tools.

Makesgml can be invoked like

   makesgml -i _inf_ -o _outf_ -I _include_tag_ ... -E _exclude_tag_ ...

Each argument is optional and order of the argument is arbitrary. If you omit -i option, it will read from stdin. If -o is omitted, it will write to stdout. If input file include unspecified tags in the arguments, it will be treated as specified -E.

All the sgml files from original PostgreSQL tarball will be renamed to sgmlin. Then it will be filtered by makesgml and fed to original document build scripts.

Tools configuration

When building pdf/ps file, we need JadeTeX. Because the document consists of huge number of references, we need to expand the configuration. This can be done by editing texmf.cnf file, typically placed at /etc/texmf.

So far, I've modified two configuration parameters as follows:

   hash_extra = 50000
   hash_size.mpost = 120000

Progress

• makesgml is complete (Apr.1st, 2011)
• Created new branch "documentation"
• Makefile modified (Apr.7th, 2011)