Re: Improve initdb and pg_controldata manual pages
От | Robert Haas |
---|---|
Тема | Re: Improve initdb and pg_controldata manual pages |
Дата | |
Msg-id | AANLkTimEo_v0JcPgT46=rQnPfZaVLtr_oPgnOuorJddk@mail.gmail.com обсуждение исходный текст |
Ответ на | Improve initdb and pg_controldata manual pages (Leslie S Satenstein <lsatenstein@yahoo.com>) |
Список | pgsql-docs |
On Wed, Mar 9, 2011 at 8:43 PM, Leslie S Satenstein <lsatenstein@yahoo.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 adverbsrefer 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 variableactually contain values associated with keywords, and together these are the functions input parameters. The functiondoes 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
В списке pgsql-docs по дате отправления: