From: Tom Lane <tgl@sss.pgh.pa.us>
To: Alexander Lakhin <exclusion@gmail.com>
Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: backpatching documentation after conversion to XML
Date: Sun, 22 Oct 2017 12:42:44 -0400
Message-ID: <14052.1508690564@sss.pgh.pa.us> (raw)
In-Reply-To: <dec8f417-4b42-4e4f-8dfd-d8256bb437b4@gmail.com>
References: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com>
<dec8f417-4b42-4e4f-8dfd-d8256bb437b4@gmail.com>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
Alexander Lakhin <exclusion@gmail.com> writes:
> 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.
That's true, but I'd at least like the diffs to apply to the .sgml
files in the older branches. I'm not sure whether git's built-in
support for file renames would handle such cases automatically;
but even if it doesn't, having to account for these changes by hand
will raise the pain factor very substantially.
> I think we should make a script to backport doc/-related commits.
That's an interesting idea, but I really doubt that you'll be able
to make a script that copes with this without having back-patched
the changes we're discussing. As an example, any given closing tag
might've already been spelled out in the back branches; we've never
been consistent about that. So you couldn't just automatically
shorten all the closing tags and expect to have a patch that applies.
BTW, there is also this recent complaint that we're now emitting
HTML anchors in all-lower-case:
https://www.postgresql.org/message-id/os1mii$lpk$1@blaine.gmane.org
I assume this is a toolchain change rather than a source code change,
so there's not a lot we can do to undo the change. However, if we were
to downcase all the SGML IDs in the back branches, then at least the
anchors would be consistent across versions. That's probably not the
answer that Kellerer wanted, but it's better than the status quo.
(And it'd be good to get it done before next month's update releases.)
regards, tom lane
--
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: tgl@sss.pgh.pa.us, exclusion@gmail.com, peter.eisentraut@2ndquadrant.com
Subject: Re: backpatching documentation after conversion to XML
In-Reply-To: <14052.1508690564@sss.pgh.pa.us>
* 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