Diff of this page with other version

From: Marcos Pegoraro <marcos(at)f10(dot)com(dot)br>
To: pgsql-www(at)postgresql(dot)org
Subject: Diff of this page with other version
Date: 2024-03-02 14:35:41
Message-ID: CAB-JLwYmR+sW9spQQMjnLT0hbAR_3qTCqqJgt-sC3=NgCSJyRg@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-www

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

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.

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.

Users would select this option following this: On every doc page you have
on title Supported Versions: 16 / 15 / 14 / 13 / 12. Then, if we have on
the right of that some options like Compare Version: rb16 / rb15 / rb14 /
rb13 / rb12. If these rb16, rb15 are radio buttons, I can compare the
actual page with one of previous versions, only one comparison each time.

This comparison would be only with previous versions. We are on page 13,
radio buttons are 13, 12, 11 and so on. You'll never compare 13 with a
greater version and if you compare 13 with 13 obviously nothing changes on
the appearance of that page.

And to show those changes we need just a small Javascript which will
repaint the page we are seeing with those green colors depending on version
you are and what you are comparing to.

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.

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.

The attached image shows what it would do

Attachment Content-Type Size
DocDiff.png image/png 144.8 KB

Responses

Browse pgsql-www by date

  From Date Subject
Next Message Alvaro Herrera 2024-03-02 14:44:32 Re: Diff of this page with other version
Previous Message Allan Rey Quiban 2024-03-01 16:12:40