Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1rgmaN-007w6K-3w for pgsql-www@arkaria.postgresql.org; Sun, 03 Mar 2024 14:13:03 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1rgmaL-0016bH-13 for pgsql-www@arkaria.postgresql.org; Sun, 03 Mar 2024 14:13:01 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1rgmaK-0016b9-7J for pgsql-www@lists.postgresql.org; Sun, 03 Mar 2024 14:13:01 +0000 Received: from mail-ej1-x62d.google.com ([2a00:1450:4864:20::62d]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.94.2) (envelope-from ) id 1rgmaC-002Z35-Fp for pgsql-www@postgresql.org; Sun, 03 Mar 2024 14:12:59 +0000 Received: by mail-ej1-x62d.google.com with SMTP id a640c23a62f3a-a4536b16523so21258766b.3 for ; Sun, 03 Mar 2024 06:12:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=f10-com-br.20230601.gappssmtp.com; s=20230601; t=1709475170; x=1710079970; darn=postgresql.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=gAxXOg9BKigw5S99rGZ4vMxzHFg2MG+g1hXL3UcqX2g=; b=D1aCBAUUiZ9op+7Ntq/knL4HxmciyPAwWnlO5y+AXDB47IkQ/64eBFHuxKQ8g9Pacn sF6n+YJEDwJLDNpUq8xhjOVqGEVP3yQvDelim2CrtOLNSFLjGj7q2BSyiEOp72Mqo85D DcIVY+zpw9ccBIGUo0IkTOrgTkc3XK2yILNY1IUK6Z3WsaEg/IEIYGL+pka3ByQ8jCwa t4iuwndUfOeQc6nLgyfPhhgXj4djIgI3tN0t4l1owtV5Y5HkVqM1mrICUac1myl9kAXZ 0Tg9hHVNHfn+hYt/h4/0pJYu9d8AiOx/LdflXe0RqpWp7piSX3iKHzR3CM7YUCdhnPlL PtVg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709475170; x=1710079970; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=gAxXOg9BKigw5S99rGZ4vMxzHFg2MG+g1hXL3UcqX2g=; b=E/rSqsB45jLaQ3/6rx8LMpogZ1GLoFJEu8K6FKkg6BU+48+ZYJBsQO2H4bpuLFdIvs bv5YWd1PuSaVMQyUdHO9HSeczCI60WVOaY4e8gpjW71i/oJaxaElgzvHpKc6HHQ3zoHw mRwh5yK5yaXZm+boWITZ0vndsoPgX6b4johyqHM+VbUs5ucEukP919jzVRGeSk9BVPK0 mNq15FcMhy7Et4qd80Ukwu+aCR5rWgq8q5uMxZ03YH0++1Ewp3ZDtf7iZXGTKsD7lgUh N7bi92aRHatQcin8rtCH0hdXjBD2v2h9ZKBKbx9IqzLqo4rDCbsSFnFa/HuDa65Objqb eKuw== X-Forwarded-Encrypted: i=1; AJvYcCX7smmN+MChxKFhTKPH+E/u63UTmFv/OJh1RofDJSvfwpeTYtfFc3airS4CKfFGVf+j3NtSZ+bzQNyYZi1clBarCHklWl7b3GE= X-Gm-Message-State: AOJu0YxpcsQh5G6x/p542YZmisWLX4tCpY2E8aShdHho5hVvQskwUAer 7MwydqWGI2VOgYwKVdZBULrvXeOp0GNOxwVXFImvg6bvYv8daKh3WHv6N71HZVejSvBGQZo3Yta dkh1xi31M6Y9ywd1bMmi4PPTahLnZ1Bs88Hr8 X-Google-Smtp-Source: AGHT+IHsrdgi5J0UmPg+E5b/rkqi/Rgwt6ugsLGrAbE9pwTWag8cLpl6sf9AN4z8LYThtYbfxzhb6J/0DFj6qGWwDB8= X-Received: by 2002:a17:906:3c4c:b0:a44:1f23:7d55 with SMTP id i12-20020a1709063c4c00b00a441f237d55mr3949505ejg.25.1709475170429; Sun, 03 Mar 2024 06:12:50 -0800 (PST) MIME-Version: 1.0 References: <3129677.1709400823@sss.pgh.pa.us> In-Reply-To: From: Marcos Pegoraro Date: Sun, 3 Mar 2024 11:12:02 -0300 Message-ID: Subject: Re: Diff of this page with other version To: Jimmy Angelakos Cc: Tom Lane , Erik Wienhold , pgsql-www@postgresql.org Content-Type: multipart/alternative; boundary="000000000000493f550612c23403" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --000000000000493f550612c23403 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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: variable%TYPE Version devel: name table.column%TYPE name variable%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: CREATE INDEX CONCURRENTLY, and then *install* it *as an official *constraint using this syntax. See the example below= . Version devel: CREATE UNIQUE INDEX CONCURRENTLY, 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: data_source row. If used in a WHEN NOT MATCHED clause, the expression can use values from the **data_source**= . Version devel: data_source row. If used in a WHEN NOT MATCHED clause, the expression can use values from the **data_source **. 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 CREATEROLE user; Version devel: Also note that, because this automatic grant is granted by the bootstrap *superuser*, it cannot be removed or changed by the CREATEROLE 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, ... stratnum translate well-known strategy numbers to ones used by the operator class (optional) 12 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: FOR TABLE/ version devel: FOR TABLE/ 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=C3=A1b., 2 de mar. de 2024 =C3=A0s 17:28, Jimmy Angelakos escreveu: > On 02/03/2024 17:33, Tom Lane wrote: > > Erik Wienhold 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 her= e. > > Best regards, > Jimmy > --000000000000493f550612c23403 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
<= font color=3D"#666666" style=3D"" face=3D"verdana, sans-serif">I do agree, = automation is the way. But automation of what, SGML or HTML.=C2=A0
I think it is better to have an automated way to inpu= t some tags on SGML,
but then verify manually= if those steps done are=C2=A0correct and then create=C2=A0
all HTML correctly, instead of running an on-the-fly = htmld= iff.

Let m= e explain why some automated HTML diff could not work properly.

1 - Only added text, = easy to solve, paint all that line.
PLPGSQL.S= GML - Version 16:
Version devel:
<replaceable>name</replaceabl= e> <replaceable>table</replaceable>.<replaceable>colum= n</replaceable>%TYPE
<replaceable>name</replaceable> &= lt;replaceable>variable</replaceable>%TYPE
=
2 - Some texts were changed only = to a better text, but this time will=C2=A0show the=C2=A0
entire paragraph or word by word ? Because the change can happe= n on=C2=A0
10=C2=A0or 20 words spread for 5 = lines. So it'll not be pretty=C2=A0to have a word=C2=A0
with style, followed by another=C2=A0without, followed by an= other with style=C2=A0
= again for several line= s.=C2=A0
ALTER_TABLE.SGML - Version 16:
=C2=A0=C2=A0 =C2=A0 =C2=A0 =C2=A0<comma= nd>CREATE INDEX CONCURRENTLY</command>, and then install it as an
=C2=A0 =C2= =A0 =C2=A0 =C2=A0official constraint using this syntax.=C2=A0 See the e= xample below.
Version devel:
=C2=A0 =C2=A0 =C2=A0 =C2=A0<command>CREATE UNIQUE IND= EX CONCURRENTLY</command>, and then convert it to a
=C2=A0 = =C2=A0 =C2=A0 =C2=A0constraint using this syntax.=C2=A0 See the example bel= ow.

3 = - Some texts only changed an internal tag,=C2=A0this time literal by replac= eable.=C2=A0
MERGE.SGML - Version 16:<= /div>
=C2=A0 =C2=A0 =C2=A0 <literal>data_source<= ;/literal> row.
=C2=A0 =C2=A0 =C2=A0 If used in a <literal>WHEN= NOT MATCHED</literal> clause, the
=C2=A0 =C2=A0 =C2=A0 expression= can use values from the <literal>data_source</literal&g= t;.
Version devel:
=C2=A0 =C2=A0 =C2=A0 <replaceable>data_source</replace= able> row.
=C2=A0 =C2=A0 =C2=A0 If used in a <literal>WHEN NOT = MATCHED</literal> clause, the
=C2=A0 =C2=A0 =C2=A0 expression can = use values from the <replaceable>data_source</replaceabl= e>.

But sometimes it would be better that the committer=C2=A0could choose = how it is better=C2=A0
= to emphasise=C2=A0that= text.=C2=A0This text is better to show diff only on superuser wor= d or= =C2=A0
the entire paragraph = should be shown diff ?=C2=A0
USER-MANAGE.SGML= -=C2=A0 Version 16:
Also note that, beca= use this automatic
=C2=A0 =C2=A0grant is granted by the bootstrap use= r, it cannot be removed or changed by
=C2=A0 =C2=A0the <literal&g= t;CREATEROLE</literal> user;
Versio= n devel:
Also note that, because this automat= ic
=C2=A0 =C2=A0grant is granted by the bootstrap superuser, it c= annot be removed or changed by
=C2=A0 =C2=A0the <literal>CREATEROL= E</literal> user;

Some are a mix of new and changed.=C2=A0
XINDEX.SGML - Version 16:
=C2= =A0 =C2=A0GiST indexes have eleven support functions, six of = which are optional,
Version devel:=
=C2=A0 =C2=A0GiST indexes have twelve suppo= rt functions, seven of which are optional,
=C2=A0 =C2=A0...
=C2=A0 =C2=A0 =C2= =A0 <row>
=C2=A0 =C2=A0 =C2=A0 =C2=A0<entry><function>= stratnum</function></entry>
=C2=A0 =C2=A0 =C2=A0 =C2=A0<e= ntry>translate well-known strategy numbers to ones
=C2=A0 =C2=A0 =C2= =A0 =C2=A0 used by the operator class (optional)</entry>
=C2=A0 = =C2=A0 =C2=A0 =C2=A0<entry>12</entry>
=C2=A0 =C2=A0 =C2=A0 &= lt;/row>

Some others removed something, so will it add a blank red line to s= how diff ?
VACUUM.SGML - version 16:<= /div>=C2=A0 =C2=A0When= the option list is surrounded by parentheses, the options can be
=C2=A0= =C2=A0written in any order.=C2=A0 Without parentheses, options must be spe= cified
=C2=A0 =C2=A0in exactly the order shown above.
version devel:

Some were changed only=C2=A0href
ALTER_PUBLICATION.SGML -=C2=A0version 16:
=C2=A0 =C2=A0<link linkend=3D"sql-createpublication-for-t= able"><literal>FOR TABLE</literal></link>/
version devel:
= =C2=A0 =C2=A0<link linkend=3D"sql-createpublication-params-f= or-table"><literal>FOR TABLE</literal></link>/

Some were changed o= nly=C2=A0item number on rendered=C2=A0HTML.
functions-json.html -=C2=A0Version 15:
Table <= b>9.49. jsonpath Operators and Methods
Version 1= 6:
Table 9.50. jsonpath Operators = and Methods

<= /div>
So, I think the better way is to have a tool to sh= ow diffs and give to the committer=C2=A0
the = responsibility to choose which one is better.=C2=A0=C2=A0
<= div class=3D"gmail_default" style=3D"">I know this is a huge job, but once it is done the only th= ing needed is that all=C2=A0
new commits shou= ld be done=C2=A0with=C2=A0this additional DIFF step.
If = we think only in supported versions and go changing all from older. All dif= fs found on=C2=A0
version 12 should be on ver= sion 13 too. All diffs from 12 and 13 should be on 14=C2=A0and so on
So, if you compare any file with any of its pre= vious supported versions, it would work.

=
regards
Marcos


Em s=C3=A1b., 2 de mar.= de 2024 =C3=A0s 17:28, Jimmy Angelakos <vyruss@hellug.gr> escreveu:

On 02/03/2024 17:33, Tom Lane wrote:

Erik Wienhold &= lt;ewie@ewie.name&g= t; 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.=C2=A0 For
example, if I check create_table.sgml= between v15 and v16, I see that
the addition of STORAGE modified an ex= isting line.=C2=A0 So that regex has to
match and wrap just the relevan= t substring.=C2=A0 When new storage modes are
added we end up with nest= ed version info in order to compare vXX with
pre v16:

Yeah.=C2=A0 I think the chances of getting people to do this in the .s= gml
files are precisely zero.=C2=A0 What might have a chance of happeni= ng is
to provide a way on the website of running htmldiff or similar to= ol
over two versions of a doc page on-the-fly and show the results.
=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0regards, tom lane

I agree with Tom, I think automation of this process is the way to go he= re.

Best regards,
Jimmy

--000000000000493f550612c23403--