Re: what should install-world do when docs are not available?

[Andres Freund]

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!


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

Re: what should install-world do when docs are not available?

[Andrew Dunstan]

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




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

Re: what should install-world do when docs are not available?

[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

Re: what should install-world do when docs are not available?

[Andres Freund]

Hi,

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

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

Re: what should install-world do when docs are not available?

[Justin Pryzby]

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

These sound awkward.  Recommend:

Enables building the documentation in PDF
format. It defaults to auto.

> + 
> +  -Ddocs_html_style={ simple | website }
> +  
> +
> + Influences which CSS stylesheet is used. If
> + website, instead of the default
> + simple, is used, HTML documentation will use the
> + stylesheet used on  + 
> url="https://www.postgresql.org/docs/current/";>postgresql.org.

s/Influences/Controls/

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

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

Re: what should install-world do when docs are not available?

[Andres Freund]

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
>From 2ea3b10f37f85aa71edd38253fe2364be8242aa7 Mon Sep 17 00:00:00 2001
From: Andres Freund 
Date: Wed, 29 Mar 2023 12:25:26 -0700
Subject: [PATCH v4 1/6] doc: Remove support for 'htmlhelp' format

We had partial support for generating documentation suitable for .chm
files. However, we only had wired up generating the input files using
docbook-xsl, not generating an actual .chm file. Nor did we document how to do
so.  Additionally, it was very slow to generate htmlhelp, as we never applied
the docbook-xsl stylesheet performance improvements to htmlhelp.

It doesn't look like there's any interest in the htmlhelp output, so remove
it, instead of spending cycles to finish the support.

Discussion: https://postgr.es/m/20230324165822.wcrj3akllbqqu...@awork3.anarazel.de
---
 doc/src/sgml/Makefile  | 10 
 doc/src/sgml/meson.build   | 11 
 doc/src/sgml/stylesheet-hh.xsl | 47 --
 3 files changed, 68 deletions(-)
 delete mode 100644 doc/src/sgml/stylesheet-hh.xsl

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index b96c7cbf223..3c4aa6bebe3 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -148,14 +148,6 @@ html-stamp: stylesheet.xsl postgres-full.xml $(ALL_IMAGES)
 	cp $(srcdir)/stylesheet.css html/
 	touch $@
 
-htmlhelp: htmlhelp-stamp
-
-htmlhelp-stamp: stylesheet-hh.xsl postgres-full.xml $(ALL_IMAGES)
-	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
-	cp $(ALL_IMAGES) htmlhelp/
-	cp $(srcdir)/stylesheet.css htmlhelp/
-	touch $@
-
 # single-page HTML
 postgres.html: stylesheet-html-nochunk.xsl postgres-full.xml $(ALL_IMAGES)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
@@ -307,8 +299,6 @@ clean:
 # generated SGML files
 	rm -f $(GENERATED_SGML)
 	rm -f postgres-full.xml
-# HTML Help
-	rm -rf htmlhelp/ htmlhelp-stamp
 # EPUB
 	rm -f postgres.epub
 # Texinfo
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 157b8589e55..52237dc5ac9 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -135,17 +135,6 @@ if xsltproc_bin.found()
   installdocs += install_doc_html
 
 
-  htmlhelp = custom_target('htmlhelp',
-input: ['stylesheet-hh.xsl', postgres_full_xml],
-output: 'htmlhelp',
-depfile: 'htmlhelp.d',
-depends: doc_generated,
-command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
-build_by_default: false,
-  )
-  alldocs += htmlhelp
-
-
   # single-page HTML
   postgres_html = custom_target('postgres.html',
 input: ['stylesheet-html-nochunk.xsl', postgres_full_xml],
diff --git a/doc/src/sgml/stylesheet-hh.xsl b/doc/src/sgml/stylesheet-hh.xsl
deleted file mode 100644
index 6f4b706dac6..000
--- a/doc/src/sgml/stylesheet-hh.xsl
+++ /dev/null
@@ -1,47 +0,0 @@
-
-http://www.w3.org/1999/XSL/Transform";
-version='1.0'>
-
-http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl"/>
-
-
-
-
-
-
-
-
-
-
-
-
-pgsql-d...@lists.postgresql.org
-
-
-
-
-
-
-
-  
-
-
-
-
-
-  
-
-
-  
-
-
-
-
-
- 
-
-
-
-- 
2.38.0

>From 011e9e08d97e93888928751b0e4b31f9e6ff7206 Mon Sep 17 00:00:00 2001
From: Andres Freund 
Date: Wed, 29 Mar 2023 14:51:38 -0700
Subject: [PATCH v4 2/6] meson: docs: Preparatory cleanups

---
 doc/src/sgml/meson.build | 40 +++-
 1 file changed, 23 insertions(+), 17 deletions(-)

diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 52237dc5ac9..66c0061e96b 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -97,26 +97,32 @@ docs += postgres_full_xml
 alldocs += postgres_full_xml
 
 
-#
-# Fu

Re: what should install-world do when docs are not available?

[Peter Eisentraut]

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.

Re: what should install-world do when docs are not available?

[Andres Freund]

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

Re: what should install-world do when docs are not available?

[Peter Eisentraut]

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.

Re: what should install-world do when docs are not available?

[Andres Freund]

Hi,

On 2023-03-25 16:40:03 -0400, Tom Lane wrote:
> Andres Freund  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

Re: what should install-world do when docs are not available?

[Tom Lane]

Andres Freund  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

what should install-world do when docs are not available?

[Andres Freund]

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.xsl postgres-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