Subject: Re: [HACKERS] switching documentation build to XSLT
To: Tom Lane <tgl@sss.pgh.pa.us>,
 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
References: <2cdfe551-eb7b-b319-c96d-0d53cc0c2db8@2ndquadrant.com>
 <1aff5a5f-64aa-91c4-41c4-7952afe8a792@2ndquadrant.com>
 <31557.1479756998@sss.pgh.pa.us>
Cc: pgsql-docs@postgreSQL.org
From: Alexander Law <exclusion@gmail.com>
Message-ID: <9cb9d7a2-c659-6100-fbbf-026d84776c9d@gmail.com>
Date: Tue, 22 Nov 2016 00:05:21 +0300
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101
 Thunderbird/45.4.0
MIME-Version: 1.0
In-Reply-To: <31557.1479756998@sss.pgh.pa.us>
Content-Type: multipart/mixed;
 boundary="------------D63FEF04C025ECC97196E890"
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

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

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


--------------D63FEF04C025ECC97196E890
Content-Type: text/x-patch;
 name="1-change-subtoc-condition.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="1-change-subtoc-condition.patch"

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 &gt; $depth and local-name($toc-context)!='appendix' and local-name($toc-context)!='preface') ) and
+    ( ($qanda.in.toc = 0 and (count($nodes)&gt;1 or (count($nodes)&gt;0 and ($toc.section.depth - 1 &gt; $depth)) )) or
+      ($qanda.in.toc != 0 and (count($nodes.plus)&gt;1 or (count($nodes)&gt;0 and $toc.section.depth - 1 &gt; $depth) ))) and
+      $toc.max.depth &gt; $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>

--------------D63FEF04C025ECC97196E890
Content-Type: text/x-patch;
 name="2-add-toc-to-sect1.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="2-add-toc-to-sect1.patch"

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 &mdash; allocate memory in the upper executor context
       SPI_repalloc &mdash; 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 &gt;= 1 or count(refentry) &gt; 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>

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


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

--------------D63FEF04C025ECC97196E890--