I have identified several open issues with the documentation build under
Meson (approximately in priority order):
1. Image files are not handled at all, so they don't show up in the
final product.
2. Defaults to website stylesheet, no way to configure. This should be
adjusted to match the make build.
3. The various build targets and their combinations are mismatching and
incomplete. For example:
Top-level GNUmakefile has these targets:
- docs (builds html and man)
- html
- man
(Those are the formats that are part of a distribution build.)
doc/src/sgml/Makefile has these documented targets:
- default target is html
- all (builds html and man, maps to top-level "docs")
- html
- man
- postgres-A4.pdf
- postgres-US.pdf
- check
as well as (undocumented):
- htmlhelp
- postgres.html
- postgres.txt
- epub
- postgres.epub
- postgres.info
meson has the following documented targets:
- docs (builds only html)
- alldocs (builds all formats, including obscure ones)
as well as the following undocumented targets:
- html
- man
- html_help [sic]
- postgres-A4.pdf
- postgres-US.pdf
- postgres.epub
- [info is not implemented at all]
- [didn't find an equivalent of check]
As you can see, this is all over the place. I'd like to arrive at some
consistency across all build systems for handling each tier of
documentation formats, in terms of what is documented, what the targets
are named, and how they are grouped.
4. There doesn't appear to be a way to install the documentation.
(There are also some open questions in the top-level meson.build about
the installation directories, but I suppose if we can't install them
then exactly where to install them hasn't been thought about too
much.)
5. There doesn't appear to be an equivalent of "make world" and "make
install-world" that includes documentation builds.
