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.

The documentation can be translated to multiple languages, see po/README for
instructions about how to do that.

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

Run `make help` to get help on notable targets.

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:
 * GraphicsMagick - http://www.graphicsmagick.org/ (preferred)
 * ImageMagick - https://imagemagick.org/script/download.php ("convert" or
   "magick convert" binaries)

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 and report on manual example tests:
 * Python 3 with lxml

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

How to
------

Manual images for the reference documentation live in ``doc/html/images``.
Each ``.wkt`` file stores one drawing, optionally split into named layers by
prefixing a line with ``StyleName;WKT``. The generator associates each layer
with ``styles.conf`` and streams the resulting GraphicsMagick command without
ever writing intermediate files, so building all figures in parallel is safe.

To regenerate the helper binary and PNG artwork:

1. ``make -C doc/html/images generator``
2. ``make -C doc/html/images`` (use ``-j`` for parallel builds)

Invoke ``doc/html/images/generator`` directly to spot-check new artwork. The
``-v`` flag prints the exact GraphicsMagick or ImageMagick command, ``-s``
overrides the canvas size, and passing a second filename overrides the default
``.png`` output. Set ``POSTGIS_DOC_CONVERTER`` to the GraphicsMagick/ImageMagick
binary if autodetection cannot find ``gm``, ``magick``, or ``convert`` in
``PATH``.

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

Manual example tests are opt-out. A parseable SQL ``programlisting`` with
expected output is tested by default. Add ``role="requires-external-state"`` when
the listing depends on database objects, files, installed driver/catalog state,
prior manual setup, or other state outside the listing and outside the standard
example-test database. Use ``role="example-test"`` only as an escape hatch to
force a listing to run when the heuristics would otherwise skip it.

Put executable SQL in ``programlisting`` and expected output in the immediately
following ``screen`` element:

```
<programlisting>SELECT ST_AsText(ST_Point(1, 2));</programlisting>
<screen>POINT(1 2)</screen>
```

Use ``screen`` for interactive terminal transcripts. If the prompt is important,
mark it as ``prompt`` and the typed command as ``userinput``. Do not include shell
or psql prompts in copy-paste SQL ``programlisting`` blocks.

Example SQL formatting rules:

* SQL-only examples may be split across XML lines for diff-friendly editing,
  including a newline after ``<programlisting>`` or before ``</programlisting>``.
  The example tester trims surrounding XML whitespace before running them.
* Keep SQL keywords uppercase in touched examples.
* Use the documented function-name casing used by the manual.
* Prefer no space between a function name and ``(`` as documentation style only.
  The example tester accepts whitespace there.
* Do not put spaces around PostgreSQL casts: use ``'POINT(1 2)'::geometry``.
* Put a space after commas in SQL argument lists, unless preserving compact WKT
  output in ``screen``.
* For a multiline function call, either keep all arguments on one line, or put
  the function call on its own line and list top-level arguments below it. Align
  closing parentheses with the line that opened the call.
* Move explanatory ``--`` comments out of SQL listings into full-sentence
  ``para`` elements. Keep SQL comments only when they are part of the command.
* Do not put expected output, psql column headers, row-count footers, or
  ``-- result --`` markers inside ``programlisting``.
* For one-column scalar output, omit the psql column header and separator in
  ``screen`` unless the header is itself important to the example.
* If a docs example intentionally uses psql variables or other psql meta-commands,
  keep them in ``programlisting`` only when the listing is marked
  ``role="requires-external-state"`` or is otherwise not auto-run.
* Mark examples that require a newer GEOS/PROJ/GDAL feature than the default test
  environment with ``role="requires-external-state"`` instead of adding runner
  special cases.
* Version-reporting and extension-catalog examples are run, but their
  version/build strings and optional extension rows are treated as volatile.
  The tester checks that the query runs and returns the documented column shape.

Use ``make exampletest-report`` to inspect the current manual. Use
``make -C regress exampletest-unit`` to run fast unit tests for the manual
example parser and comparison logic.
