Re: Improve initdb and pg_controldata manual pages

On Wed, Mar 9, 2011 at 8:43 PM, Leslie S Satenstein
<lsatenstein(at)yahoo(dot)com> wrote:
> The docs need consistency, so that the information therein is not misconstrued by an English speaking / reading non-American.  The documentation has many many grammar mistakes, where pronouns refer back to more than one noun, or adverbs refer to more than one verb.  I found the authors mean very well, but they mix usage based on programming thoughts.   Fields give, instead of contains, is one example.  Here is a context to illustrate.
>
> The function xyz() has two variables. A list of keywords, and a list of values which gives results.  Now the value variable actually contain values associated with keywords, and together these are the functions input parameters. The function does not work with keywords alone and the result gives the values.

Well, I don't agree with you on this one, and I don't think the
dictionary does either.

http://www.thefreedictionary.com/Gives

The second definition is "to place in the hands of, pass" and another
definition includes the word "confer". It is completely reasonable to
think of the argument to a function as passing or conferring those
arguments to the function. I want the docs to be clear and
high-quality, but the fact that one person (you) thinks that they are
poorly worded doesn't make it true. If two or five or ten other
people come out of the woodwork and say, hey, that could be phrased
better, then of course we'll change it. However, I have heard the
word gives used in the way you don't like in many different contexts
by many people over many years, and I have never before heard anyone
say they thought it was unclear. I believe that this is quite a
normal usage in the scientific literature.

Here's are some examples from the man page for mail(1) showing the use
of the word "gives" to mean "passes as an argument" rather than
"returns as a result":

escape If defined, the first character of this option gives the charac-
ter to use in place of `~' to denote escapes.

record If defined, gives the pathname of the file used to record all
outgoing mail. If not defined, outgoing mail is not saved.
Default is norecord.

Here's another example from man zshcompsys:

For the -value- context, the form is `-value-,name,command', where name
is the name of the parameter. In the case of elements of an associa-
tive array, for example `assoc=(key <TAB>', name is expanded to
`name-key'. In certain special contexts, such as completing after
`make CFLAGS=', the command part gives the name of the command, here
make; otherwise it is empty.

If you were to argue that "gives" is *more commonly* used to denote
results than inputs, I wouldn't disagree with you; a quick grep of the
UNIX man pages on my system supports the notion that this is the case.
But just because a word has a primary meaning does not make it wrong
to use it in some other way. In fact, in my opinion, choosing
slightly different words in slightly different contexts can often make
documentation much more readable, by allowing shades of meaning to be
conveyed that would be lost if we were to insist on phrasing
everything exactly the same way in every case. Consistency is good,
but it is not the highest or only virtue, and being excessively
pedantic about it can result in text which is so formulaic that it
becomes difficult to read.

Please stop acting as if this is a debate between people who want to
improve the documentation and people who don't. That's not the
question. The question is whether the changes that you are proposing
to make are in fact improvements. I believe that's something that
reasonable people can disagree about.

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