Re: Docbook 5.x

From: Alexander Law <exclusion(at)gmail(dot)com>
To: Jürgen Purtz <juergen(at)purtz(dot)de>, pgsql-docs(at)postgresql(dot)org
Subject: Re: Docbook 5.x
Date: 2016-05-04 18:00:13
Message-ID: 572A38AD.80007@gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

04.05.2016 19:52, Jürgen Purtz пишет:
> On 04.05.2016 17:08, Alexander Law wrote:
>> As was stated in the aforementioned thread, solution 2 can be much
>> (8x) faster with some xslt optimizations, but I think now we should
>> outline some roadmap before we start to prepare patches and so.
>> Maybe we should convert to XML with DocBook4 at first step?
>> Then, once we get everything stabilized, we can upgrade to DocBook5.
>> Shouldn't we decompose the conversion procedure, so we could perform
>> fully automatic conversion without any manual changes, and then fix
>> non-valid situations, you described before?
>
> Hello Alexander,
>
> I havn't seen your xslt optimization so far. What have you done? Where
> can I find the optimized script or a description?
It was attached to the message:
http://www.postgresql.org/message-id/562E061B.1090809@postgrespro.ru
> "Divide and conquer" is a good strategy and people use it in many
> cases. As you have stated, there are two major steps: from db4-sgml to
> db4-xml and from there to db5-xml. In parallel to the second one we
> shall migrate from dsl scripts to db5-xslt scripts. Your idea to go
> step by step and stabilise at the intermediate level is good in
> general. But in this case it may be unnecessary. The first step is
> very small. It consists mainly of the elimination of shorttags and
> empty elements. This is a pure formal act without risk. If we would
> stop at this point, people are forced to switch their environment, eg
> .emacs from db4-sgml to db4-xml - and after the second step to
> db5-xml. This is possible - but the twice changing will bring
> (possibly) more confusion than advantages. The real challenge is the
> second step as it implies some manual modifications (entities,
> non-valid markup in sense of db5-schema) and a switch to a different
> output chain. Maybe we can live for a while with some files, which are
> not valid against db5-schema - as far as the output chain produces
> correct results.
By first step I mean SGML->XML conversion (while staying with DocBook4).
It's not small, IMHO, as it involves all the doc/sgml contents replacing
(with doc/xml or alike) and updating makefile (replacing 'html' target
with 'xslthtml' and so on).
Though it can (and should) be performed as one commit with using one
conversion script.
The advantage of "baby steps" for me is an opportunity to play safe.
In fact it's the question of balance between amount of redundant work
and manageability of the conversion.
IMO, amount of redundant work is not so large as:
1) we should convert and sgml->xml anyway
2) we can use existing makefile's targets
3) we should update documentation on documentation ([1], [2]) anyway.

[1] http://www.postgresql.org/docs/9.5/interactive/docguide-build.html
[2] http://www.postgresql.org/docs/9.5/interactive/docguide-authoring.html

Alexander Lakhin

In response to

Browse pgsql-docs by date

  From Date Subject
Next Message Jürgen Purtz 2016-05-04 18:06:23 Re: Docbook 5.x
Previous Message Alvaro Herrera 2016-05-04 17:12:05 Re: Docbook 5.x