Re: [HACKERS] Adding comments for system table/column names
On Sat, Oct 13, 2012 at 09:14:55PM +0200, Magnus Hagander wrote: > On Sat, Oct 13, 2012 at 9:12 PM, Bruce Momjian 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 http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] Adding comments for system table/column names
On Sat, Oct 13, 2012 at 9:12 PM, Bruce Momjian 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/ -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] Adding comments for system table/column names
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 http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] Adding comments for system table/column names
On Sat, Oct 13, 2012 at 5:17 PM, Bruce Momjian 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/ -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] Adding comments for system table/column names
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 http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] 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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] Adding comments for system table/column names
2012/10/12 Bruce Momjian > 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
[HACKERS] 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 http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers