Re: Comments on columns in the pg_catalog tables/views

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(at)fetter(dot)org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778

Remember to vote!