Thread: [DOCS] backpatching documentation after conversion to XML
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
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
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
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
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
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
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