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
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 |