From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Subject: switching documentation build to XSLT
Organization: 2ndQuadrant
To: pgsql-hackers <pgsql-hackers@postgresql.org>
Message-ID: <2cdfe551-eb7b-b319-c96d-0d53cc0c2db8@2ndquadrant.com>
Date: Thu, 10 Nov 2016 08:49:55 -0500
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:45.0)
 Gecko/20100101 Thunderbird/45.4.0
MIME-Version: 1.0
Content-Type: multipart/mixed;
 boundary="------------62964F18F20E3446C99A19B8"
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org

This is a multi-part message in MIME format.
--------------62964F18F20E3446C99A19B8
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

Some work has been going on recently to be able to update our
documentation build tool chain.  After discussion on pgsql-docs, the
people involved agree that it is time to move forward.

We are now proposing that we change the way the HTML documentation is
built from jade/openjade+docbook-dsssl to xsltproc+docbook-xsl.

If you can build the man pages now (make man, also included in make
world), then you don't need any new tools.  The new HTML build will be
using the same tools.  Otherwise, follow the documentation to set up
those tools and make that work.

The actual patch to make this change is attached.  For the build
process, nothing changes, e.g., 'make' or 'make html' will still have
the same purposes.

For the time being, you will still be able to build the documentation
the old way with 'make oldhtml', but this is mainly so that we can
compare the output and work out any formatting kinks.  Before this
patch, you can also build the documentation the new way using 'make
xslthtml', but that will go away.

I will submit a separate patch to the web site team to update the CSS
style sheets for the web site to match the new output.

There are more steps to be done after this, to move over the other
output formats (PDF), adjust the configure script, the documentation,
work out any remaining formatting problems, etc., so now is a good time
to get this rolling so that we have a good chance of reaching a steady
state before the end of the development cycle.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--------------62964F18F20E3446C99A19B8
Content-Type: text/x-patch;
 name="0001-Build-HTML-documentation-using-XSLT-stylesheets-by-d.patch"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
 filename*0="0001-Build-HTML-documentation-using-XSLT-stylesheets-by-d.pa";
 filename*1="tch"

=46rom e2e142b69e3e299932219bb5659f1bef2c78f26a Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Tue, 8 Nov 2016 12:00:00 -0500
Subject: [PATCH] Build HTML documentation using XSLT stylesheets by default

The old DSSSL build is still available for a while using the make target
"oldhtml".
---
 doc/src/sgml/Makefile       |  8 ++++----
 doc/src/sgml/stylesheet.css | 50 +++++++++++++++++------------------------=
----
 2 files changed, 23 insertions(+), 35 deletions(-)

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 84c94e8..fe7ca65 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -106,9 +106,9 @@ draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
 	$(JADE.html.call) -V draft-mode $<
 	cp $(srcdir)/stylesheet.css html/
=20
-html: html-stamp
+oldhtml: oldhtml-stamp
=20
-html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
+oldhtml-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
 	$(MAKE) check-tabs
 	$(MKDIR_P) html
 	$(JADE.html.call) -i include-index $<
@@ -258,9 +258,9 @@ ifeq ($(STYLE),website)
 XSLTPROC_HTML_FLAGS +=3D --param website.stylesheet 1
 endif
=20
-xslthtml: xslthtml-stamp
+html: html-stamp
=20
-xslthtml-stamp: stylesheet.xsl postgres.xml
+html-stamp: stylesheet.xsl postgres.xml
 	$(XMLLINT) --noout --valid postgres.xml
 	$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^
 	cp $(srcdir)/stylesheet.css html/
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index 60dcc76..f845876 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -2,18 +2,18 @@
=20
 /* color scheme similar to www.postgresql.org */
=20
-BODY {
+body {
 	color: #000000;
 	background: #FFFFFF;
 	font-family: verdana, sans-serif;
 }
=20
-A:link		{ color:#0066A2; }
-A:visited	{ color:#004E66; }
-A:active	{ color:#0066A2; }
-A:hover		{ color:#000000; }
+a:link		{ color:#0066A2; }
+a:visited	{ color:#004E66; }
+a:active	{ color:#0066A2; }
+a:hover		{ color:#000000; }
=20
-H1 {
+h1 {
 	font-size: 1.4em;
 	font-weight: bold;
 	margin-top: 0em;
@@ -21,34 +21,34 @@ H1 {
 	color: #EC5800;
 }
=20
-H2 {
+h2 {
 	font-size: 1.2em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: bold;
-	color: #666;
+	color: #EC5800;
 }
=20
-H3 {
+h3 {
 	font-size: 1.1em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: bold;
 	color: #666;
 }
=20
-H4 {
+h4 {
 	font-size: 0.95em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: normal;
 	color: #666;
 }
=20
-H5 {
+h5 {
 	font-size: 0.9em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: normal;
 }
=20
-H6 {
+h6 {
 	font-size: 0.85em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: normal;
@@ -56,13 +56,13 @@ H6 {
=20
 /* center some titles */
=20
-.BOOK .TITLE, .BOOK .CORPAUTHOR, .BOOK .COPYRIGHT {
+.book .title, .book .corpauthor, .book .copyright {
 	text-align: center;
 }
=20
 /* decoration for formal examples */
=20
-DIV.EXAMPLE {
+div.example {
 	padding-left: 15px;
 	border-style: solid;
 	border-width: 0px;
@@ -71,28 +71,16 @@ DIV.EXAMPLE {
 	margin: 0.5ex;
 }
=20
-/* less dense spacing of TOC */
-
-.BOOK .TOC DL DT {
-	padding-top: 1.5ex;
-	padding-bottom: 1.5ex;
-}
-
-.BOOK .TOC DL DL DT {
-	padding-top: 0ex;
-	padding-bottom: 0ex;
-}
-
 /* miscellaneous */
=20
-PRE.LITERALLAYOUT, .SCREEN, .SYNOPSIS, .PROGRAMLISTING {
+pre.literallayout, .screen, .synopsis, .programlisting {
 	margin-left: 4ex;
 }
=20
-.COMMENT	{ color: red; }
+.comment	{ color: red; }
=20
-VAR		{ font-family: monospace; font-style: italic; }
+var		{ font-family: monospace; font-style: italic; }
 /* Konqueror's standard style for ACRONYM is italic. */
-ACRONYM		{ font-style: inherit; }
+acronym		{ font-style: inherit; }
=20
-.OPTION		{ white-space: nowrap; }
+.option		{ white-space: nowrap; }
--=20
2.10.2


--------------62964F18F20E3446C99A19B8
Content-Type: text/plain
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

--------------62964F18F20E3446C99A19B8--