Re: Diff of this page with other version

I do agree, automation is the way. But automation of what, SGML or HTML.
I think it is better to have an automated way to input some tags on SGML,
but then verify manually if those steps done are correct and then create
all HTML correctly, instead of running an on-the-fly htmldiff.

Let me explain why some automated HTML diff could not work properly.

1 - Only added text, easy to solve, paint all that line.
PLPGSQL.SGML - Version 16:
<replaceable>variable</replaceable>%TYPE
Version devel:
<replaceable>name</replaceable>
<replaceable>table</replaceable>.<replaceable>column</replaceable>%TYPE
<replaceable>name</replaceable> <replaceable>variable</replaceable>%TYPE

2 - Some texts were changed only to a better text, but this time will show
the
entire paragraph or word by word ? Because the change can happen on
10 or 20 words spread for 5 lines. So it'll not be pretty to have a word
with style, followed by another without, followed by another with style
again for several lines.
ALTER_TABLE.SGML - Version 16:
<command>CREATE INDEX CONCURRENTLY</command>, and then *install* it
*as an official *constraint using this syntax. See the example below.
Version devel:
<command>CREATE UNIQUE INDEX CONCURRENTLY</command>, and then
*convert* it to a
constraint using this syntax. See the example below.

3 - Some texts only changed an internal tag, this time literal by
replaceable.
MERGE.SGML - Version 16:
<literal>data_source</literal> row.
If used in a <literal>WHEN NOT MATCHED</literal> clause, the
expression can use values from the *<literal>*data_source*</literal>*.
Version devel:
<replaceable>data_source</replaceable> row.
If used in a <literal>WHEN NOT MATCHED</literal> clause, the
expression can use values from the *<replaceable>*data_source
*</replaceable>*.

But sometimes it would be better that the committer could choose how it is
better
to emphasise that text. This text is better to show diff only on superuser
word or
the entire paragraph should be shown diff ?
USER-MANAGE.SGML - Version 16:
Also note that, because this automatic
grant is granted by the bootstrap *user*, it cannot be removed or
changed by
the <literal>CREATEROLE</literal> user;
Version devel:
Also note that, because this automatic
grant is granted by the bootstrap *superuser*, it cannot be removed or
changed by
the <literal>CREATEROLE</literal> user;

Some are a mix of new and changed.
XINDEX.SGML - Version 16:
GiST indexes have *eleven* support functions, *six* of which are
optional,
Version devel:
GiST indexes have *twelve* support functions, *seven* of which are
optional,
...
<row>
<entry><function>stratnum</function></entry>
<entry>translate well-known strategy numbers to ones
used by the operator class (optional)</entry>
<entry>12</entry>
</row>

Some others removed something, so will it add a blank red line to show diff
?
VACUUM.SGML - version 16:
When the option list is surrounded by parentheses, the options can be
written in any order. Without parentheses, options must be specified
in exactly the order shown above.
version devel:

Some were changed only href
ALTER_PUBLICATION.SGML - version 16:
<link linkend="sql-createpublication-for-table"><literal>FOR
TABLE</literal></link>/
version devel:
<link linkend="sql-createpublication-*params*-for-table"><literal>FOR
TABLE</literal></link>/

Some were changed only item number on rendered HTML.
functions-json.html - Version 15:
Table *9.49*. jsonpath Operators and Methods
Version 16:
Table *9.50*. jsonpath Operators and Methods

So, I think the better way is to have a tool to show diffs and give to the
committer
the responsibility to choose which one is better.
I know this is a huge job, but once it is done the only thing needed is
that all
new commits should be done with this additional DIFF step.
If we think only in supported versions and go changing all from older. All
diffs found on
version 12 should be on version 13 too. All diffs from 12 and 13 should be
on 14 and so on
So, if you compare any file with any of its previous supported versions, it
would work.

regards
Marcos

Em sáb., 2 de mar. de 2024 às 17:28, Jimmy Angelakos <vyruss(at)hellug(dot)gr>
escreveu:

> On 02/03/2024 17:33, Tom Lane wrote:
>
> Erik Wienhold <ewie(at)ewie(dot)name> writes:
>
> I think you underestimate the effort because the changes are not always
> as clear (adding one line) as for copy.sgml as you've shown above. For
> example, if I check create_table.sgml between v15 and v16, I see that
> the addition of STORAGE modified an existing line. So that regex has to
> match and wrap just the relevant substring. When new storage modes are
> added we end up with nested version info in order to compare vXX with
> pre v16:
>
>
> Yeah. I think the chances of getting people to do this in the .sgml
> files are precisely zero. What might have a chance of happening is
> to provide a way on the website of running htmldiff or similar tool
> over two versions of a doc page on-the-fly and show the results.
>
> regards, tom lane
>
> I agree with Tom, I think automation of this process is the way to go here.
>
> Best regards,
> Jimmy
>