Reference_Manual

• Postgres-XC Reference Manual Preparation
• Tools configuration
• Makefile tweak
• Progress
  • Qquestions to other members
• TIPS to make in Cent OS 5.6
• Upgrade base PostgreSQL document

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

Makefile tweak

In Linux environment, which is Koichi's main documentation environment, ./configure somehow select "openjade", not "jade" for sgml handling. This should be forced to use jade. Openjade cannot handle the stylesheet properly and cause error.

Generating pdf directly may cause an error. Advise to make PostScript first and then convert it to PDF.

Progress

• makesgml is complete (Apr.1st, 2011)
• Created new branch "documentation"
• Makefile modified (Apr.7th, 2011)
• Finished to mark unreviewed part as "This is specific to PG".(May 19th).
• Finished introduction. (May 19th).

Qquestions to other members

• Do we support "-o" option in pg_dumpall?

TIPS to make in Cent OS 5.6

• Configure style sheet location as:

  ./configure ... DOCBOOKSTYLE=/usr/share/sgml/docbook/dsssl-stylesheets JADE=jade

• Needed to tweak texmf.cnf as follows. Location is /usr/share/texmf/web2c.

  • May work with smaller configuration but TeX's configuration is very small considering available memory in today's PC/servers and it is safer to provide more memory to TeX.
  • Make sure to install jadetex.
  • jade seems to work better than openjade.

  hash_extra = 100000
  hash_size.mpost = 120000
  pool_size = 2500000
  max_strings = 400000

Please note that JADE in CentOS looks more strict in the tag syntax check. It is recommended to run JADE in CentOS to fix potential tag problems.

You should upgrade docbook-xsl to the latest version (at least to 1.73). CentOS 5.6's docbook-xsl is very old, 1.69, and is not sufficient to create man pages. The latest file is available at http://sourceforge.net/projects/docbook/files/.

After you've downloaded extract it to /sur/share/sgml/docbook, rename the top directory to xsl-stylesheets-1.69.1-5.1. You may have to rename the original stylesheet directory.

Upgrade base PostgreSQL document

Assume Postgres-XC document source is kept in the directory "doc-xc" as in the current GIT repo.

• Copy the original PostgreSQL document (directory "doc") used as the basis of current XC document to doc-orig or other new directory of your choice.

  cp -rf $origdoc doc-orig

• Change suffix of all the sgml files in "doc-orig" directory from ".sgml" to ".sgmlin".

• Get patch file from "doc-orig" to "doc-xc".

  cp -rf $doc-xc doc-xc-orig
  diff -crN doc-orig doc-xc-orig > patchfile

• Then get new version of PostgreSQL document (doc).

• Copy new "doc" into "doc-xc".

  cp -rf $newpgdoc doc-xc

• Change suffix of all the sgml files in "doc-xc" directory from ".sgml" to ".sgmlin".

• Apply the patch to "doc-xc".

  cd doc-xc
  patch -p1