Subject: Re: Docbook 5.x
To: pgsql-docs@postgresql.org
References: <57179283.6080704@purtz.de>
 <20160503193441.GA61759@alvherre.pgsql>
 <CAF4Au4zUVOuWjWc+B72yvvpVo=TJad6=x9chig7Ls9DNa7Kgrg@mail.gmail.com>
 <572A0AD2.2070909@purtz.de> <572A1089.7030004@gmail.com>
 <4f55ecfb-3aaf-4f1d-7364-05f9153c7526@2ndquadrant.com>
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Message-ID: <57779402.1080306@purtz.de>
Date: Sat, 2 Jul 2016 12:14:26 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.8.0
MIME-Version: 1.0
In-Reply-To: <4f55ecfb-3aaf-4f1d-7364-05f9153c7526@2ndquadrant.com>
Content-Type: multipart/alternative;
 boundary="------------090205070500070705080900"
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

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


On 05.05.2016 03:09, Peter Eisentraut wrote:
> I think the process should be something like this:
>
> - Apply your XSLT performance patch.  The patch should be submitted to 
> the next commit fest.
>
> - Wait a while to make sure everyone is happy with the performance. 
> Keep tweaking if necessary.
>
> - Port all DSSSL customizations to XSLT.  Manually evaluate output for 
> quality.
>
> - Switch to XSLT build for official HTML documentation. [milestone 1]
>
> - Convert sources to XML. (There could be substeps here.) [milestone 2]
>
> - Then consider upgrading to DocBook 5. [milestone 3]

During the step from DocBook 4 to DocBook 5 [M3] we will face the 
problem that there are incompatibilities in the DocBook structure. Our 
source is affected by:

 1. It's no longer possible to use <option> and <optional> in a
    recursive fashion.
 2. The content model of <literal>, <function>, <command> and similar
    elements has changed.

In my opinion the first issue is not acceptable and the second one may 
need some DocBook redesign as well as manual changes in our source code. 
The DocBook TC has accepted this concerns and works on a solution. But 
as they are in the last phase of bringing 5.1 to an official OASIS 
standard, we probably have to wait (a long time) until 5.2. You can 
follow the discussion here: 
https://lists.oasis-open.org/archives/docbook/201606/msg00007.html and 
in a direct mail from Bob Stayton:

-----
Hi,
I'm investigating this issue.  I'm trying to track down the history and 
reasoning for this change, but have not yet completed that research.  It 
looks like a mistake to me to limit the content model so much when we 
were consciously trying to maintain backwards compatibility unless there 
were good reasons not to.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net
-----


Jürgen Purtz

Btw: Since 16 June 2016 Norman Welsh is no longer chairman of the TC. 
Now Bob holds this position, Norman changed to a 'normal' member of the TC.


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

<html>
  <head>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <br>
    <div class="moz-cite-prefix">On 05.05.2016 03:09, Peter Eisentraut
      wrote:<br>
    </div>
    <blockquote
      cite="mid:4f55ecfb-3aaf-4f1d-7364-05f9153c7526@2ndquadrant.com"
      type="cite">I think the process should be something like this:
      <br>
      <br>
      - Apply your XSLT performance patch.  The patch should be
      submitted to the next commit fest.
      <br>
      <br>
      - Wait a while to make sure everyone is happy with the
      performance. Keep tweaking if necessary.
      <br>
      <br>
      - Port all DSSSL customizations to XSLT.  Manually evaluate output
      for quality.
      <br>
      <br>
      - Switch to XSLT build for official HTML documentation. [milestone
      1]
      <br>
      <br>
      - Convert sources to XML. (There could be substeps here.)
      [milestone 2]
      <br>
      <br>
      - Then consider upgrading to DocBook 5. [milestone 3]
      <br>
    </blockquote>
    <br>
    During the step from DocBook 4 to DocBook 5 [M3] we will face the
    problem that there are incompatibilities in the DocBook structure.
    Our source is affected by:<br>
    <ol>
      <li>It's no longer possible to use &lt;option&gt; and
        &lt;optional&gt; in a recursive fashion.</li>
      <li>The content model of &lt;literal&gt;, &lt;function&gt;,
        &lt;command&gt; and similar elements has changed.<br>
      </li>
    </ol>
    In my opinion the first issue is not acceptable and the second one
    may need some DocBook redesign as well as manual changes in our
    source code. The DocBook TC has accepted this concerns and works on
    a solution. But as they are in the last phase of bringing 5.1 to an
    official OASIS standard, we probably have to wait (a long time)
    until 5.2. You can follow the discussion here:
    <a class="moz-txt-link-freetext" href="https://lists.oasis-open.org/archives/docbook/201606/msg00007.html">https://lists.oasis-open.org/archives/docbook/201606/msg00007.html</a>
    and in a direct mail from Bob Stayton:<br>
    <br>
    -----<br>
    Hi,
    <br>
    I'm investigating this issue.  I'm trying to track down the history
    and reasoning for this change, but have not yet completed that
    research.  It looks like a mistake to me to limit the content model
    so much when we were consciously trying to maintain backwards
    compatibility unless there were good reasons not to.
    <br>
    <br>
    Bob Stayton
    <br>
    Sagehill Enterprises
    <br>
    <a class="moz-txt-link-abbreviated" href="mailto:bobs@sagehill.net">bobs@sagehill.net</a><br>
    -----<br>
    <br>
    <br>
    Jürgen Purtz<br>
    <br>
    Btw: Since 16 June 2016 Norman Welsh is no longer chairman of the
    TC. Now Bob holds this position, Norman changed to a 'normal' member
    of the TC.<br>
    <br>
  </body>
</html>

--------------090205070500070705080900--