J.1. DocBook

The documentation sources are written in DocBook, which is a markup language superficially similar to HTML. Both of these languages are applications of the Standard Generalized Markup Language, SGML, which is essentially a language for describing other languages. In what follows, the terms DocBook and SGML are both used, but technically they are not interchangeable.

DocBook allows an author to specify the structure and content of a technical document without worrying about presentation details. A document style defines how that content is rendered into one of several final forms. DocBook is maintained by the OASIS group. The official DocBook site has good introductory and reference documentation and a complete O'Reilly book for your online reading pleasure. The NewbieDoc Docbook Guide is very helpful for beginners. The FreeBSD Documentation Project also uses DocBook and has some good information, including a number of style guidelines that might be worth considering.

To make it simpler to compare original PostgreSQL documentation with Postgres-XC, we decided to generate DocBook file from new file prefixed as sgmlin. sgmlin file is essentially DocBook file with additional tags <!## tag> and <!## end>. The former is a start tag and the latter is the stop tag. These tags should occupy whole line. No other tags or CCDATA should appear in the same line. The tool makesgml takes these file, filter only Postgres-XC specific contents and generate target sgml files.

Makefile has been modified to accommodate these changes.