Re: Adding comments for system table/column names

On Fri, Oct 12, 2012 at 01:29:21PM -0400, Bruce Momjian wrote:
> There was a thread in January of 2012 where we discussed the idea of
> pulling system table/column name descriptions from the SGML docs and
> creating SQL comments for them:
> 
>     http://archives.postgresql.org/pgsql-hackers/2012-01/msg00837.php
> 
> Magnus didn't seem to like the idea:
> 
>     http://archives.postgresql.org/pgsql-hackers/2012-01/msg00848.php
> 
>     Well, I'd expect some of those columns to get (at least over time)
>     significantly more detailed information than they have now. Certainly
>     more than you'd put in comments in the catalogs. And having some sort
>     of combination there seems to overcomplicate things...
> 
> I think the idea of having the short descriptions in SQL and longer ones
> in SGML is not maintainable.  One idea would be to clip the SQL
> description to be no longer than a specified number of characters, with
> proper word break detection.

I prefer overlong entries to machine-truncated ones.  Seeing "Does the access
method support ordered" for both pg_am.amcanorder and pg_am.amcanorderbyop
thanks to the choice of truncation point does not seem like a win.

We could store a short version in the SGML markup, solely for this process to
extract.  In its absence, use the documentation-exposed text. The extractor
could emit a warning when it uses a string longer than N characters, serving
as a hint to add short-version markup for some column.  If that's too hard,
though, I'd still prefer overlong entries to nothing or to truncated entries.

> Should I continue working on this patch?

Please do; I've missed having this information handy.

Thanks,
nm