From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Subject: Re: Docbook 5.x
To: Simon Riggs <simon@2ndQuadrant.com>, pgsql-docs@postgresql.org
References: <57179283.6080704@purtz.de>
 <CANP8+jJdn=riff_qstQ+C7784o1gK5rgbJtnXKZ+5FTZxVBn7Q@mail.gmail.com>
Message-ID: <5728F9CC.7050402@purtz.de>
Date: Tue, 3 May 2016 21:19:40 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.2
MIME-Version: 1.0
In-Reply-To: 
 <CANP8+jJdn=riff_qstQ+C7784o1gK5rgbJtnXKZ+5FTZxVBn7Q@mail.gmail.com>
Content-Type: multipart/alternative;
 boundary="------------020804080809070105090108"
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

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

Hello,

the conversion of PostgreSQL documentation from Docbook 4.x to 5.x 
consists of the following steps:

 1. pure sgml --> xml conversion (done, Perl script)
 2. 4.x markup --> 5.x markup (done, Docbook standard migration script)
 3. post-processing of 5.x files (done, Perl: xi:include, entities, ...)
 4. generate the complete file postgres_all.xml with xmllint (done)
 5. generate online documentation (html, man, text)
 6. generate print documentation (rtf, pdf)
 7. adopt Makefile to the new situation

After step 3 we have well-formed xml files, most of them are valid 
against Docbook 5.0 xsd. Actually the following non-valid situations occur:

  * a lot of unknown xref targets, as the target exists in a different file
  * 4 remaining sgml-entities: standalone-xxx and include-xxx
  * some markups, which are not valid in 5.x, mostly with <synopsis> and
    <function>. This must be resolved manually (5.x offers comprehensive
    possibilities for very detailed markups with <funcsynopsis> and
    <cmdsynopsis>)

Steps 5 and 6 implies the replacement of our dsssl script with xslt 
scripts. I guess that this is much more difficult and lengthy than 
everything else I have done in this project so far. Furthermore I don't 
have any knowledge about dsssl. And this is the reason why I write this 
mail. Is anybody out there who can support me for the dsssl --> xslt 
conversion - or at least can answer questions like:

  * Is our file stylesheet.dsl written from scratch - or is it derived
    from any docbook 1/2/3/4.x generic stylesheet?
  * Which person has developed this file?
  * What is the role of the *.xsl files in the sgml-directory and how do
    they collaborate with stylesheet.dsl?

Regards, Jürgen


On 20.04.2016 20:41, Simon Riggs wrote:
> On 20 April 2016 at 15:30, Jürgen Purtz <juergen@purtz.de 
> <mailto:juergen@purtz.de>> wrote:
>
>     What I have done so far is:
>
>       * Conversion of sgml files to valid xml syntax with a perl
>         skript. I failed to use 'osx' or 'spam'.
>       * Conversion of these xml files to Docbook5.x format using
>         xsltproc and Docbooks xslt-migration skripts.
>       * Creation of html files using xsltproc and Docbooks xslt skripts.
>       * Creation of fo files using xsltproc and Docbooks xslt skripts.
>       * Creation of pdf files using fop.
>       * The conversions needs less than 10 minutes on a Intel i5
>         processor.
>
> So you believe you have/can convert between the two formats 
> accurately, so we can change things in a single commit?
>
> What verification is offered? Possible?
>
> And that is ready to go now? Will you post your perl script, or the 
> patch? Other projects use the same file formats, e.g. Slony, XL etc
>
> If an automatic migration is possible do we need to change at all?
>
> -- 
> Simon Riggs http://www.2ndQuadrant.com/ <http://www.2ndquadrant.com/>
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


--------------020804080809070105090108
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">
    Hello,<br>
    <br>
    the conversion of PostgreSQL documentation from Docbook 4.x to 5.x
    consists of the following steps:<br>
    <ol>
      <li>pure sgml --&gt; xml conversion (done, Perl script)<br>
      </li>
      <li>4.x markup --&gt; 5.x markup (done, Docbook standard migration
        script)</li>
      <li>post-processing of 5.x files (done, Perl: xi:include,
        entities, ...)</li>
      <li>generate the complete file postgres_all.xml with xmllint
        (done)<br>
      </li>
      <li>generate online documentation (html, man, text)</li>
      <li>generate print documentation (rtf, pdf) <br>
      </li>
      <li>adopt Makefile to the new situation<br>
      </li>
    </ol>
    After step 3 we have well-formed xml files, most of them are valid
    against Docbook 5.0 xsd. Actually the following non-valid situations
    occur:<br>
    <ul>
      <li>a lot of unknown xref targets, as the target exists in a
        different file</li>
      <li>4 remaining sgml-entities: standalone-xxx and include-xxx<br>
      </li>
      <li>some markups, which are not valid in 5.x, mostly with
        &lt;synopsis&gt; and &lt;function&gt;. This must be resolved
        manually (5.x offers comprehensive possibilities for very
        detailed markups with &lt;funcsynopsis&gt; and
        &lt;cmdsynopsis&gt;)</li>
    </ul>
    Steps 5 and 6 implies the replacement of our dsssl script with xslt
    scripts. I guess that this is much more difficult and lengthy than
    everything else I have done in this project so far. Furthermore I
    don't have any knowledge about dsssl. And this is the reason why I
    write this mail. Is anybody out there who can support me for the
    dsssl --&gt; xslt conversion - or at least can answer questions
    like:<br>
    <ul>
      <li>Is our file stylesheet.dsl written from scratch - or is it
        derived from any docbook 1/2/3/4.x generic stylesheet?</li>
      <li>Which person has developed this file?</li>
      <li>What is the role of the *.xsl files in the sgml-directory and
        how do they collaborate with stylesheet.dsl? <br>
      </li>
    </ul>
    Regards, Jürgen<br>
    <br>
    <br>
    <br>
    <div class="moz-cite-prefix">On 20.04.2016 20:41, Simon Riggs wrote:<br>
    </div>
    <blockquote
cite="mid:CANP8+jJdn=riff_qstQ+C7784o1gK5rgbJtnXKZ+5FTZxVBn7Q@mail.gmail.com"
      type="cite">
      <div dir="ltr">On 20 April 2016 at 15:30, Jürgen Purtz <span
          dir="ltr">&lt;<a moz-do-not-send="true"
            href="mailto:juergen@purtz.de" target="_blank">juergen@purtz.de</a>&gt;</span>
        wrote:<br>
        <div class="gmail_extra">
          <div class="gmail_quote">
            <div> </div>
            <blockquote class="gmail_quote" style="margin:0px 0px 0px
0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
              <div text="#000000" bgcolor="#FFFFFF"><font
                  face="Helvetica, Arial, sans-serif">What I have done
                  so far is:<br>
                </font>
                <ul>
                  <li><font face="Helvetica, Arial, sans-serif">Conversion

                      of sgml files to valid xml syntax with a perl
                      skript. I failed to use 'osx' or 'spam'.</font></li>
                  <li><font face="Helvetica, Arial, sans-serif">Conversion

                      of these xml files to Docbook5.x format using
                      xsltproc and Docbooks xslt-migration skripts.</font></li>
                  <li><font face="Helvetica, Arial, sans-serif">Creation
                      of html files using xsltproc and Docbooks xslt
                      skripts.</font></li>
                  <li><font face="Helvetica, Arial, sans-serif">Creation
                      of fo files using xsltproc and Docbooks xslt
                      skripts.</font></li>
                  <li><font face="Helvetica, Arial, sans-serif">Creation
                      of pdf files using fop.</font></li>
                  <li><font face="Helvetica, Arial, sans-serif">The
                      conversions needs less than 10 minutes on a Intel
                      i5 processor.<br>
                    </font></li>
                </ul>
              </div>
            </blockquote>
            <div>So you believe you have/can convert between the two
              formats accurately, so we can change things in a single
              commit?</div>
            <div><br>
            </div>
            <div>
              <div class="gmail_quote">What verification is offered?
                Possible?</div>
            </div>
            <div><br>
            </div>
            <div>And that is ready to go now? Will you post your perl
              script, or the patch? Other projects use the same file
              formats, e.g. Slony, XL etc</div>
            <div><br>
            </div>
            <div>If an automatic migration is possible do we need to
              change at all?</div>
            <div><br>
            </div>
          </div>
          -- <br>
          <div class="gmail_signature">
            <div dir="ltr"><span style="color:rgb(136,136,136)">Simon
                Riggs                </span><a moz-do-not-send="true"
                href="http://www.2ndquadrant.com/"
                style="color:rgb(17,85,204)" target="_blank">http://www.2ndQuadrant.com/</a><br
                style="color:rgb(136,136,136)">
              <span style="color:rgb(136,136,136)">PostgreSQL
                Development, 24x7 Support, Remote DBA, Training &amp;
                Services</span><br>
            </div>
          </div>
        </div>
      </div>
    </blockquote>
    <br>
  </body>
</html>

--------------020804080809070105090108--