RE: Improve docs syntax checking and enable it in the meson build

Dear Nazir,

> > 01.
> > I found that postgres core was built when I ran `meson test --suite doc`
> > command, but ideally it's not needed. Per my experiment, we must clarify
> > dependencies for the test, something like below.
> >
> > ```
> > --- a/doc/src/sgml/meson.build
> > +++ b/doc/src/sgml/meson.build
> > @@ -337,7 +337,8 @@ test(
> > 'doc' / 'sgml_syntax_check',
> > meson_bin,
> > args: ['compile', postgres_full_xml_target],
> > - suite: 'doc'
> > + suite: 'doc',
> > + depends: doc_generated,
> > )
> > ```
>
> Sorry, I didn't understand what you meant, could you please elaborate?

Sure. Let's consider the below scenario, that I wanted to just verify the syntax
of documentations. For the autoconf/make build system, below commands can avoid
building C sources and generate needed .sgml files.

```
$ ./configure
...
$ cd doc/src/sgml/
$ make check
{ \
echo "<!ENTITY version \"19devel\">"; \
echo "<!ENTITY majorversion \"19\">"; \
} > version.sgml
'/usr/bin/perl' ./mk_feature_tables.pl YES ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-supported.sgml
'/usr/bin/perl' ./mk_feature_tables.pl NO ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml
'/usr/bin/perl' ./generate-errcodes-table.pl ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml
'/usr/bin/perl' ./generate-keywords-table.pl . > keywords-table.sgml
'/usr/bin/perl' ./generate-targets-meson.pl targets-meson.txt generate-targets-meson.pl > targets-meson.sgml
'/usr/bin/perl' ../../../src/backend/utils/activity/generate-wait_event_types.pl --docs ../../../src/backend/utils/activity/wait_event_names.txt
'/usr/bin/perl' ./sgml_syntax_check.pl --srcdir .
/usr/bin/xmllint --nonet --path . --path . --output postgres-full.xml --noent --valid postgres.sgml
```

In case of meson build system, however, added test was run after all C files
were built. Ideally it is not needed.

```
$ meson setup ../postgres/
...
$ meson test --suite doc
ninja: Entering directory `/home/hayato/builddir'
[884/2468] Compiling C object ... // C sources were built here
...
```

Also, I have been working on a project which translates the documentation [1],
and the syntax check is used for the github CI. I'm very sad if building
everything is needed to just check the doc.

> 'postgres_full_xml_target' target already depends on 'doc_generated'
> and 'sgml_check_stamp' targets.

I'm not faimilar with Meson, but my theory is that Meson cannot understand that
the test only depends on postgres_full_xml. That's why all sources are built.

Based on the discussion, the fix should be like;

```
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -337,7 +337,8 @@ test(
'doc' / 'sgml_syntax_check',
meson_bin,
args: ['compile', postgres_full_xml_target],
- suite: 'doc'
+ suite: 'doc',
+ depends: postgres_full_xml
)
```

[1]: https://github.com/pgsql-jp/jpug-doc

Best regards,
Hayato Kuroda
FUJITSU LIMITED