Thread: 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
dependentobject is inobjid | oid | not null | The OID of the specific dependent objectobjsubid | integer
|not null | For a table column, this is the column number (the objid and classid refer to the table itself). For all
otherobject types, this column is zero.refclassid | oid | not null | The OID of the system catalog the referenced
objectis inrefobjid | oid | not null | The OID of the specific referenced objectrefobjsubid | integer | not
null | For a table column, this is the column number (the refobjid and refclassid refer to the table itself). For all
otherobject types, this column is zero.deptype | "char" | not null | A code defining the specific semantics of
thisdependency 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: > 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 thetable 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 referto 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 frompeople 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!