Re: 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 <bruce@momjian.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@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com
 + It's impossible for everything to be true. +