Thread: 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.
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
Attachment
=?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> 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 <sect1> 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 <sect1>, instead of having it in front of the chapter preface? The same issue exists for the sub-sub-tables-of-contents for <sect1>s, though it's less bad because few of those have grown enormous lists of <sect2>'s. regards, tom lane
On 06.05.20 00:01, Tom Lane wrote: > 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. Generic solutions are always better than individual ones. > 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.) If we drop TOCs, we loose the automatically created links. As a substitute we would need tables like in example 51.1. So it's again an individual solution. > Or ... is there a way to postpone it to the bottom of the page, > ie just before the first <sect1>, instead of having it in front > of the chapter preface? > > The same issue exists for the sub-sub-tables-of-contents for <sect1>s, > though it's less bad because few of those have grown enormous lists > of <sect2>'s. Swapping TOC and content may work in such cases, but for me it seems to be a hard work with xslt. A real generic solution would be an adaption of the HTML output to the PDF output: two columns with a collapsible menu containing all TOC information in the left one ('outline' in PDF) and nothing than content in the right one. But this is a huge change of the look-and-feel as well as for all technical stuff: HTML, CSS, bootstrap, Javascript, Ajax(?), ... . -- Jürgen Purtz