Re: Documentation - chapter 52, system catalogs
On 04.05.20 17:23, PG Doc comments form wrote: 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. I think that the topic "fdw" is only a symptom, not the real reason for the confusion. We can improve the chapters "System Catalog" and "Information Schema" in general by centralizing some already existing paragraphs in the "Overview" chapter and adding some more explanations. The attached patch contains: - for "System Catalog": moving paragraphs from bottom of 51. to top of 51.1. (in PG 11 it is chapter 52); explanation that "System Catalog" is a synonym for a concrete schema and its tables. - for "Information Schema": moving paragraphs from bottom of 36. to middle of 36.1. ; an explanation that it relies on the system catalog; change the title of 36.1. to "Overview" in correlation with "System Catalog". -- Jürgen Purtz diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index ce33df9e58..8854bda05f 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -6,6 +6,23 @@ System Catalogs + + Overview + + + The term system catalog is a widely used + synonym for the schema pg_catalog and + its tables. They are listed in + with links to more detailed documentation. + + + + Most system catalogs are copied from the template database during + database creation and are thereafter database-specific. A few + catalogs are physically shared across all databases in a cluster; + these are noted in the descriptions of the individual catalogs. + + The system catalogs are the place where a relational database management system stores schema metadata, such as information about @@ -23,21 +40,6 @@ of the system catalogs is ever decreasing. - - Overview - - -lists the system catalogs. - More detailed documentation of each catalog follows below. - - - - Most system catalogs are copied from the template database during - database creation and are thereafter database-specific. A few - catalogs are physically shared across all databases in a cluster; - these are noted in the descriptions of the individual catalogs. - - System Catalogs diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index 7a995a1b64..ea8561d9e5 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -7,46 +7,8 @@ information schema - - The information schema consists of a set of views that contain - information about the objects defined in the current database. The - information schema is defined in the SQL standard and can therefore - be expected to be portable and remain stable — unlike the system - catalogs, which are specific to - PostgreSQL and are modeled after - implementation concerns. The information schema views do not, - however, contain information about - PostgreSQL-specific features; to inquire - about those you need to query the system catalogs or other - PostgreSQL-specific views. - - - - - When querying the database for constraint information, it is possible - for a standard-compliant query that expects to return one row to - return several. This is because the SQL standard requires constraint - names to be unique within a schema, but - PostgreSQL does not enforce this - restriction. PostgreSQL - automatically-generated constraint names avoid duplicates in the - same schema, but users can specify such duplicate names. - - - - This problem can appear when querying information schema views such - as check_constraint_routine_usage, - check_constraints, domain_constraints, and - referential_constraints. Some other views have similar - issues but contain the table name to help distinguish duplicate - rows, e.g., constraint_column_usage, - constraint_table_usage, table_constraints. - - - - - The Schema + Overview The information schema itself is a schema named @@ -57,6 +19,44 @@ the space savings achieved by that are minuscule). + + The information schema consists of a set of views to tables + in the schema pg_catalog, so it contains + information about the objects defined in the current database. The + information schema is defined in the SQL standard and can therefore + be expected
Re: Another modest proposal for docs formatting: catalog descriptions
Fabien COELHO writes: > 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? Meh. I'm not a fan of overuse of upper case --- it's well established that that's harder to read than lower or mixed case. And it's definitely project policy that type names are generally treated as identifiers not keywords, even if some of them happen to be keywords under the hood. The markup I had in mind was for the field name and for the type name, but no decoration beyond that. As for the references, it seems to me that your notation would lead people to think that there are actual FK constraints in place, which of course there are not (especially not on the views). I'm not hugely against it but I prefer what I suggested. > I guess that reference targets would still be navigable. Yeah, they'd still have wrappers --- if I recall what those look like in the documentation sources, they don't need any change except for addition of the "(references ...)" text. regards, tom lane
Re: Direct links to edit documentation
On Mon, May 4, 2020 at 07:06:55PM +0200, Magnus Hagander wrote: > 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". All I can say is that most emails we get about the docs using the form are just complaints, and we have to write some suggested text and get approaval from the reporter that the text is clear. We don't get many acutal _suggestions_. -- 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: Documentation - chapter 52, system catalogs
=?UTF-8?Q?J=c3=bcrgen_Purtz?= writes: > The attached patch contains: > - for "System Catalog": moving paragraphs from bottom of 51. to top of > 51.1. (in PG 11 it is chapter 52); explanation that "System Catalog" is > a synonym for a concrete schema and its tables. > - for "Information Schema": moving paragraphs from bottom of 36. to > middle of 36.1. ; an explanation that it relies on the system catalog; > change the title of 36.1. to "Overview" in correlation with "System > Catalog". I don't like this patch much; it seems to me that from a semantic standpoint, it's making things worse not better. Text that's ahead of the first is more important than the text after it, or should be. I don't deny that we have a problem here: in the website rendering, that text tends to be pushed down out of sight by the chapter's sub-table-of-contents. But that issue exists for every chapter that's got more than a couple of sections. We shouldn't hack around it for just these two chapters. Chapter 9 and Appendix F are additional examples where this is a fairly urgent issue. I wonder if we should just drop the sub-table-of-contents material. (I'm assuming DocBook can be coerced to do that; but since the PDF output has no such material, it seems like it ought to be possible.) Or ... is there a way to postpone it to the bottom of the page, ie just before the first , instead of having it in front of the chapter preface? The same issue exists for the sub-sub-tables-of-contents for s, though it's less bad because few of those have grown enormous lists of 's. regards, tom lane
Re: Another modest proposal for docs formatting: catalog descriptions
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
Hello Tom, oid OID Meh. I'm not a fan of overuse of upper case --- it's well established that that's harder to read than lower or mixed case. And it's definitely project policy that type names are generally treated as identifiers not keywords, even if some of them happen to be keywords under the hood. I found "oid oid" stuttering kind of strange, hence an attempt at suggesting something that could distinguish them. The markup I had in mind was for the field name and for the type name, but no decoration beyond that. Ok. If they are displayed a little differently afterwards that'd may help. As for the references, it seems to me that your notation would lead people to think that there are actual FK constraints in place, which of course there are not (especially not on the views). In practice the system ensures that the target exists, so it is as-if there would be a foreign key enforced? My point is that using differing syntaxes for the more-or-less the same concept does not help user understand the semantics, but maybe that is just me. I'm not hugely against it but I prefer what I suggested. Ok! -- Fabien.
