Re: Docbook 5.x

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: pgsql-docs(at)postgresql(dot)org
Subject: Re: Docbook 5.x
Date: 2016-11-16 14:40:33
Message-ID: 542a25dc-d951-78de-45fa-ba0de06834fd@purtz.de
Views: Raw Message | Whole Thread | Download mbox
Thread:
Lists: pgsql-docs


> Hello Peter,
>
> I saw that you committed the patch to switch the html build to XSLT by
> default.
> So It seems, now we can continue the move to XML.
> I'd suggest to move in several steps.
> Please see the attached scripts.
> The main script is 7_check_conversion.sh. It performs all the
> conversion and checks whether the html output is the same.
> I suggest to split conversion in three commits.
> Commit#0 is for manual corrections - it replaces "<" with "&lt;" and
> so on in some sgml's and it doesn't affect the build or outputs.
> It needed just for the next step - automatic conversion. These changes
> to sgml's are countable and observable.
>
> Commit#1 performs conversion of all SGML's to make them compatible
> with XML (as much as possible). (Thanks to Jurgen for his sgml2xml.pl
> script.)
> These changes to sgml's are massive, but they are produced
> automatically, so we need just to check the script and make sure that
> the output is the same.
> After that commit we still can use SGML build.
>
> And the last commit, commit#2 is for switching to XML. At that point
> doc/src/sgml renamed to doc/src/xml, build environment modified and
> cleaned, but changes in sgml/xml are minimal, so we can observe and
> check them.
>
> After the commit#2 we get all our docs in XML (DocBook 4.2) and can
> build it just as we did with 'make html/man/...' before.
> Maybe the commit#2 should be applied later, but commits #0 and #1 are
> not intrusive and can be applied anytime.
>
> Best regards,
> Alexander
>

Hello,

I greatly welcome the next steps toward XML.

In addition to the submitted scripts I want to point out that we will
get validation error messages if the following three things coincide: a)
Docbook 4.2, b) use of XInclude, c) a different directory (eg: 'ref').
The xi:base attribute (to specify a different directory) was introduced
into the Docbook DTD with version 4.3. Older DTDs cannot use it without
manual changes to the DTD, please see:
http://www.sagehill.net/docbookxsl/ValidXinclude.html. To overcome this
shortage I suggest the use of Docbook 4.3 (or 4.5) - as a separate
commit or implicitly with commit #2. As far as I have seen, all
converted documents validate against 4.5.

Kind regards
Jürgen Purtz

In response to

Browse pgsql-docs by date

  From Date Subject
Next Message Gunnar "Nick" Bluth 2016-11-16 21:07:41 Re: Missing important information in backup.sgml
Previous Message Stephen Frost 2016-11-16 14:36:51 Re: Missing important information in backup.sgml