Re: backpatching documentation after conversion to XML

Hello,
21.10.2017 19:57, Peter Eisentraut wrote:
> In a nearby message, Tom pointed out that the ongoing conversion of the
> documentation sources from SGML to XML could/will cause problems when
> backpatching. The changes made so far would merely cause merge
> conflicts but there is an additional issue to consider that can cause
> compatibility problems.
Peter, are you going to rename all the *.sgml to *.xml (and to move the
files from sgml/ to /xml directory) as I did?
If so (I think it would be right), then backpatching without some
modifications will be impossible anyway.
> One workaround (other than being careful) would be to write
>
> <xref linkend="foo"></xref>
>
> and maintain that style until the last SGML-based version goes EOL.
I've tried to write '<xref linkend="installation"></xref>' in start.sgml
and got:
/usr/bin/osx -wall -wno-unused-param -wfully-tagged -wempty -wdata-delim
-winstance-ignore-ms -winstance-include-ms -winstance-param-entity -D .
-D . -x lower postgres.sgml >postgres.xml.tmp
/usr/bin/osx:start.sgml:32:63:E: end tag for element "XREF" which is not
open
It seems that this workaround will not work. (The xref tag in sgml
considered as closed automatically.)

> Another workaround would be to backpatch a check that greps for
> something like '[^<]/>' in *.sgml and errors on that.
>
> (AFAICT, this is the last major issue impacting the conversion, so when
> we have resolved this, this can go ahead.)
>
> Thoughts?

I think we should make a script to backport doc/-related commits. So for
each commit we want to backport we would need to split a "doc/" part and
to convert it (move from xml to sgml, change a file extension, convert
tags, the attributes case and so on...). Maybe some of the changes can
be backported to simplify the script, but we will need to perform some
processing anyway.

I can write such a script if it can be useful.

Best regards,

------
Alexander Lakhin
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company