Comments on columns in the pg_catalog tables/views
Folks,
Before I dive into this, is there some reason why the pg_catalog.*
tables/views should not have comments that match the descriptions in
the docs? I can see where this could cause some maintenance issues,
and those probably need to be addressed, but it sure would be nice if
\d+ pg_depend pulled up something like:
Table "pg_catalog.pg_depend"
Column | Type | Modifiers | Description
-------------+---------+-----------+-------------
classid | oid | not null | The OID of the system catalog the dependent object is in
objid | oid | not null | The OID of the specific dependent object
objsubid | integer | not null | For a table column, this is the column number (the objid and classid refer to the table itself). For all other object types, this column is zero.
refclassid | oid | not null | The OID of the system catalog the referenced object is in
refobjid | oid | not null | The OID of the specific referenced object
refobjsubid | integer | not null | For a table column, this is the column number (the refobjid and refclassid refer to the table itself). For all other object types, this column is zero.
deptype | "char" | not null | A code defining the specific semantics of this dependency relationship; see text.
Cheers,
D
--
David Fetter david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!
David Fetter <david@fetter.org> writes:
Before I dive into this, is there some reason why the pg_catalog.*
tables/views should not have comments that match the descriptions in
the docs? I can see where this could cause some maintenance issues,
Yeah. If you can figure a way to auto-generate the comments from the
sgml files, it'd be nice, but I definitely don't want to manually
maintain Yet Another set of per-column information.
regards, tom lane
I wrote:
David Fetter <david@fetter.org> writes:
Before I dive into this, is there some reason why the pg_catalog.*
tables/views should not have comments that match the descriptions in
the docs? I can see where this could cause some maintenance issues,
Yeah. If you can figure a way to auto-generate the comments from the
sgml files, it'd be nice, but I definitely don't want to manually
maintain Yet Another set of per-column information.
Dept of second thoughts: actually, perhaps see if you can generate the
pg_description entries from the C comments in the include/catalog header
files. There's already a strong motivation to hold those to
shorter-than-a-line length, whereas the column descriptions in
catalogs.sgml tend to run on a little longer, and wouldn't format nicely
in \dt+.
regards, tom lane
On Wed, Oct 12, 2005 at 07:11:12PM -0400, Tom Lane wrote:
I wrote:
David Fetter <david@fetter.org> writes:
Before I dive into this, is there some reason why the
pg_catalog.* tables/views should not have comments that match the
descriptions in the docs? I can see where this could cause some
maintenance issues,Yeah. If you can figure a way to auto-generate the comments from
the sgml files, it'd be nice, but I definitely don't want to
manually maintain Yet Another set of per-column information.Dept of second thoughts: actually, perhaps see if you can generate
the pg_description entries from the C comments in the
include/catalog header files. There's already a strong motivation
to hold those to shorter-than-a-line length, whereas the column
descriptions in catalogs.sgml tend to run on a little longer, and
wouldn't format nicely in \dt+.
My thought is that by the time somebody is doing \dt+ (or equivalent
in other tools than psql) on a pg_catalog table or view, they need to
see details and are at most slightly concerned about the formatting.
Speaking of formatting, isn't there also a formatting TODO attached to
that? IOW, shouldn't these be de-coupled?
Cheers,
D
--
David Fetter david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!
David Fetter <david@fetter.org> writes:
On Wed, Oct 12, 2005 at 07:11:12PM -0400, Tom Lane wrote:
Dept of second thoughts: actually, perhaps see if you can generate
the pg_description entries from the C comments in the
include/catalog header files.
My thought is that by the time somebody is doing \dt+ (or equivalent
in other tools than psql) on a pg_catalog table or view, they need to
see details and are at most slightly concerned about the formatting.
If they need to see more than the most brief description, they should be
consulting the SGML documentation; that's what it's there for. Using
that same text for \dt+ comments will just encourage people to mis-optimize
the SGML text for the wrong purpose. We already have short comments in
the C code; why not use those?
regards, tom lane
Yes for the love of god do it :D
David Fetter wrote:
Show quoted text
Folks,
Before I dive into this, is there some reason why the pg_catalog.*
tables/views should not have comments that match the descriptions in
the docs? I can see where this could cause some maintenance issues,
and those probably need to be addressed, but it sure would be nice if
\d+ pg_depend pulled up something like:Table "pg_catalog.pg_depend"
Column | Type | Modifiers | Description
-------------+---------+-----------+-------------
classid | oid | not null | The OID of the system catalog the dependent object is in
objid | oid | not null | The OID of the specific dependent object
objsubid | integer | not null | For a table column, this is the column number (the objid and classid refer to the table itself). For all other object types, this column is zero.
refclassid | oid | not null | The OID of the system catalog the referenced object is in
refobjid | oid | not null | The OID of the specific referenced object
refobjsubid | integer | not null | For a table column, this is the column number (the refobjid and refclassid refer to the table itself). For all other object types, this column is zero.
deptype | "char" | not null | A code defining the specific semantics of this dependency relationship; see text.Cheers,
D
David Fetter wrote:
Dept of second thoughts: actually, perhaps see if you can generate
the pg_description entries from the C comments in the
include/catalog header files. There's already a strong motivation
to hold those to shorter-than-a-line length, whereas the column
descriptions in catalogs.sgml tend to run on a little longer, and
wouldn't format nicely in \dt+.My thought is that by the time somebody is doing \dt+ (or equivalent
in other tools than psql) on a pg_catalog table or view, they need to
see details and are at most slightly concerned about the formatting.
And not all tools have this formatting issue...
I like the long comments I can take from pg_settings, enabling pgAdmin
to deliver precise information on each config option.
Regards,
Andreas
On Thu, Oct 13, 2005 at 08:59:51AM +0000, Andreas Pflug wrote:
David Fetter wrote:
Dept of second thoughts: actually, perhaps see if you can generate
the pg_description entries from the C comments in the
include/catalog header files. There's already a strong motivation
to hold those to shorter-than-a-line length, whereas the column
descriptions in catalogs.sgml tend to run on a little longer, and
wouldn't format nicely in \dt+.My thought is that by the time somebody is doing \dt+ (or
equivalent in other tools than psql) on a pg_catalog table or view,
they need to see details and are at most slightly concerned about
the formatting.And not all tools have this formatting issue... I like the long
comments I can take from pg_settings, enabling pgAdmin to deliver
precise information on each config option.
I agree that we shouldn't hobble ourselves with what may be a
temporary weakness in psql's formatting, and Andreas brings up an
excellent point. It should be fairly easy for admin tools of whatever
kind to pull those descriptions from the catalog. I noticed that the
other person who chimed in with enthusiasm was another developer of a
different admin tool :)
Here's what I've come up with so far in re: what this change should
and should not do:
* Move comments to one source. This may be easiest to push into the
non-sgml sources.
* Minimal intrusion for developers who touch pg_catalog.* I haven't
touched pg_catalog, and would like some feedback from people who do
on what might constitute "minimal intrusion."
* No perl required for the server build. It's OK for the SGML doc
build, though, as some is already required.
* Some way to interleave the comments which now live in
catalogs.sgml back into there.
* The perennial Stuff Dave Hasn't Thought Of.
What's next?
Cheers,
D
--
David Fetter david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!