Feedback-ID: i131946ab:Fastmail
Message-ID: <3fc3bb9b-f7f8-d442-35c1-ec82280c564a@enterprisedb.com>
Date: Wed, 15 Mar 2023 08:14:09 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0)
 Gecko/20100101 Thunderbird/102.8.0
Content-Language: en-US
From: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
Subject: meson documentation build open issues
To: pgsql-hackers <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: <https://www.postgresql.org/message-id/3fc3bb9b-f7f8-d442-35c1-ec82280c564a%40enterprisedb.com>
Precedence: bulk

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.