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 <and...@anarazel.de>
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..00000000000
--- a/doc/src/sgml/stylesheet-hh.xsl
+++ /dev/null
@@ -1,47 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
- version='1.0'>
-
-<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl"/>
-<xsl:include href="stylesheet-common.xsl" />
-
-<!-- Parameters -->
-<xsl:param name="htmlhelp.use.hhk" select="'1'"/>
-
-<xsl:param name="base.dir" select="'htmlhelp/'"></xsl:param>
-<xsl:param name="html.stylesheet" select="'stylesheet.css'"></xsl:param>
-<xsl:param name="use.id.as.filename" select="'1'"></xsl:param>
-<xsl:param name="manifest.in.base.dir" select="1"/>
-<xsl:param name="make.valid.html" select="1"></xsl:param>
-<xsl:param name="generate.id.attributes" select="1"></xsl:param>
-<xsl:param name="generate.legalnotice.link" select="1"></xsl:param>
-<xsl:param name="link.mailto.url">pgsql-d...@lists.postgresql.org</xsl:param>
-<xsl:param name="chunker.output.indent" select="'yes'"/>
-<xsl:param name="chunk.quietly" select="1"></xsl:param>
-
-
-<!-- Change display of some elements -->
-
-<xsl:template match="command">
- <xsl:call-template name="inline.monoseq"/>
-</xsl:template>
-
-<!--
- Format multiple terms in varlistentry vertically, instead
- of comma-separated.
- -->
-
-<xsl:template match="varlistentry/term[position()!=last()]">
- <span class="term">
- <xsl:call-template name="anchor"/>
- <xsl:apply-templates/>
- </span><br/>
-</xsl:template>
-
-
-<!-- strip directory name from image filerefs -->
-<xsl:template match="imagedata/@fileref">
- <xsl:value-of select="substring-after(., '/')"/>
-</xsl:template>
-
-</xsl:stylesheet>
--
2.38.0
>From 011e9e08d97e93888928751b0e4b31f9e6ff7206 Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
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
-#
-# Full documentation as html, text
-#
if xsltproc_bin.found()
xsltproc_flags = [
'--nonet',
'--stringparam', 'pg.version', pg_version,
- '--param', 'website.stylesheet', '1'
+ '--path', '@OUTDIR@',
]
xsltproc = xmltools_wrapper + [
'--tool', xsltproc_bin, '--',
]
+endif
+
+
+#
+# Full documentation as html, text
+#
+if xsltproc_bin.found()
+ xsltproc_html_flags = xsltproc_flags + [
+ '--param', 'website.stylesheet', '1'
+ ]
html = custom_target('html',
input: ['stylesheet.xsl', postgres_full_xml],
output: 'html',
depfile: 'html.d',
- depends: doc_generated,
- command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_html_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += html
@@ -140,8 +146,7 @@ if xsltproc_bin.found()
input: ['stylesheet-html-nochunk.xsl', postgres_full_xml],
output: 'postgres.html',
depfile: 'postgres.html.d',
- depends: doc_generated,
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTPUT@', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTPUT@', xsltproc_html_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += postgres_html
@@ -151,7 +156,6 @@ if xsltproc_bin.found()
postgres_txt = custom_target('postgres.txt',
input: [postgres_html],
output: 'postgres.txt',
- depends: doc_generated,
command: [pandoc, '-t', 'plain', '-o', '@OUTPUT@', '@INPUT@'],
build_by_default: false,
)
@@ -164,19 +168,21 @@ endif
# INSTALL in html, text
#
if xsltproc_bin.found()
+ # Depend on postgres_full_xml, so validity errors are raised in one place,
+ # and so dependencies don't need to be re-specified.
install_xml = custom_target('INSTALL.xml',
input: ['standalone-profile.xsl', 'standalone-install.xml'],
output: 'INSTALL.xml',
depfile: 'INSTALL.xml.d',
- depends: doc_generated + [postgres_full_xml],
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTPUT@', xsltproc_flags, '--xinclude', '@INPUT@'],
+ depends: postgres_full_xml,
+ command: [xsltproc, '-o', '@OUTPUT@', xsltproc_flags, '--xinclude', '@INPUT@'],
build_by_default: false,
)
install_html = custom_target('INSTALL.html',
input: ['stylesheet-text.xsl', install_xml],
output: 'INSTALL.html',
depfile: 'INSTALL.html.d',
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTPUT@', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTPUT@', xsltproc_html_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += install_html
@@ -204,8 +210,7 @@ if xsltproc_bin.found()
input: ['stylesheet-man.xsl', postgres_full_xml],
output: ['man1', 'man3', 'man7'],
depfile: 'man.d',
- depends: doc_generated,
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_html_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += man
@@ -229,7 +234,9 @@ endif
# Full documentation as PDF
#
if fop.found() and xsltproc_bin.found()
- xsltproc_fo_flags = xsltproc_flags + ['--stringparam', 'img.src.path', meson.current_source_dir() + '/']
+ xsltproc_fo_flags = xsltproc_flags + [
+ '--stringparam', 'img.src.path', meson.current_source_dir() + '/'
+ ]
foreach format, detail: {'A4': 'A4', 'US': 'USletter'}
postgres_x_fo_f = 'postgres-@0@.fo'.format(format)
@@ -239,9 +246,8 @@ if fop.found() and xsltproc_bin.found()
postgres_x_fo = custom_target(postgres_x_fo_f,
input: ['stylesheet-fo.xsl', postgres_full_xml],
output: postgres_x_fo_f,
- depends: doc_generated,
depfile: postgres_x_fo_dep,
- command: [xsltproc, '--path', '@OUTDIR@/', xsltproc_fo_flags,
+ command: [xsltproc, xsltproc_fo_flags,
'--stringparam', 'paper.type', detail,
'-o', '@OUTPUT@', '@INPUT@'],
build_by_default: false,
--
2.38.0
>From c0f61809faa86228b958f8b7e12d0d98faae3c4c Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Wed, 29 Mar 2023 15:33:49 -0700
Subject: [PATCH v4 3/6] meson: add docs, docs_pdf options
---
meson.build | 37 ++++++++++++++++++++++++++++++++++
meson_options.txt | 9 +++++++++
doc/src/sgml/installation.sgml | 33 ++++++++++++++++++++++++++++++
doc/src/sgml/meson.build | 21 ++++++-------------
4 files changed, 85 insertions(+), 15 deletions(-)
diff --git a/meson.build b/meson.build
index 61e94be8641..1f2ec448684 100644
--- a/meson.build
+++ b/meson.build
@@ -341,6 +341,8 @@ program_zstd = find_program(get_option('ZSTD'), native: true, required: false)
dtrace = find_program(get_option('DTRACE'), native: true, required: get_option('dtrace'))
missing = find_program('config/missing', native: true)
cp = find_program('cp', required: false, native: true)
+xmllint_bin = find_program(get_option('XMLLINT'), native: true, required: false)
+xsltproc_bin = find_program(get_option('XSLTPROC'), native: true, required: false)
bison_flags = []
if bison.found()
@@ -567,6 +569,39 @@ endif
+###############################################################
+# Option: docs in HTML and man page format
+###############################################################
+
+docs_opt = get_option('docs')
+docs_dep = not_found_dep
+if not docs_opt.disabled()
+ if xmllint_bin.found() and xsltproc_bin.found()
+ docs_dep = declare_dependency()
+ elif docs_opt.enabled()
+ error('missing required tools for docs in HTML / man page format')
+ endif
+endif
+
+
+
+###############################################################
+# Option: docs in PDF format
+###############################################################
+
+docs_pdf_opt = get_option('docs_pdf')
+docs_pdf_dep = not_found_dep
+if not docs_pdf_opt.disabled()
+ fop = find_program(get_option('FOP'), native: true, required: docs_pdf_opt)
+ if xmllint_bin.found() and xsltproc_bin.found() and fop.found()
+ docs_pdf_dep = declare_dependency()
+ elif docs_pdf_opt.enabled()
+ error('missing required tools for docs in PDF format')
+ endif
+endif
+
+
+
###############################################################
# Library: GSSAPI
###############################################################
@@ -3322,6 +3357,8 @@ if meson.version().version_compare('>=0.57')
{
'bonjour': bonjour,
'bsd_auth': bsd_auth,
+ 'docs': docs_dep,
+ 'docs_pdf': docs_pdf_dep,
'gss': gssapi,
'icu': icu,
'ldap': ldap,
diff --git a/meson_options.txt b/meson_options.txt
index 4402dd4299d..c203dcce6fe 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -79,6 +79,12 @@ option('bonjour', type : 'feature', value: 'auto',
option('bsd_auth', type : 'feature', value: 'auto',
description: 'build with BSD Authentication support')
+option('docs', type : 'feature', value: 'auto',
+ description: 'documentation in HTML and man page format')
+
+option('docs_pdf', type : 'feature', value: 'auto',
+ description: 'documentation in PDF format')
+
option('dtrace', type : 'feature', value: 'disabled',
description: 'DTrace support')
@@ -159,6 +165,9 @@ option('DTRACE', type : 'string', value: 'dtrace',
option('FLEX', type : 'array', value: ['flex', 'win_flex'],
description: 'path to flex binary')
+option('FOP', type : 'string', value: 'fop',
+ description: 'path to fop binary')
+
option('GZIP', type : 'string', value: 'gzip',
description: 'path to gzip binary')
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 70ab5b77d86..8b87a274fcb 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -2893,6 +2893,39 @@ ninja install
</variablelist>
</sect3>
+ <sect3 id="meson-options-docs">
+ <title>Documentation</title>
+
+ <para>
+ See <xref linkend="docguide-toolsets"/> for the tools needed for building
+ the documentation.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-docs-meson">
+ <term><option>-Ddocs={ auto | enabled | disabled }</option></term>
+ <listitem>
+ <para>
+ Enables the building of documentation in <acronym>HTML</acronym> and
+ <acronym>man</acronym> format. It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-docs-pdf-meson">
+ <term><option>-Ddocs_pdf={ auto | enabled | disabled }</option></term>
+ <listitem>
+ <para>
+ Enables the building of documentation in <acronym>PDF</acronym>
+ format. It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
<sect3 id="meson-options-misc">
<title>Miscellaneous</title>
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 66c0061e96b..7719adfc73b 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -5,9 +5,6 @@ installdocs = []
alldocs = []
doc_generated = []
-xmllint_bin = find_program(get_option('XMLLINT'), native: true, required: false)
-
-
version_sgml = configure_file(
input: 'version.sgml.in',
output: 'version.sgml',
@@ -68,8 +65,6 @@ if not xmllint_bin.found()
endif
pandoc = find_program('pandoc', native: true, required: false)
-xsltproc_bin = find_program(get_option('XSLTPROC'), native: true, required: false)
-fop = find_program('fop', native: true, required: false)
xmltools_wrapper = [
python, files('xmltools_dep_wrapper'),
@@ -113,7 +108,7 @@ endif
#
# Full documentation as html, text
#
-if xsltproc_bin.found()
+if docs_dep.found()
xsltproc_html_flags = xsltproc_flags + [
'--param', 'website.stylesheet', '1'
]
@@ -204,7 +199,7 @@ endif
#
# Man pages
#
-if xsltproc_bin.found()
+if docs_dep.found()
# FIXME: implement / consider sqlmansectnum logic
man = custom_target('man',
input: ['stylesheet-man.xsl', postgres_full_xml],
@@ -233,7 +228,7 @@ endif
#
# Full documentation as PDF
#
-if fop.found() and xsltproc_bin.found()
+if docs_pdf_dep.found()
xsltproc_fo_flags = xsltproc_flags + [
'--stringparam', 'img.src.path', meson.current_source_dir() + '/'
]
@@ -291,7 +286,7 @@ db2x_xsltproc = find_program('db2x_xsltproc', native: true, required: false)
db2x_texixml = find_program('db2x_texixml', native: true, required: false)
makeinfo = find_program('makeinfo', native: true, required: false)
-if db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
+if xsltproc_bin.found() and db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
postgres_texixml = custom_target('postgres.texixml',
output: 'postgres.texixml',
command: [db2x_xsltproc, '-s', 'texi',
@@ -315,15 +310,11 @@ if db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
endif
-if docs.length() == 0
- run_target('docs', command: [missing, 'xsltproc'])
-else
+if docs_dep.found()
alias_target('docs', docs)
alias_target('install-docs', installdocs)
endif
-if alldocs.length() == 0
- run_target('alldocs', command: [missing, 'xsltproc'])
-else
+if alldocs.length() != 0
alias_target('alldocs', alldocs)
endif
--
2.38.0
>From cad43f9fcc130a8f3c5f6f80601a470536cd7449 Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Wed, 15 Mar 2023 16:45:14 -0700
Subject: [PATCH v4 4/6] docs: html: copy images to output as part of xslt
build
---
doc/src/sgml/Makefile | 1 -
doc/src/sgml/stylesheet-common.xsl | 22 ++++++++++++++++++++++
doc/src/sgml/stylesheet.xsl | 6 ++++++
3 files changed, 28 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 3c4aa6bebe3..11ecdaf717e 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -144,7 +144,6 @@ html: html-stamp
html-stamp: stylesheet.xsl postgres-full.xml $(ALL_IMAGES)
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
- cp $(ALL_IMAGES) html/
cp $(srcdir)/stylesheet.css html/
touch $@
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index 761484c7fef..d2928f86eb7 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -101,4 +101,26 @@
<xsl:apply-templates select="." mode="xref"/>
</xsl:template>
+
+<!--
+ Support for copying images to the output directory, so the output is self
+ contained.
+-->
+<xsl:template name="write-image">
+ <xsl:variable name="input_filename">
+ <xsl:value-of select="imagedata/@fileref"/>
+ </xsl:variable>
+
+ <!-- references images directly, without images/ -->
+ <xsl:variable name="output_filename">
+ <xsl:value-of select="concat($chunk.base.dir, substring-after($input_filename, '/'))"/>
+ </xsl:variable>
+
+ <xsl:call-template name="write.chunk">
+ <xsl:with-param name="filename" select="$output_filename"/>
+ <xsl:with-param name="content" select="document($input_filename)"/>
+ </xsl:call-template>
+</xsl:template>
+
+
</xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index b6141303abd..c492dc38e54 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -29,6 +29,12 @@
</xsl:param>
+<!-- copy images to the output directory, so the output is self contained -->
+<xsl:template match="imageobject">
+ <xsl:call-template name="write-image"/>
+ <xsl:apply-templates select="imagedata"/>
+</xsl:template>
+
<!-- strip directory name from image filerefs -->
<xsl:template match="imagedata/@fileref">
<xsl:value-of select="substring-after(., '/')"/>
--
2.38.0
>From f463fec1b519938ed77276c5a5eeaf3e1f940f0d Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Wed, 29 Mar 2023 15:34:21 -0700
Subject: [PATCH v4 5/6] docs: load stylesheet via custom.css.source
---
doc/src/sgml/Makefile | 3 +--
doc/src/sgml/meson.build | 2 +-
doc/src/sgml/stylesheet-html-common.xsl | 8 ++++++++
doc/src/sgml/stylesheet-html-nochunk.xsl | 3 +++
doc/src/sgml/stylesheet.css.xml | 8 ++++++++
doc/src/sgml/stylesheet.xsl | 11 -----------
6 files changed, 21 insertions(+), 14 deletions(-)
create mode 100644 doc/src/sgml/stylesheet.css.xml
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 11ecdaf717e..71cbef230f3 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -39,7 +39,7 @@ ifndef FOP
FOP = $(missing) fop
endif
-XMLINCLUDE = --path .
+XMLINCLUDE = --path . --path $(srcdir)
ifdef XMLLINT
XMLLINT := $(XMLLINT) --nonet
@@ -144,7 +144,6 @@ html: html-stamp
html-stamp: stylesheet.xsl postgres-full.xml $(ALL_IMAGES)
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
- cp $(srcdir)/stylesheet.css html/
touch $@
# single-page HTML
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 7719adfc73b..19531ebbcc7 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -96,7 +96,7 @@ if xsltproc_bin.found()
xsltproc_flags = [
'--nonet',
'--stringparam', 'pg.version', pg_version,
- '--path', '@OUTDIR@',
+ '--path', '@OUTDIR@', '--path', '@CURRENT_SOURCE_DIR@',
]
xsltproc = xmltools_wrapper + [
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index 9df2782ce4f..bb6429ef7cf 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -18,6 +18,14 @@
<xsl:param name="make.graphic.viewport" select="0"/>
<xsl:param name="link.mailto.url">pgsql-d...@lists.postgresql.org</xsl:param>
<xsl:param name="toc.max.depth">2</xsl:param>
+<xsl:param name="website.stylesheet" select="0"/>
+<xsl:param name="custom.css.source">
+ <xsl:if test="$website.stylesheet = 0">stylesheet.css.xml</xsl:if>
+</xsl:param>
+<xsl:param name="html.stylesheet">
+ <xsl:if test="not($website.stylesheet = 0)">https://www.postgresql.org/media/css/docs-complete.css</xsl:if>
+</xsl:param>
+
<!--
The below allows the stylesheets provided by the website to be applied fully
diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl
index 8167127b93a..5a0bb4ea08f 100644
--- a/doc/src/sgml/stylesheet-html-nochunk.xsl
+++ b/doc/src/sgml/stylesheet-html-nochunk.xsl
@@ -7,6 +7,9 @@
<xsl:include href="stylesheet-html-common.xsl" />
<xsl:include href="stylesheet-speedup-xhtml.xsl" />
+<!-- except when referencing the online stylesheet, embed stylesheet -->
+<xsl:param name="generate.css.header" select="$website.stylesheet = 0"/>
+
<!-- embed SVG images into output file -->
<xsl:template match="imagedata[@format='SVG']">
<xsl:variable name="filename">
diff --git a/doc/src/sgml/stylesheet.css.xml b/doc/src/sgml/stylesheet.css.xml
new file mode 100644
index 00000000000..a21fcca576f
--- /dev/null
+++ b/doc/src/sgml/stylesheet.css.xml
@@ -0,0 +1,8 @@
+<!--
+ wrapper around stylesheet.css.xml to allow it to be loaded via docbook-xsl's
+ generate.css.header parameter.
+-->
+<!DOCTYPE style [
+<!ENTITY css SYSTEM "stylesheet.css">
+]>
+<style>&css;</style>
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index c492dc38e54..363cc93e6b0 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -17,17 +17,6 @@
<xsl:param name="chunk.quietly" select="1"></xsl:param>
<xsl:param name="admon.style"></xsl:param> <!-- handled by CSS stylesheet -->
-<xsl:param name="website.stylesheet" select="0"/>
-
-<xsl:param name="html.stylesheet">
- <xsl:choose>
- <xsl:when test="$website.stylesheet = 0">stylesheet.css</xsl:when>
- <xsl:otherwise>
- https://www.postgresql.org/media/css/docs-complete.css
- </xsl:otherwise>
- </xsl:choose>
-</xsl:param>
-
<!-- copy images to the output directory, so the output is self contained -->
<xsl:template match="imageobject">
--
2.38.0
>From 049af2a9375ad6c0f91bff21bef70b84f84cf523 Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Wed, 29 Mar 2023 15:24:30 -0700
Subject: [PATCH v4 6/6] meson: docs: Allow configuring simple/website style
Discussion: https://postgr.es/m/
---
meson_options.txt | 3 +++
doc/src/sgml/installation.sgml | 13 +++++++++++++
doc/src/sgml/meson.build | 7 ++++---
3 files changed, 20 insertions(+), 3 deletions(-)
diff --git a/meson_options.txt b/meson_options.txt
index c203dcce6fe..5b44a8829d3 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -85,6 +85,9 @@ option('docs', type : 'feature', value: 'auto',
option('docs_pdf', type : 'feature', value: 'auto',
description: 'documentation in PDF format')
+option('docs_html_style', type : 'combo', choices: ['simple', 'website'],
+ description: 'CSS stylesheet for HTML documentation')
+
option('dtrace', type : 'feature', value: 'disabled',
description: 'DTrace support')
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 8b87a274fcb..29d4d3b74df 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -2923,6 +2923,19 @@ ninja install
</listitem>
</varlistentry>
+ <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>.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect3>
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 19531ebbcc7..e9506acc5bb 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -109,9 +109,10 @@ endif
# Full documentation as html, text
#
if docs_dep.found()
- xsltproc_html_flags = xsltproc_flags + [
- '--param', 'website.stylesheet', '1'
- ]
+ xsltproc_html_flags = xsltproc_flags
+ if get_option('docs_html_style') == 'website'
+ xsltproc_html_flags += ['--param', 'website.stylesheet', '1']
+ endif
html = custom_target('html',
input: ['stylesheet.xsl', postgres_full_xml],
--
2.38.0
