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!

---------------------------(end of broadcast)---------------------------
TIP 9: In versions below 8.0, the planner will ignore your desire to
choose an index scan if your joining column's datatypes do not
match

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

---------------------------(end of broadcast)---------------------------
TIP 3: Have you checked our extensive FAQ?

http://www.postgresql.org/docs/faq

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

---------------------------(end of broadcast)---------------------------
TIP 9: In versions below 8.0, the planner will ignore your desire to
choose an index scan if your joining column's datatypes do not
match

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!

---------------------------(end of broadcast)---------------------------
TIP 6: explain analyze is your friend

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

---------------------------(end of broadcast)---------------------------
TIP 2: Don't 'kill -9' the postmaster

Yes for the love of god do it

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 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


---------------------------(end of broadcast)---------------------------
TIP 6: explain analyze is your friend

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

---------------------------(end of broadcast)---------------------------
TIP 2: Don't 'kill -9' the postmaster

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!

---------------------------(end of broadcast)---------------------------
TIP 5: don't forget to increase your free space map settings