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 PDFs:
 * dblatex - http://dblatex.sourceforge.net
 * rsvg-convert from librsvg (preferred for visual-example SVG fallbacks)
 * GraphicsMagick or ImageMagick as an optional SVG fallback rasterizer

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
 * A running PostgreSQL server and the staged PostGIS build

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

How to
------

Reference figures are generated from executable manual examples. Run
``make -C regress visual-examples`` before HTML or PDF targets. The staged
PostGIS build supplies geometry paths and raster outputs; the renderer writes
SVG plus a manifest under ``doc/html/images/visual-examples``. HTML embeds the
SVG files directly, while PDF rasterizes the same files as a backend fallback.

Do not add screenshots or authored geometry PNGs. Static raster files under
``doc/html/images/static`` are limited to branding and interface icons. Use
DocBook markup for equations and tables. See the repository-only developer
manual at https://gitea.osgeo.org/postgis/postgis/src/branch/master/doc/development/manual.md
for layout roles, labels, textual-output policy, native geometry/EWKT output
handling, and the visual review procedure.

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.

Running ``make -C regress visual-examples`` executes every runnable manual
example against the staged PostGIS build and renders a figure whenever its
result or SQL literals contain geometry. The same PostGIS build parses and
normalizes the geometry and supplies the SVG paths; no second geometry
implementation or checked-in image is needed. HTML embeds those SVG files and
the PDF image step rasterizes the same files at high resolution. The HTML and
PDF targets fail with a reminder if these assets have not been generated.

The textual output remains in the manual. HTML initially folds it only when
the figure contains that geometry result; scalar output and input-only figures
remain visible. Add ``role="visual-primary"`` and a stable ``xml:id`` to an
adjacent ``screen`` only when an authored example needs an explicit stable
figure identity or preference. Add ``role="text-primary"`` to a ``screen`` when
its exact geometry type or coordinates are essential; HTML then keeps Output
expanded while still showing the generated figure. Use ``role="visual-overlay"``
when input and output layers must share one coordinate frame, and
``role="visual-separate-output"`` when independent output columns must be shown
in separate, equally scaled frames. Geometry columns named with an ``input_``
prefix are treated as authored input layers; in separate-output mode their
remaining column names also label their frames.
Use ``role="visual-output-only"`` when setup geometry literals or constructors
appear in the SQL but the figure should render only the query output.
Aliases on cast WKT literals and geometry result columns become figure legend
labels; quote an alias when the label needs spaces.

A plain paragraph immediately before a ``programlisting`` is rendered as the
introduction to that example card. Examples without an introduction retain the
same standalone Code styling.

The full ``make -C regress exampletest`` target also regenerates these assets
while testing every runnable manual example. The narrower visual target shares
its staged-install and database recipe but does not require unrelated optional
features used elsewhere in the manual.

For contributor workflow, local testing, and garden checks, see
https://gitea.osgeo.org/postgis/postgis/src/branch/master/doc/development/.

The audited Trac wiki migration record and recovered attachments live in
``doc/trac-wiki/``.
