Re: Diff of this page with other version

On 2024-03-02 15:35 +0100, Marcos Pegoraro wrote:
> I think it is so common to all that it is difficult to see small diffs when
> navigating through doc pages of different versions of the same page. I'm
> not talking about completely new doc pages, like merge.sgml from version 14
> to 15, but those ones which have small diffs on that file. As an example
> consider copy.sgml

+1 for the general idea.

> Version 16 has this text
>     NULL '<replaceable class="parameter">null_string</replaceable>'
>     DEFAULT '<replaceable class="parameter">default_string</replaceable>'
>     HEADER [ <replaceable class="parameter">boolean</replaceable> | MATCH ]
>     QUOTE '<replaceable class="parameter">quote_character</replaceable>'
> 
> But version 15 has this
>     NULL '<replaceable class="parameter">null_string</replaceable>'
>     HEADER [ <replaceable class="parameter">boolean</replaceable> | MATCH ]
>     QUOTE '<replaceable class="parameter">quote_character</replaceable>'
> 
> As you can see, the DEFAULT line was added on version 16, but it is not
> easy to see what was changed on both versions.
> 
> Another example would be SQL/JSON Path Operators And Methods of func.sgml
> of version 16 and devel. There are new methods boolean(), decimal(),
> bigint(), timestamp(), timestamptz() and some others but they are not easy
> to see that they don't exist in version 16 but would be there when version
> 17 comes in.

I think that it's relatively easy to add version info to the <entry>
elements in func.sgml.  But only focusing on additions to the docs
totally misses changes to the text itself which is sometimes reworded
instead of just adding sama paragraphs.

> One can say that I have to read release notes before I upgrade a cluster
> because that page shows all important features and changes between
> versions. But sometimes this is a small info that just shows a better
> understanding of that feature or maybe we have several versions running and
> have doubts of what small feature exists in what version.
> 
> So, it would be interesting if we could visually see what was changed on
> both pages. Then, what I propose is something like you have when using a
> diff tool,  but in a single page, not side by side.
> 
> An easy way to do that would be add on all changed text a tag like
> <span class = "v16" style="background-color:green">Here goes changed or new
> text</span>
> 
> Obviously when a commit is done the committer has to add this span tag to
> that commit, so that part would be colored with green background only if
> page 16 is compared with previous ones.

The HTML is generated from the SGML docs.  So version info has to be
added there.  Or we use some automated tool to get the diff of the
rendered HTML.  W3C has a diff tool[1][2] based on GNU diffutils.  See
[3] for a diff of CREATE TABLE between v15 and v16.

> I know we have to put these tags to all files we already have but this can
> be done with some regex search tool to do this change to all files.

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:

    <span class="v16">STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | <span class="vXX">FOOBAR</span>  | DEFAULT
}</span>

> So, would this change on all doc pages be relevant ?
> If you agree with me than we can think if a tool to convert is needed or
> just a search replace is fine.

I recommend looking into [2] as a proof-of-concept.

[1] https://services.w3.org/htmldiff
[2] https://github.com/w3c/htmldiff-ui
[2]
https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2F15%2Fsql-createtable.html&doc2=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2F16%2Fsql-createtable.html

-- 
Erik