mirror of
https://github.com/postgres/postgres.git
synced 2025-07-23 03:21:12 +03:00
969509c3f2
It appears no longer possible to build the SGML docs without a local installation of the DocBook DTD, because sourceforge.net now only permits HTTPS access, and no common version of xsltproc supports that. Hence, remove the bits of our documentation suggesting that that's possible or useful. In fact, we might as well add the --nonet option to the build recipes automatically, for a bit of extra security. Also fix our documentation-tool-installation recipes for macOS to ensure that xmllint and xsltproc are pulled in from MacPorts or Homebrew. The previous recipes assumed you could use the Apple-supplied versions of these tools; which still works, except that you'd need to set an environment variable to ensure that they would find DTD files provided by those package managers. Simpler and easier to just recommend pulling in the additional packages. In HEAD, also document how to build docs using Meson, and adjust "ninja docs" to just build the HTML docs, for consistency with the default behavior of doc/src/sgml/Makefile. In a fit of neatnik-ism, I also made the ordering of the package lists match the order in which the tools are described at the head of the appendix. Aleksander Alekseev, Peter Eisentraut, Tom Lane Discussion: https://postgr.es/m/CAJ7c6TO8Aro2nxg=EQsVGiSDe-TstP4EsSvDHd7DSRsP40PgGA@mail.gmail.com
Images
======
This directory contains images for use in the documentation.
Creating an image
-----------------
A variety of tools can be used to create an image. The appropriate
choice depends on the nature of the image. We prefer workflows that
involve diffable source files.
These tools are acceptable:
- Graphviz (https://graphviz.org/)
- Ditaa (http://ditaa.sourceforge.net/)
We use SVG as the format for integrating the image into the ultimate
output formats of the documentation, that is, HTML, PDF, and others.
Therefore, any tool used needs to be able to produce SVG.
This directory contains makefile rules to build SVG from common input
formats, using some common styling.
fixup-svg.xsl applies some postprocessing to the SVG files produced by
those external tools to address assorted issues. See comments in
there, and adjust and expand as necessary.
Both the source and the SVG output file are committed in this
directory. That way, we don't need all developers to have all the
tools installed. While we accept that there could be some gratuitous
diffs in the SVG output depending the specific tool, let's keep an eye
on that and keep it to a minimum.
Using an image in DocBook
-------------------------
Here is an example for using an image in DocBook:
<figure id="gin-internals-figure">
<title>GIN Internals</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
</imageobject>
</mediaobject>
</figure>
Notes:
- The real action is in the <mediaobject> element, but typically a
<figure> should be wrapped around it and an <xref> to the figure
should be put into the text somewhere. Don't just put an image into
the documentation without a link to it and an explanation of it.
- Things are set up so that we only need one <imagedata> element, even
with different output formats.
- The attribute format="SVG" is required. If you omit it, it will
still appear to work, but the stylesheets do a better job if the
image is declared as SVG explicitly.
- The width should be set to something. This ensures that the image
is scaled to fit the page in PDF output. (Other widths than 100%
might be appropriate.)