pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedbackpatching documentation after conversion to XML
7+ messages / 4 participants
[nested] [flat]
* backpatching documentation after conversion to XML
@ 2017-10-21 16:57 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-10-22 07:30 ` Re: backpatching documentation after conversion to XML Jürgen Purtz <juergen@purtz.de>
2017-10-22 15:33 ` Re: backpatching documentation after conversion to XML Alexander Lakhin <exclusion@gmail.com>
0 siblings, 2 replies; 7+ messages in thread
From: Peter Eisentraut @ 2017-10-21 16:57 UTC (permalink / raw)
To: pgsql-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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: backpatching documentation after conversion to XML
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2017-10-22 07:30 ` Jürgen Purtz <juergen@purtz.de>
1 sibling, 0 replies; 7+ messages in thread
From: Jürgen Purtz @ 2017-10-22 07:30 UTC (permalink / raw)
To: pgsql-docs
On 21.10.2017 18:57, Peter Eisentraut wrote:
> 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.
Just to classify the impact: afaik we use the 'empty tag' technique for
the three docbook tags 'xref' (>3000 times), 'co' (7 times), and
'footnoteref' (4 times).
Jürgen Purtz
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: backpatching documentation after conversion to XML
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2017-10-22 15:33 ` Alexander Lakhin <exclusion@gmail.com>
2017-10-22 16:42 ` Re: backpatching documentation after conversion to XML Tom Lane <tgl@sss.pgh.pa.us>
2017-11-03 18:29 ` Re: backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 2 replies; 7+ messages in thread
From: Alexander Lakhin @ 2017-10-22 15:33 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; pgsql-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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: backpatching documentation after conversion to XML
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-10-22 15:33 ` Re: backpatching documentation after conversion to XML Alexander Lakhin <exclusion@gmail.com>
@ 2017-10-22 16:42 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-10-22 18:00 ` Re: backpatching documentation after conversion to XML Alexander Lakhin <exclusion@gmail.com>
1 sibling, 1 reply; 7+ messages in thread
From: Tom Lane @ 2017-10-22 16:42 UTC (permalink / raw)
To: Alexander Lakhin <exclusion@gmail.com>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; pgsql-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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: backpatching documentation after conversion to XML
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-10-22 15:33 ` Re: backpatching documentation after conversion to XML Alexander Lakhin <exclusion@gmail.com>
2017-10-22 16:42 ` Re: backpatching documentation after conversion to XML Tom Lane <tgl@sss.pgh.pa.us>
@ 2017-10-22 18:00 ` Alexander Lakhin <exclusion@gmail.com>
0 siblings, 0 replies; 7+ messages in thread
From: Alexander Lakhin @ 2017-10-22 18:00 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; pgsql-docs
22.10.2017 19:42, Tom Lane writes:
>> 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.
I understand the major difficulties we have to deal with. I have the
following plan in mind:
1. Get a diff for a single xml.
2. Find corresponding sgml in the old target branch.
3. Convert the sgml to xml following the same procedure that we applied
for the master branch.
4. Try to apply the diff.
5. If it's applied successfully, detect the lines where changes occured
(sgml->xml conversion doesn't move the lines) and
modify corresponding lines in sgml with the content modified for sgml
(<xref .../> changed to <xref > and so on.)
I think this should work for 90% of cases.
------
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: backpatching documentation after conversion to XML
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-10-22 15:33 ` Re: backpatching documentation after conversion to XML Alexander Lakhin <exclusion@gmail.com>
@ 2017-11-03 18:29 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-11-10 13:51 ` Re: backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 1 reply; 7+ messages in thread
From: Peter Eisentraut @ 2017-11-03 18:29 UTC (permalink / raw)
To: Alexander Lakhin <exclusion@gmail.com>; pgsql-docs
On 10/22/17 11:33, Alexander Lakhin wrote:
> Peter, are you going to rename all the *.sgml to *.xml (and to move the
> files from sgml/ to /xml directory) as I did?
Not at the moment, but maybe later. That can be a separate discussion.
> If so (I think it would be right), then backpatching without some
> modifications will be impossible anyway.
git cherry-pick should be able to handle it.
>> Another workaround would be to backpatch a check that greps for
>> something like '[^<]/>' in *.sgml and errors on that.
I have since figured out that the SP option -wnet will cause errors on
XML-style empty tags, so I plan to proceed that way after the minor
releases.
--
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: backpatching documentation after conversion to XML
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-10-22 15:33 ` Re: backpatching documentation after conversion to XML Alexander Lakhin <exclusion@gmail.com>
2017-11-03 18:29 ` Re: backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2017-11-10 13:51 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 0 replies; 7+ messages in thread
From: Peter Eisentraut @ 2017-11-10 13:51 UTC (permalink / raw)
To: Alexander Lakhin <exclusion@gmail.com>; pgsql-docs
On 11/3/17 14:29, Peter Eisentraut wrote:
>>> Another workaround would be to backpatch a check that greps for
>>> something like '[^<]/>' in *.sgml and errors on that.
> I have since figured out that the SP option -wnet will cause errors on
> XML-style empty tags, so I plan to proceed that way after the minor
> releases.
I have committed that.
--
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
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2017-11-10 13:51 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2017-10-21 16:57 backpatching documentation after conversion to XML Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-10-22 07:30 ` Jürgen Purtz <juergen@purtz.de>
2017-10-22 15:33 ` Alexander Lakhin <exclusion@gmail.com>
2017-10-22 16:42 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-10-22 18:00 ` Alexander Lakhin <exclusion@gmail.com>
2017-11-03 18:29 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-11-10 13:51 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
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