Re: [DOCS] Documenting removal of nonnullvalue() and friends
Tom Lane wrote: > Peter Eisentraut writes: > > On tor, 2010-10-14 at 19:17 -0400, Robert Haas wrote: > >> Part of the problem, I think, is that people don't necessarily find > >> this stuff via the documentation. They fire up psql or pgAdmin and > >> start typing backslash commands. They see something good, so they use > >> it. How are they to know it's undocumented? > > > This could possibly be addressed if we more diligently maintained the > > system catalogs comments, and then possibly default the comments of > > undocumented objects to "internal object, don't use". > > I thought about this a bit more last night. It's certainly true that > a lot of "internal" functions have comments that don't suggest that > they're not meant to be used directly. What I think would be a good > plan for functions that underlie operators is that we move any useful > comments from pg_proc to pg_operator, and then install a comment in > pg_proc that says "implementation of operator +" (or whatever the > operator name is). This will not only let people know that they should > use an operator instead, but which one to use, when they find the > function via \df. > > I believe that there are a few cases where we document both the operator > and the equivalent function, so in those cases both should have the > regular comment. > > The same sort of approach could be used for functions that are meant as > aggregate support, if they don't have any real stand-alone use. I think > most of the other categories of support functions are already pretty > obviously internal, if there even are any that don't have "internal" > arguments. > > If that sounds like a reasonable plan, I'm willing to have a go at it > after the commitfest closes. Tom, any work on this? A TODO? -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documenting removal of nonnullvalue() and friends
Bruce Momjian writes: > Tom Lane wrote: >> I thought about this a bit more last night. It's certainly true that >> a lot of "internal" functions have comments that don't suggest that >> they're not meant to be used directly. What I think would be a good >> plan for functions that underlie operators is that we move any useful >> comments from pg_proc to pg_operator, and then install a comment in >> pg_proc that says "implementation of operator +" (or whatever the >> operator name is). >> ... >> If that sounds like a reasonable plan, I'm willing to have a go at it >> after the commitfest closes. > Tom, any work on this? A TODO? I haven't done anything about this yet, but it's still on my to-do list. Right now (or at least after I finish the patches I'm working on) would probably be about the best possible time to do it, since hopefully we have the minimum number of unapplied patches that would need to be revised to follow the new convention. regards, tom lane -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documenting removal of nonnullvalue() and friends
Tom Lane wrote: > Bruce Momjian writes: > > Tom Lane wrote: > >> I thought about this a bit more last night. It's certainly true that > >> a lot of "internal" functions have comments that don't suggest that > >> they're not meant to be used directly. What I think would be a good > >> plan for functions that underlie operators is that we move any useful > >> comments from pg_proc to pg_operator, and then install a comment in > >> pg_proc that says "implementation of operator +" (or whatever the > >> operator name is). > >> ... > >> If that sounds like a reasonable plan, I'm willing to have a go at it > >> after the commitfest closes. > > > Tom, any work on this? A TODO? > > I haven't done anything about this yet, but it's still on my to-do list. > Right now (or at least after I finish the patches I'm working on) would > probably be about the best possible time to do it, since hopefully we > have the minimum number of unapplied patches that would need to be > revised to follow the new convention. Good point. -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
[DOCS] minor doc stylesheet patch
Hi,
I was reading pg 8.4 doc and having all the links underlined seemed
"kinda old web habit that disturbs the eye" :)
attached is a minor patch to fix it.
Thanks,
Serhat
--- stylesheet.css 2011-02-27 22:35:17.306352994 +0200
+++ stylesheet.css 2011-02-27 22:32:27.178353000 +0200
@@ -7,6 +7,8 @@
background: #FF;
}
+A {text-decoration:none;}
+A:hover {text-decoration:underline;}
A:link { color: #66; }
A:visited { color: #99; }
A:active { color: #FF; }
--
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
