Re: Adding comments for system table/column names

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.

Here is how psql displays column and table comments:

test=> create table test(x int);
CREATE TABLE
test=> comment on column test.x IS 'wow';
COMMENT
test=> \d+ test
Table "public.test"
Column | Type | Modifiers | Storage | Stats target | Description
--------+---------+-----------+---------+--------------+-------------
x | integer | | plain | | wow
Has OIDs: no

test=> comment on table test is 'yikes';
COMMENT
test=> \d+
List of relations
Schema | Name | Type | Owner | Size | Description
--------+------+-------+----------+---------+-------------
public | test | table | postgres | 0 bytes | yikes
(1 row)

Should I continue working on this patch?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

2012/10/12 Bruce Momjian <bruce(at)momjian(dot)us>

> 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.
>
> Here is how psql displays column and table comments:
>
> test=> create table test(x int);
> CREATE TABLE
> test=> comment on column test.x IS 'wow';
> COMMENT
> test=> \d+ test
> Table "public.test"
> Column | Type | Modifiers | Storage | Stats target |
> Description
>
> --------+---------+-----------+---------+--------------+-------------
> x | integer | | plain | | wow
> Has OIDs: no
>
> test=> comment on table test is 'yikes';
> COMMENT
> test=> \d+
> List of relations
> Schema | Name | Type | Owner | Size | Description
> --------+------+-------+----------+---------+-------------
> public | test | table | postgres | 0 bytes | yikes
> (1 row)
>
> Should I continue working on this patch?
>
>
Hi all,

If it can help, Euler wrote about that some time ago in your blog [1].

Regards,

[1] http://eulerto.blogspot.com.br/2010/11/comment-on-catalog-tables.html

--
Fabrízio de Royes Mello
Consultoria/Coaching PostgreSQL
>> Blog sobre TI: http://fabriziomello.blogspot.com
>> Perfil Linkedin: http://br.linkedin.com/in/fabriziomello
>> Twitter: http://twitter.com/fabriziomello

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

On Sat, Oct 13, 2012 at 07:03:49AM -0400, Noah Misch wrote:
> 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.

I think the simplest solution would be to place SGML comment markers
around text we want to extract from overly-long SGML descriptions.
Descriptions without SGML comments would be extracted unchanged.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Sat, Oct 13, 2012 at 5:17 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> On Sat, Oct 13, 2012 at 07:03:49AM -0400, Noah Misch wrote:
>> 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.
>
> I think the simplest solution would be to place SGML comment markers
> around text we want to extract from overly-long SGML descriptions.
> Descriptions without SGML comments would be extracted unchanged.

Not sure how convenient that is, but it would certainly work. And it
would be a lot better than cutting off at word or character limits or
anything like that.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

On Sat, Oct 13, 2012 at 09:10:05PM +0200, Magnus Hagander wrote:
> >> > 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.
> >
> > I think the simplest solution would be to place SGML comment markers
> > around text we want to extract from overly-long SGML descriptions.
> > Descriptions without SGML comments would be extracted unchanged.
>
> Not sure how convenient that is, but it would certainly work. And it
> would be a lot better than cutting off at word or character limits or
> anything like that.

Well, I figure we have to do something, because people would like those
descriptions, and recording them in two places is too much overhead.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Sat, Oct 13, 2012 at 9:12 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> On Sat, Oct 13, 2012 at 09:10:05PM +0200, Magnus Hagander wrote:
>> >> > 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.
>> >
>> > I think the simplest solution would be to place SGML comment markers
>> > around text we want to extract from overly-long SGML descriptions.
>> > Descriptions without SGML comments would be extracted unchanged.
>>
>> Not sure how convenient that is, but it would certainly work. And it
>> would be a lot better than cutting off at word or character limits or
>> anything like that.
>
> Well, I figure we have to do something, because people would like those
> descriptions, and recording them in two places is too much overhead.

Agreed, this is definitely better than the other options there. And
the best suggetsion so far.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

On Sat, Oct 13, 2012 at 09:14:55PM +0200, Magnus Hagander wrote:
> On Sat, Oct 13, 2012 at 9:12 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > On Sat, Oct 13, 2012 at 09:10:05PM +0200, Magnus Hagander wrote:
> >> >> > 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.
> >> >
> >> > I think the simplest solution would be to place SGML comment markers
> >> > around text we want to extract from overly-long SGML descriptions.
> >> > Descriptions without SGML comments would be extracted unchanged.
> >>
> >> Not sure how convenient that is, but it would certainly work. And it
> >> would be a lot better than cutting off at word or character limits or
> >> anything like that.
> >
> > Well, I figure we have to do something, because people would like those
> > descriptions, and recording them in two places is too much overhead.
>
> Agreed, this is definitely better than the other options there. And
> the best suggetsion so far.

OK, I will work on this in the coming months for 9.3.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +