Subject: Re: Docbook 5.x
To: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>,
 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: pgsql-docs@postgresql.org
References: <57179283.6080704@purtz.de>
 <CAF4Au4zUVOuWjWc+B72yvvpVo=TJad6=x9chig7Ls9DNa7Kgrg@mail.gmail.com>
 <db902495-52f2-ee33-b229-5fe094cf4937@2ndquadrant.com>
 <572AD007.60900@gmail.com>
 <bcc78f65-ef7f-22ea-0d7a-a83b7b7538b6@2ndquadrant.com>
 <5752E599.2090505@gmail.com>
 <de53dbdf-a0f1-5673-bbee-ca4f3d75f278@2ndquadrant.com>
 <576d0623-a89c-b3de-e321-dc48a579ff1a@2ndquadrant.com>
 <eb1abd5e-4210-b5c5-522c-d15e4e62a09b@gmail.com>
 <b4f74ac9-09ba-d198-092b-e2bfbf1c0194@2ndquadrant.com>
 <4adecfc6-2f2e-2ff2-bfa3-58b7d397227b@gmail.com>
 <c7e45017-c918-d2ec-a7e5-f696e41c5314@gmail.com>
 <e4e972b8-425b-164b-031e-f6db2daef9d2@2ndquadrant.com>
 <8f227b2a-5093-8d99-85da-ea00e18343f6@gmail.com>
 <aab72af9-928c-e116-d342-804bf78911c6@gmail.com>
 <449e34c4-9cc8-d17d-5ebe-be92b4c0a87a@gmail.com>
 <09b13d85-e259-2464-723a-467210264afe@2ndquadrant.com>
 <f00bf53f-e6b5-a033-69be-0c63878f0d30@gmail.com>
 <9e8cafe4-7cfd-59be-6856-172c15dc758f@2ndquadrant.com>
 <ac8351bf-a97a-5ff7-1df5-747a3962efb8@purtz.de>
From: Alexander Lakhin <exclusion@gmail.com>
Message-ID: <11c0be48-6125-bbe1-1d02-6d61e889bd5e@gmail.com>
Date: Mon, 18 Sep 2017 17:38:27 +0300
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.2.1
MIME-Version: 1.0
In-Reply-To: <ac8351bf-a97a-5ff7-1df5-747a3962efb8@purtz.de>
Content-Type: multipart/alternative;
 boundary="------------16F2A55CCEB4C93CEBF301A4"
Content-Language: en-US
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

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

Hello,
15.09.2017 21:54, Jürgen Purtz wrote:
> 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?
Peter, can you show what performance drop you see with the profiling 
(e.g. for HTML)?
I get the following numbers:
1. make html with profiling (import profile-chunk.xsl in stylesheet.xsl):
85.98user 0.76system 1:29.85elapsed

2. make html without profiling (import chunk.xsl in stylesheet.xsl):
77.36user 0.62system 1:21.28elapsed

3. Separate profiling (performed before making epub, as dbtoepub doesn't 
support profiling)
8.52user 0.22system 0:10.31elapsed

So I get ~10% performance drop when making html. Are you concerned about 
the same overhead?
I would choose some standard way to have separate content in the same 
file, but if the overhead is not acceptable, and we're not going to 
extend the profiling usage, then we need to invent something that will 
complicate XML-related processing (I think about translation but the 
other issues are possible too).

> 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[@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'.
>
Jürgen, this approach implemented by applying profiling.xsl in Makefile 
(for make postgres.epub). (See Makefile in 
https://www.postgresql.org/message-id/attachment/54854/pg-doc.check.tar.bz2)

Best regards,
Alexander

--------------16F2A55CCEB4C93CEBF301A4
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <div class="moz-cite-prefix">Hello, <br>
      15.09.2017 21:54, Jürgen Purtz wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:ac8351bf-a97a-5ff7-1df5-747a3962efb8@purtz.de">
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
      <div class="moz-cite-prefix">On 15.09.2017 19:32, Peter Eisentraut
        wrote:<br>
      </div>
      <blockquote type="cite"
        cite="mid:9e8cafe4-7cfd-59be-6856-172c15dc758f@2ndquadrant.com">
        <pre wrap="">On 9/8/17 08:30, Alexander Lakhin wrote:
</pre>
        <blockquote type="cite">
          <blockquote type="cite">
            <pre wrap="">I have started working through these patches now. I have committed the 
escaping of &lt; and &amp; and will work through the rest slowly, to minimize 
disruptions to other development.
</pre>
          </blockquote>
          <pre wrap="">Great!

I have rebased all the remaining patches and updated scripts for the 
current master (see attachment).
</pre>
        </blockquote>
        <pre wrap="">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?</pre>
      </blockquote>
    </blockquote>
    Peter, can you show what performance drop you see with the profiling
    (e.g. for HTML)?<br>
    I get the following numbers:<br>
    1. make html with profiling (import profile-chunk.xsl in
    stylesheet.xsl):<br>
    <tt>85.98user 0.76system 1:29.85elapsed</tt><br>
    <br>
    2. make html without profiling (import chunk.xsl in stylesheet.xsl):<br>
    <tt>77.36user 0.62system 1:21.28elapsed<br>
      <br>
    </tt>3. Separate profiling (performed before making epub, as
    dbtoepub doesn't support profiling)<br>
    <tt>8.52user 0.22system 0:10.31elapsed</tt><br>
    <br>
    So I get ~10% performance drop when making html. Are you concerned
    about the same overhead?<br>
    I would choose some standard way to have separate content in the
    same file, but if the overhead is not acceptable, and we're not
    going to extend the profiling usage, then we need to invent
    something that will complicate XML-related processing (I think about
    translation but the other issues are possible too).<br>
    <br>
    <blockquote type="cite"
      cite="mid:ac8351bf-a97a-5ff7-1df5-747a3962efb8@purtz.de">
      <p>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:</p>
      <p>&lt;xsl:template match="phrase[@id='install-ldap-links']"&gt;<br>
          &lt;xsl:text&gt;the documentation about client authentication
        and libpq&lt;/xsl:text&gt;<br>
        &lt;/xsl:template&gt;</p>
      <p>This approach spreads the intended text over two very different
        files (in this example: 'installation.xml' and
        'standalone-profile.xsl'). </p>
      <p>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 <b>generic</b>
        xsl file shall create the extended output similar to
        'standalone-profile.xsl'.</p>
    </blockquote>
    Jürgen, this approach implemented by applying profiling.xsl in
    Makefile (for make postgres.epub). (See Makefile in
<a class="moz-txt-link-freetext" href="https://www.postgresql.org/message-id/attachment/54854/pg-doc.check.tar.bz2">https://www.postgresql.org/message-id/attachment/54854/pg-doc.check.tar.bz2</a>)<br>
    <br>
    Best regards,<br>
    Alexander<br>
  </body>
</html>

--------------16F2A55CCEB4C93CEBF301A4--