Thread

Changing on SGML Notes

Marcos Pegoraro <marcos@f10.com.br> — 2025-09-15T17:26:22Z

There are lots of places where some notes are added to documentation
related to some changes on a specific version.
... default behavior has changed in PostgreSQL 9.0
... Before PostgreSQL 10, it was necessary to ...
... Beginning with PostgreSQL 16 ...

But the problem is that sometimes that note is inside a huge paragraph and
the reader doesn't know where it starts and ends, so needs to read that
paragraph entirely. If we just enclose that text to "Note on Version X" it
would be easier because if he is using version 14 and there is a note
talking about some change on version 10, he doesn't care.

Examples ...
If I'm using version 18 I don't care about this paragraph entirely.
PQinitSSL and PQinitOpenSSL are maintained for backwards compatibility, but
are no longer required since PostgreSQL 18. PQinitSSL has been present
since PostgreSQL 8.0, while PQinitOpenSSL was added in PostgreSQL 8.4, so
PQinitSSL might be preferable for applications that need to work with older
versions of libpq.

Starts talking about vertion 8.2 but ends with newer versions, so I have to
read it entirely too.
Before PostgreSQL 8.2, the .* syntax was not expanded in row constructors,
so that writing ROW(t.*, 42) created a two-field row whose first field was
another row value. The new behavior is usually more useful. If you need the
old behavior of nested row values, write the inner row value without .*,
for instance ROW(t, 42).

So, what do you think if we create a separate <note> tag, so only users
interested in that version have to read it ?

Would it be good ?

regards
Marcos