Re: meson documentation build open issues

Hi,

On 2023-03-15 08:14:09 +0100, Peter Eisentraut wrote:
> 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.

Hm. Somehow I thought I'd tackled that at some point. Ah. I got there for the
PDF output, but didn't realize it's also an issue for the html output.

For FO it sufficed to set the img.src.path param. For HTML that's not enough,
because that just adjusts the link to the file - but we don't want to link to
the source file. We actually solved this for the single-page html version - we
just embed the svg. I wonder if we should just do that as well.

Another way would be to emit the files into the desired place as part of the
stylesheet. While it requires touching xslt, it does seems somewhat more
elegant than just copying files around. I did implement that, curious what you
think.

> 2. Defaults to website stylesheet, no way to configure. This should be
> adjusted to match the make build.

Should we add a meson option?

> 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]

renamed in the attached patch.

> - postgres-A4.pdf
> - postgres-US.pdf
> - postgres.epub

Note that these are actually named doc/src/sgml/{html,man,...}, not top-level
targets.

> - [info is not implemented at all]

Would be easy to implement, but not sure it's worth doing.

> - [didn't find an equivalent of check]

That's probably worth doing - should it be run as an actual test, or be a
target?

> 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.)

WIP patch for that attached. There's now
install-doc-man
install-doc-html
run targets and a
install-docs
alias target.

I did end up getting stuck when hacking on this, and ended up adding css
support for nochunk and support for the website style for htmlhelp and
nochunk, as well as obsoleting the need for copying the css files... But
perhaps that's a bit too much.

Greetings,

Andres Freund