Re: Docbook 5.x

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: Simon Riggs <simon(at)2ndQuadrant(dot)com>, pgsql-docs(at)postgresql(dot)org
Subject: Re: Docbook 5.x
Date: 2016-05-03 19:19:40
Message-ID: 5728F9CC.7050402@purtz.de
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

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(at)purtz(dot)de
> <mailto:juergen(at)purtz(dot)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

In response to

Browse pgsql-docs by date

  From Date Subject
Next Message Alvaro Herrera 2016-05-03 19:34:42 Re: Docbook 5.x
Previous Message Josh berkus 2016-05-03 16:14:34 Fwd: [CORE] Documentation Error: Ceiling, Floor