Hi,
On 2023-03-22 11:59:17 -0700, Andres Freund wrote:
> Unless somebody sees a reason to wait, I am planning to commit:
> meson: add install-{quiet, world} targets
> meson: add install-{docs,doc-html,doc-man} targets
> meson: make install_test_files more generic, rename to install_files
I've done that now.
> For the .css: docbook-xsl actually has support for writing the .css: [1] - but
> it requires the .css file be valid xml. I wonder if the cleanest approch would
> be to have a build step to create .css.xml - then the non-chunked build's
> generate.css.header would do the right thing.
We don't even need to do that! The attached patch just creates a wrapper
css.xml that loads the .css via an entity reference.
I think this looks reasonably complicated, given that it gives us a working
stylesheet for the non-chunked output?
I don't know if my hack of putting the paramters in stylesheet-common.xsl is
reasonable. Perhaps we should just include stylesheet-html-common.xsl in
stylesheet-hh.xsl, then this uglyness wouldn't be required.
Greetings,
Andres Freund
>From e7145805c25c0f1af983268882107f1557b67d44 Mon Sep 17 00:00:00 2001
From: Andres Freund <[email protected]>
Date: Wed, 15 Mar 2023 16:45:14 -0700
Subject: [PATCH v3 1/4] docs: html: copy images to output as part of xslt
build
---
doc/src/sgml/Makefile | 2 --
doc/src/sgml/stylesheet-common.xsl | 22 ++++++++++++++++++++++
doc/src/sgml/stylesheet-hh.xsl | 6 ++++++
doc/src/sgml/stylesheet.xsl | 7 ++++++-
4 files changed, 34 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index b96c7cbf223..1b098f983ec 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 $@
@@ -152,7 +151,6 @@ 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 $@
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-hh.xsl b/doc/src/sgml/stylesheet-hh.xsl
index 6f4b706dac6..568ccf36d2a 100644
--- a/doc/src/sgml/stylesheet-hh.xsl
+++ b/doc/src/sgml/stylesheet-hh.xsl
@@ -39,6 +39,12 @@
</xsl:template>
+<xsl:template match="imageobject">
+ <xsl:call-template name="write-image"/>
+ <!-- copy images to the output directory, so the output is self contained -->
+ <xsl:apply-templates select="imagedata"/>
+</xsl:template>
+
<!-- strip directory name from image filerefs -->
<xsl:template match="imagedata/@fileref">
<xsl:value-of select="substring-after(., '/')"/>
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index b6141303abd..f9163e7d946 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -29,7 +29,12 @@
</xsl:param>
-<!-- strip directory name from image filerefs -->
+<xsl:template match="imageobject">
+ <xsl:call-template name="write-image"/>
+ <!-- copy images to the output directory, so the output is self contained -->
+ <xsl:apply-templates select="imagedata"/>
+</xsl:template>
+
<xsl:template match="imagedata/@fileref">
<xsl:value-of select="substring-after(., '/')"/>
</xsl:template>
--
2.38.0
>From fdd771319069322383e144eba68f07f2c305abc1 Mon Sep 17 00:00:00 2001
From: Andres Freund <[email protected]>
Date: Fri, 24 Mar 2023 00:13:53 -0700
Subject: [PATCH v3 2/4] docs: load stylesheet via custom.css.source
---
doc/src/sgml/Makefile | 4 +---
doc/src/sgml/meson.build | 12 ++++++------
doc/src/sgml/stylesheet-common.xsl | 14 ++++++++++++++
doc/src/sgml/stylesheet-hh.xsl | 1 -
doc/src/sgml/stylesheet-html-nochunk.xsl | 3 +++
doc/src/sgml/stylesheet.css.xml | 8 ++++++++
doc/src/sgml/stylesheet.xsl | 11 -----------
7 files changed, 32 insertions(+), 21 deletions(-)
create mode 100644 doc/src/sgml/stylesheet.css.xml
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 1b098f983ec..9be480613b4 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,14 +144,12 @@ 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 $@
htmlhelp: htmlhelp-stamp
htmlhelp-stamp: stylesheet-hh.xsl postgres-full.xml $(ALL_IMAGES)
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
- cp $(srcdir)/stylesheet.css htmlhelp/
touch $@
# single-page HTML
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 157b8589e55..d9c46224dc9 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -104,7 +104,7 @@ if xsltproc_bin.found()
xsltproc_flags = [
'--nonet',
'--stringparam', 'pg.version', pg_version,
- '--param', 'website.stylesheet', '1'
+ '--path', '@CURRENT_SOURCE_DIR@', '--path', '@OUTDIR@',
]
xsltproc = xmltools_wrapper + [
@@ -140,7 +140,7 @@ if xsltproc_bin.found()
output: 'htmlhelp',
depfile: 'htmlhelp.d',
depends: doc_generated,
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += htmlhelp
@@ -152,7 +152,7 @@ if xsltproc_bin.found()
output: 'postgres.html',
depfile: 'postgres.html.d',
depends: doc_generated,
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTPUT@', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTPUT@', xsltproc_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += postgres_html
@@ -180,14 +180,14 @@ if xsltproc_bin.found()
output: 'INSTALL.xml',
depfile: 'INSTALL.xml.d',
depends: doc_generated + [postgres_full_xml],
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTPUT@', xsltproc_flags, '--xinclude', '@INPUT@'],
+ 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_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += install_html
@@ -216,7 +216,7 @@ if xsltproc_bin.found()
output: ['man1', 'man3', 'man7'],
depfile: 'man.d',
depends: doc_generated,
- command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
+ command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
build_by_default: false,
)
alldocs += man
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index d2928f86eb7..c1a7d46bcc6 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -42,6 +42,20 @@
<xsl:param name="variablelist.term.separator"></xsl:param>
<xsl:param name="xref.with.number.and.title" select="0"></xsl:param>
+<!--
+ currently htmlhelp and "normal" html have no common stylesheet, so this is
+ implemented here
+-->
+<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.xml</xsl:if>
+</xsl:param>
+
<!-- Change display of some elements -->
diff --git a/doc/src/sgml/stylesheet-hh.xsl b/doc/src/sgml/stylesheet-hh.xsl
index 568ccf36d2a..fb659d2ec38 100644
--- a/doc/src/sgml/stylesheet-hh.xsl
+++ b/doc/src/sgml/stylesheet-hh.xsl
@@ -9,7 +9,6 @@
<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>
diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl
index 8167127b93a..fae8d5fbd96 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" />
+<!-- embed stylesheet.css if using that -->
+<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 f9163e7d946..65606ca3dbe 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>
-
<xsl:template match="imageobject">
<xsl:call-template name="write-image"/>
--
2.38.0
>From 4a220cc1bf79e19e9cb5e94d8a650123a0347bb4 Mon Sep 17 00:00:00 2001
From: Andres Freund <[email protected]>
Date: Sun, 19 Mar 2023 11:11:37 -0700
Subject: [PATCH v3 3/4] docs: speed up docs build by special-casing the
gentext.template
---
doc/src/sgml/stylesheet-speedup-common.xsl | 79 ++++++++++++++++++++++
1 file changed, 79 insertions(+)
diff --git a/doc/src/sgml/stylesheet-speedup-common.xsl b/doc/src/sgml/stylesheet-speedup-common.xsl
index e3fb582a1cc..5266ff587b9 100644
--- a/doc/src/sgml/stylesheet-speedup-common.xsl
+++ b/doc/src/sgml/stylesheet-speedup-common.xsl
@@ -96,5 +96,84 @@
<!-- Just hardcode the language for the whole document, to make it faster. -->
<xsl:template name="l10n.language">en</xsl:template>
+<xsl:param name='pg.l10n.xml' select="document('file:///usr/share/xml/docbook/stylesheet/docbook-xsl/common/en.xml')[1]"/>
+
+<xsl:template name="gentext.template.recurse">
+ <xsl:param name="context"/>
+ <xsl:param name="name"/>
+ <xsl:param name="origname"/>
+ <xsl:param name="verbose"/>
+
+
+ <xsl:choose>
+ <xsl:when test="contains($name, '/')">
+ <xsl:call-template name="gentext.template.recurse">
+ <xsl:with-param name="context" select="$context"/>
+ <xsl:with-param name="name" select="substring-after($name, '/')"/>
+ <xsl:with-param name="origname" select="$origname"/>
+ <xsl:with-param name="verbose" select="$verbose"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+
+ <!-- FIXME: should find a way to avoid the concat and [1] here -->
+ <xsl:variable name="template.node"
+ select="key('l10n-template', concat($context, '#', $name))[1]"/>
+
+ <xsl:choose>
+ <xsl:when test="$template.node/@text">
+ <xsl:value-of select="$template.node/@text"/>
+ </xsl:when>
+ <xsl:when test="$verbose = 0">
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:message>
+ <xsl:text>No template for "</xsl:text>
+ <xsl:value-of select="$origname"/>
+ <xsl:text>" (or any of its leaves) exists in the context named "</xsl:text>
+ <xsl:value-of select="$context"/>
+ <xsl:text>" in the "</xsl:text>
+ <xsl:text>" en localization.</xsl:text>
+ </xsl:message>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:template>
+
+
+<xsl:template name="gentext.template">
+ <xsl:param name="context" select="'default'"/>
+ <xsl:param name="name" select="'default'"/>
+ <xsl:param name="origname" select="$name"/>
+ <xsl:param name="lang" select="'en'"/>
+ <xsl:param name="verbose" select="1"/>
+
+ <!-- FIXME: unnecessary recursion for leading -->
+ <xsl:for-each select="$pg.l10n.xml">
+ <xsl:variable name="context.node"
+ select="key('l10n-context', $context)[1]"/>
+
+ <xsl:if test="count($context.node) = 0
+ and $verbose != 0">
+ <xsl:message>
+ <xsl:text>No context named "</xsl:text>
+ <xsl:value-of select="$context"/>
+ <xsl:text>" exists in the "</xsl:text>
+ <xsl:value-of select="$lang"/>
+ <xsl:text>" localization.</xsl:text>
+ </xsl:message>
+ </xsl:if>
+
+ <xsl:for-each select="$context.node">
+ <xsl:call-template name="gentext.template.recurse">
+ <xsl:with-param name="context" select="$context"/>
+ <xsl:with-param name="name" select="$name"/>
+ <xsl:with-param name="origname" select="$origname"/>
+ <xsl:with-param name="verbose" select="$verbose"/>
+ </xsl:call-template>
+ </xsl:for-each>
+ </xsl:for-each>
+</xsl:template>
</xsl:stylesheet>
--
2.38.0
>From 37c880b04e13efa36b67832c647255ee80e726bd Mon Sep 17 00:00:00 2001
From: Andres Freund <[email protected]>
Date: Sun, 19 Mar 2023 19:29:41 -0700
Subject: [PATCH v3 4/4] VERY WIP: parallel doc generation
---
doc/src/sgml/meson.build | 17 +++++++++++
doc/src/sgml/postgres.sgml | 2 +-
doc/src/sgml/stylesheet.xsl | 49 +++++++++++++++++++++++++++++++
doc/src/sgml/xmltools_dep_wrapper | 5 ++++
4 files changed, 72 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index d9c46224dc9..c6195965a71 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -121,6 +121,23 @@ if xsltproc_bin.found()
)
alldocs += html
+ parts = ['bookinfo', 'preface', 'tutorial', 'sql', 'admin', 'client-interfaces', 'server-programming', 'reference', 'internals', 'appendixes', 'biblio', 'bookindex']
+ html_parts = []
+ foreach part : parts
+ html_parts += custom_target('html-@0@'.format(part),
+ input: ['stylesheet.xsl', postgres_full_xml],
+ output: 'html-stamp-@0@'.format(part),
+ depfile: 'html.d',
+ depends: doc_generated,
+ command: [
+ xmltools_wrapper, '--tool', xsltproc_bin, '--stamp', '@OUTPUT0@', '--',
+ '-o', '@OUTDIR@/', xsltproc_flags, '--stringparam', 'rootid', part, '@INPUT@',
+ ],
+ build_by_default: false,
+ )
+ endforeach
+ alias_target('html-parts', html_parts)
+
install_doc_html = custom_target('install-html',
output: 'install-html',
command: [
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 2e271862fc1..a169fd6f30a 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -23,7 +23,7 @@ break is not needed in a wider output rendering.
<book id="postgres">
<title>PostgreSQL &version; Documentation</title>
- <bookinfo>
+ <bookinfo id="bookinfo">
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
<productname>PostgreSQL</productname>
<productnumber>&version;</productnumber>
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 65606ca3dbe..f9986d17f4a 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -28,6 +28,55 @@
<xsl:value-of select="substring-after(., '/')"/>
</xsl:template>
+<!-- Emit index.html and legalnotice.html -->
+<xsl:template name="pg.write.bookinfo">
+ <xsl:for-each select="/book">
+ <xsl:call-template name="process-chunk">
+ <xsl:with-param name="prev" select="/dontexist"/>
+ <xsl:with-param name="next" select="preface"/>
+ <xsl:with-param name="content">
+
+ <div>
+ <xsl:apply-templates select="." mode="common.html.attributes"/>
+ <xsl:call-template name="id.attribute">
+ <xsl:with-param name="conditional" select="0"/>
+ </xsl:call-template>
+
+ <xsl:call-template name="book.titlepage"/>
+
+ <xsl:apply-templates select="dedication" mode="dedication"/>
+ <xsl:apply-templates select="acknowledgements" mode="acknowledgements"/>
+
+ <xsl:variable name="toc.params">
+ <xsl:call-template name="find.path.params">
+ <xsl:with-param name="table" select="normalize-space($generate.toc)"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <xsl:call-template name="make.lots">
+ <xsl:with-param name="toc.params" select="$toc.params"/>
+ <xsl:with-param name="toc">
+ <xsl:call-template name="division.toc">
+ <xsl:with-param name="toc.title.p" select="contains($toc.params, 'title')"/>
+ </xsl:call-template>
+ </xsl:with-param>
+ </xsl:call-template>
+ </div>
+ </xsl:with-param>
+ </xsl:call-template>
+ </xsl:for-each>
+</xsl:template>
+
+<xsl:template match="/book/bookinfo" mode="process.root" priority="2">
+ <xsl:choose>
+ <xsl:when test="$rootid = 'bookinfo'">
+ <xsl:call-template name="pg.write.bookinfo"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:apply-imports/>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:template>
<!--
Customization of header
diff --git a/doc/src/sgml/xmltools_dep_wrapper b/doc/src/sgml/xmltools_dep_wrapper
index dd96f784268..a5f5981dcee 100644
--- a/doc/src/sgml/xmltools_dep_wrapper
+++ b/doc/src/sgml/xmltools_dep_wrapper
@@ -14,6 +14,7 @@ parser = argparse.ArgumentParser(
parser.add_argument('--targetname', type=str, required=False, nargs='+')
parser.add_argument('--depfile', type=str, required=False)
parser.add_argument('--tool', type=str, required=True)
+parser.add_argument('--stamp', type=str, required=False, default=None)
parser.add_argument('flags', nargs='*')
args = parser.parse_args()
@@ -51,4 +52,8 @@ else:
command = [args.tool] + args.flags
res = subprocess.run(command)
+if args.stamp is not None:
+ with open(args.stamp, "w") as f:
+ pass
+
exit(res.returncode)
--
2.38.0
