Re: meson documentation build open issues

Hi,

On 2023-11-09 15:32:39 +0100, Peter Eisentraut wrote:
> On 09.11.23 01:59, Andres Freund wrote:
> > > I think we could build doc/src/sgml/postgres-full.xml by default. That
> > > takes less than 0.5 seconds here and it's an intermediate target for html
> > > and man.
> > That does require the docbook dtd to be installed, afaict. I think we would
> > need a configure test for that to be present if we want to build it by
> > default, otherwise we'll cause errors on plenty systems that don't get them
> > today. The docbook dts aren't a huge dependency, but still. Some OSs might
> > not have a particularly install source for them, e.g. windows.
>
> I was thinking we would do it only if the required tools are found.
> Basically like
>
> postgres_full_xml = custom_target('postgres-full.xml',
> input: 'postgres.sgml',
> output: 'postgres-full.xml',
> depfile: 'postgres-full.xml.d',
> command: [xmllint, '--nonet', '--noent', '--valid',
> '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'],
> depends: doc_generated,
> - build_by_default: false,
> + build_by_default: xmllint_bin.found(),
> )

We don't get to that point if xmllint isn't found...

> Besides giving you a quick validity check of the XML, this also builds the
> doc_generated, which draw from non-doc source files, so this would also
> serve to check that those are sound and didn't mess up the docs.

Unfortunately presence of xmllint doesn't guarantee presence of the relevant
DTDs. Without docbook-xml installed, you'll get something like

../../../../../home/andres/src/postgresql/doc/src/sgml/postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
]>
^

and a bunch of other subsequent errors.

I think if we want to do this, we'd need a configure time check for being able
to validate a document with
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"...

That's certainly doable. If we go there, we imo also should check if the
relevant xslt stylesheets are installed.

Greetings,

Andres Freund