pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedswitching documentation build to XSLT
10+ messages / 3 participants
[nested] [flat]
* switching documentation build to XSLT
@ 2016-11-10 13:49 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 10+ messages in thread
From: Peter Eisentraut @ 2016-11-10 13:49 UTC (permalink / raw)
To: pgsql-hackers <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
Attachments:
0001-Build-HTML-documentation-using-XSLT-stylesheets-by-d.patch (text/x-patch, 3.6K) download
From 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/
-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: #000000;
background: #FFFFFF;
font-family: verdana, sans-serif;
}
-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; }
-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 { 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; }
-.OPTION { white-space: nowrap; }
+.option { white-space: nowrap; }
--
2.10.2
* Re: switching documentation build to XSLT
@ 2016-11-16 14:17 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 4 replies; 10+ messages in thread
From: Peter Eisentraut @ 2016-11-16 14:17 UTC (permalink / raw)
To: pgsql-hackers <pgsql-hackers@postgresql.org>
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
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-19 20:34 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
3 siblings, 1 reply; 10+ messages in thread
From: Tom Lane @ 2016-11-19 20:34 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> If you find any changes in the output that bother you, let pgsql-docs know.
I notice that whereas <xref> used to generate text like
Section 4.1.2.7
now you get
Section 4.1.2.7, “Constants of Other Types”
This is probably an improvement in most places, but there may be some
places where the text now reads awkwardly and we need to rephrase or
re-punctuate to make it non-confusing. Keep an eye out for that ...
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-21 19:36 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
3 siblings, 1 reply; 10+ messages in thread
From: Tom Lane @ 2016-11-21 19:36 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> If you find any changes in the output that bother you, let pgsql-docs know.
The table of contents for Appendix F has gotten more verbose, in a way
that doesn't seem like an improvement; compare
https://www.postgresql.org/docs/9.6/static/contrib.html
https://www.postgresql.org/docs/devel/static/contrib.html
On the other hand, the table of contents disappeared entirely in
dblink, which is definitely not an improvement:
https://www.postgresql.org/docs/9.6/static/dblink.html
https://www.postgresql.org/docs/devel/static/dblink.html
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-21 21:05 Alexander Law <exclusion@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 10+ messages in thread
From: Alexander Law @ 2016-11-21 21:05 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Hello,
Attached patches fix the issues.
I wrote about these differences before -- see issues 12 and 20 in
http://oc.postgrespro.ru/index.php/s/Gj2PGZ9IHUbDC5t/download
(See
https://www.postgresql.org/message-id/4ffd72d6-8ab6-37c6-d7d5-dfed8967c0fc%40gmail.com)
If you find that some other differences are not improvements too, I can
prepare corresponding patches.
Best regards,
Alexander
21.11.2016 22:36, Tom Lane пишет:
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
>> If you find any changes in the output that bother you, let pgsql-docs know.
> The table of contents for Appendix F has gotten more verbose, in a way
> that doesn't seem like an improvement; compare
>
> https://www.postgresql.org/docs/9.6/static/contrib.html
> https://www.postgresql.org/docs/devel/static/contrib.html
>
> On the other hand, the table of contents disappeared entirely in
> dblink, which is definitely not an improvement:
>
> https://www.postgresql.org/docs/9.6/static/dblink.html
> https://www.postgresql.org/docs/devel/static/dblink.html
>
> regards, tom lane
>
>
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments: download all (2 files, .tar.gz)
1-change-subtoc-condition.patch (text/x-patch, 4.9K) download
commit e2434ec62315233bb22907fc2a6fb603e3fadd2f
Author: Alexander Lakhin <a.lakhin@postgrespro.ru>
Date: Mon Nov 21 22:54:36 2016 +0300
Change subtoc output condition
As in contrib.html:
F.1. adminpack
F.1.1. Functions Implemented
F.2. auth_delay
F.2.1. Configuration Parameters
F.2.2. Author
F.3. auto_explain
->
F.1. adminpack
F.2. auth_delay
F.3. auto_explain
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 42e8cce..494dbf5 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -384,4 +384,102 @@ Customization of header
</xsl:if>
</xsl:template>
+
+<!-- Change subtoc output condition -->
+
+<!-- from xhtml/autotoc.xsl -->
+
+<xsl:template name="subtoc">
+ <xsl:param name="toc-context" select="."/>
+ <xsl:param name="nodes" select="NOT-AN-ELEMENT"/>
+
+ <xsl:variable name="nodes.plus" select="$nodes | qandaset"/>
+
+ <xsl:variable name="subtoc">
+ <xsl:element name="{$toc.list.type}" namespace="http://www.w3.org/1999/xhtml">
+ <xsl:choose>
+ <xsl:when test="$qanda.in.toc != 0">
+ <xsl:apply-templates mode="toc" select="$nodes.plus">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ </xsl:apply-templates>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:apply-templates mode="toc" select="$nodes">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ </xsl:apply-templates>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:element>
+ </xsl:variable>
+
+ <xsl:variable name="depth">
+ <xsl:choose>
+ <xsl:when test="local-name(.) = 'section'">
+ <xsl:value-of select="count(ancestor::section) + 1"/>
+ </xsl:when>
+ <xsl:when test="local-name(.) = 'sect1'">1</xsl:when>
+ <xsl:when test="local-name(.) = 'sect2'">2</xsl:when>
+ <xsl:when test="local-name(.) = 'sect3'">3</xsl:when>
+ <xsl:when test="local-name(.) = 'sect4'">4</xsl:when>
+ <xsl:when test="local-name(.) = 'sect5'">5</xsl:when>
+ <xsl:when test="local-name(.) = 'refsect1'">1</xsl:when>
+ <xsl:when test="local-name(.) = 'refsect2'">2</xsl:when>
+ <xsl:when test="local-name(.) = 'refsect3'">3</xsl:when>
+ <xsl:when test="local-name(.) = 'topic'">1</xsl:when>
+ <xsl:when test="local-name(.) = 'simplesect'">
+ <!-- sigh... -->
+ <xsl:choose>
+ <xsl:when test="local-name(..) = 'section'">
+ <xsl:value-of select="count(ancestor::section)"/>
+ </xsl:when>
+ <xsl:when test="local-name(..) = 'sect1'">2</xsl:when>
+ <xsl:when test="local-name(..) = 'sect2'">3</xsl:when>
+ <xsl:when test="local-name(..) = 'sect3'">4</xsl:when>
+ <xsl:when test="local-name(..) = 'sect4'">5</xsl:when>
+ <xsl:when test="local-name(..) = 'sect5'">6</xsl:when>
+ <xsl:when test="local-name(..) = 'topic'">2</xsl:when>
+ <xsl:when test="local-name(..) = 'refsect1'">2</xsl:when>
+ <xsl:when test="local-name(..) = 'refsect2'">3</xsl:when>
+ <xsl:when test="local-name(..) = 'refsect3'">4</xsl:when>
+ <xsl:otherwise>1</xsl:otherwise>
+ </xsl:choose>
+ </xsl:when>
+ <xsl:otherwise>0</xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <xsl:variable name="depth.from.context" select="count(ancestor::*)-count($toc-context/ancestor::*)"/>
+
+ <xsl:variable name="subtoc.list">
+ <xsl:choose>
+ <xsl:when test="$toc.dd.type = ''">
+ <xsl:copy-of select="$subtoc"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:element name="{$toc.dd.type}" namespace="http://www.w3.org/1999/xhtml">
+ <xsl:copy-of select="$subtoc"/>
+ </xsl:element>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <xsl:variable name="output.subtoc"><xsl:value-of select="
+ ( (self::set or self::book or self::part) or
+ ($toc.section.depth > $depth and local-name($toc-context)!='appendix' and local-name($toc-context)!='preface') ) and
+ ( ($qanda.in.toc = 0 and (count($nodes)>1 or (count($nodes)>0 and ($toc.section.depth - 1 > $depth)) )) or
+ ($qanda.in.toc != 0 and (count($nodes.plus)>1 or (count($nodes)>0 and $toc.section.depth - 1 > $depth) ))) and
+ $toc.max.depth > $depth.from.context
+ "/></xsl:variable>
+ <xsl:element name="{$toc.listitem.type}" namespace="http://www.w3.org/1999/xhtml">
+ <xsl:call-template name="toc.line">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ </xsl:call-template>
+ <xsl:if test="$toc.listitem.type = 'li' and $output.subtoc = 'true'">
+ <xsl:copy-of select="$subtoc.list"/>
+ </xsl:if>
+ </xsl:element>
+ <xsl:if test="$toc.listitem.type != 'li' and $output.subtoc = 'true'">
+ <xsl:copy-of select="$subtoc.list"/>
+ </xsl:if>
+</xsl:template>
+
</xsl:stylesheet>
2-add-toc-to-sect1.patch (text/x-patch, 3.5K) download
commit f1094c3a9abcd6b3d23b85262a963f42ef9a9929
Author: Alexander Lakhin <exclusion@gmail.com>
Date: Mon Nov 21 23:49:16 2016 +0300
Add TOC to sect1
As in spi-memory.html:
44.3. Memory Management
->
44.3. Memory Management
Table of Contents
SPI_palloc — allocate memory in the upper executor context
SPI_repalloc — reallocate memory in the upper executor context
diff --git a/doc/src/sgml/stylesheet-imports-xhtml.xsl b/doc/src/sgml/stylesheet-imports-xhtml.xsl
new file mode 100644
index 0000000..4139d1d
--- /dev/null
+++ b/doc/src/sgml/stylesheet-imports-xhtml.xsl
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="ASCII"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" version="1.0">
+
+<!-- Add TOC to sect1 -->
+
+<!-- from xhtml/sections.xsl -->
+
+<xsl:template match="sect1">
+ <xsl:call-template name="id.warning"/>
+
+ <xsl:element name="{$div.element}" namespace="http://www.w3.org/1999/xhtml">
+ <xsl:call-template name="common.html.attributes">
+ <xsl:with-param name="inherit" select="1"/>
+ </xsl:call-template>
+ <xsl:call-template name="id.attribute">
+ <xsl:with-param name="conditional" select="0"/>
+ </xsl:call-template>
+
+ <xsl:choose>
+ <xsl:when test="@renderas = 'sect2'">
+ <xsl:call-template name="sect2.titlepage"/>
+ </xsl:when>
+ <xsl:when test="@renderas = 'sect3'">
+ <xsl:call-template name="sect3.titlepage"/>
+ </xsl:when>
+ <xsl:when test="@renderas = 'sect4'">
+ <xsl:call-template name="sect4.titlepage"/>
+ </xsl:when>
+ <xsl:when test="@renderas = 'sect5'">
+ <xsl:call-template name="sect5.titlepage"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="sect1.titlepage"/>
+ </xsl:otherwise>
+ </xsl:choose>
+
+ <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:if test="contains($toc.params, 'toc') and ($generate.section.toc.level >= 1 or count(refentry) > 0)">
+ <xsl:call-template name="section.toc">
+ <xsl:with-param name="toc.title.p" select="contains($toc.params, 'title')"/>
+ </xsl:call-template>
+ <xsl:call-template name="section.toc.separator"/>
+ </xsl:if>
+ <xsl:apply-templates/>
+ <xsl:call-template name="process.chunk.footnotes"/>
+ </xsl:element>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 494dbf5..209afdf 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -9,6 +9,7 @@
exclude-result-prefixes="#default">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
+<xsl:import href="stylesheet-imports-xhtml.xsl" />
<xsl:include href="stylesheet-common.xsl" />
<xsl:include href="stylesheet-speedup-xhtml.xsl" />
@@ -482,4 +483,20 @@ Customization of header
</xsl:if>
</xsl:template>
+
+<!-- To use imported templates from stylesheet-imports-xhtml.xsl -->
+
+<!-- from xhtml/chunk-code.xsl -->
+
+<xsl:template match="sect1">
+ <xsl:choose>
+ <xsl:when test="$onechunk != 0 and parent::*">
+ <xsl:apply-imports/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="process-chunk-element"/>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:template>
+
</xsl:stylesheet>
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-22 16:18 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
3 siblings, 0 replies; 10+ messages in thread
From: Tom Lane @ 2016-11-22 16:18 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> If you find any changes in the output that bother you, let pgsql-docs know.
I noticed that <remark> sections now appear in the output, which they did
not use to: compare
https://www.postgresql.org/docs/9.6/static/dml.html
https://www.postgresql.org/docs/devel/static/dml.html
If we don't want to consider that bad, somebody needs to run around and
change all such sections into comments, because we have not historically
expected them to get printed.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-22 18:47 Tom Lane <tgl@sss.pgh.pa.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 10+ messages in thread
From: Tom Lane @ 2016-11-22 18:47 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
I wrote:
> I notice that whereas <xref> used to generate text like
> Section 4.1.2.7
> now you get
> Section 4.1.2.7, “Constants of Other Types”
I also find that for some reason, the results are not formatted
consistently. Section cross-references are printed with quotes
as shown above, but chapter cross-references have no quotes and
instead the chapter title is italicized. See for example the
various cross-references for GiST about halfway down this page:
https://www.postgresql.org/docs/devel/static/indexes-types.html
TBH though, the more examples of this I look at, the less convinced
I am that it's an improvement at all. We have an awful lot of
parenthetical cross-references like "(see Section 1.2.3)", which
previously were easy to ignore while reading, but with long section
titles attached to them they quite interrupt the sentence flow.
I can kind of see the point when printing on dead trees, but in
any format where the reference is a hyperlink, I think I'd vote
for dropping the title and going back to the old output.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-23 02:39 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
3 siblings, 1 reply; 10+ messages in thread
From: Tom Lane @ 2016-11-23 02:39 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> If you find any changes in the output that bother you, let pgsql-docs know.
So, while I'm complaining, have a look at the Note near the bottom
of
https://www.postgresql.org/docs/devel/static/datatype-numeric.html
and compare to its appearance in
https://www.postgresql.org/docs/9.6/static/datatype-numeric.html
Now, to my taste, our past markup of note/tip/etc is already
overemphasizing them. They're inset with narrower margins and
put on a different-color background, which makes it hard to avoid
the impression that they're the most important thing on the page
and you should barely bother to read anything else. In almost no
case is that actually warranted; certainly not for stuff with
markup less than <warning>. (Personally I'd argue that <note> means
it's *less* important than the surrounding text, not more so.)
But putting them in bold type with a separated heading is just over
the top. What are we going to do for text that's actually critical
... make it bright red and blinking?
Just to add confusion, the note on the previous page is set
in normal type:
https://www.postgresql.org/docs/devel/static/datatype.html
which I don't understand since the sgml source is about the same.
But this one is still different from the way it was rendered by
the old toolchain.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-23 14:20 Alexander Law <exclusion@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 10+ messages in thread
From: Alexander Law @ 2016-11-23 14:20 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Hello,
The attached patch fixes this.
Best regards,
Alexander
22.11.2016 21:47, Tom Lane пишет:
> I wrote:
>> I notice that whereas <xref> used to generate text like
>> Section 4.1.2.7
>> now you get
>> Section 4.1.2.7, “Constants of Other Types”
> I also find that for some reason, the results are not formatted
> consistently. Section cross-references are printed with quotes
> as shown above, but chapter cross-references have no quotes and
> instead the chapter title is italicized. See for example the
> various cross-references for GiST about halfway down this page:
>
> https://www.postgresql.org/docs/devel/static/indexes-types.html
>
> TBH though, the more examples of this I look at, the less convinced
> I am that it's an improvement at all. We have an awful lot of
> parenthetical cross-references like "(see Section 1.2.3)", which
> previously were easy to ignore while reading, but with long section
> titles attached to them they quite interrupt the sentence flow.
>
> I can kind of see the point when printing on dead trees, but in
> any format where the reference is a hyperlink, I think I'd vote
> for dropping the title and going back to the old output.
>
> regards, tom lane
>
>
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments:
xref-without-number-and-title.patch (text/x-patch, 513B) download
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index c23d38f..9393848 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -37,6 +37,7 @@
<xsl:param name="punct.honorific" select="''"></xsl:param>
<xsl:param name="variablelist.term.break.after">1</xsl:param>
<xsl:param name="variablelist.term.separator"></xsl:param>
+<xsl:param name="xref.with.number.and.title" select="0"></xsl:param>
<!-- Change display of some elements -->
* Re: [HACKERS] switching documentation build to XSLT
@ 2016-11-23 14:52 Alexander Law <exclusion@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 10+ messages in thread
From: Alexander Law @ 2016-11-23 14:52 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
Hello,
It seems that there is some post-processing after `make html` that adds
class = "c1" or class = "c2" to html.
(It makes <div class="note c2"> or <div class="note c1">)
And docs.css on the website contains the rule:
.emphasis,
.c2 {
font-weight: bold;
}
So I think, the issue is related to publishing on the website.
Best regards,
Alexander
23.11.2016 05:39, Tom Lane writes:
> Just to add confusion, the note on the previous page is set
> in normal type:
>
> https://www.postgresql.org/docs/devel/static/datatype.html
>
> which I don't understand since the sgml source is about the same.
> But this one is still different from the way it was rendered by
> the old toolchain.
>
> regards, tom lane
>
>
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 10+ messages in thread
end of thread, other threads:[~2016-11-23 14:52 UTC | newest]
Thread overview: 10+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2016-11-10 13:49 switching documentation build to XSLT Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2016-11-16 14:17 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2016-11-19 20:34 ` Tom Lane <tgl@sss.pgh.pa.us>
2016-11-22 18:47 ` Tom Lane <tgl@sss.pgh.pa.us>
2016-11-23 14:20 ` Alexander Law <exclusion@gmail.com>
2016-11-21 19:36 ` Tom Lane <tgl@sss.pgh.pa.us>
2016-11-21 21:05 ` Alexander Law <exclusion@gmail.com>
2016-11-22 16:18 ` Tom Lane <tgl@sss.pgh.pa.us>
2016-11-23 02:39 ` Tom Lane <tgl@sss.pgh.pa.us>
2016-11-23 14:52 ` Alexander Law <exclusion@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox