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: <5766FF20.4020005@purtz.de>
Date: Sun, 19 Jun 2016 22:22:56 +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="------------030008060709020803010807"
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

This is a multi-part message in MIME format.
--------------030008060709020803010807
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] 

Alexander and I continue to work on this path. In the meanwhile we have 
reached a state where xml files are well formed and valid against 
docbook 4 dtd - each single file as well as the big postgres_all.xml 
file. Thanks to Alexander's performance patch all XSLT processes run 
very fast (the slowest is fo+pdf with 6:30 min).

On this basis I actually work on the HTML generation. But in opposite to 
the previous steps (where we create identical copies of the sgml files) 
the new css file is very different from the old one. This results from 
the following:

  * The XSLT process generates other HTML elements and other classes in
    comparison to the dsssl process.
  * XML files are case sensitive. All object names (id, ulink, linkend,
    zone, ...) are now lower case.
  * Sometimes the order of elements changed.
  * As the previous css file was constructed (some years ago) from three
    different css files, he contains redundant and sometimes
    contradictory information. I did a complete review.

To get a feedback from the community I have published the resulting 
postgres_all.html and its pgdoc_online.css file. Please refer to 
https://github.com/JuergenPurtz/pgdoc_db5/blob/master/postgresql-9.5.3/doc/src/db4_xml/postgres_all.html 
respective pgdoc_online.css to get the files. Please compare the html 
file with pages you are familiar with. And remember: the look-and-feel 
is similar, but far from identical.

Jürgen Purtz


--------------030008060709020803010807
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]
    </blockquote>
    <br>
    Alexander and I continue to work on this path. In the meanwhile we
    have reached a state where xml files are well formed and valid
    against docbook 4 dtd - each single file as well as the big
    postgres_all.xml file. Thanks to Alexander's performance patch all
    XSLT processes run very fast (the slowest is fo+pdf with 6:30 min).
    <br>
    <br>
    On this basis I actually work on the HTML generation. But in
    opposite to the previous steps (where we create identical copies of
    the sgml files) the new css file is very different from the old one.
    This results from the following:<br>
    <ul>
      <li>The XSLT process generates other HTML elements and other
        classes in comparison to the dsssl process.</li>
      <li>XML files are case sensitive. All object names (id, ulink,
        linkend, zone, ...) are now lower case.<br>
      </li>
      <li>Sometimes the order of elements changed.</li>
      <li>As the previous css file was constructed (some years ago) from
        three different css files, he contains redundant and sometimes
        contradictory information. I did a complete review.<br>
      </li>
    </ul>
    To get a feedback from the community I have published the resulting
    postgres_all.html and its pgdoc_online.css file. Please refer to
    <a class="moz-txt-link-freetext" href="https://github.com/JuergenPurtz/pgdoc_db5/blob/master/postgresql-9.5.3/doc/src/db4_xml/postgres_all.html">https://github.com/JuergenPurtz/pgdoc_db5/blob/master/postgresql-9.5.3/doc/src/db4_xml/postgres_all.html</a>
    respective pgdoc_online.css to get the files. Please compare the
    html file with pages you are familiar with. And remember: the
    look-and-feel is similar, but far from identical.<br>
    <br>
    Jürgen Purtz<br>
    <br>
  </body>
</html>

--------------030008060709020803010807--