Обсуждение: what should install-world do when docs are not available?

Hi,

A question by Justin made me wonder what the right behaviour for world,
install-world should be when the docs tools aren't available. I'm wondering
from the angle of meson, but it also seems something we possibly should think
about for autoconf.

Right now if one does install-world with autoconf, without having xmllint or
xsltproc available, one gets an error:
ERROR: `xmllint' is missing on your system.

Is that good? Should meson behave the same?

I wonder if, for meson, the best behaviour would be to make 'docs' a feature
set to auto. If docs set to enabled, and the necessary tools are not
available, fail at that time, instead of doing so while building.

If that's what we decide to do, perhaps "docs" should be split further? The
dependencies for pdf generation are a lot more heavyweight.


We should probably also generate a useful error when the stylesheets aren't
available. Right now we just generate a long error:

/usr/bin/xsltproc --nonet --path . --stringparam pg.version '16devel'
/home/andres/src/postgresql/doc/src/sgml/stylesheet.xslpostgres-full.xml
 
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
compilation error: file /home/andres/src/postgresql/doc/src/sgml/stylesheet.xsl line 6 element import
xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/common/entities.ent
/home/andres/src/postgresql/doc/src/sgml/stylesheet-html-common.xsl:4: warning: failed to load external entity
"http://docbook.sourceforge.net/release/xsl/current/common/entities.ent"
%common.entities;
                 ^
/home/andres/src/postgresql/doc/src/sgml/stylesheet-html-common.xsl:116: parser error : Entity 'primary' not defined
                          translate(substring(&primary;, 1, 1),
...


Greetings,

Andres Freund

[1] https://www.postgresql.org/message-id/20230325180310.o6drykb3uz4u4x4r%40awork3.anarazel.de

Andres Freund <andres@anarazel.de> writes:
> Right now if one does install-world with autoconf, without having xmllint or
> xsltproc available, one gets an error:
> ERROR: `xmllint' is missing on your system.

> Is that good? Should meson behave the same?

Since install-world is defined to install documentation, it should
do so or fail trying.  Maybe we could skip the xmllint step, but you'd
still need xsltproc so I'm not sure that that moves the bar very far.

> If that's what we decide to do, perhaps "docs" should be split further? The
> dependencies for pdf generation are a lot more heavyweight.

Yeah.  Personally I think "docs" should just build/install the HTML
docs, but maybe I'm too narrow-minded.

> We should probably also generate a useful error when the stylesheets aren't
> available.

Maybe, but we haven't had that in the autoconf case either, and there
have not been too many complaints.  Not sure it's worth putting extra
effort into.

            regards, tom lane

Hi,

On 2023-03-25 16:40:03 -0400, Tom Lane wrote:
> Andres Freund <andres@anarazel.de> writes:
> > Right now if one does install-world with autoconf, without having xmllint or
> > xsltproc available, one gets an error:
> > ERROR: `xmllint' is missing on your system.
>
> > Is that good? Should meson behave the same?
>
> Since install-world is defined to install documentation, it should
> do so or fail trying.  Maybe we could skip the xmllint step, but you'd
> still need xsltproc so I'm not sure that that moves the bar very far.

xmllint is the more commonly installed tool (it's part of libxml, which
libxslt depends on), so that wouldn't help much - and we now depend on xmllint
to build the input to xsltproc anyway...


> > If that's what we decide to do, perhaps "docs" should be split further? The
> > dependencies for pdf generation are a lot more heavyweight.
>
> Yeah.  Personally I think "docs" should just build/install the HTML
> docs, but maybe I'm too narrow-minded.

Sorry, I meant docs as a meson option, not as a build target. The 'docs'
target builds just the html doc (as with autoconf), and install-doc installs
both html and manpages (also as with autoconf).

I am basically wondering if we should make it so that if you say
-Ddocs=enabled and xmllint or xsltproc aren't available, you get an error at
configure time. And if -Ddocs=auto, the summary at the end of configure will
tell you if the necessary tools to build the docs are available, but not error
out.

The extension to that could be to have a separate -Ddoc_pdf option, which'd
mirror the above.

Greetings,

Andres Freund

On 25.03.23 21:14, Andres Freund wrote:
> I wonder if, for meson, the best behaviour would be to make 'docs' a feature
> set to auto. If docs set to enabled, and the necessary tools are not
> available, fail at that time, instead of doing so while building.

Makes sense to me.

> If that's what we decide to do, perhaps "docs" should be split further? The
> dependencies for pdf generation are a lot more heavyweight.

I think "docs" should be html and man, because that's what gets installed.

pdf and other things can just be an ad hoc build target and doesn't need 
install support.

Hi,

On 2023-03-29 18:15:02 +0200, Peter Eisentraut wrote:
> On 25.03.23 21:14, Andres Freund wrote:
> > I wonder if, for meson, the best behaviour would be to make 'docs' a feature
> > set to auto. If docs set to enabled, and the necessary tools are not
> > available, fail at that time, instead of doing so while building.
> 
> Makes sense to me.
> 
> > If that's what we decide to do, perhaps "docs" should be split further? The
> > dependencies for pdf generation are a lot more heavyweight.
> 
> I think "docs" should be html and man, because that's what gets installed.
> 
> pdf and other things can just be an ad hoc build target and doesn't need
> install support.

I just meant for feature detection.

Greetings,

Andres Freund

On 29.03.23 18:25, Andres Freund wrote:
> On 2023-03-29 18:15:02 +0200, Peter Eisentraut wrote:
>> On 25.03.23 21:14, Andres Freund wrote:
>>> I wonder if, for meson, the best behaviour would be to make 'docs' a feature
>>> set to auto. If docs set to enabled, and the necessary tools are not
>>> available, fail at that time, instead of doing so while building.
>>
>> Makes sense to me.
>>
>>> If that's what we decide to do, perhaps "docs" should be split further? The
>>> dependencies for pdf generation are a lot more heavyweight.
>>
>> I think "docs" should be html and man, because that's what gets installed.
>>
>> pdf and other things can just be an ad hoc build target and doesn't need
>> install support.
> 
> I just meant for feature detection.

Ah yes, then things like fop should either be a separate feature or just 
do something light weight, like failing the target if fop isn't there.

Hi,

On 2023-03-29 18:39:27 +0200, Peter Eisentraut wrote:
> On 29.03.23 18:25, Andres Freund wrote:
> > On 2023-03-29 18:15:02 +0200, Peter Eisentraut wrote:
> > > On 25.03.23 21:14, Andres Freund wrote:
> > > > I wonder if, for meson, the best behaviour would be to make 'docs' a feature
> > > > set to auto. If docs set to enabled, and the necessary tools are not
> > > > available, fail at that time, instead of doing so while building.
> > > 
> > > Makes sense to me.
> > > 
> > > > If that's what we decide to do, perhaps "docs" should be split further? The
> > > > dependencies for pdf generation are a lot more heavyweight.
> > > 
> > > I think "docs" should be html and man, because that's what gets installed.
> > > 
> > > pdf and other things can just be an ad hoc build target and doesn't need
> > > install support.
> > 
> > I just meant for feature detection.
> 
> Ah yes, then things like fop should either be a separate feature or just do
> something light weight, like failing the target if fop isn't there.

Attached is an implementation of this approach. This includes some lightly
polished patches from [1] and a new patch to remove htmlhelp.

Greetings,

Andres Freund

[1] https://postgr.es/m/3fc3bb9b-f7f8-d442-35c1-ec82280c564a%40enterprisedb.com

> +        Enables the building of documentation in <acronym>HTML</acronym> and
> +        <acronym>man</acronym> format. It defaults to auto.
> +
> +        Enables the building of documentation in <acronym>PDF</acronym>
> +        format. It defaults to auto.

These sound awkward.  Recommend:

Enables building the documentation in <acronym>PDF</acronym>
format. It defaults to auto.

> +     <varlistentry id="configure-docs-html-style">
> +      <term><option>-Ddocs_html_style={ simple | website }</option></term>
> +      <listitem>
> +        <para>
> +         Influences which <acronym>CSS</acronym> stylesheet is used. If
> +         <literal>website</literal>, instead of the default
> +         <literal>simple</literal>, is used, HTML documentation will use the
> +         stylesheet used on <ulink
> +         url="https://www.postgresql.org/docs/current/">postgresql.org</ulink>.

s/Influences/Controls/

I think the default should be given separately from the description of
the other option.

Controls which <acronym>CSS</acronym> stylesheet is used.
The default is <literal>simple</literal>.
If set to <literal>website</literal>, the HTML documentation will use the
same stylesheet used on <ulink
url="https://www.postgresql.org/docs/current/">postgresql.org</ulink>.

Hi,

On 2023-03-29 17:51:01 -0500, Justin Pryzby wrote:
> > +        Enables the building of documentation in <acronym>HTML</acronym> and
> > +        <acronym>man</acronym> format. It defaults to auto.
> > +
> > +        Enables the building of documentation in <acronym>PDF</acronym>
> > +        format. It defaults to auto.
> 
> These sound awkward.  Recommend:
> 
> Enables building the documentation in <acronym>PDF</acronym>
> format. It defaults to auto.
> 
> > +     <varlistentry id="configure-docs-html-style">
> > +      <term><option>-Ddocs_html_style={ simple | website }</option></term>
> > +      <listitem>
> > +        <para>
> > +         Influences which <acronym>CSS</acronym> stylesheet is used. If
> > +         <literal>website</literal>, instead of the default
> > +         <literal>simple</literal>, is used, HTML documentation will use the
> > +         stylesheet used on <ulink
> > +         url="https://www.postgresql.org/docs/current/">postgresql.org</ulink>.
> 
> s/Influences/Controls/
> 
> I think the default should be given separately from the description of
> the other option.
> 
> Controls which <acronym>CSS</acronym> stylesheet is used.
> The default is <literal>simple</literal>.
> If set to <literal>website</literal>, the HTML documentation will use the
> same stylesheet used on <ulink
> url="https://www.postgresql.org/docs/current/">postgresql.org</ulink>.

Your alternatives are indeed better. Except that "the same" seems a bit
misleading to me, sounding like it could just be a copy. I changed to "will
reference the stylesheet for ...".

Pushed the changes.

Greetings,

Andres Freund

Hi,

On 2023-04-04 21:46:11 -0700, Andres Freund wrote:
> Pushed the changes.

This failed on crake - afaict because the meson buildfarm code disables all
features. Because 'docs' is a feature now, the BF code building
doc/src/sgml/html fails.

Greetings,

Andres Freund

Hi,

On 2023-04-04 21:46:11 -0700, Andres Freund wrote:

Pushed the changes.

This failed on crake - afaict because the meson buildfarm code disables all
features. Because 'docs' is a feature now, the BF code building
doc/src/sgml/html fails.

I changed it so that if the config mandates building docs we add -Ddocs=enabled and if it mandates building a pdf we also add -Ddocs_pdf=enabled. See

<https://github.com/PGBuildFarm/client-code/commit/b18a129f91352f77e67084a758462b92ac1abaf7>

It's a slight pity that you have to pick this at setup time, but I guess the upside is that we don't spend time looking for stuff we're not actually going to use.

cheers

andrew

--
Andrew Dunstan
EDB: https://www.enterprisedb.com

Hi,

On 2023-04-06 14:52:51 -0400, Andrew Dunstan wrote:
> On 2023-04-05 We 00:57, Andres Freund wrote:
> > Hi,
> > 
> > On 2023-04-04 21:46:11 -0700, Andres Freund wrote:
> > > Pushed the changes.
> > This failed on crake - afaict because the meson buildfarm code disables all
> > features. Because 'docs' is a feature now, the BF code building
> > doc/src/sgml/html fails.
> 
> 
> I changed it so that if the config mandates building docs we add
> -Ddocs=enabled and if it mandates building a pdf we also add
> -Ddocs_pdf=enabled. See

Sounds good, thanks!


> <https://github.com/PGBuildFarm/client-code/commit/b18a129f91352f77e67084a758462b92ac1abaf7>
> 
> It's a slight pity that you have to pick this at setup time,

FWIW, you can change options with meson configure -Ddocs=enabled (or whatnot),
in an existing buildtree. It'll rerun configure (with caching). For options
like docs, it won't lead to rebuilding binaries.


> but I guess the upside is that we don't spend time looking for stuff we're
> not actually going to use.

And that you'll learn that tools are missing before you get through most of
the build...

Greetings,

Andres Freund