Documentation - chapter 52, system catalogs
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/11/catalogs-overview.html Description: The documentation for chapter 52 does not clearly identify the schema associated with the system catalogs in either the chapter header or overview sections; had I not stumbled across a reference in the documentation for the postgres_fdw to the pg_catalog search path, I would have been unable to reference the content in those catalogs via foreign data wrappers, and although the majority of the content has been exposed via the information_schema views and tables, there remain a few elements of interest that appear to only exist in the pg_catalog qualified content.
Re: Direct links to edit documentation
I see how that can be pretty useful for something that's as simple as asciidoc. But I wonder how useful it would be for our docbook documentation. There'd be no preview (which there i sin the elastic), and we know how difficult it can be to get the tags right without running test builds even for those that are used to working in the system. Though if what we're considering are basically drive-by typo fixes and such, those would probably work in a scenario like that, since you're unlikely to need a preview or break a build. Another complication would be that we don't have a 1-1 mapping between source files and output URLs. So you'd have to find some way to track it back to the exactly right portion of the source file. This would probably be possible if we were to do it as a feature on our own site (and not just a source-edit-on-github-style), but it would probably ont be a trivial piece of work. Question is if the benefit would outweigh the cost, compared to just receiving comments and "manually patching them in". //Magnus On Wed, Apr 29, 2020 at 11:39 PM Yuri Astrakhan wrote: > ElasticSearch also uses AsciiDoc with the "edit_me" module that generates > those. Code - > https://github.com/elastic/docs/blob/master/resources/asciidoctor/lib/edit_me/extension.rb > > It results in a semi-transparent "edit me" button at the top to the right > of the page title, e.g. > https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geotilegrid-aggregation.html > > On Wed, Apr 29, 2020 at 1:27 PM Bruce Momjian wrote: > >> On Wed, Apr 29, 2020 at 04:36:37PM +, PG Doc comments form wrote: >> > The following documentation comment has been logged on the website: >> > >> > Page: https://www.postgresql.org/docs/12/runtime-config-wal.html >> > Description: >> > >> > Would it be possible to add "edit this page" links to every PostgreSQL >> doc >> > page, pointing to the docs git repo, ideally on a site that allows >> > on-the-site editing without locally cloning i.e. github? This will >> make it >> > far easier to contribute tiny changes like adding more links in the >> text. >> > For example, https://www.postgresql.org/docs/12/runtime-config-wal.html >> has >> > a lot of useful information, but many setting keywords are not links, >> making >> > it harder to find. Commenting on that page that a link is missing seems >> > silly, whereas if there was an edit button, users could have submitted >> their >> > edits directly. >> >> Wow, that sounds like a nice idea, but I have no idea how to do that. >> >> -- >> Bruce Momjian https://momjian.us >> EnterpriseDB https://enterprisedb.com >> >> + As you are, so once was I. As I am, so you will be. + >> + Ancient Roman grave inscription + >> >
Re: Direct links to edit documentation
> On 4 May 2020, at 19:06, Magnus Hagander wrote: > Question is if the benefit would outweigh the cost, compared to just receiving > comments and "manually patching them in". Another question is the cost of managing access to such a system, we haven't exactly had the best of luck with input from interactive systems in the past. Is a community login enough or does it need an extra bit like the Wiki? Just thinking out loud of the costs involved which need to be offset. cheers ./daniel
Re: Direct links to edit documentation
(accidentally sent my last post without the links at the bottom, fixed) Daniel and Magnus, thanks for your replies. Here's my personal 2-click submission "ideal scenario", that may differ from other contributors, but seems to be very common now for many FOSS projects. I think this will work for the vast majority of the documentation pages. Note that this is not a wiki-style editing, but a proper pull request process subject to maintainer's review. * While viewing the "CREATE TABLE" page [1], I click some "edit" button (e.g. in the upper right corner) * It takes me to the GitHub "edit" page [2] (this is the link target of the gray pencil icon on page [3] - upper right corner on gray background) * I edit the page -- the syntax seems trivial enough for the vast majority of non-structural edits. I can add more examples, improve grammar, add links, etc. * I click "Propose file changes" at the bottom. This automatically will create a fork of the repo, and create a pull request into the main Postgres github repo. * (automated step) some bot creates a PR against the primary Postgres repo, submitting the change. * Maintainers review and merge the change. Now, I do see that https://github.com/postgres/postgres is not the primary repo, and that currently PRs to it do not go to the maintainers, but I think it would greatly simplify the path of user contributions if GitHub PRs were auto-submitted using the proper Postgres process (i.e. with a bot?). Just compare the above 2 clicks process to submit a documentation change with the giant instruction page at https://wiki.postgresql.org/wiki/Submitting_a_Patch -- clearly it is a big deterrent for small improvements. [1] https://www.postgresql.org/docs/current/sql-createtable.html [2] https://github.com/postgres/postgres/edit/master/doc/src/sgml/ref/create_table.sgml [3] https://github.com/postgres/postgres/blob/master/doc/src/sgml/ref/create_table.sgml On Mon, May 4, 2020 at 3:23 PM Daniel Gustafsson wrote: > > On 4 May 2020, at 19:06, Magnus Hagander wrote: > > > Question is if the benefit would outweigh the cost, compared to just > receiving > > comments and "manually patching them in". > > Another question is the cost of managing access to such a system, we > haven't > exactly had the best of luck with input from interactive systems in the > past. > Is a community login enough or does it need an extra bit like the Wiki? > Just > thinking out loud of the costs involved which need to be offset. > > cheers ./daniel
Re: Direct links to edit documentation
Daniel and Magnus, thanks for your replies. Here's my personal 2-click submission "ideal scenario", that may differ from other contributors, but seems to be very common now for many FOSS projects. I think this will work for the vast majority of the documentation pages. Note that this is not a wiki-style editing, but a proper pull request process subject to maintainer's review. * While viewing the "CREATE TABLE" page [1], I click some "edit" button (e.g. in the upper right corner) * It takes me to the GitHub "edit" page [2] (this is the link target of the gray pencil icon on page [3] - upper right corner on gray background) * I edit the page -- the syntax seems trivial enough for the vast majority of non-structural edits. I can add more examples, improve grammar, add links, etc. * I click "Propose file changes" at the bottom. This automatically will create a fork of the repo, and create a pull request into the main Postgres github repo. * (automated step) some bot creates a PR against the primary Postgres repo, submitting the change. * Maintainers review and merge the change. Now, I do see that https://github.com/postgres/postgres is not the primary repo, and that currently PRs to it do not go to the maintainers, but I think it would greatly simplify the path of user contributions if GitHub PRs were auto-submitted using the proper Postgres process (i.e. with a bot?). Just compare the above 2 clicks process to submit a documentation change with the giant instruction page at https://wiki.postgresql.org/wiki/Submitting_a_Patch -- clearly it is a big deterrent for small improvements. On Mon, May 4, 2020 at 3:23 PM Daniel Gustafsson wrote: > > On 4 May 2020, at 19:06, Magnus Hagander wrote: > > > Question is if the benefit would outweigh the cost, compared to just > receiving > > comments and "manually patching them in". > > Another question is the cost of managing access to such a system, we > haven't > exactly had the best of luck with input from interactive systems in the > past. > Is a community login enough or does it need an extra bit like the Wiki? > Just > thinking out loud of the costs involved which need to be offset. > > cheers ./daniel
minor rewording in ceil(), ceiling() and floor() function descriptions
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/functions-math.html Description: Proposed rewording for ceil() and ceiling(): "smallest integer..." Proposed rewording for floor(): "greatest integer..." Rationale: the proposed rewording is more aligned to their respective mathematical definitions References: - https://proofwiki.org/wiki/Definition:Ceiling_Function - https://proofwiki.org/wiki/Definition:Floor_Function
Another modest proposal for docs formatting: catalog descriptions
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? regards, tom lane [1] https://www.postgresql.org/docs/devel/catalog-pg-attrdef.html
Re: Another modest proposal for docs formatting: catalog descriptions
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: minor rewording in ceil(), ceiling() and floor() function descriptions
PG Doc comments form writes: > Proposed rewording for ceil() and ceiling(): "smallest integer..." > Proposed rewording for floor(): "greatest integer..." > Rationale: the proposed rewording is more aligned to their respective > mathematical definitions Actually, that's very nearly the wording we used to have, and then changed because people found it confusing: https://www.postgresql.org/message-id/flat/20160606054056.1385.38085%40wrigleys.postgresql.org https://git.postgresql.org/gitweb/?p=postgresql.git&a=commitdiff&h=7feb60c1bb0b1e9c97561171e9194d56694620ad As of just a few days ago in HEAD, we have the room for clarifying examples that we lacked then, so I added some: https://www.postgresql.org/docs/devel/functions-math.html#FUNCTIONS-MATH-FUNC-TABLE So maybe the confusion argument has less force than it used to. Still, I'm disinclined to go back. In this particular area, I think Matlab's precedent is at least as strong as Wikipedia's. regards, tom lane
Re: Roles for pg_basebackup
On Sun, May 03, 2020 at 03:53:31PM +0900, Michael Paquier wrote: > Fine for me as well as far as it goes. I'll go apply it if there are > no objections. And done. -- Michael signature.asc Description: PGP signature
Re: Another modest proposal for docs formatting: catalog descriptions
Hello Tom, 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. Thoughts? +1 My 0.02€: I'm wondering whether the description could/should match SQL syntax, eg: oid OID adrelid OID REFERENCES pg_class(oid) adnum INT2 REFERENCES pg_attribute(attnum) … Or maybe just uppercase type names, especially when repeated? oid OID adrelid OID (references pg_class.oid) adnum INT2 (references pg_attribute.attnum) … I guess that reference targets would still be navigable. -- Fabien.
