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:
- PDF (A4 and US Legal size)
- man
- html docs
Target should be as follows:
- postgres-A4.pdf or postgres-US.pdf
- man
- 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 <!## tag> ... <!## end>. These tags can appear just itself as separate lines. Lines not enclosed with any such tags are common to all.
So SGML file may look like...
... <para> <!## PG> ... <!## end> <!## XC> ... <!## end> </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. It is highly recommended to use jade instead. Openjade cannot handle the stylesheet properly and cause error. However, openjade may check SGML tag error more strictly so it will be a good idea to use openjade when you build html and man.
When you build pdf, you should use "jade" instead. This can be configured by specifying JADE=jade in ./configure command line.
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.
Upgrading the 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 < patchfile
- Resolve patch conflict manually.