Skip site navigation (1) Skip section navigation (2)

Re: Adding comments for system table/column names

From: Bruce Momjian <bruce(at)momjian(dot)us>
To: Noah Misch <noah(at)leadboat(dot)com>
Cc: PostgreSQL-development <pgsql-hackers(at)postgreSQL(dot)org>,Magnus Hagander <magnus(at)hagander(dot)net>
Subject: Re: Adding comments for system table/column names
Date: 2012-10-13 15:17:32
Message-ID: 20121013151732.GD31038@momjian.us (view raw or flat)
Thread:
Lists: pgsql-hackers
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. +


In response to

Responses

pgsql-hackers by date

Next:From: Stephen FrostDate: 2012-10-13 15:45:13
Subject: Re: Successor of MD5 authentication, let's use SCRAM
Previous:From: Guillaume LelargeDate: 2012-10-13 14:47:06
Subject: Bug in -c CLI option of pg_dump/pg_restore

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group