Subject: Re: backpatching documentation after conversion to XML
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>,
 pgsql-docs <pgsql-docs@postgresql.org>
References: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com>
From: Alexander Lakhin <exclusion@gmail.com>
Message-ID: <dec8f417-4b42-4e4f-8dfd-d8256bb437b4@gmail.com>
Date: Sun, 22 Oct 2017 18:33:26 +0300
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.4.0
MIME-Version: 1.0
In-Reply-To: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Content-Language: en-US
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

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


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs