Re: Docbook 5.x

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com>
Cc: pgsql-docs(at)postgresql(dot)org, Alexander Law <exclusion(at)gmail(dot)com>
Subject: Re: Docbook 5.x
Date: 2017-09-15 18:54:57
Message-ID: ac8351bf-a97a-5ff7-1df5-747a3962efb8@purtz.de
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

On 15.09.2017 19:32, Peter Eisentraut wrote:
> On 9/8/17 08:30, Alexander Lakhin wrote:
>>> I have started working through these patches now. I have committed the
>>> escaping of < and & and will work through the rest slowly, to minimize
>>> disruptions to other development.
>> Great!
>>
>> I have rebased all the remaining patches and updated scripts for the
>> current master (see attachment).
> So, I've been looking at this profiling stuff, to replace the marked
> sections in the installation instructions. I found the overhead of that
> a bit too much for building the full documentation, so I have come up
> with the attached alternative solution. What do you think?
>

I'm not happy with the 'particular conversions'-part of
'standalone-profile.xsl'. It applies subsequent modifications, which are
in not very intuitive to a reader, eg:

<xsl:template match="phrase[(at)id='install-ldap-links']">
  <xsl:text>the documentation about client authentication and
libpq</xsl:text>
</xsl:template>

This approach spreads the intended text over two very different files
(in this example: 'installation.xml' and 'standalone-profile.xsl').

My suggestion is to keep the source code in one file in the same manner
as with the SGML standalone-include/standalone-ignore mechanism. A
*generic* xsl file shall create the extended output similar to
'standalone-profile.xsl'.

installation.xml:

support for authentication and connection parameter lookup (see
<phrase condition="standalone">the documentation about client
authentication and libpq</phrase>
<phrase condition="default"><xref linkend="libpq-ldap"/> and<xref
linkend="auth-ldap"/></phrase>
for more information). On Unix,
...

collectAll.xsl (similar to standalone-profile.xsl):

  <!-- parameters and variables -->
  <xsl:param name="pg.Standalone" select="'default'"/>
  <!-- <xsl:param name="pg.Standalone" select="'standalone'"/> -->

  <!-- Process all nodes  -->
  <xsl:template match="*|@*|text()|processing-instruction()|comment()">
    <xsl:choose>
      <xsl:when test="(not (@condition) or @condition=$pg.Standalone )">
        <!-- copy nodes without a 'condition' attribute and such nodes,
where 'condition' meets the given criteria  -->
        <xsl:copy>
          <xsl:apply-templates
select="*|@*|text()|processing-instruction()|comment()"/>
        </xsl:copy>
      </xsl:when>
    </xsl:choose>
  </xsl:template>

I'm sorry that I actually cannot deliver a patch because I'm abroad and
have limited resources (but many challenges). But I hope that the idea
gets clear. The attached collectAll.xsl file contains a more complex
solution for the case that we have to deal with more than one
include/ignore type, eg: index-generating.

Attachment Content-Type Size
collectAll.xsl application/xslt+xml 3.0 KB

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message zszmigiero 2017-09-16 12:31:06 CREATE GROUP: REPLICATION, NOREPLICATION, BYPASSRLS, NOBYPASSRLS, CONNECTION LIMIT connlimit
Previous Message Peter Eisentraut 2017-09-15 14:32:45 Re: Docbook 5.x