Re: [HACKERS] switching documentation build to XSLT

[Peter Eisentraut]

On 11/10/16 5:49 AM, Peter Eisentraut wrote:
> We are now proposing that we change the way the HTML documentation is
> built from jade/openjade+docbook-dsssl to xsltproc+docbook-xsl.

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

This has been committed.

If you find any changes in the output that bother you, let pgsql-docs know.

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


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

[HACKERS] switching documentation build to XSLT

[Peter Eisentraut]

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
From e2e142b69e3e299932219bb5659f1bef2c78f26a Mon Sep 17 00:00:00 2001
From: Peter Eisentraut 
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/
 
-html: html-stamp
+oldhtml: oldhtml-stamp
 
-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 += --param website.stylesheet 1
 endif
 
-xslthtml: xslthtml-stamp
+html: html-stamp
 
-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 @@
 
 /* color scheme similar to www.postgresql.org */
 
-BODY {
+body {
 	color: #00;
 	background: #FF;
 	font-family: verdana, sans-serif;
 }
 
-A:link		{ color:#0066A2; }
-A:visited	{ color:#004E66; }
-A:active	{ color:#0066A2; }
-A:hover		{ color:#00; }
+a:link		{ color:#0066A2; }
+a:visited	{ color:#004E66; }
+a:active	{ color:#0066A2; }
+a:hover		{ color:#00; }
 
-H1 {
+h1 {
 	font-size: 1.4em;
 	font-weight: bold;
 	margin-top: 0em;
@@ -21,34 +21,34 @@ H1 {
 	color: #EC5800;
 }
 
-H2 {
+h2 {
 	font-size: 1.2em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: bold;
-	color: #666;
+	color: #EC5800;
 }
 
-H3 {
+h3 {
 	font-size: 1.1em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: bold;
 	color: #666;
 }
 
-H4 {
+h4 {
 	font-size: 0.95em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: normal;
 	color: #666;
 }
 
-H5 {
+h5 {
 	font-size: 0.9em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: normal;
 }
 
-H6 {
+h6 {
 	font-size: 0.85em;
 	margin: 1.2em 0em 1.2em 0em;
 	font-weight: normal;
@@ -56,13 +56,13 @@ H6 {
 
 /* center some titles */
 
-.BOOK .TITLE, .BOOK .CORPAUTHOR, .BOOK .COPYRIGHT {
+.book .title, .book .corpauthor, .book .copyright {
 	text-align: center;
 }
 
 /* decoration for formal examples */
 
-DIV.EXAMPLE {
+div.example {
 	padding-left: 15px;
 	border-style: solid;
 	border-width: 0px;
@@ -71,28 +71,16 @@ DIV.EXAMPLE {
 	margin: 0.5ex;
 }
 
-/* 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 */
 
-PRE.LITERALLAYOUT, .SCREEN, .SYNOPSIS, .PROGRAMLISTING {
+pre.literallayout, .screen, .synopsis, .programlisting {
 	margin-left: 4ex;
 }
 
-.COMMENT	{ color: red; }
+.comment	{ color: red; }
 
-VAR		{