Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Robert Haas]

On Tue, Oct 12, 2010 at 9:05 PM, Josh Kupershmidt  wrote:
> On Tue, Oct 12, 2010 at 1:03 PM, Josh Kupershmidt  wrote:
>> Perhaps a mention of this change could be made in the 8.4 release notes?
>
> And here's a patch for the 8.4 release notes.

It seems odd to change our release notes after the fact.  I don't
think we usually do that.

I'm also not really sure that this is important enough to be worth
documenting.  It looks fairly self-explanatory.

*ducks*

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

[DOCS] formula about the number of WAL files

[Fujii Masao]

Hi,


29.4. WAL Configuration

There will always be at least one WAL segment file, and will normally not
be more than (2 + checkpoint_completion_target) * checkpoint_segments + 1
or checkpoint_segments + wal_keep_segments + 1 files.


The above formula is wrong. The correct is

(2 + checkpoint_completion_target) * checkpoint_segments +
wal_keep_segments + 1

The attached patch fixes this fault.

Regards,

-- 
Fujii Masao
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center


num_of_wal_formula_v2.patch
Description: Binary data

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

[DOCS] description of translate()

[Josh Kupershmidt]

Hi all,

I noticed that the existing description of the string translate()
function 

currently has a description of:

  Any character in string that matches a character in the from set is
replaced by the corresponding character in the to set

This description leaves off the other half of translate()'s
capability, namely stripping unwanted characters entirely. The comment
for the translate() in oracle_compat.c is helpful here, saying:

  If from is longer than to, occurrences of the extra characters in
from are deleted.

Attached is a patch to update the doc page based on this comment's wording.

Josh


func.sgml.patch
Description: Binary data

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Josh Kupershmidt]

On Wed, Oct 13, 2010 at 9:56 PM, Robert Haas  wrote:
> On Tue, Oct 12, 2010 at 9:05 PM, Josh Kupershmidt  wrote:
>> On Tue, Oct 12, 2010 at 1:03 PM, Josh Kupershmidt  wrote:
>>> Perhaps a mention of this change could be made in the 8.4 release notes?
>>
>> And here's a patch for the 8.4 release notes.
>
> It seems odd to change our release notes after the fact.  I don't
> think we usually do that.

Well, I do count 10 or so updates to release-8.4.sgml since its
release date (2009-07-01). Granted, most of these are minor cleanups
or to document further point releases.

> I'm also not really sure that this is important enough to be worth
> documenting.  It looks fairly self-explanatory.

Oh well.

Would anyone favor instead back-patching the documentation for the
8.3, 8.2, and 8.1 branches to include mentions of these
previously-undocumented functions, instead? In
, Tom
opined that they should be left undocumented, but I really don't agree
with that.

I almost concluded the original -novice poster was simply missing a
user-defined function from her old database, since googling for
"postgresql nonnullvalue" brought up nothing useful, and there was no
mention of it in the (current) source code. It seems pretty harsh to
me to intentionally not document these functions, even if they are
obscure and not terribly useful.

Josh

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Robert Haas]

On Tue, Oct 12, 2010 at 8:28 AM, Fujii Masao  wrote:
> On Sat, Oct 9, 2010 at 10:04 AM, Brendan Jurd  wrote:
>> Hi folks,
>>
>> I have just set up HS+SR for the first time, and for the most part,
>> the docs were excellent.  The one exception for me was the discussion
>> of archive_cleanup_command.  This is a pretty important part of
>> constructing a healthy standby server, and IMO the docs don't give it
>> the treatment it deserves.
>>
>> Under "25.2.4. Setting Up a Standby Server", we have:
>>
>> "You can use archive_cleanup_command to prune the archive of files no
>> longer needed by the standby."
>>
>> ... then a few paragraphs later ...
>>
>> "If you're using a WAL archive, its size can be minimized using the
>> archive_cleanup_command  option to remove files that are no longer
>> required by the standby server. Note however, that if you're using the
>> archive for backup purposes, you need to retain files needed to
>> recover from at least the latest base backup, even if they're no
>> longer needed by the standby."
>>
>> So there are a couple of brief mentions of what
>> archive_cleanup_command is for, but nothing about how it works, no
>> exampes of how to use it, and no links at all.  Contrast how we deal
>> with archive_command, restore_command and primary_conninfo.
>>
>> I'd like to suggest a few ways we could improve on this:
>>
>> 1. Remove the former paragraph.  It's stranded out there on its own in
>> the middle of some unrelated text, and doesn't say anything of
>> substance not also said in the latter paragraph.
>>
>> 2. Include an example archive_cleanup_command in the recovery.conf
>> example snippet.
>>
>> 3. Link to 26.1 which actually explains how a_c_c works.
>>
>> 4. Mention, and link to, pg_archivecleanup from both 25.2.4 and 26.1.
>> This is the utility that most newcomers to WAL archiving will want to
>> use, so it's rather weird of us not to advertise it.
>>
>> I'm willing to write a patch for this, but I thought I'd raise the
>> suggestions on-list first, before getting too invested.  So, please
>> comment if you have an opinion on this.
>
> Agreed.

Is someone working on a patch?

> And, ISTM that we should mention that we must not just specify
> pg_archivecleanup in archive_cleanup_command when there are multiple
> standby servers. This is because, in that case, we must calculate
> the oldest restart point in those standbys and delete the archived
> WAL files according to that point.

How do we expect people to do that, by the way?

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Robert Haas]

On Wed, Oct 13, 2010 at 11:25 PM, Josh Kupershmidt  wrote:
> On Wed, Oct 13, 2010 at 9:56 PM, Robert Haas  wrote:
>> On Tue, Oct 12, 2010 at 9:05 PM, Josh Kupershmidt  wrote:
>>> On Tue, Oct 12, 2010 at 1:03 PM, Josh Kupershmidt  
>>> wrote:
 Perhaps a mention of this change could be made in the 8.4 release notes?
>>>
>>> And here's a patch for the 8.4 release notes.
>>
>> It seems odd to change our release notes after the fact.  I don't
>> think we usually do that.
>
> Well, I do count 10 or so updates to release-8.4.sgml since its
> release date (2009-07-01). Granted, most of these are minor cleanups
> or to document further point releases.

As far as I'm aware they're all for further point releases or markup
adjustments.  I'm not aware of a case where we've changed the
*content* of the release notes after the fact.  I might be wrong, of
course.

>> I'm also not really sure that this is important enough to be worth
>> documenting.  It looks fairly self-explanatory.
>
> Oh well.
>
> Would anyone favor instead back-patching the documentation for the
> 8.3, 8.2, and 8.1 branches to include mentions of these
> previously-undocumented functions, instead? In
> , Tom
> opined that they should be left undocumented, but I really don't agree
> with that.
>
> I almost concluded the original -novice poster was simply missing a
> user-defined function from her old database, since googling for
> "postgresql nonnullvalue" brought up nothing useful, and there was no
> mention of it in the (current) source code. It seems pretty harsh to
> me to intentionally not document these functions, even if they are
> obscure and not terribly useful.

Well, I certainly would have supported documenting them when they
existed, and release-noting them when they were removed, but I'm not
too sure how much value there is in doing it years after the fact.  A
future Google search will probably find this thread, or that one.

Still, I don't think it would be unreasonable to add a note to the
prior-release documentation saying - hey, these functions exist.  They
are for internal use only, and do not exist in later versions.  Don't
use 'em.  Now, how many people will actually see that note?  Probably
not many.  But it wouldn't bother me to have it there.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Peter Eisentraut]

On tor, 2010-10-14 at 08:50 -0400, Robert Haas wrote:
> Still, I don't think it would be unreasonable to add a note to the
> prior-release documentation saying - hey, these functions exist.  They
> are for internal use only, and do not exist in later versions.  Don't
> use 'em.  Now, how many people will actually see that note?  Probably
> not many.  But it wouldn't bother me to have it there.

Just like there is a philosophical argument against changing the release
notes after the release, there is an argument against changing a past
release to "retroactively predict" how future releases behave.  We have
made exceptions to both points on occasion, but usually only for
critical upgrade-related issues.



-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Josh Kupershmidt]

On Thu, Oct 14, 2010 at 10:00 AM, Peter Eisentraut  wrote:
> The sets of intentionally documented and undocumented functions is part
> of the API specification of a release, and we're not changing that after
> the release, especially not when a future release ends up reverting the
> change.

Fair enough. I still think that we shouldn't be intentionally leaving
features undocumented, as it just leads to confusion down the road
(e.g. trying to figure out what some legacy code is doing, without
documentation).

I'm curious now, though: are there any other functions which we're
leaving intentionally undocumented? The only similar one I've run
across are the deprecated "-a" and "-A" arguments to the createuser
command. (There's another argument for documenting deprecated
features/arguments: it's easier to know what needs to be ripped out in
future releases).

Josh

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Tom Lane]

Peter Eisentraut  writes:
> On tor, 2010-10-14 at 08:50 -0400, Robert Haas wrote:
>> Still, I don't think it would be unreasonable to add a note to the
>> prior-release documentation saying - hey, these functions exist.  They
>> are for internal use only, and do not exist in later versions.  Don't
>> use 'em.  Now, how many people will actually see that note?  Probably
>> not many.  But it wouldn't bother me to have it there.

> Just like there is a philosophical argument against changing the release
> notes after the release, there is an argument against changing a past
> release to "retroactively predict" how future releases behave.  We have
> made exceptions to both points on occasion, but usually only for
> critical upgrade-related issues.

I would put this whole issue in the category of "if you use undocumented
features, you should not be surprised when they undocumentedly break".
There are many many places where it's possible to see undocumented
implementation details in Postgres.  If we put in release-note warnings
every time we changed one of those details, the release notes would be
twice as long and half as useful as they are now.

regards, tom lane

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Tom Lane]

Josh Kupershmidt  writes:
> I'm curious now, though: are there any other functions which we're
> leaving intentionally undocumented?

Practically all the functions underlying operators are undocumented, eg
int4pl(int, int).  (If you consider IS NOT NULL to be an operator, then
nonnullvalue is exactly one of those.)  It's possible for people to use
those directly but it's discouraged.  I do *not* want to add them to the
docs, because (a) I do *not* want people to use them directly and (b)
there are a hell of a lot of them, so the docs would get much much
longer with no actual added value.

Perhaps what we should really add to the docs is a statement that use of
undocumented functions is deprecated and we will not be responsible when
your code breaks because one of those is changed or removed.

regards, tom lane

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Peter Eisentraut]

On ons, 2010-10-13 at 23:25 -0400, Josh Kupershmidt wrote:
> Would anyone favor instead back-patching the documentation for the
> 8.3, 8.2, and 8.1 branches to include mentions of these
> previously-undocumented functions, instead? In
> , Tom
> opined that they should be left undocumented, but I really don't agree
> with that.

The sets of intentionally documented and undocumented functions is part
of the API specification of a release, and we're not changing that after
the release, especially not when a future release ends up reverting the
change.


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Brendan Jurd]

On 14 October 2010 08:45, Robert Haas  wrote:
> Is someone working on a patch?

Yes, I will prepare a patch to get us started.

Cheers,
BJ

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Simon Riggs]

On Fri, 2010-10-15 at 02:24 +1100, Brendan Jurd wrote:

> I'll drop this onto the next open commitfest.  If it passes muster, it
> sure wouldn't hurt to backpatch it to 9.0.

Committed. Not sure there's anything there worth backpatching? There
aren't any doc bugs there.

-- 
 Simon Riggs   www.2ndQuadrant.com
 PostgreSQL Development, 24x7 Support, Training and Services


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Brendan Jurd]

On 12 October 2010 23:28, Fujii Masao  wrote:
> On Sat, Oct 9, 2010 at 10:04 AM, Brendan Jurd  wrote:
>> I have just set up HS+SR for the first time, and for the most part,
>> the docs were excellent.  The one exception for me was the discussion
>> of archive_cleanup_command.  This is a pretty important part of
>> constructing a healthy standby server, and IMO the docs don't give it
>> the treatment it deserves.
...

> Agreed.
>
> And, ISTM that we should mention that we must not just specify
> pg_archivecleanup in archive_cleanup_command when there are multiple
> standby servers. This is because, in that case, we must calculate
> the oldest restart point in those standbys and delete the archived
> WAL files according to that point.

As promised, here is a patch to try to address $SUBJECT.

Summary of changes:

In 25.2.4. "Setting Up a Standby Server":

 * Get rid of the extraneous short paragraph,
 * move the full-size paragraph up to where the now-extinct short para was,
 * add an archive_cleanup_command to the example recovery.conf,
 * flesh out the wording,
 * add links to 26.1 and F.22.

In 26.1. "Archive recovery settings":

 * Add detail to the description of how it works,
 * add an example recovery.conf snippet,
 * per Fujii-san's comment, indicate that multi-standby setups require
more finesse,
 * link to F.22.

In F.22. "pg_archivecleanup":

 * Edit and clarify wording,
 * standardise label for the  argument,
 * again indicate the multi-standby issue,
 * link to 25.2.

I'll drop this onto the next open commitfest.  If it passes muster, it
sure wouldn't hurt to backpatch it to 9.0.

Cheers,
BJ
*** a/doc/src/sgml/high-availability.sgml
--- b/doc/src/sgml/high-availability.sgml
***
*** 681,691  protocol to make nodes agree on a serializable transactional 
order.
 
  
 
- You can use archive_cleanup_command to prune the archive of
- files no longer needed by the standby.
-
- 
-
  If you're setting up the standby server for high availability purposes,
  set up WAL archiving, connections and authentication like the primary
  server, because the standby server will work as a primary server after
--- 681,686 
***
*** 697,708  protocol to make nodes agree on a serializable transactional 
order.
--- 692,716 
 
  
 
+ If you're using a WAL archive, its size can be minimized using the  parameter to remove files that are no
+ longer required by the standby server.
+ The pg_archivecleanup utility is designed specifically to
+ be used with archive_cleanup_command in typical single-standby
+ configurations, see .
+ Note however, that if you're using the archive for backup purposes, you
+ need to retain files needed to recover from at least the latest base
+ backup, even if they're no longer needed by the standby.
+
+ 
+
  A simple example of a recovery.conf is:
  
  standby_mode = 'on'
  primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
  restore_command = 'cp /path/to/archive/%f %p'
  trigger_file = '/path/to/trigger_file'
+ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r'
  
 
  
***
*** 712,725  trigger_file = '/path/to/trigger_file'
  the primary to allow them to be connected simultaneously.
 
  
-
- If you're using a WAL archive, its size can be minimized using
- the archive_cleanup_command option to remove files that are
- no longer required by the standby server. Note however, that if you're
- using the archive for backup purposes, you need to retain files needed
- to recover from at least the latest base backup, even if they're no
- longer needed by the standby.
-

  

--- 720,725 
*** a/doc/src/sgml/pgarchivecleanup.sgml
--- b/doc/src/sgml/pgarchivecleanup.sgml
***
*** 8,17 
   
  
   
!   pg_archivecleanup is designed to cleanup an archive when 
used
!   as an archive_cleanup_command when running with
!   standby_mode = on. pg_archivecleanup can
!   also be used as a standalone program to clean WAL file archives.
   
  
   
--- 8,18 
   
  
   
!   pg_archivecleanup is designed to be used as an
!   archive_cleanup_command to clean up WAL file archives 
when
!   running as a standby server (see ).
!   pg_archivecleanup can also be used as a standalone program 
to
!   clean WAL file archives.
   
  
   
***
*** 39,58 
 server to use pg_archivecleanup, put this into its
 recovery.conf configuration file:
  
! archive_cleanup_command = 'pg_archivecleanup archiveDir %r'
  
!where archiveDir is the directory from which WAL segment
!files should be restored.


!When used within archive_cleanup_command,
!all WAL files logically preceding the value of the %r
!will be removed archivelocation. This minimizes
!the number of files that need to be retained, while preserving
!crash-restart capability.

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Robert Haas]

On Thu, Oct 14, 2010 at 2:33 PM, Simon Riggs  wrote:
> On Fri, 2010-10-15 at 02:24 +1100, Brendan Jurd wrote:
>
>> I'll drop this onto the next open commitfest.  If it passes muster, it
>> sure wouldn't hurt to backpatch it to 9.0.
>
> Committed. Not sure there's anything there worth backpatching? There
> aren't any doc bugs there.

It's a while until 9.1 comes out, so it might be helpful to back-patch to 9.0.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Robert Haas]

On Thu, Oct 14, 2010 at 10:00 AM, Peter Eisentraut  wrote:
> On ons, 2010-10-13 at 23:25 -0400, Josh Kupershmidt wrote:
>> Would anyone favor instead back-patching the documentation for the
>> 8.3, 8.2, and 8.1 branches to include mentions of these
>> previously-undocumented functions, instead? In
>> , Tom
>> opined that they should be left undocumented, but I really don't agree
>> with that.
>
> The sets of intentionally documented and undocumented functions is part
> of the API specification of a release, and we're not changing that after
> the release, especially not when a future release ends up reverting the
> change.

I find the idea of things being intentionally undocumented quite
difficult.  How is someone coming along supposed to know which things
are intentionally undocumented and which things are unintentionally
undocumented?

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Brendan Jurd]

On 15 October 2010 05:33, Simon Riggs  wrote:
> On Fri, 2010-10-15 at 02:24 +1100, Brendan Jurd wrote:
>> I'll drop this onto the next open commitfest.  If it passes muster, it
>> sure wouldn't hurt to backpatch it to 9.0.
>
> Committed. Not sure there's anything there worth backpatching? There
> aren't any doc bugs there.
>

Thanks for the commit Simon.

Agreed that there are no doc bugs.  The reason I suggested a backpatch
is that I'm concerned that a lot of people are going to be approaching
the whole Standby topic for the first time with 9.0, so it would be
nice to give those folks an accessible account of how
archive_cleanup_command is meant to be used.

I was also working from the assumption that the "we only packpatch bug
fixes" policy applied to the code, not so much to the documentation.
If I was in error about that, well fair enough then.

Cheers,
BJ

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] [HACKERS] Docs for archive_cleanup_command are poor

[Tom Lane]

Brendan Jurd  writes:
> Agreed that there are no doc bugs.  The reason I suggested a backpatch
> is that I'm concerned that a lot of people are going to be approaching
> the whole Standby topic for the first time with 9.0, so it would be
> nice to give those folks an accessible account of how
> archive_cleanup_command is meant to be used.

Yeah, if this is a material improvement in the usefulness of the HS
docs, I think including it into 9.0.x isn't a bad idea.

regards, tom lane

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Tom Lane]

Robert Haas  writes:
> I find the idea of things being intentionally undocumented quite
> difficult.  How is someone coming along supposed to know which things
> are intentionally undocumented and which things are unintentionally
> undocumented?

They should assume the lack of documentation is intentional.  Six or
seven years ago your argument might have held some water, but we've
been quite rigorous about requiring externally-visible features to be
documented from the get-go.

regards, tom lane

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Robert Haas]

On Thu, Oct 14, 2010 at 6:07 PM, Tom Lane  wrote:
> Robert Haas  writes:
>> I find the idea of things being intentionally undocumented quite
>> difficult.  How is someone coming along supposed to know which things
>> are intentionally undocumented and which things are unintentionally
>> undocumented?
>
> They should assume the lack of documentation is intentional.  Six or
> seven years ago your argument might have held some water, but we've
> been quite rigorous about requiring externally-visible features to be
> documented from the get-go.

That just doesn't match my experience.  We goof.  People find it.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Tom Lane]

Robert Haas  writes:
> On Thu, Oct 14, 2010 at 6:07 PM, Tom Lane  wrote:
>> They should assume the lack of documentation is intentional.  Six or
>> seven years ago your argument might have held some water, but we've
>> been quite rigorous about requiring externally-visible features to be
>> documented from the get-go.

> That just doesn't match my experience.  We goof.  People find it.

Sure, there are bugs of that sort, just like we have bugs of many other
sorts.  When people find them, we fix them.  But the general principle
is that functions and operators that are meant to be used directly from
SQL are shown in the SGML documentation; and those that aren't, aren't.

There are probably upwards of a thousand entries in pg_proc that are
not, and never were, meant to be directly invoked from SQL.  (In
particular, with 706 entries in pg_operator, there are presumably about
700 functions underlying operators; and then you've got functions
underlying aggregates, index AM support functions, selectivity
estimation functions, text search support functions, foreign data
wrapper functions, yadda yadda.)  It is not sane to propose documenting
those individually, not only from the standpoint of docs bloat but
because documenting them would encourage people to call them, which is
exactly not the result we want.

regards, tom lane

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Documenting removal of nonnullvalue() and friends

[Robert Haas]

On Thu, Oct 14, 2010 at 7:15 PM, Tom Lane  wrote:
> Robert Haas  writes:
>> On Thu, Oct 14, 2010 at 6:07 PM, Tom Lane  wrote:
>>> They should assume the lack of documentation is intentional.  Six or
>>> seven years ago your argument might have held some water, but we've
>>> been quite rigorous about requiring externally-visible features to be
>>> documented from the get-go.
>
>> That just doesn't match my experience.  We goof.  People find it.
>
> Sure, there are bugs of that sort, just like we have bugs of many other
> sorts.  When people find them, we fix them.  But the general principle
> is that functions and operators that are meant to be used directly from
> SQL are shown in the SGML documentation; and those that aren't, aren't.
>
> There are probably upwards of a thousand entries in pg_proc that are
> not, and never were, meant to be directly invoked from SQL.  (In
> particular, with 706 entries in pg_operator, there are presumably about
> 700 functions underlying operators; and then you've got functions
> underlying aggregates, index AM support functions, selectivity
> estimation functions, text search support functions, foreign data
> wrapper functions, yadda yadda.)  It is not sane to propose documenting
> those individually, not only from the standpoint of docs bloat but
> because documenting them would encourage people to call them, which is
> exactly not the result we want.

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?

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs