Re: A minor bug in doc. Hovering over heading shows # besides it.

[Jonathan S. Katz]

On 7/18/24 1:59 PM, Daniel Gustafsson wrote:

On 18 Jul 2024, at 15:49, Tom Lane  wrote:

Daniel Gustafsson  writes:

While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other
docs, commonly used for this.  There is a lot of variability though so
whichever we choose it will be wrong one for someone.


I like this suggestion better because that's U+00B6, ie part of
LATIN-1, so it's *far* more likely to render correctly everywhere
than U+01F517 is.  We could also consider the section sign §
(U+00A7).

In any case, a tooltip would help reduce confusion.


Looking a bit closer, the Python documentation does just this, a pilcrow with a
tool-tip ("Link to this heading") when hovering over it


I forgot why we went with the "#" and not the (TIL the name) pilcrow 
symbol, but I'm generally used to seeing the pilcrow when I browse docs 
and may have voiced that at the time (though the record may show 
otherwise). So +1 to that.


Thanks,

Jonathan



OpenPGP_signature.asc
Description: OpenPGP digital signature

Re: Monetary Data Types Improvement

[Jonathan S. Katz]

On 3/20/24 11:07 AM, Dave Cramer wrote:



On Wed, 20 Mar 2024 at 10:59, Erik Wienhold > wrote:


On 2024-03-18 23:24 +0100, David Rowley wrote:
 > My vote would go to adding a deprecation notice to that section
of the
 > docs.  There's some talk [1] about how we discourage the usage of the
 > money type and that goes on to discuss the possibilities of moving it
 > into a contrib module.
 >
 > My hope would be that deprecation notice would steer most people away
 > from using it and therefore reduce the number of questions about it
 > due to fewer new use cases of it.
 >
 > [1]
https://www.postgresql.org/message-id/zxgh74ykj3iwv...@paquier.xyz


+1

Huh, I didn't know that it used to have a deprecation notice at some
point.  But that note was removed in 8.3:

https://www.postgresql.org/message-id/20071009123315.5fb283c1.darcy%40druid.net 



Sadly that was a mistake. Money is not really a useful type.


Here's[1] the latest "let's remove money" discussion (there's allegedly 
a hackers thread too, but I'm having trouble finding it.


+1 on reinstating the deprecation notice, given it'll be some years 
before we can fully remove it (at least based on the discussion).


Thanks,

Jonathan

[1] 
https://www.postgresql.org/message-id/flat/18240-c5da758d7dc1ecf0%40postgresql.org


OpenPGP_signature.asc
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/23/23 8:41 AM, Daniel Gustafsson wrote:

On 22 Aug 2023, at 16:25, Jonathan S. Katz  wrote:

On 8/22/23 3:10 AM, Daniel Gustafsson wrote:


This is in line with what I imagined as well, so unless anyone thinks otherwise
I will apply this and backpatch it to all branches.


I could argue it both ways on whether or not to backpatch. However, given the 
list of drivers should work with all supported PG releases, and it expands on 
the current known list, I'd +1 backpatching.


I opted for backpatching as the table is equally incomplete for all branches,
and the wiki equally applicable.


Agreed; thanks!

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/22/23 3:10 AM, Daniel Gustafsson wrote:


This is in line with what I imagined as well, so unless anyone thinks otherwise
I will apply this and backpatch it to all branches.


I could argue it both ways on whether or not to backpatch. However, 
given the list of drivers should work with all supported PG releases, 
and it expands on the current known list, I'd +1 backpatching.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include rust as an externally maintained procedural language

[Jonathan S. Katz]

On 8/22/23 3:24 AM, Daniel Gustafsson wrote:

On 22 Aug 2023, at 05:35, Jonathan S. Katz  wrote:

On 8/12/23 12:45 PM, Bruce Momjian wrote:

On Fri, Aug 11, 2023 at 05:05:48PM -0400, Jonathan Katz wrote:

On 8/11/23 2:46 PM, PG Doc comments form wrote:



Considering the increasing support and stability for PL/Rust, it should be
referenced within Postgresql's docs [1].


There's an up-to-date list of the different PL's in on this page in the
wiki:

https://wiki.postgresql.org/wiki/PL_Matrix

Similar to this thread[1], I wonder if we just link to the wiki from the
documentation, given it will be easier to maintain the list from there.

Makes sense.


Please see attached patch that does exactly this. It follows similar semantics 
as [1].


LGTM, let's apply it along with the patch in [1] to all branches.


Thanks!

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include rust as an externally maintained procedural language

[Jonathan S. Katz]

On 8/12/23 12:45 PM, Bruce Momjian wrote:

On Fri, Aug 11, 2023 at 05:05:48PM -0400, Jonathan Katz wrote:

On 8/11/23 2:46 PM, PG Doc comments form wrote:



Considering the increasing support and stability for PL/Rust, it should be
referenced within Postgresql's docs [1].


There's an up-to-date list of the different PL's in on this page in the
wiki:

https://wiki.postgresql.org/wiki/PL_Matrix

Similar to this thread[1], I wonder if we just link to the wiki from the
documentation, given it will be easier to maintain the list from there.


Makes sense.


Please see attached patch that does exactly this. It follows similar 
semantics as [1].


Thanks,

Jonathan

[1] 
https://www.postgresql.org/message-id/flat/169165415312.635.10247434927885764880%40wrigleys.postgresql.org


diff --git a/doc/src/sgml/external-projects.sgml 
b/doc/src/sgml/external-projects.sgml
index 2d0fd723b2..57b47f7a75 100644
--- a/doc/src/sgml/external-projects.sgml
+++ b/doc/src/sgml/external-projects.sgml
@@ -170,58 +170,18 @@
   
In addition, there are a number of procedural languages that are developed
and maintained outside the core PostgreSQL
-   distribution.  lists some of these
-   packages. Note that some of these projects might not be released under the 
same
-   license as PostgreSQL. For more information on 
each
-   procedural language, including licensing information, refer to its website
+   distribution. A list of
+   https://wiki.postgresql.org/wiki/PL_Matrix;>procedural 
languages
+   is maintained on the PostgreSQL wiki. Note that some of these projects are
+   not released under the same license as 
PostgreSQL.
+   For more information on each procedural language, including licensing
+   information, refer to its website
and documentation.
   
 
-  
-   Externally Maintained Procedural Languages
-
-   
-
- 
-  Name
-  Language
-  Website
- 
-
-
-
- 
-  PL/Java
-  Java
-  https://tada.github.io/pljava/;>
- 
-
- 
-  PL/Lua
-  Lua
-  https://github.com/pllua/pllua-ng;>
- 
-
- 
-  PL/R
-  R
-  https://github.com/postgres-plr/plr;>
- 
-
- 
-  PL/sh
-  Unix shell
-  https://github.com/petere/plsh;>
- 
-
- 
-  PL/v8
-  JavaScript
-  https://github.com/plv8/plv8;>
- 
-
-   
-  
+  
+   https://wiki.postgresql.org/wiki/PL_Matrix;>
+  
  
 
  


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/21/23 10:55 AM, Jonathan S. Katz wrote:

On 8/21/23 7:58 AM, Daniel Gustafsson wrote:

On 11 Aug 2023, at 02:23, Jonathan S. Katz  wrote:


The last time this came up, I think we discussed linking to the wiki 
page from the docs, vs. trying to keep the docs up-to-date with all 
of the drivers available. Perhaps it's worth seeing if we want to 
make any changes to the docs page prior to the v16 GA?


The docs page does mention that the list is likely to be incomplete, 
with the

following sentence, but there is no mention of the Wiki page at all:

 "Table H.1 includes a list of some of these projects."

That being said, a lot of readers will likely skim over and 
immediately look at
the table, missing the small disclaimer.  I wonder if we aren't 
serving our
users better by removing the table and only referring to the Wiki 
page?  Having
two lists will prompt the discussion of what to include where over and 
over

again, which isn't helping anyone.


This is what I was saying. I was waiting on attempting a patch to see if 
there was consensus. There's now a couple of threads now with similar 
suggestions, I'll work on getting patches ready.


Suggested patch attached. Notes:

1. Replaced language to reference the wiki page
2. Replaced table with the URL
3. Changed the "licenses" comment to be more affirmative, i.e., there 
are language interfaces that are released under licenses different than 
the PostgreSQL Licence.


Jonathan
diff --git a/doc/src/sgml/external-projects.sgml 
b/doc/src/sgml/external-projects.sgml
index 2d0fd723b2..110692da7d 100644
--- a/doc/src/sgml/external-projects.sgml
+++ b/doc/src/sgml/external-projects.sgml
@@ -40,99 +40,17 @@

 
All other language interfaces are external projects and are distributed
-   separately.  includes a list of
-   some of these projects. Note that some of these packages might not be
-   released under the same license as PostgreSQL. 
For more
-   information on each language interface, including licensing terms, refer to
-   its website and documentation.
+   separately. A
+   https://wiki.postgresql.org/wiki/List_of_drivers;>list of 
language interfaces
+   is maintained on the PostgreSQL wiki. Note that some of these packages are
+   not released under the same license as 
PostgreSQL.
+   For more information on each language interface, including licensing terms,
+   refer to its website and documentation.
   
 
-  
-   Externally Maintained Client Interfaces
-
-   
-
- 
-  Name
-  Language
-  Comments
-  Website
- 
-
-
-
- 
-  DBD::Pg
-  Perl
-  Perl DBI driver
-  https://metacpan.org/dist/DBD-Pg;>
- 
-
- 
-  JDBC
-  Java
-  Type 4 JDBC driver
-  https://jdbc.postgresql.org/;>
- 
-
- 
-  libpqxx
-  C++
-  C++ interface
-  https://pqxx.org/;>
- 
-
- 
-  node-postgres
-  JavaScript
-  Node.js driver
-  https://node-postgres.com/;>
- 
-
- 
-  Npgsql
-  .NET
-  .NET data provider
-  https://www.npgsql.org/;>
- 
-
- 
-  pgtcl
-  Tcl
-  
-  https://github.com/flightaware/Pgtcl;>
- 
-
- 
-  pgtclng
-  Tcl
-  
-  https://sourceforge.net/projects/pgtclng/;>
- 
-
- 
-  pq
-  Go
-  Pure Go driver for Go's database/sql
-  https://github.com/lib/pq;>
- 
-
- 
-  psqlODBC
-  ODBC
-  ODBC driver
-  https://odbc.postgresql.org/;>
- 
-
- 
-  psycopg
-  Python
-  DB API 2.0-compliant
-  https://www.psycopg.org/;>
- 
-
-   
-  
+  
+https://wiki.postgresql.org/wiki/List_of_drivers;>
+  
  
 
  


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/21/23 7:58 AM, Daniel Gustafsson wrote:

On 11 Aug 2023, at 02:23, Jonathan S. Katz  wrote:



The last time this came up, I think we discussed linking to the wiki page from 
the docs, vs. trying to keep the docs up-to-date with all of the drivers 
available. Perhaps it's worth seeing if we want to make any changes to the docs 
page prior to the v16 GA?


The docs page does mention that the list is likely to be incomplete, with the
following sentence, but there is no mention of the Wiki page at all:

 "Table H.1 includes a list of some of these projects."

That being said, a lot of readers will likely skim over and immediately look at
the table, missing the small disclaimer.  I wonder if we aren't serving our
users better by removing the table and only referring to the Wiki page?  Having
two lists will prompt the discussion of what to include where over and over
again, which isn't helping anyone.


This is what I was saying. I was waiting on attempting a patch to see if 
there was consensus. There's now a couple of threads now with similar 
suggestions, I'll work on getting patches ready.


Thanks,

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: ROWS vs RANGE in release notes for pg 16

[Jonathan S. Katz]

Hi Erwin,

On 8/18/23 7:41 PM, Erwin Brandstetter wrote:

The release notes for Postgres 16 says here:
https://www.postgresql.org/docs/16/release-16.html#RELEASE-16-PERFORMANCE 


 > Allow window functions to use ROWS mode internally when RANGE mode is 
specified but unnecessary (David Rowley)


But the fix also applies to the much more common case where no mode has 
been specified, RANGE unfortunately being the default - including the 
most common use case "row_number() OVER (ORDER BY col)". This is what 
made me investigate, test and eventually propose a fix in the first 
place. See:


https://www.postgresql.org/message-id/flat/CAGHENJ7LBBszxS%2BSkWWFVnBmOT2oVsBhDMB1DFrgerCeYa_DyA%40mail.gmail.com
 

https://www.postgresql.org/message-id/flat/CAApHDvohAKEtTXxq7Pc-ic2dKT8oZfbRKeEJP64M0B6%2BS88z%2BA%40mail.gmail.com
 


Also, I was hoping to get a mention in the release note for working this 
out:


 > Allow window functions to use the faster ROWS mode internally when 
RANGE mode is specified or would be used by default, but unnecessary 
(David Rowley, Erwin Brandstetter)


Thanks for flagging. I suggest adding the comment to the release notes 
thread on -hackers:


https://www.postgresql.org/message-id/flat/ZGaPa7M3gc2THeDJ%40momjian.us

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include rust as an externally maintained procedural language

[Jonathan S. Katz]

On 8/11/23 2:46 PM, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/external-pl.html
Description:

The documentation [1] contains a list of independently maintained procedural
languages. Recently, PL/Rust [2] has reached its version 1.0 [3] and appears
to be stable.

Major companies have expressed interest in the extension. Kiwi Copple, the
founder of Supabase, has stated his company is researching the language for
his platform [4]. Meanwhile, Amazon's RDS team has already announced support
for PL/Rust as a trusted language extension [5] on their PostgreSQL
instances [6].

Considering the increasing support and stability for PL/Rust, it should be
referenced within Postgresql's docs [1].


There's an up-to-date list of the different PL's in on this page in the 
wiki:


https://wiki.postgresql.org/wiki/PL_Matrix

Similar to this thread[1], I wonder if we just link to the wiki from the 
documentation, given it will be easier to maintain the list from there.


Thanks,

Jonathan

[1] 
https://www.postgresql.org/message-id/flat/169165415312.635.10247434927885764880%40wrigleys.postgresql.org




OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

Hi Fabian,

On 8/10/23 3:55 AM, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/external-interfaces.html
Description:

Hi,

I'm reaching out to ask if the Swift Postgres could be included in the
listing here:

https://www.postgresql.org/docs/current/external-interfaces.html

Name: PostgresNIO
Language: Swift
Comments: Non-blocking, event-driven client built with SwiftNIO
Website: https://github.com/vapor/postgres-nio


As of late, we've been keeping the canonical list on the wiki page here, 
which already includes PostgresNIO:


https://wiki.postgresql.org/wiki/List_of_drivers

The last time this came up, I think we discussed linking to the wiki 
page from the docs, vs. trying to keep the docs up-to-date with all of 
the drivers available. Perhaps it's worth seeing if we want to make any 
changes to the docs page prior to the v16 GA?


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Clarify errhint in sources.sgml

[Jonathan S. Katz]

On 7/12/23 3:08 AM, Daniel Gustafsson wrote:

It was noted in 20230712015948.byqaftt57glwk...@awork3.anarazel.de that the
errhint example in sources.sgml isn't as helpful as it could be.  errhint
should use a complete sentence, but the example doesn't, so I propose the
attached change which makes it so.  The style for hints is clearly spelled out
further down on the page, but for anyone looking for a quick answer and not
reading the whole page the current example might be misleading.


+1. No need to bikeshed this one.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Change "two" to "three" for decades of development in history

[Jonathan S. Katz]

On 6/22/23 9:23 PM, Tom Lane wrote:

Michael Paquier  writes:

"With multiple decades of development behind it, PostgreSQL.."


+1.  It sure seems silly trying to automate changing this.


+1. With the proposed language, we can revisit it once it gets to 
"centuries."


Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: large scale reliable software system

[Jonathan S. Katz]

On 6/21/23 12:52 PM, B M wrote:

Dear all,

After greeting,

I taught PostgreSQL myself and developed a small scale 
experimentalsoftware system using PostgreSQL in the back-end.


I would like to know your advices to develop a large scale reliable 
software system using PostgreSQL in the back-end, through which i can 
share the storage with the different system users where they login to 
the system through the web application front-end with different 
passwords and usernames , save the privacy of each user data, improve 
overall system security and performance, achieve fast response, make 
backups and save the stored data from loss. The system will be hosted on 
a cloud.


This mailing list is to discuss issues related to the PostgreSQL 
documentation, not system design. There are some other places you can 
have this discussion[1] (such as pgsql-general@), though many of the 
questions you have are generally broad topics that turn into very deep, 
detailed conversations.


Thanks,

Jonathan

[1] https://www.postgresql.org/support/



OpenPGP_signature
Description: OpenPGP digital signature

Re: confusing positioning of notes in connection settings

[Jonathan S. Katz]

On 6/7/23 11:17 AM, Peter Eisentraut wrote:


The proposed text in the patch is

"This parameter is supported only on systems that {have this property} 
(which does not include Windows)."


I don't see how the change you are proposing is correct.


I see -- I had read it quickly and didn't sound it out. Nit withdrawn.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

clarifying trigger/rule behavior on logical replication subscribers

[Jonathan S. Katz]

Hi,

While answering a question on "do triggers fire on a logical replication 
subscriber by default?" I tried to look up a reference to this behavior 
in the docs. There wasn't a clear reference point, but on the 
architecture page[1], I found this line that was closest to the answer:


"The apply process on the subscriber database always runs with 
session_replication_role set to replica, which produces the usual 
effects on triggers and constraints."


which assumes that the reader knows what the "usual effects" are.

Attached is a patch that disambiguates this.

Two additional items:

1. I do think this should be backpatched because it clarifies an 
existing behavior.


2. I don't know if we want to add a note about the trigger/rule behavior 
elsewhere in the logical replication section. I don't know if a reader 
would be expecting to find this in the "architecture" section.


Thanks,

Jonathan

[1] 
https://www.postgresql.org/docs/devel/logical-replication-architecture.html
From 23aaa7fe401d85736ebf426626b063075a75c918 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Tue, 6 Jun 2023 09:51:32 -0400
Subject: [PATCH] doc: Clarify behavior of triggers/rules in a logical
 subscriber

By default, triggers and rules do not fire on a logical replication
subscriber based on the "session_replication_role" GUC being set to
"replica". However, the docs in the logical replication section assumed
that the reader understood how this GUC worked. This modifies the docs to
be more explicit, and link back to the GUC itself.
---
 doc/src/sgml/logical-replication.sgml | 10 +++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml 
b/doc/src/sgml/logical-replication.sgml
index 59cf92e6a9..b18cff73ed 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1654,9 +1654,13 @@ CONTEXT:  processing remote data for replication origin 
"pg_16395" during "INSER
 
   
The apply process on the subscriber database always runs with
-   session_replication_role set
-   to replica, which produces the usual effects on triggers
-   and constraints.
+   session_replication_role
+   set to replica. This means that, by default,
+   triggers and rules will not fire on a replica. Users can optionally choose 
to
+   enable triggers and rules on a table using the
+   ALTER TABLE command
+   and the literal>ENABLE TRIGGER and ENABLE RULE
+   clauses.
   
 
   
-- 
2.37.1 (Apple Git-137.1)



OpenPGP_signature
Description: OpenPGP digital signature

Re: confusing positioning of notes in connection settings

[Jonathan S. Katz]

On 5/31/23 7:53 AM, Daniel Gustafsson wrote:

On 31 May 2023, at 13:16, Peter Eisentraut  
wrote:



The first two hunks are pretty straightforward, they just move the existing 
text around.

For the other two, which are not supported on Windows, I added an explicit 
parenthetical note.  We don't list which of the Unix-like platforms support the 
respective options, but I suspect that it's all of them in practice?  
(Otherwise we should be more explicit.)  So I think calling out Windows 
explicitly is sensible, also considering that the first two settings are 
supported on Windows but the latter two are not.


I think this is a clear improvement over the current docs.


+1.

Small nit:

"which does not include Windows" =>
"which is not supported on Windows"

(in two places)


Should we call out Windows explicitly in the same way in the corresponding
options in the libpq connection string param docs as well?


Probably, but I see language like this:

"It is only supported on systems where TCP_USER_TIMEOUT is available; on 
other systems, it has no effect."


If this is really only unsupported / has different settings on Windows, 
I think it's OK to call that out. The original gripe was about 
readability, but if we think the description in the other settings is no 
clear enough, we can edit it.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: The use "Postgres" in docs

[Jonathan S. Katz]

On 3/14/23 7:31 AM, Alvaro Herrera wrote:

On 2023-Mar-14, Daniel Gustafsson wrote:


The docs use PostgreSQL and not Postgres in all but two places, which I think
we should change like in the attached to be consistent. Any objections to this?


Both are very new.  No objection to the change.


+1 -- good catch.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: February 9th, 2023 Release links to a missing page

[Jonathan S. Katz]

On 2/20/23 8:57 PM, Kirk Wolak wrote:
On Sun, Feb 19, 2023 at 4:55 PM Jonathan S. Katz 


Well, that gives me an idea. In the release announcement, we could
put a
line that says "You can send any corrections or suggestions to the
public pgsql-...@lists.postgresql.org
<mailto:pgsql-...@lists.postgresql.org> mailing list" or something like
that. That way, it would remove the guessing on what to do.

Perfect...  I love this community!


Thanks. As I'd probably forget before the next update announcement, I 
sketched out the draft of it to ensure it included a line[1] around how 
to report corrections/suggestions.


Thanks again!

Jonathan

[1] 
https://git.postgresql.org/gitweb/?p=press.git;a=commitdiff;h=c5d98a4a9caece103205d1a213b11fa96086bd13;hp=9bffe5a98298e034976708a29c88a98a4cec9831


OpenPGP_signature
Description: OpenPGP digital signature

Re: February 9th, 2023 Release links to a missing page

[Jonathan S. Katz]

On 2/19/23 3:55 PM, Kirk Wolak wrote:
On Wed, Feb 15, 2023 at 2:05 PM Jonathan S. Katz <mailto:jk...@postgresql.org>> wrote:


The release announcements go through the news system, which does not
have a feedback collection mechanism as anyone can post news. Emailing
pgsql-docs, or even better pgsql-www, seems to be good enough for this
case as we can quickly fix it, but I'm open to other suggestions.

Thank you.  Good answer as well...   I figured out to just send it here...


Well, that gives me an idea. In the release announcement, we could put a 
line that says "You can send any corrections or suggestions to the 
public pgsql-...@lists.postgresql.org mailing list" or something like 
that. That way, it would remove the guessing on what to do.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: February 9th, 2023 Release links to a missing page

[Jonathan S. Katz]

On 2/15/23 1:59 PM, Kirk Wolak wrote:

It looks like a simple bad reference name:

On this line:

  * Fix the |psql|
 commands
|\sf| and |\ef| to handle SQL-language functions that have
SQL-standard function bodies
 (i.e. 
|BEGIN ATOMIC|).


the link for function bodies is called: "sql-create*procedure*.html"
and I believe it should be "sql-create*function*.html"


The end of the URL is correct. The problem is "currenet" should be 
"current". I've made that correction. Thanks!



Side Note:
On such a posting is there no direct link to SUBMIT a correction (by 
design?)


The release announcements go through the news system, which does not 
have a feedback collection mechanism as anyone can post news. Emailing 
pgsql-docs, or even better pgsql-www, seems to be good enough for this 
case as we can quickly fix it, but I'm open to other suggestions.


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Tightening the trust auth advice

[Jonathan S. Katz]

On 1/12/23 4:32 AM, Magnus Hagander wrote:
The page at https://www.postgresql.org/docs/current/auth-trust.html 
 goes through 
some length to explain why Trust is sometimes a good idea.


Is it really though? And in particular, aren't there better choices?


This first case it lists sounds like a good case for "peer" 
authentication...and the multi-user case it lists also sounds like a goo 
use for "peer".


The case that I think "trust" is good at, which we don't list, is doing 
local development / testing of PG.


As a first step, I think we should put a  box on the page 
explicitly saying that that trust, unless limited in pg_hba, will allow 
any user to become superuser which allows them to bypass all other 
security restrictions.


+1

Second, we're kind of going out of our way to recommend setting unix 
socket permissions etc -- in those cases, wouldn't it in almost every 
case just be better for the user to use "peer" auth instead of trust, 
and we should recommend them to use that instead? Is it really any less 
appropriate and/or convenient? (It was listed as appropriate back in 
2001 in 6f0f5bf2fbe, but the world has changed a bit in 20+ years..)


Yeah, I think forwarding folks to the documentation on "peer" is a good 
idea here. I don't know if we want to keep any language around for 
historical context "Prior to "peer" auth, "trust" was used for this but 
on modern systems you can use "peer" instead for better security."


And finally, the sentence "It is seldom reasonable to use trust for any 
TCP/IP connections other than those from localhost (127.0.0.1)." should 
probably be amended with an ", and only reasonable for localhost if you 
trust every single user on the host"?


I'd invert it: "It is not recommended to use "trust" for any TCP/IP 
(non-local) connection. You should use "trust" with localhost 
(127.0.0.1) connections only if you trust every single user on that host."


Thoughts? I'll be happy to work up a patch if there's agreement on the 
general idea.


Reading through this, I'm not shocked there's still a good amount of 
"trust" prevalent in the wild. I agree with tightening this up.


Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: 'value' has special behaviour in alter system

[Jonathan S. Katz]

On 12/15/22 10:50 AM, David G. Johnston wrote:
On Thu, Dec 15, 2022 at 4:45 AM PG Doc comments form 
mailto:nore...@postgresql.org>> wrote:


The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/sql-altersystem.html

Description:

Documentation say
ALTER SYSTEM SET configuration_parameter { TO | = } { value | 'value' |
DEFAULT }

The variant 'value' has special, not obvious behaviour and must be
documented.


This syntax representation and accompanying text annoys me too.  It is 
logical behavior and described accurately, but I think readability could 
be improved.


I suggest changing it to:

SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }

Values can be specified as unquoted alphanumeric+underscore sequences.  
If the value contains any non-alphanumeric (plus underscore) characters 
it should be enclosed in quotes (single or double, it does not matter).  
For settings that accept multiple values, separate each value to be 
supplied with a comma (and optional whitespace).


+1 in general. I would also suggest we add an example in the Examples 
section to show what the output is when you add single-quotes.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: No multi range functions on version 12

[Jonathan S. Katz]

On 12/15/22 6:46 AM, Magnus Hagander wrote:
On Thu, Dec 15, 2022 at 12:45 PM PG Doc comments form 
mailto:nore...@postgresql.org>> wrote:


The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/rangetypes.html

Description:

Hello, according to the documentation, Postgres 12 should have multi
range
functions. However, in my installation of Postgres 12.12, I don't
have any
multi range function. When I ran them Postgres said they didn't
exist and I
can't see them when querying through pg_proc.


What documentation says they should be in version 12? The page you 
commented on is about PostgreSQL 15, and multiranges were not present in 
version 12...


Multiranges were added in PostgreSQL 14:

"Range types have been extended by adding multiranges, allowing 
representation of noncontiguous data ranges."[1]


Jonathan

[1] https://www.postgresql.org/docs/release/14.0/


OpenPGP_signature
Description: OpenPGP digital signature

Re: Usability ideas: text width and headers that are links

[Jonathan S. Katz]

Hi,

Thanks for the suggestions. Comments inline:

On 10/21/22 9:54 AM, Niels Bom wrote:

Hi!

I have 2 small ideas to improve the usability of the PostgreSQL documentation. 
I'm looking at v15 (1) mostly.

Idea 1:
Give the text width of the main content a max width.


Why? Can you please provide examples? Screenshots are OK.


Idea 2:
Each h3 and h4 element should be a link pointing to the nearest parent section 
with an id. This makes deeplinking to specific parts of a page easier. This 
prevents people from having to scroll to the top, find out which 
table-of-content-link they have to click to get the deeplink of where they 
wanted to link. This is actually quite a common pattern. See the Python docs 
(2) and the Mozilla docs (3) as examples. The pattern on those sites is even a 
little nicer by showing an icon on hover.


This has been on my backlog for awhile, i.e. to have the hovering 
"anchor holders". I'll try to move it up on the list.


Thanks,

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: pl Lua

[Jonathan S. Katz]

On 10/17/22 6:03 AM, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/external-pl.html
Description:

Your page, https://www.postgresql.org/docs/15/external-pl.html

Please include another, active Lua binding for PostgreSQL.


There is currently a matrix in the wiki that lists out several PL 
languages[1] and their status. Perhaps we want to consider linking to 
that from the documentation, given this list may keep changing?


Thanks,

Jonathan

[1] https://wiki.postgresql.org/wiki/PL_Matrix



OpenPGP_signature
Description: OpenPGP digital signature

Re: Search engine linking to latest docs

[Jonathan S. Katz]

On 7/25/22 6:08 PM, Trevor Gross wrote:

Hey all,

I think the PG community is pretty aware that there are some issues with 
search engines taking users to the right versions of the docs. You 
google something simple like "postgres drop column" and the first 
postgresql.org  result takes you to the v7.4 docs 
- EOL over a decade ago. It's a similar story for many searches, lots of 
results take you to v8 or v9 docs first.


One of the efforts this year to improve it has already yielded results, 
where much more significant search traffic going to the latest docs 
(stats here):


https://www.postgresql.org/message-id/25aa516b-4fa7-5083-366e-09cf4f838...@postgresql.org

The 7.4 page does include the canonical link, but perhaps due to the 
amount of links going to the 7.4 ALTER TABLE page / the term not having 
been updated in awhile, it has not been reindex yet.


(Perhaps these recent searches will help with that reindexing :)



(Note that if you've clicked "current" in the docs before, it will 
automatically redirect you. This is more relevant to newer users, and 
the actual links on google).


I do not have the personal expertise to help this situation at all, but 
I would like to call attention to this active thread for the rust docs 
repo - https://github.com/rust-lang/docs.rs/issues/1438 
. The corresponding 
site docs.rs  has similar issues of always linking to 
outdated versions, and they're currently in the process of working to 
improve things. The thread contains a good bit of findings and 
trial/error. Knowing that PG has similar issues, it seems like there is 
a possibility of benefiting from mutual lessons learned in improving SEO 
and linking.


Agree in mutual benefits. This topic has been worked on for decades(!) 
now on the pgsql-www mailing list. For instance, our findings on 
"rel=canonical" are the opposite of what appears in that GitHub thread, 
and matches what some other OSS projects are doing (e.g. Django).


We consider "latest" to be a "superset" of the other versions. We 
explicitly do not want to redirect from old to new, given we support 5 
(and briefly 6) major PostgreSQL versions at any given time and want to 
ensure users have access to older doc versions.


Again, I have no concrete proposals to make, but wanted to draw 
attention to the issue and a good thread of ways to improve / possible 
solutions.


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: documentation on HOT

[Jonathan S. Katz]

On 7/22/22 8:51 AM, Bruce Momjian wrote:

On Thu, Jul 21, 2022 at 10:02:18PM -0400, Bruce Momjian wrote:

On Sun, Feb  6, 2022 at 09:29:56PM -0500, Jonathan Katz wrote:

I agree with Bruce's point that we should have a new section (or
subsection). As I mentioned in my previous post, given HOT involves
indexing, I would suggest putting it there.

I think that something that follows the general outline of Laurenz's post
would satisfy the user requirements. It explains at a high level what HOT
is, it's advantages, and how it works.


Attached is a patch that adds a new HOT section to the storage chapter.


I wasn't happy with the last paragraph so I added some more details.
URL contents updated too:

https://momjian.us/tmp/pgsql/storage-hot.html


Thanks! This is great. Probably the most concise and clear explanation I 
have seen for HOT, which is exactly what we need for the docs :)


A few suggestions:

s/Fortunately, there is/To help reduce overhead, PostgreSQL has/

s/In summary, h/H/

> You can increase the change of HOT updates by using non-default table 
fillfactor settings.


I think we should expand on this and explain how adjusting "fillfactor" 
will affect this. I think that may change the final sentence too.


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Can we still dump version 7?

[Jonathan S. Katz]

On 5/31/22 12:21 PM, Tom Lane wrote:

"Jonathan S. Katz"  writes:

On 5/31/22 10:55 AM, Tom Lane wrote:

I wonder whether we should update this or just remove it --- it's
clearly something that's likely to get missed again.



While burdensome, +1 for updating. We don't want users to get caught by
surprise if pg_dumpall does not work on an old version when trying to
update to a newer version.


Further investigation shows that we've failed to update this twice in
the past six years, and failed to update a similar comment about psql
once.  I fixed 'em, but I have very little hope that they'll stay fixed.


Could we add as part of the branching procedure that we update this value?

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Can we still dump version 7?

[Jonathan S. Katz]

On 5/31/22 10:55 AM, Tom Lane wrote:

"Daniel Westermann (DWE)"  writes:

I guess this statement is not true anymore?
"Current releases of the dump programs can read data from any server version back to 
7.0."
https://www.postgresql.org/docs/current/upgrading.html


Ugh, missed that, thanks for spotting it.

I wonder whether we should update this or just remove it --- it's
clearly something that's likely to get missed again.


While burdensome, +1 for updating. We don't want users to get caught by 
surprise if pg_dumpall does not work on an old version when trying to 
update to a newer version.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Should we really recommend "-A md5 or -A password"?

[Jonathan S. Katz]

On 5/31/22 8:35 AM, Magnus Hagander wrote:



On Tue, May 31, 2022 at 2:29 PM Daniel Westermann (DWE) 
> wrote:


Hi,

I just came across this:
"Also, specify -A md5 or -A password so that the default trust
authentication mode is not used;"
https://www.postgresql.org/docs/current/creating-cluster.html


Shouldn't we change that to "-A scram-sha-256" ?


Yes I think we absolutely should!


+1

Proposed patch attached. This also removes "-A password" from that 
sentence as well.


Jonathan
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 62cec614d3..fac9b6b3bd 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -199,8 +199,8 @@ postgres$ initdb -D 
/usr/local/pgsql/data
  password
  of the superuser

-   Also, specify -A md5 or
-   -A password so that the default trust 
authentication
+   Also, specify -A scram-sha-256
+   so that the default trust authentication
mode is not used; or modify the generated pg_hba.conf
file after running initdb, but
before you start the server for the first time. (Other


OpenPGP_signature
Description: OpenPGP digital signature

Re: documentation on HOT

[Jonathan S. Katz]

On 2/6/22 8:56 PM, David G. Johnston wrote:
On Sun, Feb 6, 2022 at 6:08 PM Jonathan S. Katz <mailto:jk...@postgresql.org>> wrote:



Given the importance of HOT, it seems like this would be a good
topic to
document. I would suggest something higher-level for general users in
the "Indexes"[4] section, and something lower-level in internals[5]
(which could perhaps be derived from [2]).

Thoughts on this?


I'm doubting there is any disagreement that this is needed.  Three of us 
said as much recently [1] while discussing a user question regarding our 
documentation for expression indexes.


I did try to search for previous discussion on this (not well enough 
apparently) and I was unable to find the thread. That is also part of 
the challenge with the term HOT.


I presently haven't felt moved to fill the need myself as so I was fine 
with at least providing a high-level summary in the glossary which we 
also the general user to understand the idea without having to dive into 
the README.


I don't agree that such an explanation belongs in the glossary. That 
feels like it would be too brief, and I think that does a disservice to 
the topic and our users.


I agree with Bruce's point that we should have a new section (or 
subsection). As I mentioned in my previous post, given HOT involves 
indexing, I would suggest putting it there.


I think that something that follows the general outline of Laurenz's 
post would satisfy the user requirements. It explains at a high level 
what HOT is, it's advantages, and how it works.


  The details for internals can continue to be handled there 
in the interest of at least getting something committed for the majority 
of users.


I do think there should be some reference of it to the docs. Even if we 
have a page in the "Internals" section that says "For more information 
on how HOT works, please see ".


That said, is there any reasoning why the HOT README (or something 
similar to it) is not in the "Internals" section of the documentation, 
similar to other indexing topics?


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

documentation on HOT

[Jonathan S. Katz]

Hi,

While working on the 2020-02-10 release announcement, in order to better 
describe one of the fixes, I tried to find a reference in the docs that 
described what HOT is, how it works, etc. in a user-friendly manner.


This lead me to the acronyms page[1], which lead me to a document in the 
repo[2]. The closest thing I found was a blog post that Laurenz Albe 
wrote on the topic[3].


Given the importance of HOT, it seems like this would be a good topic to 
document. I would suggest something higher-level for general users in 
the "Indexes"[4] section, and something lower-level in internals[5] 
(which could perhaps be derived from [2]).


Thoughts on this?

Thanks,

Jonathan

[1] https://www.postgresql.org/docs/current/acronyms.html
[2] 
https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/access/heap/README.HOT;hb=HEAD
[3] 
https://www.cybertec-postgresql.com/en/hot-updates-in-postgresql-for-better-performance/

[4] https://www.postgresql.org/docs/current/indexes.html
[5] https://www.postgresql.org/docs/current/internals.html


OpenPGP_signature
Description: OpenPGP digital signature

Re: missing a white space in the last sentence of 51.6. Executor

[Jonathan S. Katz]

On 1/17/22 2:02 PM, Tom Lane wrote:

PG Doc comments form  writes:

The last sentence of 51.6. Executor appears:
"...feeding that up toModifyTable to perform the insertion."


Hm, the space is definitely there in the source file:

 A simple INSERT ... VALUES command creates a
 trivial plan tree consisting of a single Result
 node, which computes just one result row, feeding that up
 to ModifyTable to perform the insertion.

I also see it rendered properly in HTML when looking at a local docs
build.  I think this is some sort of spacing issue in the website
style sheets.  Other  segments on the same page are also
rendered with less-than-usual spacing around them (to my eye
anyway); though this is the only one that looks like it has no
space at all.


I don't think it's the website stylesheets; those are identical between 
both core "make" and the website itself.


It looks like the whitespace character was stripped out in the generated 
HTML on the website. My thought is that tidylib's parser did that. We 
set indent[1] to "auto", and in the tidylib docs it does indicate that 
it could expose "layout issues" in some browsers. This makes me think 
that this could be the culprit, though I haven't tested it yet.


Is there any reason why we use that setting at all, given the doc HTML 
in the website is generated + stored in the DB, and we rarely, if ever 
need to debug it?


Thanks,

Jonathan

[1] http://tidy.sourceforge.net/docs/quickref.html#indent


OpenPGP_signature
Description: OpenPGP digital signature

Re: Add TypeScript driver

[Jonathan S. Katz]

On 1/4/22 2:40 AM, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/external-interfaces.html
Description:

Hi. I am Eray Hanoglu, author of postgresql-client javascript driver written
in TypeScript (https://www.npmjs.com/package/postgresql-client). It is an
open-sourced project under MIT license.


I think it's worth adding it here:

https://wiki.postgresql.org/wiki/List_of_drivers

which I can go ahead and do so.

I think we've discussed this in the past, but we should probably 
reference that wiki page from the docs, with some verbiage around it 
being a community-maintained list and not official recommendations.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: ORDER BY in materialized view example?

[Jonathan S. Katz]

On 11/23/21 12:44 PM, Tom Lane wrote:

Peter Eisentraut  writes:

On 23.11.21 07:18, Maciek Sakrejda wrote:

An example in the materialized view documentation [1] includes an ORDER
BY clause without a clear reason. Does it help build the index more
efficiently? I suppose it's also sort of like a CLUSTER?



I agree the ORDER BY is not relevant to the example.  There might be
some implementation-dependent advantage to ordering a materialized view,
but if there is, it isn't explained in the example.


Yeah.  It would result in the initial contents of the matview being
ordered, but I'm sure we don't wish to guarantee that REFRESH would
preserve that.  I'm on board with just removing the ORDER BY from
that example.


+1


I'd rather say something like

 If there is an ORDER BY clause in the matview's defining query,
 the original contents of the matview will be ordered that way;
 but REFRESH MATERIALIZED VIEW does not guarantee to preserve
 that ordering.


+1. I think I got bit by this in the real world years back. The above 
comment is pretty clear.


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: I came here to determine how much storage a boolean variable uses

[Jonathan S. Katz]

On 8/30/21 11:31 AM, David G. Johnston wrote:
> On Sun, Aug 29, 2021 at 11:59 PM PG Doc comments form
> mailto:nore...@postgresql.org>> wrote:
> 
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/13/datatype.html
> 
> Description:
> 
> I'd like to see a fourth column added to Table 8-1 that contains the
> size or
> size range of the data type. 
> 
> 
> I would argue this is sufficiently provided by the pg_attribute
> catalog's attlen and attalign fields, as pointed to on the same page
> linked below.
> 
> Maybe a note about the amount of space in the
> row that a NULL column uses vs a NOT NULL.
> 
> 
> Implementation detail that is covered in the internals section:
> 
> https://www.postgresql.org/docs/current/storage-page-layout.html#STORAGE-TUPLE-LAYOUT
> 

Well, it is provided one level deeper in the data type docs, e.g.:

https://www.postgresql.org/docs/13/datatype-boolean.html

I think it's a reasonable request to consider. It potentially duplicates
the info in the data types section (i.e. one more thing to maintain),
but it does provide some convenience for scanning it across the
consolidated table.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Use of the word master

[Jonathan S. Katz]

On 8/5/21 2:26 PM, Dave Cramer wrote:
> PostgreSQL: Documentation: 13: 30.1. Publication
> 
> 
> 
> "A /publication/ can be defined on any physical replication master."
> 
> I would propose "any physical replication primary"

It could be any instance that's writable though. Perhaps:

"A publication can be defined on any database that can accept writes."

or

"A publication can be defined on any database that is not in recovery."

That said, +1 for the wording change.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Git is not an acronym

[Jonathan S. Katz]

On 6/10/21 7:40 AM, Daniel Gustafsson wrote:
> Commit 651377933e031 cleaned up references to CVS replacing them with Git.
> Replacing CVS with Git in acronyms.sgml seems a bit incorrect though as Git
> isn't an acronym (but CVS is, hence the original item replaced).  We also 
> never
> refer to Git with  tags.  The attached removes Git from the 
> acronyms
> page.

According to the README[1] and reference in the Wikipedia page that our
docs point too, "git" can be an acronym based on context. I don't think
it's harmful to leave it in.

Jonathan

[1] https://github.com/git/git/blob/master/README.md



OpenPGP_signature
Description: OpenPGP digital signature

Re: failed to connect to PostgreSQL server on "db01:5432" using INET socket

[Jonathan S. Katz]

Hi,

On 5/24/21 12:45 AM, Moin Akther wrote:
> Dear Team,
> 
>  
> 
> We are getting below error logs from pgpool.
> 
>  
> 
> May 18 07:48:31 pgpool[22685]: [7-1] 2021-05-18 07:48:31: pid 22685:
> LOG: failed to connect to PostgreSQL server on "db01:5432" using INET socket
> May 18 07:48:31 pgpool[22650]: 2021-05-18 07:48:31: pid 22685: LOG:
> failed to connect to PostgreSQL server on "db01:5432" using INET socket
> 
> May 18 07:48:31 pgpool[22685]: [7-1] 2021-05-18 07:48:31: pid 22685:
> LOG: failed to connect to PostgreSQL server on "db01:5432" using INET socket
> May 18 07:48:31 pgpool[22650]: 2021-05-18 07:48:31: pid 22685: LOG:
> failed to connect to PostgreSQL server on "db01:5432" using INET socket
> 
> Kindly help us to know the actual root cause of this issue is id due to
> Network or something related with PostgreSQL DB ?

This mailing list is for discussing issues related to the PostgreSQL
documentation, not for support questions.

Please see my previous response around the appropriate mailing lists for
asking these questions:

https://www.postgresql.org/message-id/9016af56-68a2-e666-6697-7cc789975929%40postgresql.org

Thanks,

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: pgpool: APPARENT DEADLOCK!!! Complete Status: Managed Threads: 3 Active Threads: 3

[Jonathan S. Katz]

Hi Moin,

On 5/18/21 3:30 AM, Moin Akther wrote:
> Dear Team,
> 
>  
> 
> We are facing issue whenever application is connecting to pgpool 4^th Node.

This email address is for contributing to the PostgreSQL documentation[1].

The Pgpool project provides contact information on reporting issues here:

https://www.pgpool.net/mediawiki/index.php/Main_Page#Contacts

Thanks,

Jonathan

[1] https://www.postgresql.org/docs/



OpenPGP_signature
Description: OpenPGP digital signature

Re: Link t the souce code

[Jonathan S. Katz]

On 5/6/21 6:05 PM, Tom Lane wrote:
> Alvaro Herrera  writes:
>> I agree -- if the user wanted packages, they would not be reading that
>> page of the docs.  I'd just have it point to the same page that the
>> download page points to for source downloads, not a version-specific
>> one, as in the attached patch.
> 
> +1.  I think people reading this may have their own ideas about
> which version they want.  Also, getting the link to be sane in
> the devel docs might be problematic.

+1 on all of the above.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: mingw.org fails to load anything of value

[Jonathan S. Katz]

On 4/4/21 9:30 PM, Michael Paquier wrote:
> On Sun, Apr 04, 2021 at 09:47:08AM -0400, Jonathan S. Katz wrote:
>> Diving deeper while updating the links, I stumbled across this note:
>>
>> "The MinGW.org web‑site is undergoing an overhaul, whilst in the process
>> of transferring to a new hosting provider. During this transitional
>> phase, some pages may be temporarily unavailable."[1]
>>
>> So it appears this is part of a migration.
>>
>> Anyway, here is a patch updating the URLs.
> 
> Are we sure that mingw.org is completely dead?  The message showing up
> on their site seems to mean that this URL change is just temporary?

We would have to ask directly to clarify, but mingw.org domain itslf
looks very much like a parked domain.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: mingw.org fails to load anything of value

[Jonathan S. Katz]

On 4/4/21 9:30 AM, Jonathan S. Katz wrote:
> On 4/3/21 7:01 AM, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/13/installation-platform-notes.html
>> Description:
>>
>> 16.7.4. MinGW/Native Windows refers to the site http://www.mingw.org which
>> for me loads a blank page
> 
> Checking it out this morning, it went to a domain parking page.
> 
> Going off of Wikipedia[1], it seems that this is the project page:
> 
> https://mingw.osdn.io/
> 
> It gets better. The HTTPS link to mingw-w64.org has a cert invalid
> error, though the HTTP link works fine.
> 
> So I guess we need a few updates. I could propose a patch in a few moments.

Diving deeper while updating the links, I stumbled across this note:

"The MinGW.org web‑site is undergoing an overhaul, whilst in the process
of transferring to a new hosting provider. During this transitional
phase, some pages may be temporarily unavailable."[1]

So it appears this is part of a migration.

Anyway, here is a patch updating the URLs.

Jonathan

[1] https://mingw.osdn.io/index.html?page=docs.html

diff --git a/doc/src/sgml/install-windows.sgml 
b/doc/src/sgml/install-windows.sgml
index 64687b12e6..9ae8bb50ca 100644
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -230,7 +230,7 @@ $ENV{MSBFLAGS}="/m";
  
   Both Bison and Flex
   are included in the msys tool suite, available
-  from http://www.mingw.org/wiki/MSYS;> as part of the
+  from https://mingw.osdn.io;> as part of the
   MinGW compiler suite.
  
 
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 66ad4ba938..e9d433233b 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -982,7 +982,7 @@ build-postgresql:
  configure will check for the required
  header files and libraries to make sure that your
  OpenSSL installation is sufficient
- before proceeding. 
+ before proceeding.
 

   
@@ -2455,14 +2455,14 @@ xcrun --show-sdk-path
 those).  MinGW, the Unix-like build tools, and MSYS, a collection
 of Unix tools required to run shell scripts
 like configure, can be downloaded
-from http://www.mingw.org/;>.  Neither is
+from https://mingw.osdn.io;>.  Neither is
 required to run the resulting binaries; they are needed only for
 creating the binaries.

 

  To build 64 bit binaries using MinGW, install the 64 bit tool set
- from https://mingw-w64.org/;>, put its bin
+ from http://mingw-w64.org;>, put its bin
  directory in the PATH, and run
  configure with the
  --host=x86_64-w64-mingw32 option.


OpenPGP_signature
Description: OpenPGP digital signature

Re: mingw.org fails to load anything of value

[Jonathan S. Katz]

On 4/3/21 7:01 AM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/13/installation-platform-notes.html
> Description:
> 
> 16.7.4. MinGW/Native Windows refers to the site http://www.mingw.org which
> for me loads a blank page

Checking it out this morning, it went to a domain parking page.

Going off of Wikipedia[1], it seems that this is the project page:

https://mingw.osdn.io/

It gets better. The HTTPS link to mingw-w64.org has a cert invalid
error, though the HTTP link works fine.

So I guess we need a few updates. I could propose a patch in a few moments.

Jonathan

[1] https://en.wikipedia.org/wiki/MinGW



OpenPGP_signature
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/2/21 9:11 AM, Stephen Frost wrote:
> Greetings,
> 
> * Jonathan S. Katz (jk...@postgresql.org) wrote:

>> Thanks Stephen! Do we have any additional follow up on the pgweb side?
> 
> Yes and no. :)
> 
> Once the next set of minor releases is pushed out, I'll double-check
> that everything is working properly (the 'obsolete' pages should start
> showing up instead of the redirects, since we'll no longer be going
> through the "page not found" code path) and will then go remove the
> alias/redirects from the pages that no longer need them.

Great -- thanks for confirming.

Thanks,

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/1/21 3:34 PM, Stephen Frost wrote:
> Greetings,
> 
> * Stephen Frost (sfr...@snowman.net) wrote:

>> I've written a patch to begin to make this change and sent it into
>> -hackers for comments, thread is here:
>>
>> https://postgr.es/m/20201120211304.gg16...@tamriel.snowman.net
> 
> Just to wrap this up- this change has now been committed for v14.

Thanks Stephen! Do we have any additional follow up on the pgweb side?

Thanks,

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Update to reflect that TLS1 and TLSv1.1 are now deprecated

[Jonathan S. Katz]

On 3/24/21 5:49 AM, Daniel Gustafsson wrote:
> The recently published RFC 8996 deprecates the use of TLSv1 and TLSv1.1, the
> attached rewords where we say our default of 1.2 is industry best practice 
> with
> a link to the authoritative source.

I would s/as of/stated in/ and add a comma after RFC 8996, but otherwise
+1 from me.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: scram-sha-256 authentication

[Jonathan S. Katz]

On 1/4/21 12:04 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/auth-password.html
> Description:
> 
> How do you encode a plain password to the corresponding SCRAM-SHA-256
> encryption? Using online tools I obtain a result in a different format the
> in e.g. the "PostgreSQL Administration Cookbook", where the encrypted value
> starts with "SCRAM-SHA-256$4096:".

It's better to ask these questions in one of the community support
areas[1] as the form on the documentation page is intended for
documentation suggestions/corrections. I will provide some guidance below :)

I am not sure what your end goal is, but there are a few ways to create
the hashed SCRAM verifier:

- Using the \password flag in "psql"
- Using one of the connection drivers that interfaces with libpq's
PQencryptPasswordConn function[2]
  - Some driver's handle the password hashing independently

If those are not acceptable, I also have a talk that goes through an
example for how to create a SCRAM verifier and what the different parts
mean[3] as well as an example of creating the verifier in Python[4].

In terms of how things start above, i.e. "SCRAM-SHA-256$4096:" that
presents the hashing function to use and the number of iterations to use
to hash the password (similar to PBKDF2). The full verifier has the
following components with the following delimters:

DIGEST$ITERATIONS:SALT$STORED_KEY:SERVER_KEY

Hope this helps,

Jonathan

[1] https://www.postgresql.org/support/
[2]
https://www.postgresql.org/docs/current/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN
[3]
https://www2.slideshare.net/jkatz05/get-your-insecure-postgresql-passwords-to-scram
[4] https://gist.github.com/jkatz/e0a1f52f66fa03b732945f6eb94d9c21



OpenPGP_signature
Description: OpenPGP digital signature

Re: The sub-categories do not have anchors on this page

[Jonathan S. Katz]

On 12/17/20 10:11 AM, David G. Johnston wrote:
> On Thu, Dec 17, 2020 at 8:01 AM Bruce Momjian  > wrote:
> 
> On Thu, Dec 10, 2020 at 05:59:15PM -0300, Álvaro Herrera wrote:
> > On 2020-Dec-10, Steven Pousty wrote:
> >
> > > They certainly do at the top of the page, that's why I sent the
> second
> > > email. I was hoping to have anchors down the page where that
> actual topic
> > > is. The rational for this is, when I write a blog post, teach a
> class, help
> > > someone on slack... I can give them the URL right to the section
> I want
> > > them to read. This anchor would prevent just giving the url to
> the whole
> > > page and telling them to search for it.
> >
> > Ah -- so what you want is to have something like an icon (typically a
> > chain link icon) that appears next to the title, and points to itself?
> > Many sites do that.  I think it's a useful idea and we should consider
> > it, but it's a modification that would be done to the tooling and so
> > it'd affect the whole documentation, not just this page.
> 
> I see your point --- these sub-sections are mixed with others on the
> same page, so how would you know the link location?  I usually dig
> through the sgml and find one, or add one if it is missing, but that is
> hardly scalable.  Having a link icon makes sense --- even if they can
> just click on the subsection title and the URL changes to that section
> URL would be helpful.
> 
> 
> +1
> 
> I would have used this numerous times recently when pointing people to
> where to find answers to their questions.

Something to help with this has been on my backlog for a bit. We may be
able to resolve this with the pgweb CSS layer.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: link may be broken

[Jonathan S. Katz]

On 12/4/20 5:39 AM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/13/index.html
> Description:
> 
> Hello,
> 
> the following page:
> 
> https://www.postgresql.org/about/featurematrix/detail/340/
> 
> contains a link to "VACUUM  documentation":
> 
> https://www.postgresql.org/docs/latest/sql-vacuum.html/
> 
> following the link, I get a page saying "The URL you specified does not
> exist."

Fixed. Needed to s/latest/current/

Thanks for reporting!

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Possible Example Error in Documentation

[Jonathan S. Katz]

On 11/5/20 7:37 PM, Tom Lane wrote:
> PG Doc comments form  writes:
>> The following documentation comment has been logged on the website:
>> Page: https://www.postgresql.org/docs/12/plpgsql-transactions.html
>> Description:
> 
>> We are using Postgres 12. When I use the example given for
>> transaction_test1() from the documentation here:
>> https://www.postgresql.org/account/comments/new/12/plpgsql-transactions.html/,
>> the procedure is created without incident.  However, when I attempt "CALL
>> transaction_test1();", I receive the "invalid transaction termination"
>> error.
> 
> Hmm, it works for me.

Ditto.

I did get that error message if I put a "BEGIN;" statement before
executing the CALL statement.

Jonathan

Re: Version 13 documentation layout is harder to read than version 12

[Jonathan S. Katz]

On 9/29/20 3:00 PM, Tom Lane wrote:
> Niels Andersen  writes:
>>   2.  Is there a middle ground?
>>  *   Version 12 had 6 columns, version 13 has one.
>>  *   Could we have fewer columns? What if we had 3 columns: One for 
>> operator or function, one for the details and description, and one for an 
>> example with the results.
> 
> A lot of these tables *did* have three columns before.  They were still too
> wide.  See e.g. "Table 9.88 Replication SQL Functions" in the v12 docs.
> 
> Moreover, in a lot of places functions were just ridiculously
> under-documented because of the tiny amount of space available.
> If you compare v12 and v13 closely you'll notice that there's more
> text for many functions (9.35 Geometric Operators is a handy example);
> and there's room to add more now, wherever we need to.
> 
> Note that another reason for making these changes was so that the
> tables would render in a less-than-completely-unreadable fashion in PDF
> output, which is a good deal narrower than what most people use for
> web browser windows (and a good deal less forgiving of overruns, too).
> But I think it's a net benefit for HTML output as well, in that the
> output does adapt much better than before to smaller window sizes.
> Not everybody wants to dedicate their whole screen to Postgres docs.

I'll also note it helps on mobile viewing as well. We (likely the royal
"we" in this case) still need to figure out some things with the font
size on mobile to make it a bit easier to read, but the measurable
readability of the tables in the v13 docs is better than v12 on smaller
browsing windows.

> Anyway, a very large amount of effort went into this redesign this
> past spring, and we already tried a lot of variants, and already went
> through the predictable complaints within the developer community.
> I'm disinclined to redesign it again right now.  If people are still
> unhappy in a year or so, maybe there will be some appetite for a revisit.

I would say on this particular page, the only thing I find slightly
confusing is when the "->" operator is being described ("json -> integer
-> json"), but I think that may just be an unfortunate happenstance and
not grounds for redesign, at least at this time.

In recent times (which likely extends to the before times), I've found
when we've rolled out any UI/UX changes across pgweb properties there is
a mix of love/hate that is based on personal preference, which may or
may not coincide with what the overall goal of the change was.

If there is something that in a defined way is hampering usability, then
we should address it, but otherwise, per Tom's analysis, I would let
this bake a bit more and see if we want to make improvements towards the
end of the v14 development cycle.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 6/1/20 6:57 PM, Tom Lane wrote:
> =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?=  writes:
>> I have spotted this change recently at progress monitoring devel docs (
>> https://www.postgresql.org/docs/devel/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING).
>> Current version seems a little chaotic since there are multiple tables on
>> the same page with 2 mixed layouts. Older layout (for example v12 one -
>> https://www.postgresql.org/docs/12/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING)
>> is much easier to read for me.
> 
>> Is this final change? I do not see any problem on this (progress
>> monitoring) page in old layout. Is there any example of problematic page?
>> Maybe there's a different way to solve this. For example instead of
>> in-lining long text as a column description, it should be possible to link
>> to detailed description in custom paragraph or table. See description
>> column at table 27.22. at progress monitoring page for column "phase" for
>> similar approach.
> 
> I'm not planning on revisiting that work, no.  And converting every
> table/view description table into two (or more?) tables sure doesn't
> sound like an improvement.
> 
> Perhaps there's a case for reformatting the phase-description tables
> in the progress monitoring section to look more like the view tables.
> (I hadn't paid much attention to them, since they weren't causing PDF
> rendering problems.)  On the other hand, you could argue that it's
> good that they don't look like the view tables, since the info they
> are presenting is fundamentally different.  I don't honestly see much
> wrong with the way it is now.

I think it looks fine. +1 for leaving it.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/10/20 2:03 PM, Jonathan S. Katz wrote:
> On 5/10/20 12:27 PM, Tom Lane wrote:
>> Just FTR, here's a complete patch for this. 
> 
> Cool. I'll play around with it tonight once I clear out release work.
> Per upthread reference, I believe you've become a CSS maven yourself.

Time slipped a bit (sorry!), but while prepping for the release I
reviewed this. Visually, it looks WAY better. The code checks out too. I
think any tweaks would be primarily around personal preference on the
UI, so it may be better just to commit and get it out in the wild.

...and so I did. Committed[1].

Jonathan

[1]
https://git.postgresql.org/gitweb/?p=pgweb.git;a=commitdiff;h=93716f2a817dbdae8cccf86bc951b45b68ea52d9



signature.asc
Description: OpenPGP digital signature

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/10/20 12:27 PM, Tom Lane wrote:
> Just FTR, here's a complete patch for this. 

Cool. I'll play around with it tonight once I clear out release work.
Per upthread reference, I believe you've become a CSS maven yourself.

> I successfully regenerated
> the column names, types, and ordering from the system catalogs, and
> plugged the descriptions back into that by dint of parsing them out of
> the XML.  The "references" data was based on findoidjoins' results plus
> hand additions to cover all the cases we are calling out now (there are
> a lot of "references" links for attnums and a few other non-OID columns,
> plus references links for views which findoidjoins doesn't consider).
> So I have pretty high confidence that this info is OK.  I'd be too
> embarrassed to show anybody the code though ;-) ... it was just a brute
> force hack.
If it works it works ;)

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/6/20 5:18 PM, Alvaro Herrera wrote:
> Hello
> 
> I think the recent changes to CSS might have broken things in the XSLT
> build; apparently the SGML tooling did things differently.  Compare the
> screenshot of tables 67.2 and 67.3 ... 9.6 on the left, master on the
> right.  Is the latter formatting correct/desirable?

I know that 9.6 uses a different subset of the styles, and I recall the
text being blue during the original conversion. For example, the "table"
in the 9.6 docs has a class of "CALSTABLE" whereas in master, it is
"table" (and we operate off of it as "table.table" when doing lookups,
to ensure anything else with class "table" is unaffected).

There's also not as much control over some of the older documentation as
there are less classes we can bind the CSS too.

The latest changes should only affect master (devel) and beyond.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/5/20 7:42 PM, Tom Lane wrote:
> Here's a really quick-n-dirty prototype patch that just converts the
> pg_aggregate table to the proposed style, plus a screenshot for those
> who don't feel like actually building the docs with the patch.

Not opposed to building the docs, but the screenshot expedites things ;)

> Looking at the results, it seems like we could really use a bit more
> horizontal space between the column names and data types, and perhaps
> also between the types and the (references) annotations.  Other than
> that it looks decent.  I don't know what's the cleanest way to add
> some space there --- I'd rather not have the SGML text do it explicitly.

If each element (i.e. column name, data type) is wrapped in a HTML
element with its own class (e.g. a span) it's fairly easy to add that
space with CSS. I'm not sure the ramifications for the PDFs though.

> There's room for complaint that this takes up more vertical space than
> the old way, assuming you have a reasonably wide window.  I'm not
> terribly bothered by that, but maybe someone else will be?  I'm inclined
> to think that that's well worth the benefit that we won't feel compelled
> to keep column descriptions short.

I think for reference materials, vertical space is acceptable. It seems
to be the "mobile way" of doing things, since people are scrolling down.

(And unlike the mailing lists, we don't need to keep the font small ;)

Anyway, +1

> BTW, this being just a test hack, I repurposed the "func_table_entry" and
> "func_signature" style marker roles.  If we do this for real then of
> course we'd want to use different roles, even if they happen to mark up
> the same for now.

Agreed.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/4/20 9:52 PM, Tom Lane wrote:
> As of HEAD, building the PDF docs for A4 paper draws 538 "contents
> ... exceed the available area" warnings.  While this is a nice step
> forward from where we were (v12 has more than 1500 such warnings),
> we're far from done fixing that issue.
> 
> A large chunk of the remaining warnings are about tables that describe
> the columns of system catalogs, system views, and information_schema
> views.  The typical contents of a row in such a table are a field name,
> a field data type, possibly a "references" link, and then a description.
> Unsurprisingly, this does not work very well for descriptions of more
> than a few words.  And not infrequently, we *need* more than a few words.
> 
> ISTM this is more or less the same problem we have/had with function
> descriptions, and so I'm tempted to solve it in more or less the same
> way.  Let's redefine the table layout to look like, say, this for
> pg_attrdef [1]:
> 
> oid oid
>   Row identifier
> 
> adrelid oid (references pg_class.oid)
>   The table this column belongs to
> 
> adnum int2 (references pg_attribute.attnum)
>   The number of the column
> 
> adbin pg_node_tree
>   The column default value, in nodeToString() representation. Use
>   pg_get_expr(adbin, adrelid) to convert it to an SQL expression.
> 
> That is, let's go over to something that's more or less like a table-ized
> , with the fixed items for an entry all written on the first
> line, and then as much description text as we need.  The actual markup
> would be closely modeled on what we did for function-table entries.
> 
> Thoughts?

+1. Looks easy enough to read in a plaintext email, and if there are any
minor style nuances on the HTML front, I'm confident we'll solve them.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/28/20 2:19 PM, Magnus Hagander wrote:
> On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz  <mailto:jk...@postgresql.org>> wrote:
> 
> On 4/9/20 11:45 PM, Bruce Momjian wrote:
> > On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
> >> On 4/9/20 4:57 PM, Bruce Momjian wrote:
> >>> Jonathan, Stephen, with the minor release done, can we focus on
> adding
> >>> the URL redirect and completing the patch to rename this feature
> in the
> >>> docs?  Thanks.
> >>
> >> Yes, I have a prototype for this ready, which I had scrambled
> together
> >> before the release. I am happy to make it committable in the
> coming days.
> >
> > Thanks.  Once that is done Stephen can apply my patch with his
> > additions.
> 
> Please see attached patch for pgweb that allows for the documentation to
> be redirected from a page that is removed to a newer page. The way
> it works:
> 
> - Checks to see if a page is found. If it is, great!
> - Now if a page 404s, we first check to see if there is a forwarding
> address, i.e. the new page. If it is, we issue a 301 (permanent
> redirecTt).
> - If it's still not found, we abort.
> 
> I believe this gives us the desired behavior.
> 
> Thoughts on the patch?
> 
> 
>  Looks good to me. Go for it.

This is deployed. Ready for the patch in core.

Thanks!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: List of pages from versions 9, 10, and 11 that don't exist in "current"

[Jonathan S. Katz]

On 4/25/20 1:12 PM, Michael Christofides wrote:
> Hi there,
> 
> Does anyone have an easy way of seeing which pages from the 9.x, 10,
> or 11 docs don't have a "current" version?

I don't have an easy way, but I have a pedantic way:

1. Set up the pgweb app[1]
2. Set up the requirements for the docload.py utility
(tools/docs/docload.py)
3. Download the release source PG12 all the way down. You would really
only need one, likely the latest (e.g. at the time of this writing 12.2,
11.7, ...)
4. Load each one into the database. You may need to explicitly create
the "Version" objects in the admin for pgweb
5. Write SQL to see which filenames are present in an earlier version
but not a later one.

> For context, I've built a Firefox extension that redirects old
> versions of the docs to their "current" version, except when either:
> * you're already on the docs, or
> * when a "current" version of the page doesn't exist.

Sounds interesting. There is presently a patch[3] that could/should help
to address this case. The challenge, outside of the file that was the
impetus for the patch, would be finding the forwarding addresses for the
new pages. I believe Step 5 in the above would help with that.

Thanks!

Jonathan

[1] https://www.postgresql.org/developer/related-projects/
[2] https://www.postgresql.org/ftp/source/
[3]
https://www.postgresql.org/message-id/4490e710-85f7-87a9-74dd-793d27440bed%40postgresql.org



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/9/20 11:45 PM, Bruce Momjian wrote:
> On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
>> On 4/9/20 4:57 PM, Bruce Momjian wrote:
>>> Jonathan, Stephen, with the minor release done, can we focus on adding
>>> the URL redirect and completing the patch to rename this feature in the
>>> docs?  Thanks.
>>
>> Yes, I have a prototype for this ready, which I had scrambled together
>> before the release. I am happy to make it committable in the coming days.
> 
> Thanks.  Once that is done Stephen can apply my patch with his
> additions.

Please see attached patch for pgweb that allows for the documentation to
be redirected from a page that is removed to a newer page. The way it works:

- Checks to see if a page is found. If it is, great!
- Now if a page 404s, we first check to see if there is a forwarding
address, i.e. the new page. If it is, we issue a 301 (permanent redirecTt).
- If it's still not found, we abort.

I believe this gives us the desired behavior.

Thoughts on the patch?

Thanks,

Jonathan
From e2120f0a80697d13dc6d951f363d01feb60c9b9d Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Tue, 11 Feb 2020 14:41:46 -0500
Subject: [PATCH] Introduce documentation redirects for doc pages that are
 renamed

The web documentation used to suffer from a problem that if a
documentation page were renamed in a newer version, any references
pointing to said documentation would be lost. For example, the feature
known as "Default Roles" was renamed to "Privileged Roles" but caused
a change in the URL.

This patch introduces the ability to create a "DocPageRedirect" by
specifying the previous name of the documentation page (e.g.
"default-roles.html") and the new name (e.g. "privileged-roles.html")
such that the continuity is preserved between versions.
---
 pgweb/docs/admin.py   |  3 ++-
 pgweb/docs/migrations/0004_docpageredirect.py | 24 +++
 pgweb/docs/models.py  | 11 +
 pgweb/docs/views.py   | 15 ++--
 4 files changed, 50 insertions(+), 3 deletions(-)
 create mode 100644 pgweb/docs/migrations/0004_docpageredirect.py

diff --git a/pgweb/docs/admin.py b/pgweb/docs/admin.py
index d2f2590..79f1d12 100644
--- a/pgweb/docs/admin.py
+++ b/pgweb/docs/admin.py
@@ -1,5 +1,6 @@
 from django.contrib import admin
 
-from .models import DocPageAlias
+from .models import DocPageAlias, DocPageRedirect
 
 admin.site.register(DocPageAlias)
+admin.site.register(DocPageRedirect)
diff --git a/pgweb/docs/migrations/0004_docpageredirect.py 
b/pgweb/docs/migrations/0004_docpageredirect.py
new file mode 100644
index 000..d19f959
--- /dev/null
+++ b/pgweb/docs/migrations/0004_docpageredirect.py
@@ -0,0 +1,24 @@
+# Generated by Django 2.2.12 on 2020-04-24 23:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+dependencies = [
+('docs', '0003_docs_alias'),
+]
+
+operations = [
+migrations.CreateModel(
+name='DocPageRedirect',
+fields=[
+('id', models.AutoField(auto_created=True, primary_key=True, 
serialize=False, verbose_name='ID')),
+('redirect_from', models.CharField(max_length=64, unique=True, 
help_text='Page to redirect from, e.g. "old_page.html"')),
+('redirect_to', models.CharField(max_length=64, unique=True, 
help_text='Page to redirect to, e.g. "new_page.html"')),
+],
+options={
+'verbose_name_plural': 'Doc page redirects',
+},
+),
+]
diff --git a/pgweb/docs/models.py b/pgweb/docs/models.py
index 87afe1c..a4558a6 100644
--- a/pgweb/docs/models.py
+++ b/pgweb/docs/models.py
@@ -33,3 +33,14 @@ class DocPageAlias(models.Model):
 class Meta:
 db_table = 'docsalias'
 verbose_name_plural = 'Doc page aliases'
+
+
+class DocPageRedirect(models.Model):
+"""DocPageRedirect offers the ability to redirect from a page that has been
+completely removed from the PostgreSQL documentation
+"""
+redirect_from = models.CharField(max_length=64, null=False, blank=False, 
unique=True, help_text='Page to redirect from, e.g. "old_page.html"')
+redirect_to = models.CharField(max_length=64, null=False, blank=False, 
unique=True, help_text='Page to redirect from, e.g. "new_page.html"')
+
+class Meta:
+verbose_name_plural = "Doc page redirects"
diff --git a/pgweb/docs/views.py b/pgweb/docs/views.py
index 0566129..6763795 100644
--- a/pgweb/docs/views.py
+++ b/pgweb/docs/views.py
@@ -16,7 +16,7 @@ from pgweb.util.misc import send_template_mail
 from pgweb.core.models import Version
 from pgweb.util.db import exec_to_dict
 
-from .models import DocPage
+from 

Re: PDF documentation bug: different table columns overlap and are unreadable

[Jonathan S. Katz]

On 4/17/20 3:37 AM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/index.html
> Description:
> 
> In the PDF documentation, some table columns overflow and overlap with the
> next column. This makes the content of both columns unreadable.

Thanks for reporting. There is ongoing work on this, with some changes
already committed to the development version:

https://www.postgresql.org/message-id/flat/9326.1581457869%40sss.pgh.pa.us

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Developer FAQ / What information is available to learn PostgreSQL internals?

[Jonathan S. Katz]

On 4/16/20 4:20 AM, Marc Rechté wrote:
> 
> https://wiki.postgresql.org/wiki/Developer_FAQ
> 
> This link is dead: introduction to Hacking PostgreSQL - With lots of
> code review!
> https://linux.org.au/conf/2007/att_data/Miniconfs(2f)PostgreSQL/attachments/hacking_intro.pdf

It appears that is has been updated:

https://wiki.postgresql.org/index.php?title=Developer_FAQ=34818=34772

Thanks for reporting!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: pre-requiste for installation

[Jonathan S. Katz]

On 4/12/20 8:21 AM, Ankush Chawla wrote:
> hi 
> 
> what is the pre-requiste packages for Postgres Installation on SUSE Linux
> 
> I have already transferred .run file
> 
> What would be pre-requiste package, hardware or software requirements ,
> any readme available?

I believe these are listed on this page:

https://zypp.postgresql.org/howtozypp.php

which is linked to from the SuSE downloads page:

https://www.postgresql.org/download/linux/suse/

In general, it's better to ask these types of questions on the
pgsql-gene...@lists.postgresql.org mailing list[1] as this mailing list
is geared towards the maintenance of the PostgreSQL documentation.

Hope this helps,

Jonathan

[1] https://www.postgresql.org/support/



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/9/20 4:57 PM, Bruce Momjian wrote:
> On Thu, Feb  6, 2020 at 10:59:09AM -0500, Jonathan Katz wrote:
>> On 2/6/20 12:11 AM, Bruce Momjian wrote:
>>> On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
> Using this feature to handle the rename of a file *between* major
> versions, thus leaving the changes in master, should be safe (as long
> as we add an entry to that table in pgweb).
>
> As for back branches, I think we have to say that it's too close to
> the minor release to safely have something done in pgweb before then.

 This part I agree on, but let's sync offline to see if there is
 something within reason, with a preference to *not* rush if we're
 worried about breaking something right before release.
>>>
>>> Folks, is it Thursday.  Can we revert this and return to it when we are
>>> not rushed?  Alternatively, can someone who controls all the moving
>>> parts, like  redirects and Stephen's patch additions take ownership of
>>> this issue, with authority to revert the patch if things are too close?
>>
>> Magnus and I briefly discussed what it would take, but the probability
>> of having the redirects ready on pgweb before the release is
>> slim-to-none, as we'd like to thoroughly test.
>>
>> We can start experimenting with it now, and commit a fix after the release.
>>
>> I don't have the power to revert changes directly to the documentation
>> in core, so I cannot take ownership of that part. However, I am happy to
>> own the completion of the redirect feature.
> 
> Jonathan, Stephen, with the minor release done, can we focus on adding
> the URL redirect and completing the patch to rename this feature in the
> docs?  Thanks.

Yes, I have a prototype for this ready, which I had scrambled together
before the release. I am happy to make it committable in the coming days.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/14/20 8:56 PM, Peter Geoghegan wrote:
> On Fri, Feb 14, 2020 at 5:51 PM Tom Lane  wrote:
>> Hm, I wouldn't go into that much detail; it'd likely soon be out of
>> date anyway.  I had in mind something more like "If the STYLE=website
>> option is used, the generated HTML files will include references to
>> stylesheets hosted at www.postgresql.org, so that viewing them will
>> require network access."
> 
> But everything else looks good, right?
> 
> I would like to commit this patch shortly.

Language updates attached...mostly kept Tom's suggestions.

Thanks,

Jonathan
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index c99198f5e5..64ebdb3257 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -276,6 +276,13 @@ checking for fop... fop
 doc/src/sgml$ make STYLE=website html
 

+
+   
+If the STYLE=website optoin is used, the generated HTML
+files include references to stylesheets hosted on https://www.postgresql.org/docs/current/;>postgresql.org and
+require network access to view.
+   
  
 
  
diff --git a/doc/src/sgml/stylesheet-html-common.xsl 
b/doc/src/sgml/stylesheet-html-common.xsl
index 9edce52a10..d9961089c6 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -18,6 +18,14 @@
 pgsql-docs@lists.postgresql.org
 2
 
+
+
+  docContent
+  container-fluid col-10
+
 
 
 
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 4ff6e8ed24..bc5a904e0b 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -23,11 +23,15 @@
 
   
 stylesheet.css
-
https://www.postgresql.org/media/css/docs.css
+
+  https://www.postgresql.org/media/css/fontawesome.css
+  https://www.postgresql.org/media/css/bootstrap.min.css
+  https://www.postgresql.org/media/css/main.css
+  https://www.postgresql.org/media/css/normalize.css
+
   
 
 
-
 
 
  


signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/14/20 6:06 PM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> To load the webfont, the "main.css" file uses a CSS "@import"
>> instruction, which has a limitation that it can only be used as the top
>> of the file. As main.css is not the first file in the "docs.csS"
>> sandwich, it does not load.
>> Buried in some version of the DocBook[1] documentation were in
>> instructions on how to load in multiple stylesheets via
>>  
>> which I followed in our XSLT, which lead to that portion of the diff.
> 
> It looks to me like the main text font now matches, but the font used for
>  text doesn't quite -- see the attached, and note for example the
> capital T's in CREATE TYPE.  (Local build with this patch on the left,
> website on the right.)  Still, it's enormously closer than before.

Hmm, I'm not getting that. They're both identical for me, at least in
Chrome...

...but I hopped over into Safari, and I saw a difference between the
local file in Chrome, and what .org looks like in Safari.

I dove into this a bit. For this view, we are just using the default
"monospace" font that is referenced by a particular browser. It seems
like there was a change in Safari 12 where you can no longer override
the default monospace font. It appears to be using "SF Mono."

In Chrome, it appears that it is using Courier.

A potential solution is that we drop the use of "monospace" in relying
on the OS default and just pick a font. I would say that this is outside
the scope of the patch that's being proposed, but certainly something to
look into on the pgweb side given we're creating an inconsistent
cross-browser experience.

> 
>> Not included is one of Tom's original questions, which is should we just
>> make using the website styles the default? As it stands, this would
>> require network connectivity to preview the look for a page. If we want
>> to ensure consistent views across the board, then I would say we import
>> the stylesheets, knowing that "main.css" is volatile.
> 
> The point about network access seems to me to be sufficient reason not
> to make it the default.  I'd actually say that we ought to annotate
> section J.3.1 to point out that "make STYLE=website" will result in
> that.  However, I'm not quite clear on whether that means external
> access during viewing, or during build, or both?  The note should say.

It would only be during viewing -- the build just puts the URL into the
HTML file.

But don't take my word for it, please see the attached patch ;)

Jonathan
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index c99198f5e5..17f2bf42ac 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -276,6 +276,43 @@ checking for fop... fop
 doc/src/sgml$ make STYLE=website html
 

+
+   
+Viewing the documentation built using the https://www.postgresql.org/docs/current/;>postgresql.org
+stylesheet requires Internet connectivity, as the HTML pages contain
+references to remotely hosted stylesheets, including:
+
+ 
+  
+   https://www.postgresql.org/media/css/fontawesome.css;>
+https://www.postgresql.org/media/css/fontawesome.css
+   
+  
+ 
+ 
+  
+   https://www.postgresql.org/media/css/bootstrap.min.css;>
+https://www.postgresql.org/media/css/bootstrap.min.css
+   
+  
+ 
+ 
+  
+   https://www.postgresql.org/media/css/main.css;>
+https://www.postgresql.org/media/css/main.css
+   
+  
+ 
+ 
+  
+   https://www.postgresql.org/media/css/normalize.css;>
+https://www.postgresql.org/media/css/normalize.css
+   
+  
+ 
+
+   
  
 
  
diff --git a/doc/src/sgml/stylesheet-html-common.xsl 
b/doc/src/sgml/stylesheet-html-common.xsl
index 9edce52a10..d9961089c6 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -18,6 +18,14 @@
 pgsql-docs@lists.postgresql.org
 2
 
+
+
+  docContent
+  container-fluid col-10
+
 
 
 
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 4ff6e8ed24..bc5a904e0b 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -23,11 +23,15 @@
 
   
 stylesheet.css
-
https://www.postgresql.org/media/css/docs.css
+
+  https://www.postgresql.org/media/css/fontawesome.css
+  https://www.postgresql.org/media/css/bootstrap.min.css
+  https://www.postgresql.org/media/css/main.css
+  https://www.postgresql.org/media/css/normalize.css
+
   
 
 
-
 
 
  


signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/11/20 10:56 PM, Jonathan S. Katz wrote:
> On 2/11/20 3:49 PM, Jonathan S. Katz wrote:
>> On 2/11/20 3:41 PM, Peter Geoghegan wrote:
>>> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz  
>>> wrote:
>>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>>> variations but in my quick review of it, I could not figure out how to
>>>> make a XSLT respect having multiple stylesheets (likely due to my lack
>>>> of familiarity with XSLT).
>>>
>>> I tried this patch out.
>>
>> Thanks!
>>
>>> The alignment is a little off, since the docs
>>> don't appear in the website's frame, and lack the website's header. It
>>> would be nice if the same margins appeared to the left and to the
>>> right. 
>>
>> Yup, that's a direct result of not having the Bootstrap base.
>>
>>> But even still, it's a vast improvement.
>>
>> Cool.
> 
> I played around with this for a bit longer, became a bit more familiar
> with DocBook[1] (and a lot of other pages, but this one seemed
> relevant), and here is what I came up with:
> 
> As I mentioned, the way pgweb works is that it wraps a root element (the
> ...) around the imported HTMl from the
> generation, which allows it to apply the various website styles. This is
> important, because it allows us to apply some general style rules, but
> namespace them specifically to the documentation. Hold this thought for
> a moment.
> 
> When calling "make STYLE=website html", this turns on a flag that embeds
> the URL to the old "docs.css" content that we generated. I did an
> experiment where I overloaded the "dynamic CSS generator" we have in our
> code to include the bootstrap.css files (as well as some others) in
> addition to our new base CSS. This demonstrated a marked improvement in
> the output from the above command, but it was still not perfect: the CSS
> rules still expect there to be the #docContent namespace.
> 
> I thought this would be a good area to explore to see if I could get the
> #docContent ID wrapped around the content body. As I was writing this
> note (where actually I was about to throw in the towel), on a hunch I
> improved my Googling and found a solution (attached).
> 
> This works with pgweb as pgweb extracts the content from the  tag
> that is generated by "make html" so this is unaffected.
> 
> For this solution to fully work, I also need to make a patch to pgweb. I
> have it 80% done, where the final 20% is getting rid of some annoying
> errors of files it is looking for (the Bootstrap minification expects a
> CSS map file. I believe I can silence that).
> 
> It's not perfect: we don't have a full container around the generated
> documentation so you can't see it exactly in terms of how it's render on
> the website, but it's way closer to the look and feel. I might be able
> to add a few more attributes to make it look closer to the website in
> that regard, though after there is consensus that this approach is ok.
> 
> That said, I think this is a happy compromise that allows said mode to
> appear mostly like what you would find on the website.

Realizing this might be a bit wonky to test, I made the necessary
changes to pgweb and pushed those, so the results of the patch now look
like what I was seeing. If you were previously testing it, rebuild the
docs with STYLE=website and it should now look better.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/11/20 3:49 PM, Jonathan S. Katz wrote:
> On 2/11/20 3:41 PM, Peter Geoghegan wrote:
>> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz  
>> wrote:
>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>> variations but in my quick review of it, I could not figure out how to
>>> make a XSLT respect having multiple stylesheets (likely due to my lack
>>> of familiarity with XSLT).
>>
>> I tried this patch out.
> 
> Thanks!
> 
>> The alignment is a little off, since the docs
>> don't appear in the website's frame, and lack the website's header. It
>> would be nice if the same margins appeared to the left and to the
>> right. 
> 
> Yup, that's a direct result of not having the Bootstrap base.
> 
>> But even still, it's a vast improvement.
> 
> Cool.

I played around with this for a bit longer, became a bit more familiar
with DocBook[1] (and a lot of other pages, but this one seemed
relevant), and here is what I came up with:

As I mentioned, the way pgweb works is that it wraps a root element (the
...) around the imported HTMl from the
generation, which allows it to apply the various website styles. This is
important, because it allows us to apply some general style rules, but
namespace them specifically to the documentation. Hold this thought for
a moment.

When calling "make STYLE=website html", this turns on a flag that embeds
the URL to the old "docs.css" content that we generated. I did an
experiment where I overloaded the "dynamic CSS generator" we have in our
code to include the bootstrap.css files (as well as some others) in
addition to our new base CSS. This demonstrated a marked improvement in
the output from the above command, but it was still not perfect: the CSS
rules still expect there to be the #docContent namespace.

I thought this would be a good area to explore to see if I could get the
#docContent ID wrapped around the content body. As I was writing this
note (where actually I was about to throw in the towel), on a hunch I
improved my Googling and found a solution (attached).

This works with pgweb as pgweb extracts the content from the  tag
that is generated by "make html" so this is unaffected.

For this solution to fully work, I also need to make a patch to pgweb. I
have it 80% done, where the final 20% is getting rid of some annoying
errors of files it is looking for (the Bootstrap minification expects a
CSS map file. I believe I can silence that).

It's not perfect: we don't have a full container around the generated
documentation so you can't see it exactly in terms of how it's render on
the website, but it's way closer to the look and feel. I might be able
to add a few more attributes to make it look closer to the website in
that regard, though after there is consensus that this approach is ok.

That said, I think this is a happy compromise that allows said mode to
appear mostly like what you would find on the website.

Thanks,

Jonathan

[1] http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html
diff --git a/doc/src/sgml/stylesheet-html-common.xsl 
b/doc/src/sgml/stylesheet-html-common.xsl
index 9edce52a10..8c2c759c81 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -18,6 +18,13 @@
 pgsql-docs@lists.postgresql.org
 2
 
+
+
+  docContent
+
 
 
 
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 4ff6e8ed24..bd27b8c1c9 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -23,7 +23,7 @@
 
   
 stylesheet.css
-
https://www.postgresql.org/media/css/docs.css
+https://www.postgresql.org/dyncss/docs.css
   
 
 


signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/11/20 3:41 PM, Peter Geoghegan wrote:
> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz  
> wrote:
>> Anyway, attached is a first attempt at a patch. I tried a few different
>> variations but in my quick review of it, I could not figure out how to
>> make a XSLT respect having multiple stylesheets (likely due to my lack
>> of familiarity with XSLT).
> 
> I tried this patch out.

Thanks!

> The alignment is a little off, since the docs
> don't appear in the website's frame, and lack the website's header. It
> would be nice if the same margins appeared to the left and to the
> right. 

Yup, that's a direct result of not having the Bootstrap base.

> But even still, it's a vast improvement.

Cool.

>>
> There are a couple of inconsistencies in the tables and diagrams that
> appear on this documentation page (on my local build that uses your
> patch):
> 
> https://www.postgresql.org/docs/devel/storage-page-layout.html
> 
> The tables look different, which isn't too bad. The "Figure 68.1. Page
> Layout" diagram is massive, though. IIRC was an issue that had to be
> addressed on the website a little after the introduction of images
> into the docs. It seems as if my local build of the docs needs that
> same fix.

Ditto on missing the Bootstrap base. The tables rely directly on that
base for the style an formatting. For the images, the CSS classes are:

"figure col-xl-8 col-lg-10 col-md-12"

"figure" is one of our custom defined classes, but the rest are
Bootstrap and are designed to size to the particular browser window
resolution.

(For the history of the figure sizing, it was two fixes:

1. One with the SVG generation to allow for it to scale (the "S" in SVG
:) and then
2. Applying the CSS classes shown above.


Without the CSS classes, the image will scale without limit)

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/11/20 2:32 PM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 2/11/20 1:37 PM, Tom Lane wrote:
>>> I also wonder why duplicating the website's style isn't the default.
>>> Doesn't seem like having authors optimize for some other style is
>>> what we really want.
> 
>> Oh, and specifically for this, my guess is because it requires one to
>> make a call over a network to load the stylesheet. :)
> 
> Surely we could provide directions about how to store that locally.

I have a little doubt about that, but per mention in the original email,
it means storing a lot more stylesheets and ones that may change with
more frequency than the project. It may not be too much of an issue, but
I do want to note that. I'm somewhat ambivalent myself, but my
preference is to have the single source of truth.

Anyway, attached is a first attempt at a patch. I tried a few different
variations but in my quick review of it, I could not figure out how to
make a XSLT respect having multiple stylesheets (likely due to my lack
of familiarity with XSLT).

This just swaps out the link. A better approach would be to find a way
to include multiple CSS stylesheets. After searching over a bunch of
different terms, I could not figure out how to get to this result, but
as mentioned, I'm close to clueless on writing XSLT at this point.

Another way we could get to the desired result add something to pgweb
similar to the old "docs.css" that is being referenced that combines the
multiple stylesheets into one. It's a bit of an anti-pattern in modern
web, so I'm not thrilled to go down that route.

Jonathan
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 4ff6e8ed24..38434367f1 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -23,7 +23,7 @@
 
   
 stylesheet.css
-
https://www.postgresql.org/media/css/docs.css
+
https://www.postgresql.org/media/css/base.css
   
 
 


signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/11/20 1:37 PM, Tom Lane wrote:

> I also wonder why duplicating the website's style isn't the default.
> Doesn't seem like having authors optimize for some other style is
> what we really want.

Oh, and specifically for this, my guess is because it requires one to
make a call over a network to load the stylesheet. :)

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Duplicating website's formatting in local doc builds

[Jonathan S. Katz]

On 2/11/20 1:37 PM, Tom Lane wrote:
> I'm wondering how to do $SUBJECT.  The fine manual suggests
> 
>   make STYLE=website html
> 
> but what I'm getting here with that is not a very close approximation
> of what I see at postgresql.org.  It's closer than the default,
> but it's not the same font, margins, etc.
> 
> I also wonder why duplicating the website's style isn't the default.
> Doesn't seem like having authors optimize for some other style is
> what we really want.

It looks like it's pulling from the wrong source[1]. It should be:


https://www.postgresql.org/dyncss/base.css

There are a few more dependencies now as well to get the Bootstrap
structure and the font:

https://www.postgresql.org/media/css/fontawesome.css
https://www.postgresql.org/media/css/bootstrap.min.css

(And one for another font...which I see we should import the dependency on).

This should likely be a small quick change. I was going to try to say
"after the release" comment, but given I'm in both codebases at the
moment, I'll do a quick test and see how it looks.

(FWIW, I test the appearance a bit differently. I actually import built
documentation into my local copy of pgweb and tinker from there, as I'll
have all the dependencies available. That likely is not a viable option
for most people working on the documentation [unless we make it easier
to get pgweb up and running]).

Jonathan

[1]
https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/stylesheet.xsl;hb=HEAD#l26



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 2/6/20 12:11 AM, Bruce Momjian wrote:
> On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
>>> Using this feature to handle the rename of a file *between* major
>>> versions, thus leaving the changes in master, should be safe (as long
>>> as we add an entry to that table in pgweb).
>>>
>>> As for back branches, I think we have to say that it's too close to
>>> the minor release to safely have something done in pgweb before then.
>>
>> This part I agree on, but let's sync offline to see if there is
>> something within reason, with a preference to *not* rush if we're
>> worried about breaking something right before release.
> 
> Folks, is it Thursday.  Can we revert this and return to it when we are
> not rushed?  Alternatively, can someone who controls all the moving
> parts, like  redirects and Stephen's patch additions take ownership of
> this issue, with authority to revert the patch if things are too close?

Magnus and I briefly discussed what it would take, but the probability
of having the redirects ready on pgweb before the release is
slim-to-none, as we'd like to thoroughly test.

We can start experimenting with it now, and commit a fix after the release.

I don't have the power to revert changes directly to the documentation
in core, so I cannot take ownership of that part. However, I am happy to
own the completion of the redirect feature.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 2/4/20 3:34 AM, Magnus Hagander wrote:
> On Mon, Feb 3, 2020 at 9:59 PM Jonathan S. Katz  wrote:

>> So, if there was something done to redirect people from specific
>> deprecated documentation pages historically, it was before my time. Most
>> of the redirects have been as general purposes ones (e.g. /docs/12), the
>> rules we put in for getting rid of "static", and the release notes,
>> which still receives some negative feedback towards it for different
>> reasons (though I think overall the effort was well-received). Anyway,
>> if we had a redirect in place, I'd want us to do it well.
> 
> We have something close to it in commit
> 496416ceda9c1015d9e7a6ef4b4fb18dae8a8d4e. But that doesn't actually
> generate redirects when requests are coming in from the outside -- it
> just makes sure our *internal* links can survive the rename of a file
> between branches.

Ah cool, didn't realize we had this feature :)

> So it may not be exactly what's being looked for here, but it might be
> a starting point. Probably the same underlying mapping table could be
> used, but I haven't investigated that closely enough to say if it's
> doable at this point, just that it's a starting point.

Yeah. It could be as simple as having a flag on it to say it should
redirect if the old file (presumably "file2" in the model) is hit. I'm
saying this without diving into the mechanics of the code.

> Using this feature to handle the rename of a file *between* major
> versions, thus leaving the changes in master, should be safe (as long
> as we add an entry to that table in pgweb).
> 
> As for back branches, I think we have to say that it's too close to
> the minor release to safely have something done in pgweb before then.

This part I agree on, but let's sync offline to see if there is
something within reason, with a preference to *not* rush if we're
worried about breaking something right before release.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 2/3/20 3:42 PM, Bruce Momjian wrote:
> On Thu, Jan 23, 2020 at 07:12:08PM -0500, R Ransbottom wrote:
>> On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote:
>>> On 2020/01/19 12:56, R Ransbottom wrote:
>>
 I would hope to find correct documentation somewhere--that somewhere
>>
>>> Indeed, however it's important that the PostgreSQL documentation remains
>>> stable for released versions.
>>
>>> As-is, the current patch set would result in the term "default role(s)"
>>> disappearing from the documentation in the next minor release, which is
>>> bound to cause confusion for anyone searching the documentation for the
>>> term they're familiar with (unless they happen to be reading this thread
>>> or following the git commit log). Cue cries of "OMG Postgres removed a
>>> feature in a minor release!!!?!!".
>>
>>> And as Stephen mentions, it will break a lot of secondary documentation -
>>> not just blogs but things like internal training  materials etc.
>>
>>> If this change is made (which I'm personally not against), then it should be
>>> only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
>>> existing documentation to somehow mention that "default roles" should be
>>> thought of as "prefined roles", and note they will be called this from Pg13.
>>
>> Ian, agreed modulo 13.
>>
>> The current section(s) could forward readers to a revised section.  The
>> DEFAULT_ROLE_* stuff could carry two names to allow a comprehensive fix
>> in 12.X.  That could allow the deprecation and misinformation to end one
>> EoL sooner.
> 
> With minor releases coming next week, and no movement on doing web
> redirects, and no clarity on what this is missing even in master, I will
> revert this patch in all branches soon.  I think everyone agrees the new
> documentation title is better, but we don't want to break things or add
> inconsistency to do it.

Sorry, I missed the original comment on the "web redirects"

So, if there was something done to redirect people from specific
deprecated documentation pages historically, it was before my time. Most
of the redirects have been as general purposes ones (e.g. /docs/12), the
rules we put in for getting rid of "static", and the release notes,
which still receives some negative feedback towards it for different
reasons (though I think overall the effort was well-received). Anyway,
if we had a redirect in place, I'd want us to do it well.


I don't know if it's possible...but if we were able to make a change in
the doc source to say "this page is now this page" either as a
standalone page, or generated a HTML page that automatically redirects,
that may solve the issue. Or if we can have a "ghost page" available
with the old link, perhaps we can put something into pgweb to
automatically redirect to the new page. Other than that, the only quick
solution I see is to hardcode it, which I'm not a fan of.

So from a pgweb standpoint, the safe thing would be to do nothing with
the URL. If you could keep the URL but change the page title, perhaps
that would suffice?

Jonathan



signature.asc
Description: OpenPGP digital signature

Listing Drivers in the Docs (was: "Re: Postgres.js driver - for Node.js")

[Jonathan S. Katz]

Hi,

For this first round, going to truncate a bit of Stephen's thoughts
(sorry Stephen) just to cover where we are at:

On 1/9/20 12:00 PM, Stephen Frost wrote:
> Greetings,
> 
> * Jonathan S. Katz (jk...@postgresql.org) wrote:
>> On 1/8/20 7:59 PM, Tom Lane wrote:

>>> However, I'm not
>>> sure that there's anything wrong with having them in the wiki's list
>>> as long as they're appropriately marked as not-OSS.
>>
>> I had an offline suggestion about including a "License" column, which
>> seems like a good idea in general as we also have in the docs. And if we
>> are going to include more drivers in the docs, we'd (read "I'd" for this
>> first pass) have to pull those together anyway.
> 
> I agree with having a license column (*cough* I might have also been the
> one to make the offline suggestion, so don't consider this an
> independent advocating of that ;).

I made a pass at the current Drivers list[1] and added in a link to all
of the license files. I would appreciate any verification to ensure I
captured them all correctly.

The added benefit of this URL is that we now have a direct link to the
source code for all of the projects on the page (whereas some were just
the project pages), which will help with checking if a project is
maintained or not :)

(It was also interesting to see which licenses all the drivers used. I
even learned of one I hadn't heard before, guess which one..)

Despite whether or not we should list out non-OSS drivers, I at least
broke them out for the time being. My feeling has not changed: we should
not list them on the wiki.

Anyway, from a quick scan, for the OSS licenses (knowing this is one of
those passionate topics), I don't see anything that I would not feel
comfortable linking to as part of our official documentation in this
batch (well...maybe one, but the spirit of the license is fine by me and
I would not staunchly object).

I think if we're comfortable where this is at, the next step would be to
define criteria for inclusion, which Stephen started in his previous
note. I'll let this bake for a bit and then follow up.

Thanks,

Jonathan

[1] https://wiki.postgresql.org/wiki/List_of_drivers

Re: Postgres.js driver - for Node.js

[Jonathan S. Katz]

On 1/8/20 7:59 PM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 1/8/20 7:00 PM, Jonathan Buhacoff wrote:
>>> I'm wondering if the short list in the documentation [2] could be
>>> replaced with a link to the corresponding wiki page [1] ?
> 
>> ...
>> Also, while scanning the list, I also saw that someone recently added
>> several drivers that appear to be non-OSS.
> 
> Yeah, the lack of curation there is exactly why we generally *don't* link
> to the wiki from the formal docs.  We should make more of an effort to
> transpose vetted info about this topic into the docs, though.

I'd be fine with taking a crack at this. I had some notes (I think I put
it on -hackers during the SCRAM discussion) on how I reorganized the
list, with what determined what was on the list, and what was an
unsupported driver.

>> ... I will wait until there is some
>> consensus before removing the other closed-source ones.
> 
> Hm.  I'd vote against including those in the docs' list, because we can't
> as-a-community review their quality and suitability. 

100% agree there.

> However, I'm not
> sure that there's anything wrong with having them in the wiki's list
> as long as they're appropriately marked as not-OSS.

I had an offline suggestion about including a "License" column, which
seems like a good idea in general as we also have in the docs. And if we
are going to include more drivers in the docs, we'd (read "I'd" for this
first pass) have to pull those together anyway.

My personal preference would be to at least separate the open source
from the closed source, but certain things we include in the column
(e.g. supports SCRAM) we would not be able to validate on a closed
source driver. But perhaps if we include said drivers on that page, we'd
not include that info.

(Also my preference with the closed source drivers would be to keep them
listed here:
https://www.postgresql.org/download/products/2-drivers-and-interfaces/
...which I realized adds yet another twist to this discussion because
one could then say "Why not list them all here?" And then it is a
curated listed as it goes through the pgweb team...and then we could
potentially link it from the docs...)

Jonathan

Re: Postgres.js driver - for Node.js

[Jonathan S. Katz]

On 1/8/20 7:00 PM, Jonathan Buhacoff wrote:
> I'm wondering if the short list in the documentation [2] could be
> replaced with a link to the corresponding wiki page [1] ?

>> [1] https://wiki.postgresql.org/wiki/List_of_drivers#Drivers
>> [2] https://www.postgresql.org/docs/current/external-interfaces.html

IIRC that was one option that was floated. And IIRC there are two
potential issues that arise:

1. While it does easy the administration burden, it's still technically
a validation of drivers in that list. Maybe that's ok, based on what happens

2. We do ship out documents as PDFs, and said PDFs can be used offline.
If one is trying to understand which drivers are available and they see
a link to it, it may not be terribly helpful :(

That all said, perhaps it's time to update the list in the documentation
and create the guidance in terms of what it takes to have a driver
included in the documentation. I'd be happy to draft up some criteria.

When I last curated the list, I did try to bring it down to specifically
drivers (e.g., not ORMs or tools that enhance PostgreSQL connectivity).

Also, while scanning the list, I also saw that someone recently added
several drivers that appear to be non-OSS. Additionally, a few of the
entries are *not* drivers, which I have gone ahead and removed[1]. I
would say at a minimum, in both the wiki and the docs, we should only
list drivers that are OSS (in particular, so we can actually validate if
they use libpq and support SCRAM), but I will wait until there is some
consensus before removing the other closed-source ones.

Jonathan

[1]
https://wiki.postgresql.org/index.php?title=List_of_drivers=34554=34553



signature.asc
Description: OpenPGP digital signature

Re: Postgres.js driver - for Node.js

[Jonathan S. Katz]

On 1/8/20 3:06 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> I recently finished a fast, 0 dependency driver for Node.js with a very user
> friendly api.

Congratulations!

> I think would be great to include in the documentation and the Wiki page
> (details below).

I went ahead and updated the list of drivers page[1] to include postgres.js

The list on the documentation page has not been updated for a long time
(at least the list) -- I went back through 9.4 and saw the same list.

I believe there was some discussion around updating the documentation
page[2] awhile back. I forget how the conclusion was reached (no
action), but I recall things being discussed were the
criteria/validation for how a driver is included in the documentation
and how to keep the list up-to-date.

(The wiki is able to keep up with the fluidity a bit more easily :)

Perhaps it's worth revisting? There are certainly reasons to keep a
maintained list in the documentation, with the noted pain that goes with
it (and I may have inadvertently volunteered myself) as users are more
likely to discover things there than the wiki page.

Thanks,

Jonathan

[1] https://wiki.postgresql.org/wiki/List_of_drivers#Drivers
[2] https://www.postgresql.org/docs/current/external-interfaces.html



signature.asc
Description: OpenPGP digital signature

Re: legacy assumptions

[Jonathan S. Katz]

Hi,

On 11/25/19 12:47 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/datatype-json.html
> Description:
> 
> I'm wondering if this one line of section 8.14 JSON Types
> (https://www.postgresql.org/docs/current/datatype-json.html) can be edited
> to remove the word "legacy":
> 
> "In general, most applications should prefer to store JSON data as jsonb,
> unless there are quite specialized needs, such as legacy assumptions about
> ordering of object keys."
> 
> I'm concerned that with the word "legacy" there, someone might come along
> eventually and decide the json column type isn't needed anymore because it's
> "legacy", where in fact there are modern and legitimate uses for a field
> that allows you to retrieve the data exactly as it was stored and allows
> JSON queries on that data (even if they are slower).

While I'm certainly sensitive to this need as once upon a time I had a
similar requirement, slightly less strict requirement, I made sure to
not rely on the PostgreSQL JSON type itself to ensure ordering was
preserved (and in my case I was able to rely on a solution external to
PostgreSQL).

The JSON RFC states that objects should be considered "unordered", and
mentions that while different parsing libraries may preserve key
ordering, "implementations whose behavior does not depend on member
ordering will be interoperable in the sense that they will not be
affected by these differences."[1]

> An alternative would be to store the
> plaintext as binary data for the integrity check and have a separate jsonb
> column with a second copy of the same data. Since different applications
> have different time/space tradeoffs, it's good to have the choice.

Another approach is to leverage PostgreSQL's expression index
capabilities, which would allow you to limit the data duplication. For
example:

CREATE TABLE docs (doc bytea);

-- populating some test data
INSERT INTO docs
SELECT ('{"id": ' || x || ', "data": [1,2,3] }')::bytea
FROM generate_series(1, 10) x;

-- create an expression index that maps to the operators supported by GIN
CREATE INDEX docs_doc_json_idx ON docs
USING gin(jsonb(encode(doc, 'escape')));

and in one test run:

EXPLAIN
SELECT doc
FROM docs WHERE encode(doc, 'escape')::jsonb @> '{"id": 567}';

I got a plan similar to:

 QUERY PLAN


 Bitmap Heap Scan on docs  (cost=28.77..306.00 rows=100 width=31)
   Recheck Cond: ((encode(doc, 'escape'::text))::jsonb @> '{"id":
567}'::jsonb)
   ->  Bitmap Index Scan on docs_doc_json_idx  (cost=0.00..28.75
rows=100 width=0)
 Index Cond: ((encode(doc, 'escape'::text))::jsonb @> '{"id":
567}'::jsonb)

In this way, you can:

- Keep the key ordering preserved and perform any integrity checks, etc.
that your application requires
- Limit your data duplication to that of the index
- Still get the benefits of the JSONB lookup functions that work with
the indexing
- Still perform JSON validation:

INSERT INTO docs VALUES ('{]'::bytea);

ERROR:  invalid input syntax for type json
DETAIL:  Expected string or "}", but found "]".
CONTEXT:  JSON data, line 1: {]

> My suggestion for that sentence:
> 
> "In general, most applications should prefer to store JSON data as jsonb,
> unless there are quite specialized needs, such as assumptions about ordering
> of object keys or the need to retrieve the data exactly as it was stored."

My preference would be that we guide in the documentation on what to do
if one has an application sensitive to ordering. I'm not opposed to the
wording, but I'd prefer we encourage people to leverage JSONB for
storage & retrieval.

Thanks!

Jonathan

[1] https://tools.ietf.org/html/rfc7159#section-4



signature.asc
Description: OpenPGP digital signature

Re: I'm surprised to see the word master here

[Jonathan S. Katz]

On 10/2/19 7:39 AM, Chris Travers wrote:
> 
> 
> On Wed, Oct 2, 2019 at 12:57 PM Erikjan Rijkers  > wrote:
> 
> On 2019-10-02 12:46, Peter Eisentraut wrote:
> > On 2019-10-02 10:21, Magnus Hagander wrote:
> >> Exactly. Both might be accurate, but one comes with a lot less
> >> baggage.
> >>
> >>     I support a search and replace. 
> >>
> >> I think it'll take a bit more than just a simple "sed script to
> >> replace", if that's what you mean. But probably not all that much --
> >> but
> >> there can certainly be cases where nearby langaugae also has to be
> >> changed to make it work properly. But I have a hard time seeing it as
> >> being a *huge* undertaking.
> >
> > I find this proposal to be dubious and unsubstantiated.  Do we need to
> > get rid of "multimaster", "postmaster"?
> >
> 
> IMHO, hat would seem a bad idea.  Let's not take the politicising too
> far.
> 
> I would say leave it at abolishing 'slave' (as we have already done).
> 
> 
> But that raises an important point, which is that if we remove master
> entirely from the replication lexicon, then I don't see how multi-master
> makes sense.  If consistency is a goal, postmaster still works but there
> is no alternative to multi-master in common usage.

At various events and tradeshows that include representation from other
database systems, the terminology that I hear is "active-active" -- this
is not one-off, but from a lot of people. This is also a common term for
the major proprietary systems as well. I hear it much more commonly than
"multi-master" even.

> Can I make a suggestion here to help ease that problem:
> 
> We standardize on "primary" and "replica" but on the first usage of
> "primary" we have a parenthetical note that "primary" is sometimes
> called "master" so that terms like multi-master continue to be
> intuitively intelligible. 

I'd +1 s/master/primary/ -- I don't know if it needs parenthetical on
the first usage in places (maybe in sections on replication/clustering,
but not everywhere).

Let's at least consider using "active-active" instead of "multi-master"
given there is already usage of that term in the industry. It would be
good to see what other systems do; matching terminology could have its
advantages. It's not politicizing if we're making the terminology more
inline with the industry.

I don't think postmaster needs to change; this is a title in many
countries[1] and I presume would also require a nontrivial effort and
potentially affect systems.

Jonathan

[1] https://en.wikipedia.org/wiki/Postmaster



signature.asc
Description: OpenPGP digital signature

Re: Formatting of warning about using ident

[Jonathan S. Katz]

On 7/22/19 10:09 AM, Tom Lane wrote:
> Peter Eisentraut  writes:
>> In general, I would argue in favor of fewer "note", "warning", etc.
>> Some documentation pages are now just a sequence of "note"s and little
>> proper text.  If the normal text properly explains a topic and its pros
>> and cons, then we don't need all that extra decoration and it makes the
>> text easier to read.
> 
> +1.  With the way these things are rendered in the current HTML output,
> they are so visually distracting that they ought to be reserved for
> absolutely critical info.  I almost feel that we should ban 
> entirely, because the rendering is completely disproportional to the
> meaning.

Based on the example of auth-ident.html, removing "note" seems to make
sense. It just seems like it's a part of the regular documentation.

However, perhaps the reason people feel the need to highlight such
things is that they want to ensure the reader catches an important
point, particularly as one is often reading the documentation quickly to
find the piece of info they're looking for (speaking from personal
experience).

That said, looking through some other pages, the "notes" feel like
they're other "asides" to add more detail around a particular point, or
calling out a specific fact. It seems like they could be inlined as part
of the regular documentation.

Something like a "warning" should be visually distracting...it's a
warning that the user could end up in a dangerous situation with their
data, so they should heed it.

> (Or, maybe, somebody could tinker with the stylesheets?)

I think lessening the use of "note" would help. It would require some
rewriting in places it's being used. That way, if we need something
that's truly a "warning" we won't feel as hesitant to add it to the docs.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]

[Jonathan S. Katz]

On 7/10/19 6:13 AM, David Harper wrote:
>> I actually agree with your opinion that "midnight" is fine.
>> That text has been that way for over fifteen years[1], and
>> nobody's complained before that it was ambiguous.
> 
> Conversely, how many users over the past fifteen years have read that table, 
> and then felt compelled (as I did) to run a query such as
> 
>   select 'today'::timestamp,'yesterday'::timestamp,'tomorrow'::timestamp;
> 
> on their PostgreSQL cluster to clear the ambiguity for themselves?

I've heard of one, but only just recently :)

If we were to s/midnight/00:00:00/ we'd probably want to do it
everywhere midnight appears. This occurs in a few places in the docs:

https://www.postgresql.org/docs/current/functions-formatting.html ()
https://www.postgresql.org/docs/current/protocol-replication.html
(XlogData section)

and there are some various code comments as well.

Count me as a +0 vote, as I've always interpreted it the way Bruce & Tom
said upthread, but if we want to change it I can write a patch.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: TOC: List of Figures

[Jonathan S. Katz]

On 7/8/19 4:21 PM, Daniel Gustafsson wrote:
>> On 8 Jul 2019, at 22:10, Tom Lane  wrote:
> 
>> let's wait till there's a
>> meaningful number of figures and then reconsider whether there's use in
>> a list of them.  It's not like it will be any harder to make that change
>> in a year or two than it is today.
> 
> In that case, let’s record this in the commitfest app and punt it forwards
> towards the release as the CFs move along so we don’t forget to re-evaluate in
> the last commitfest before 13.

Done[1].

Jonathan

[1] https://commitfest.postgresql.org/24/2204/



signature.asc
Description: OpenPGP digital signature

Re: TOC: List of Figures

[Jonathan S. Katz]

On 7/2/19 4:43 AM, Daniel Gustafsson wrote:
>> On 2 Jul 2019, at 10:13, Jürgen Purtz  wrote:
> 
>> After the integration of figures into the documentation it may be helpful to 
>> extent the TOC with a 'List of Figures'. Any opinion?
> 
> +1, I think we should.

+1

> 
>> The alternative is a downshift of the postings by one level, see attachment 
>> 2. How to realize this behavior is shown in attachment 3.
> 
> This alternative seems a better idea.

+1, seems like an easier grouping to follow.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Add XSL stylesheet to fix up SVG files

[Jonathan S. Katz]

On 6/20/19 4:32 AM, Peter Eisentraut wrote:
> On 2019-06-11 13:19, Peter Eisentraut wrote:
>> Commit 29046c44f36099f4c979b1491fcf27db2f9184f9 manually edited the SVG
>> file generated by Ditaa, which was kind of what we wanted to avoid
>> having to do.  Here is an automated way to take care of the same thing,
>> by using an XSLT stylesheet.  This also takes care of another smaller
>> issue in the SVG generated by Graphviz.
> 
> committed

I have been away and have not been able to review/test this until now.
That said, I looked at the pages with SVGs on the devel docs and they
are still scaling correctly based on the viewport.

Thanks for automating the generation to handle this!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: graphviz file extension

[Jonathan S. Katz]

On 5/24/19 8:28 AM, Joe Conway wrote:
> On 5/24/19 3:08 AM, Peter Eisentraut wrote:
>> It has come to my attention that the preferred file extension for
>> graphviz files is .gv rather than the .dot we are using.  So I propose
>> to change that for the one file we have so far (gin.dot) before we add
>> more files in the future.
> 
> 
> Agreed -- better to fix it now.

+1

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: some grammar fixes for docs

[Jonathan S. Katz]

On 5/16/19 7:32 PM, Michael Paquier wrote:
> On Thu, May 16, 2019 at 05:11:37PM +0300, Liudmila Mantrova wrote:
>> I have noticed imperfect grammar in a couple of sgml files, please consider
>> a small patch (attached).
> 
> Thanks, Liudmila for caring about such matters.
> 
>> 
>> -Transaction which last more than limit 
>> milliseconds
>> +Transactions that last more than limit 
>> milliseconds
>>  are counted and reported separately, as late.
>> 
> 
> I don't see much of a difference between "which" or "that" in this
> context, and you are right about the plural for "Transactions".  Any
> native English speaker around or anybody with an extra opinion?
> 
>>   
>>Of the two operator classes for type point,
>>quad_point_ops is the default.  
>> kd_point_ops
>> -  supports the same operators but uses a different index data structure 
>> which
>> +  supports the same operators but uses a different index data structure that
>>may offer better performance in some applications.
>>   
> 
> Same here.

Technically it should be "that" - often you say "which" when one is
speaking, but in writing, in the above cases, "that" is grammatically
correct.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: a small fix for Release notes 11.3

[Jonathan S. Katz]

On 5/16/19 10:17 AM, Liudmila Mantrova wrote:
> Hello,
> 
> Please consider a mini-patch for 11.3 release notes that fixes
> pg_dump-related wording and also makes Jonathan's name consistent with
> how it's listed in contributors list.

I am flattered by your attention to detail around my name, but I'm ok
with it either way as long as my first/last names are spelled correctly :)

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Additional "Creating a Cluster" Guidance for Windows Users

[Jonathan S. Katz]

Hi,

Per the last update release[1] I was going through some of our
documentation around creating clusters and noticed that we may want to
provide a bit more guidance around creating clusters on Windows:

https://www.postgresql.org/docs/current/creating-cluster.html

i.e.:

"Because the data directory contains all the data stored in the
database, it is essential that it be secured from unauthorized access.
initdb therefore revokes access permissions from everyone but the
PostgreSQL user, and optionally, group."

However, this does not explicitly state that initdb performs this
revocation only for *non-Windows systems* -- to lock down the data
directory after an initdb run on a Windows system, it requires manual
intervention.

I've attached a patch that explicitly states the above. I wrapped the
guidance in a "Warning" box given the data directory is exposed if not
locked down properly.

I would also recommend this is backpatched to 9.4. If in agreement on
the above methodology + wording, I can generate the backpatches.

Thanks,

Jonathan

[1] https://www.postgresql.org/about/news/1939/
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index e784268512..2ca49d2482 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -135,14 +135,23 @@ postgres$ initdb -D 
/usr/local/pgsql/data
   
Because the data directory contains all the data stored in the
database, it is essential that it be secured from unauthorized
-   access. initdb therefore revokes access
-   permissions from everyone but the
+   access. On all operating systems other than Windows,
+   initdb revokes access permissions from everyone but the
PostgreSQL user, and optionally, group.
Group access, when enabled, is read-only.  This allows an unprivileged
user in the same group as the cluster owner to take a backup of the
cluster data or perform other operations that only require read access.
   
 
+  
+   
+   If you are running PostgreSQL on Windows and create your cluster using
+   initdb, you will need to set the permissions on the data
+   directory manually. You should revoke all user access to the data directory
+   except for the PostgreSQL user.
+   
+  
+
   
Note that enabling or disabling group access on an existing cluster requires
the cluster to be shut down and the appropriate mode to be set on all


signature.asc
Description: OpenPGP digital signature

Re: Why 'infinity' is not in range '[2019-01-02, infinity]'?

[Jonathan S. Katz]

On 4/29/19 12:12 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/rangetypes.html
> Description:
> 
> Hi.
> 
> May I read this:
> 
> But [today,infinity] means something different from [today,infinity) — the
> latter excludes the special timestamp value infinity.
> 
> as 
> 
> But [today,infinity] means something different from [today,infinity) — the
> **first includes** the special timestamp value infinity.
> 
> But previous paragraph says:
> 
> But note that these infinite values are never values of the range's element
> type, and can never be part of the range. (So there is no such thing as an
> inclusive infinite bound — if you try to write one, it will automatically be
> converted to an exclusive bound.)
> 
> if 'infinity' can not be the part of a range this will mean:
> 
> [today,infinity] means same as [today,infinity)
> 
> errr... which one is correct? Please fix documentation.

'infinity' in that case is a special type of date/timestamp:

https://www.postgresql.org/docs/current/datatype-datetime.html#id-1.5.7.13.19.8

which is what that paragraph is referring to. It's discussing
"infinity-like" objects you may see that are different than how range
types treat infinity.

I re-read the language, I would not advocate for making any changes.


> PS. The problem I am faced into:
> I am implementing be-temporal interface. I have current period. It can be
> [2019-01-01,2019-02-01),
> [2019-02-01,2019-03-01) and [2019-03-01,infinity) for the current month.
> 
> When I setup current_period to one of those I will get Orders at that
> period. The Orders have with 'last_bill_date' field which will show the date
> of Invoice for that Order.
> For new Order we can set 'infinity' into 'last_bill_date' which will mean
> that we should create Invoice.
> Now to select all Order for which we should create Invoice we can write:
> 
> select * from "order" o where o.last_bill_date +interval o.bill_interval <@
> current_period();
> 
> This seems obvious that infinity is part of [value, infinity) ( or
> [value,infinity] ) range. (in other words the 'infinity' is always the part
> of range with infinite inclusive or exclusive bound.
> 
> This is just view from my point, there can be things that I am not aware of.

You should drop the 'infinity' and just let it be NULL, i.e.

daterange('2019-03-01', NULL);

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/26/19 3:04 PM, Jonathan S. Katz wrote:
> On 4/25/19 6:54 PM, Joe Conway wrote:
>> On 4/25/19 5:59 PM, Jonathan S. Katz wrote:
>>> On 4/25/19 5:26 PM, Joe Conway wrote:
>>>>
>>>> Is there any written instruction anywhere with guidance on how the SVGs
>>>> should be made?
>>>
>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/images/README;
>>
>> Awesome -- that is what I had been looking for. Shouldn't we add that to
>> the actual documentation style guide?
>>
>>> but I would suggest we had some guidance on how to ensure the image
>>> stays scalable.
>>
>> Since you seem to know the magic incarnations, can you propose some words?
> 
> Please see attached.

v2 -- fixed typo in height, and modified some of the language.

Jonathan

diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README
index dd29486a09..089375c485 100644
--- a/doc/src/sgml/images/README
+++ b/doc/src/sgml/images/README
@@ -59,3 +59,10 @@ Notes:
 - The width should be set to something.  This ensures that the image
   is scaled to fit the page in PDF output.  (Other widths than 100%
   might be appropriate.)
+
+- SVG images should be scalable as they will be rendered in a variety
+  of places (web, PDF, etc.) as well as in different viewports
+  (desktop, mobile, etc.). To help the images successfully scale,
+  please employe a "viewBox" attribute in the svg tag. For example,
+  to create with a default width and height of 400x300, you would use
+  viewBox="0.00 0.00 400.00 300.00"


signature.asc
Description: OpenPGP digital signature

Re: Documentation for partitioned indexes?

[Jonathan S. Katz]

On 4/26/19 2:53 PM, Alvaro Herrera wrote:
> On 2019-Apr-26, Tom Lane wrote:
> 
>> We appear to have a fair amount of support now for operations like
>> constructing a partitioned index piecemeal, e.g. adding indexes
>> to the partitions one at a time and then attaching them to a
>> parent partitioned index, with the parent ultimately transitioning
>> from "not valid" to "valid" once all the pieces are attached.
>>
>> However, I cannot find any coherent documentation explaining how
>> to do this (or why you'd want to).  Am I just looking in the wrong
>> places?
> 
> Hmm.  Under Notes for CREATE INDEX there is a paragraph on this:
> 
>   When CREATE INDEX is invoked on a partitioned table, the default
>   behavior is to recurse to all partitions to ensure they all have
>   matching indexes. Each partition is first checked to determine
>   whether an equivalent index already exists, and if so, that
>   index will become attached as a partition index to the index
>   being created, which will become its parent index. If no
>   matching index exists, a new index will be created and
>   automatically attached; the name of the new index in each
>   partition will be determined as if no index name had been
>   specified in the command. If the ONLY option is specified, no
>   recursion is done, and the index is marked invalid. (ALTER INDEX
>   ... ATTACH PARTITION marks the index valid, once all partitions
>   acquire matching indexes.) Note, however, that any partition
>   that is created in the future using CREATE TABLE ... PARTITION
>   OF will automatically have a matching index, regardless of
>   whether ONLY is specified.
> 
> I suppose I better add something in Chapter 5 (DDL), possibly inside the
> 5.10 section (Table Partitioning) -- a new 5.10.6 "Indexes for
> Partitioned Tables" perhaps?

+1; (though note on devel it's section 5.11, not that it matters in the
SGML)

I'd suggest keeping the title of the section similar to the one with
constraints, i.e. "Partitioning and Indexes"

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 6:54 PM, Joe Conway wrote:
> On 4/25/19 5:59 PM, Jonathan S. Katz wrote:
>> On 4/25/19 5:26 PM, Joe Conway wrote:
>>>
>>> Is there any written instruction anywhere with guidance on how the SVGs
>>> should be made?
>>
>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/images/README;
> 
> Awesome -- that is what I had been looking for. Shouldn't we add that to
> the actual documentation style guide?
> 
>> but I would suggest we had some guidance on how to ensure the image
>> stays scalable.
> 
> Since you seem to know the magic incarnations, can you propose some words?

Please see attached.

Jonathan
diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README
index dd29486a09..81b426c066 100644
--- a/doc/src/sgml/images/README
+++ b/doc/src/sgml/images/README
@@ -59,3 +59,10 @@ Notes:
 - The width should be set to something.  This ensures that the image
   is scaled to fit the page in PDF output.  (Other widths than 100%
   might be appropriate.)
+
+- SVG images should be scalable as they will be rendered in a variety
+  of places (web, PDF, etc.) as well as in different viewports
+  (desktop, mobile, etc.). To help the images successfully scale,
+  please employe a "viewBox" attribute in the svg tag. For example,
+  to set an image to contain a default width and heigh of 400x300,
+  you would use viewBox="0.00 0.00 400.00 300.00"


signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 5:26 PM, Joe Conway wrote:
>
> Is there any written instruction anywhere with guidance on how the SVGs
> should be made?

https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/images/README;

but I would suggest we had some guidance on how to ensure the image
stays scalable.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 5:22 PM, Jonathan S. Katz wrote:
> On 4/25/19 4:52 PM, Jonathan S. Katz wrote:
>> On 4/25/19 3:20 PM, Joe Conway wrote:
>>> On 4/25/19 3:06 PM, Stephen Frost wrote:
>>>> Greetings,
>>>>
>>>> * Tom Lane (t...@sss.pgh.pa.us) wrote:
>>>>> Joe Conway  writes:
>>>>>> On 4/25/19 1:08 PM, Joe Conway wrote:
>>>>>>> There is one image which can be used as an example though:
>>>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD
>>>>>
>>>>>> Here is a more precise URL:
>>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD#l934
>>>>>
>>>>> Comparing that to what I see at
>>>>>
>>>>> https://www.postgresql.org/docs/devel/storage-page-layout.html
>>>>>
>>>>> does not lead to a warm feeling about our images-in-docs stuff
>>>>> really being ready for prime time.  It works OK in some browsers
>>>>> but others (at least Safari) cut off the image.
>>>>
>>>> Yeah, I'm seeing it cut off in Chrome too, initially, and then it seems
>>>> to fix itself if I resize the window down from 4k (and stay fixed even
>>>> if I then go back to the original, much larger, size).  That seems like
>>>> a CSS or layout issue though, not an issue with the image itself..?
>>>
>>>
>>> Yeah, I see the same thing in Chrome -- maybe Jonathan has an idea what
>>> is going on and how to best fix it?
>>
>> See[1] - I'm not sure if the final piece is committed -- if when it is I
>> can finish fixing the pgweb part
> OK, so I took a quick look at the existing SVGs with my patched version
> of pgweb.
> 
> The short answer is that it's better: the SVGs are not responsive, but
> they are displaying. There still needs to be work on the SVGs as
> indicated in that thread to make them responsive[1].
> 
> With that said, the pgweb patch does fix their current display at least
> in full view, so I pushed the current patch to pgweb to do that. The fix
> will take effect the next time the nightly docload runs, or if someone
> on pginfra forces it to occur more quickly.

Good news - I did test against an older snapshot. With a newer snapshot,
the SVG on the GIN implementation page[1] is responsive but not the one
on the storage page layout[2], which is what the proposed fix in the
other thread handles.

Jonathan

[1] https://www.postgresql.org/docs/devel/gin-implementation.html
[2] https://www.postgresql.org/docs/devel/storage-page-layout.html



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 4:52 PM, Jonathan S. Katz wrote:
> On 4/25/19 3:20 PM, Joe Conway wrote:
>> On 4/25/19 3:06 PM, Stephen Frost wrote:
>>> Greetings,
>>>
>>> * Tom Lane (t...@sss.pgh.pa.us) wrote:
>>>> Joe Conway  writes:
>>>>> On 4/25/19 1:08 PM, Joe Conway wrote:
>>>>>> There is one image which can be used as an example though:
>>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD
>>>>
>>>>> Here is a more precise URL:
>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD#l934
>>>>
>>>> Comparing that to what I see at
>>>>
>>>> https://www.postgresql.org/docs/devel/storage-page-layout.html
>>>>
>>>> does not lead to a warm feeling about our images-in-docs stuff
>>>> really being ready for prime time.  It works OK in some browsers
>>>> but others (at least Safari) cut off the image.
>>>
>>> Yeah, I'm seeing it cut off in Chrome too, initially, and then it seems
>>> to fix itself if I resize the window down from 4k (and stay fixed even
>>> if I then go back to the original, much larger, size).  That seems like
>>> a CSS or layout issue though, not an issue with the image itself..?
>>
>>
>> Yeah, I see the same thing in Chrome -- maybe Jonathan has an idea what
>> is going on and how to best fix it?
> 
> See[1] - I'm not sure if the final piece is committed -- if when it is I
> can finish fixing the pgweb part
OK, so I took a quick look at the existing SVGs with my patched version
of pgweb.

The short answer is that it's better: the SVGs are not responsive, but
they are displaying. There still needs to be work on the SVGs as
indicated in that thread to make them responsive[1].

With that said, the pgweb patch does fix their current display at least
in full view, so I pushed the current patch to pgweb to do that. The fix
will take effect the next time the nightly docload runs, or if someone
on pginfra forces it to occur more quickly.

Thanks,

Jonathan

[1]
https://www.postgresql.org/message-id/flat/6d2442d1-84a2-36ef-e014-b6d1ece8a139%40postgresql.org



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 3:20 PM, Joe Conway wrote:
> On 4/25/19 3:06 PM, Stephen Frost wrote:
>> Greetings,
>>
>> * Tom Lane (t...@sss.pgh.pa.us) wrote:
>>> Joe Conway  writes:
 On 4/25/19 1:08 PM, Joe Conway wrote:
> There is one image which can be used as an example though:
> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD
>>>
 Here is a more precise URL:
 https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD#l934
>>>
>>> Comparing that to what I see at
>>>
>>> https://www.postgresql.org/docs/devel/storage-page-layout.html
>>>
>>> does not lead to a warm feeling about our images-in-docs stuff
>>> really being ready for prime time.  It works OK in some browsers
>>> but others (at least Safari) cut off the image.
>>
>> Yeah, I'm seeing it cut off in Chrome too, initially, and then it seems
>> to fix itself if I resize the window down from 4k (and stay fixed even
>> if I then go back to the original, much larger, size).  That seems like
>> a CSS or layout issue though, not an issue with the image itself..?
> 
> 
> Yeah, I see the same thing in Chrome -- maybe Jonathan has an idea what
> is going on and how to best fix it?

See[1] - I'm not sure if the final piece is committed -- if when it is I
can finish fixing the pgweb part.

Jonathan

[1]
https://www.postgresql.org/message-id/flat/6d2442d1-84a2-36ef-e014-b6d1ece8a139%40postgresql.org




signature.asc
Description: OpenPGP digital signature