Documentation diff

On 25 Feb 2024, at 14:04, Marcos Pegoraro <marcos@f10.com.br> wrote:

There are lots of new functions and better explanations of old features.
Then my question is, how to know all pages which were changed and what exactly was changed on those pages ?

Which problem are you trying to solve? You should be reading the version of
the docs which corresponds to the version you are running. If you are trying
to figure out an upgrade then the release notes are probably a better starting
point.

--
Daniel Gustafsson

Which problem are you trying to solve? You should be reading the version
of
the docs which corresponds to the version you are running. If you are
trying
to figure out an upgrade then the release notes are probably a better
starting
point.

Daniel Gustafsson

All the time we have doubts about what function exists in what version, or
was changed.
IS JSON belongs to 15 or 16, MERGE was done on 14 or 15, as example, are
completely new, so that feature will not run on previous versions.
But sometimes a function is changed a bit or a new easier function is
added, like [1]https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS.
Before all those new JSONPATH operators and methods were added, I could do
all those operations and return anything I wanted, but they are a lot
easier.

But if I don't read that page carefully, word by word, I will not see that
that function exists. And this needs to be done on all pages.
What changes were done on CREATE TABLE for version 16 ? Hmm, cool, STORAGE
can be defined at CREATE TABLE stage and not only at ALTER TABLE anymore.
But to know that I have to read that page carefully, do you understand me ?

So I was thinking of a way to get differences between this and that
versions, and for all doc pages.
Something like we already have on [2]https://www.postgresql.org/about/featurematrix/, it explicits, this feature was
introduced, this was changed, this does not exist anymore.

[1]: https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS
https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS
[2]: https://www.postgresql.org/about/featurematrix/

regards
Marcos

On 2/25/24 08:38, Marcos Pegoraro wrote:

Which problem are you trying to solve?  You should be reading the
version of
the docs which corresponds to the version you are running.  If you
are trying
to figure out an upgrade then the release notes are probably a
better starting
point.

Daniel Gustafsson

All the time we have doubts about what function exists in what version,
or was changed.
IS JSON belongs to 15 or 16, MERGE was done on 14 or 15, as example, are
completely new, so that feature will not run on previous versions.
But sometimes a function is changed a bit or a new easier function is
added, like [1].
Before all those new JSONPATH operators and methods were added, I could
do all those operations and return anything I wanted, but they are a lot
easier.

But if I don't read that page carefully, word by word, I will not see
that that function exists. And this needs to be done on all pages.
What changes were done on CREATE TABLE for version 16 ? Hmm, cool,
STORAGE can be defined at CREATE TABLE stage and not only at ALTER TABLE
anymore.
But to know that I have to read that page carefully, do you understand me ?

So I was thinking of a way to get differences between this and that
versions, and for all doc pages.
Something like we already have on [2], it explicits, this feature was
introduced, this was changed, this does not exist anymore.

Options:

1) One page release notes

https://bucardo.org/postgres_all_versions

Though you will get false positives on search for features that had
fixes in minor releases.

2) Or just read the release notes for the initial release of each major
version.

[1] -
https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS <https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS&gt;
[2] - https://www.postgresql.org/about/featurematrix/
<https://www.postgresql.org/about/featurematrix/&gt;

regards
Marcos

--
Adrian Klaver
adrian.klaver@aklaver.com

On 2024-02-25 17:38 +0100, Marcos Pegoraro wrote:

All the time we have doubts about what function exists in what version, or
was changed.

pgPedia may give you some overview, although it does not claim to be
up-to-date.

IS JSON belongs to 15 or 16, MERGE was done on 14 or 15, as example, are
completely new, so that feature will not run on previous versions.

MERGE, for example: https://pgpedia.info/m/merge.html

But if I don't read that page carefully, word by word, I will not see that
that function exists. And this needs to be done on all pages.
What changes were done on CREATE TABLE for version 16 ? Hmm, cool, STORAGE
can be defined at CREATE TABLE stage and not only at ALTER TABLE anymore.
But to know that I have to read that page carefully, do you understand me ?

CREATE TABLE: https://pgpedia.info/c/create-table.html

--
Erik

On 25 Feb 2024, at 17:38, Marcos Pegoraro <marcos@f10.com.br> wrote:

So I was thinking of a way to get differences between this and that versions, and for all doc pages.
Something like we already have on [2], it explicits, this feature was introduced, this was changed, this does not exist anymore.

The documentation is written in heavily structured form using XML, you can most
likely write a diffing tool fairly easily which gives enough hints to know what
to read up on (or find an existing tool where plugging in a XPath expression
suffice). By the sounds of it you are mostly interested in things found in
tables which makes it even easier.

--
Daniel Gustafsson

On Mon, Feb 26, 2024 at 1:49 AM Daniel Gustafsson <daniel@yesql.se> wrote:

On 25 Feb 2024, at 17:38, Marcos Pegoraro <marcos@f10.com.br> wrote:

So I was thinking of a way to get differences between this and that versions, and for all doc pages.
Something like we already have on [2], it explicits, this feature was introduced, this was changed, this does not exist anymore.

The documentation is written in heavily structured form using XML, you can most
likely write a diffing tool fairly easily which gives enough hints to know what
to read up on (or find an existing tool where plugging in a XPath expression
suffice). By the sounds of it you are mostly interested in things found in
tables which makes it even easier.

--
Daniel Gustafsson

I just found out this:
https://demo.deltaxml.com/compare-demonstration-results-sample/

but I guess the OP wants a side by side rendered html comparison.
like you buy a iphone then you can compare it like this:
https://www.apple.com/iphone/compare/

jian he <jian.universality@gmail.com> escreveu:
but I guess the OP wants a side by side rendered html comparison.
like you buy a iphone then you can compare it like this:

<https://www.apple.com/iphone/compare/&gt;&gt;
https://www.apple.com/iphone/compare/

No, I want show what changes ocurred on both versions, the page your are
seeing and other you selected. But both on same page, not side by side.

On every page you have on title Supported Versions: 16 / 15 / 14 / 13 / 12.
I would like to see on right of that some radio buttons, for Comparing
Version: rb16 / rb15 / rb14 / rb13 / rb12. If these rb16, rb15 are radio
buttons, I can compare actual page with one of previous versions, only one.
So, if you are showing a CREATE TABLE of version 16 and you are comparing
with 14 version, that STORAGE ... part would be painted
with green background, because it was added on 16 version.

If you change this part of that page
[ STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } ]
could be rewritten as
<span class = "v16" style="background-color:green"> [ STORAGE { PLAIN |
EXTERNAL | EXTENDED | MAIN | DEFAULT } ] </span>

Then a simple JS would show that text with background color green only if
comparing version you've selected is 15 or less

This page has another change, but only if you compare with version 11 of
before, because WITH OIDS was removed on version 12.
So, this text
[ WITH ( *storage_parameter* [= *value*] [, ... ] ) | WITH OIDS | WITHOUT
OIDS ]
could be rewritten as
<span class = "v12" style="background-color:red"> [ WITH (
*storage_parameter* [= *value*] [, ... ] ) | WITH OIDS | WITHOUT OIDS ]
</span>

This time that part would show something red, just to show that this part
was removed, maybe.

I know that we have to rewrite all html pages changing that this or that
text was added or changed, but I think if possible to find a tool to do
that.
And to know what exactly was changed on every page of docs would be much
better.

regards
Marcos

On 28 Feb 2024, at 19:59, Marcos Pegoraro <marcos@f10.com.br> wrote:

jian he <jian.universality@gmail.com> escreveu:
but I guess the OP wants a side by side rendered html comparison.
like you buy a iphone then you can compare it like this:
https://www.apple.com/iphone/compare/

No, I want show what changes ocurred on both versions, the page your are seeing and other you selected. But both on same page, not side by side.

Patches welcome, pgsql-www is the list for submitting changes for the website
and HTML rendering of the docs.

--
Daniel Gustafsson