From: Jürgen Purtz <juergen@purtz.de>
To: pgsql-docs@lists.postgresql.org
Subject: Re: DocBook 5.2
Date: Mon, 5 Sep 2022 16:40:33 +0200
Message-ID: <01689f3f-415c-bbd3-7c0f-5373b6c7072b@purtz.de> (raw)
In-Reply-To: <CAECtzeWEZnJ1zyKqrHvuq_5hRTvD8j6FwnQCodvY-xWx41GkKA@mail.gmail.com>
References: <ae14eca5-f57c-2db2-42ce-258bab3c6806@purtz.de>
<20220905111508.wzgmpbcarxizdnin@alvherre.pgsql>
<CAECtzeWEZnJ1zyKqrHvuq_5hRTvD8j6FwnQCodvY-xWx41GkKA@mail.gmail.com>
On 05.09.22 14:15, Guillaume Lelarge wrote:
> Le lun. 5 sept. 2022 à 13:14, Alvaro Herrera <alvherre@alvh.no-ip.org>
> a écrit :
>
> On 2022-Sep-05, Jürgen Purtz wrote:
>
> > - <sect1 id="xtypes">
> > + <sect1 xml:id="xtypes">
> > <title>User-Defined Types</title>
>
> OK, these seem quite significant changes that are likely to cause
> great
> pain. So I repeat my question, what are the benefits of making this
> change? They better be very very substantial.
>
>
> I totally agree with Alvaro.
>
> They will also cause massive pain for translators. There are already
> some changes that were pretty bad for me. For example, when all the
> tables in func.sgml were modified. In v15, I also remember massive
> changes on protocol.sgml. I won't complain if there is a significant
> benefit for readers, which is why I didn't complain for func.sgml even
> if it meant I had to translate it all over again. But if there's a
> massive change over the whole manual for a strictly limited benefit, I
> guess there won't be enough motivation for me to translate it all over
> again.
>
>
> --
> Guillaume.
The goal of the migration is an approximation to today's technology,
especially programming interfaces and standards, to be able to use and
interact with nowadays tools. Of course, this leads to internal
technical changes. It is not intended to change anything at the readers
surface. In that respect, it is comparable with the sgml to xml conversion.
* The introduction of RELAX NG instead of DTDs leads to a much richer
controlling of the sgml files.
* The introduction of namespaces instead of a DOCTYPE definition
offers the possibility to integrate tags of other namespaces into
our documentation, eg.: MathML, XInclude, XLink, ... .
* The changes during the migration consist mainly in a renaming of
tag-names. The most important for us is 'ulink'.
* After the migration the validation is much stricter than before.
Because we have used tags in a more or less 'individual' style,
especially when describing commands, there are a lot of violations
against the RELAX NG schema. Modifications caused by such problems
are those, which will create the most pain - for back-patching as
well as for translators.
* Possibly the pain for translators decreases significantly by using
the same migration scripts on their already translated sgml files.
* I don't understand where the pain for back-patching is when the
attribute 'id' changes to 'xml:id'. It is very unlikely that the id
of a section or another tag will change, or something else in such
lines. In nearly all cases such lines will keep as they are,
back-patching will not be necessary at such places.
What is the alternative to a migration? DocBook 4.5 forever?
--
J. Purtz
Attachments:
[image/png] pNPPzronN9L77gPY.png (47.6K, ../01689f3f-415c-bbd3-7c0f-5373b6c7072b@purtz.de/3-pNPPzronN9L77gPY.png)
download | view image
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: juergen@purtz.de, pgsql-docs@lists.postgresql.org
Subject: Re: DocBook 5.2
In-Reply-To: <01689f3f-415c-bbd3-7c0f-5373b6c7072b@purtz.de>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox