PostGIS Documentation
=====================

Overview
--------

PostGIS documentation is written in DocBook XML. The input file is
``postgis.xml``, which in turn includes all the individual chapter XML files.
From that file we can publish several formats, including HTML and PDF.

Make targets
------------

``make``
  same as ``make comments``

``make install``
  same as ``make comments-install``

``make uninstall``
  same as ``make comments-uninstall``

``make html``
  generates a single-file ``html/postgis.html``

``make html-localized``
  generates single-file ``html/postgis-<lang>.html`` for
  each supported language

``make chunked-html``
  generates a separate html file for every chapter or section break
  You can use CHUNKED_HTML_USER_OPTS environment variable to tweak
  the output, for example:
  > make chunked-html XSLTPROCFLAGS="--stringparam html.script custom.js

``make pdf``
  generates a single PDF file with the PostGIS version as a filename

``make pdf-localized``
  generates a single PDF file with the PostGIS version as a filename
  and ``-<lang>`` suffix for each supported language

``make images``
  generates all the images used in the HTML and PDF targets

``make comments``
  generates an SQL script that add COMMENTs for every function (derived from
  the documentation)

``make doxygen``
  generates the developer's documentation using Doxygen

``make comments-install``
  copies the ``postgis-comments.sql`` script to the PostgreSQL ``contrib``
  directory

``make comments-uninstall``
  removes the ``postgis-comments.sql`` script from the ``contrib`` directory

``make clean``
  removes generated files except comments

``make maintainer-clean``
  removes all generated files (including comments)

``make update-po``
  update translation files to be in sync with the source
  XML files. See ``make check-localized``

``make check``
  check structural correctness of XML documentation

``make check-localized``
  check structural correctness of localized (translated)
  XML documentation. Remember to run this before committing
  updates to translation files (see ``make update-po``)


Requirements
------------

To generate the html files and the comments:
 * xsltproc - http://xmlsoft.org/xslt/xsltproc2.html
 * DocBook 5 schemas and stylesheets - https://docbook.org/tools/
 * xmllint - http://xmlsoft.org

To generate the images:
 * ImageMagick - http://www.imagemagick.org/

To generate the PDFs:
 * dblatex - http://dblatex.sourceforge.net

To generate the developer's documentation:
 * Doxygen - http://www.stack.nl/~dimitri/doxygen/
 * Graphviz - http://www.graphviz.org/

To generate and manage the translated XML files:
 * poxml - https://github.com/KDE/poxml
 * gettext - https://www.gnu.org/software/gettext/

To generate the localized PDFs:
 * fonts-ipafont-gothic
 * fonts-ipafont-mincho

How to
------

To generate images used in the documentation, follow these instructions on the
PostGIS wiki: http://trac.osgeo.org/postgis/wiki/DevWikiDocNewFeature

To run garden tests against functions, follow these instructions on the PostGIS
dev wiki: http://trac.osgeo.org/postgis/wiki/DevWikiGardenTest
