Thread: Documentation diff
It's not easy to see what exactly changed between this and that version, on a specific page on documentation. As an example I got this page but you'll see this problem anywhere on docs.
and
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 ?
Regars
Marcos
> 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].
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.
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> > [2] - https://www.postgresql.org/about/featurematrix/ > <https://www.postgresql.org/about/featurematrix/> > > 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 existanymore. 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 existanymore. > > 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:
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 samepage, 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