From: Alexander Lakhin <exclusion@gmail.com>
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
To: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: backpatching documentation after conversion to XML
Date: Sun, 22 Oct 2017 18:33:26 +0300
Message-ID: <dec8f417-4b42-4e4f-8dfd-d8256bb437b4@gmail.com> (raw)
In-Reply-To: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com>
References: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
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
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: exclusion@gmail.com, peter.eisentraut@2ndquadrant.com
Subject: Re: backpatching documentation after conversion to XML
In-Reply-To: <dec8f417-4b42-4e4f-8dfd-d8256bb437b4@gmail.com>
* 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