A further step toward getting rid of the DSSSL tool chain requirement,
here is a patch to change the generation of the text INSTALL file to use
XLST and Pandoc.
The change to Pandoc is not essential to this change, but it creates
much better looking output and simplifies the locale/encoding handling
over using Lynx.
We'll need to get Pandoc installed on borka and check that that version
works as well as the one I have been using.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
From 41fe676ae519e0601b67e5ea57cf32eeb266f40f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pete...@gmx.net>
Date: Tue, 27 Dec 2016 12:00:00 -0500
Subject: [PATCH] Create INSTALL file via XSLT and Pandoc
Replace the old tool chain of jade and lynx with using xsltproc and
pandoc. As before, we create an intermediate HTML file and convert that
to plain text. Replacing jade with xsltproc removes jade from the
requirements for distribution building. The change to pandoc is
incidental, but it creates better looking output and it avoids the
delicate locale/encoding issues of lynx because it always uses UTF-8 for
both input and output.
---
doc/src/sgml/.gitignore | 1 +
doc/src/sgml/Makefile | 47 +++++++++++----------
doc/src/sgml/stylesheet-text.xsl | 89 ++++++++++++++++++++++++++++++++++++++++
3 files changed, 113 insertions(+), 24 deletions(-)
create mode 100644 doc/src/sgml/stylesheet-text.xsl
diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore
index 2f0329c15f..8197c0140d 100644
--- a/doc/src/sgml/.gitignore
+++ b/doc/src/sgml/.gitignore
@@ -21,6 +21,7 @@
# Assorted byproducts from building the above
/postgres.xml
/INSTALL.html
+/INSTALL.xml
/postgres-US.aux
/postgres-US.log
/postgres-US.out
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index fe7ca65cd4..0c18a8a84a 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -217,26 +217,22 @@ postgres.pdf:
##
-## Semi-automatic generation of some text files.
+## Generation of some text files
##
-JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-text -t sgml
ICONV = iconv
-LYNX = lynx
-
-# The documentation may contain non-ASCII characters (mostly for
-# contributor names), which lynx converts to the encoding determined
-# by the current locale. To get text output that is deterministic and
-# easily readable by everyone, we make lynx produce LATIN1 and then
-# convert that to ASCII with transliteration for the non-ASCII characters.
-# Official releases were historically built on FreeBSD, which has limited
-# locale support and is very picky about locale name spelling. The
-# below has been finely tuned to run on FreeBSD and Linux/glibc.
+PANDOC = pandoc
+
INSTALL: % : %.html
- $(PERL) -p -e 's/<H(1|2)$$/<H\1 align=center/g' $< | LC_ALL=en_US.ISO8859-1 $(LYNX) -force_html -dump -nolist -stdin | $(ICONV) -f latin1 -t us-ascii//TRANSLIT > $@
+ $(PANDOC) $< -t plain | $(ICONV) -f utf8 -t us-ascii//TRANSLIT > $@
+
+INSTALL.html: %.html : stylesheet-text.xsl %.xml
+ $(XMLLINT) --noout --valid $*.xml
+ $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@
-INSTALL.html: standalone-install.sgml installation.sgml version.sgml
- $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@
+INSTALL.xml: standalone-install.sgml installation.sgml version.sgml
+ $(OSX) -D. -x lower $(filter-out version.sgml,$^) >$@.tmp
+ $(call mangle-xml,chapter)
##
@@ -247,12 +243,15 @@ INSTALL.html: standalone-install.sgml installation.sgml version.sgml
# if we try to do "make all" in a VPATH build without the explicit
# $(srcdir) on the postgres.sgml dependency in this rule. GNU make bug?
postgres.xml: $(srcdir)/postgres.sgml $(ALMOSTALLSGML)
- $(OSX) -D. -x lower -i include-xslt-index $< >postgres.xmltmp
- $(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|eacute|egrave|gt|iacute|lt|mdash|nbsp|ntilde|oacute|ocirc|oslash|ouml|pi|quot|scaron|uuml) *\]/\&\1;/gi;' \
- -e '$$_ .= qq{<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>\n} if $$. == 1;' \
- <postgres.xmltmp > $@
- rm postgres.xmltmp
-# ' hello Emacs
+ $(OSX) -D. -x lower -i include-xslt-index $< >$@.tmp
+ $(call mangle-xml,book)
+
+define mangle-xml
+$(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|eacute|egrave|gt|iacute|lt|mdash|nbsp|ntilde|oacute|ocirc|oslash|ouml|pi|quot|scaron|uuml) *\]/\&\1;/gi;' \
+ -e '$$_ .= qq{<!DOCTYPE $(1) PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>\n} if $$. == 1;' \
+ <$@.tmp >$@
+rm $@.tmp
+endef
ifeq ($(STYLE),website)
XSLTPROC_HTML_FLAGS += --param website.stylesheet 1
@@ -386,13 +385,13 @@ check-tabs:
# This allows removing some files from the distribution tarballs while
# keeping the dependencies satisfied.
.SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index
-.SECONDARY: INSTALL.html
+.SECONDARY: INSTALL.html INSTALL.xml
.SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf
clean:
# text --- these are shipped, but not in this directory
rm -f INSTALL
- rm -f INSTALL.html
+ rm -f INSTALL.html INSTALL.xml
# single-page output
rm -f postgres.html postgres.txt
# print
@@ -400,7 +399,7 @@ clean:
# index
rm -f HTML.index $(GENERATED_SGML)
# XSLT
- rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo
+ rm -f postgres.xml *.tmp htmlhelp.hhp toc.hhc index.hhk *.fo
# EPUB
rm -f postgres.epub
# Texinfo
diff --git a/doc/src/sgml/stylesheet-text.xsl b/doc/src/sgml/stylesheet-text.xsl
new file mode 100644
index 0000000000..7d29c32cfe
--- /dev/null
+++ b/doc/src/sgml/stylesheet-text.xsl
@@ -0,0 +1,89 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+ version='1.0'
+ xmlns="http://www.w3.org/TR/xhtml1/transitional";
+ exclude-result-prefixes="#default">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/>
+<xsl:import href="stylesheet-common.xsl" />
+
+<!-- The customizations here are somewhat random in order to make the text
+ output look good. -->
+
+<!-- no section numbers or ToC -->
+<xsl:param name="chapter.autolabel" select="0"/>
+<xsl:param name="section.autolabel" select="0"/>
+<xsl:param name="generate.toc"></xsl:param>
+
+<!-- Pandoc renders HTML <b> in all caps, which doesn't always look so good.
+ make.clean.html replaces most <b>s with CSS, and generate.css.header puts
+ the CSS in the file header rather than in a separate file. And Pandoc
+ appears to ignore the CSS. So this is a roundabout way of stripping out
+ most <b> elements. -->
+<xsl:param name="generate.css.header" select="1"/>
+<xsl:param name="make.clean.html" select="1"/>
+
+<!-- don't need them, and they mess up formatting -->
+<xsl:template match="indexterm">
+</xsl:template>
+
+<xsl:template match="step">
+ <li>
+ <xsl:call-template name="common.html.attributes"/>
+ <xsl:call-template name="id.attribute"/>
+<!-- messes up formatting
+ <xsl:call-template name="anchor"/>
+-->
+ <xsl:apply-templates/>
+ </li>
+</xsl:template>
+
+<!-- removed <b> here; make.clean.html misses this
+ (https://github.com/docbook/xslt10-stylesheets/pull/21) -->
+<xsl:template match="step/title">
+ <p>
+ <xsl:call-template name="common.html.attributes"/>
+ <xsl:apply-templates/>
+ </p>
+</xsl:template>
+
+<!-- produce "ASCII markup" for emphasis and such -->
+
+<xsl:template match="emphasis">
+ <xsl:text>*</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>*</xsl:text>
+</xsl:template>
+
+<xsl:template match="para/command|para/filename|para/option|para/replaceable">
+ <xsl:text>"</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>"</xsl:text>
+</xsl:template>
+
+<xsl:template match="filename/replaceable|firstterm">
+ <xsl:apply-templates/>
+</xsl:template>
+
+<!-- tweak formatting for note, warning, etc. -->
+<xsl:template name="nongraphical.admonition">
+ <div>
+ <xsl:call-template name="common.html.attributes">
+ <xsl:with-param name="inherit" select="1"/>
+ </xsl:call-template>
+ <xsl:call-template name="id.attribute"/>
+
+ <xsl:if test="$admon.textlabel != 0 or title or info/title">
+ <p>
+ <b>
+ <xsl:call-template name="anchor"/>
+ <xsl:apply-templates select="." mode="object.title.markup"/>
+ </b>
+ </p>
+ </xsl:if>
+
+ <xsl:apply-templates/>
+ </div>
+</xsl:template>
+
+</xsl:stylesheet>
--
2.11.0
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
