From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
To: pgsql-docs <pgsql-docs@postgresql.org>
Subject: backpatching documentation after conversion to XML
Date: Sat, 21 Oct 2017 12:57:00 -0400
Message-ID: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com> (raw)
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
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.
When we finally convert the sources from SGML to XML, we will have to
change empty tags such as
<xref linkend="foo">
to XML syntax
<xref linkend="foo"/>
(like HTML versus XHTML). The problem is that if you backpatch that
literally into an SGML source, it will be interpreted as
<xref linkend="foo">>
(i.e., an additional character will appear in the output) without an
indication of an error.
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.
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?
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
--
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: peter.eisentraut@2ndquadrant.com
Subject: Re: backpatching documentation after conversion to XML
In-Reply-To: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.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