From: Tom Lane <tgl@sss.pgh.pa.us>
To: pgsql-docs@lists.postgresql.org
Cc: pgsql-hackers@lists.postgresql.org
Subject: Another modest proposal for docs formatting: catalog descriptions
Date: Mon, 04 May 2020 21:52:29 -0400
Message-ID: <12984.1588643549@sss.pgh.pa.us> (raw)
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
<variablelist>, 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, pgsql-docs@lists.postgresql.org, pgsql-hackers@lists.postgresql.org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-Reply-To: <12984.1588643549@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox