Improve initdb and pg_controldata manual pages

Bruce Momjian <bruce@momjian.us> writes:

I have applied the attached patch to improve the initdb and
pg_controldata manual pages. Patch from gabrielle <gorthx@gmail.com>.

This seems like the most bizarre choice you could have made.
It now looks like the preferred spelling of initdb's switch,
for instance, is

initdb --pgdata= /path/name

ie, *both* an equal sign and a space. Please rethink this.

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

I have applied the attached patch to improve the initdb and
pg_controldata manual pages. Patch from gabrielle <gorthx@gmail.com>.

This seems like the most bizarre choice you could have made.
It now looks like the preferred spelling of initdb's switch,
for instance, is

initdb --pgdata= /path/name

ie, *both* an equal sign and a space. Please rethink this.

Well, it actually looks like this:

initdb [option...] --pgdata= | -D directory

and this gets back to whether we are going to show '=' for long
switches, which I am waiting on a reply about. If we are, we probably
have to accept the above output --- if not, it will be removed along
with other cases. I have now removed the '=' from initdb, but it is an
open issue.

Also, keep in mind that the --help output often shows '=', e.g. from
pg_dump:

-E, --encoding=ENCODING dump the data in encoding ENCODING
-n, --schema=SCHEMA dump the named schema(s) only
-N, --exclude-schema=SCHEMA do NOT dump the named schema(s)

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:

Tom Lane wrote:

This seems like the most bizarre choice you could have made.
It now looks like the preferred spelling of initdb's switch,
for instance, is

initdb --pgdata= /path/name

ie, *both* an equal sign and a space. Please rethink this.

Well, it actually looks like this:

initdb [option...] --pgdata= | -D directory

and this gets back to whether we are going to show '=' for long
switches, which I am waiting on a reply about.

Yeah. I had not had an opinion about that before, but if this is the
sort of context the equal signs are going to be used in, I think we'd
be better off omitting them. There are two correct ways to use a
long form option with argument:

--switch=value
--switch value

This case *does not work*:

--switch= value

(At least on my machine, the switch is presumed to have an empty-string
value and then the value is seen as the next command line item.)
So we have to stay far away from any documentation layout that even
hints that that's the way to do it.

Also, keep in mind that the --help output often shows '=', e.g. from
pg_dump:

Right. I think we should leave those alone, though, if only because
changing them will cause a lot of pain for translators and it's not
worth it. The syntax shown in those messages is correct, it's just not
the whole truth. The SGML documentation is telling a different subset
of the truth, and I'm OK with that too. Since "the truth" about what
you can say does vary for different people depending on the local getopt
library, I can't get too excited about trying to document every case
that might possibly work.

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

Tom Lane wrote:

This seems like the most bizarre choice you could have made.
It now looks like the preferred spelling of initdb's switch,
for instance, is

initdb --pgdata= /path/name

ie, *both* an equal sign and a space. Please rethink this.

Well, it actually looks like this:

initdb [option...] --pgdata= | -D directory

and this gets back to whether we are going to show '=' for long
switches, which I am waiting on a reply about.

Yeah. I had not had an opinion about that before, but if this is the
sort of context the equal signs are going to be used in, I think we'd
be better off omitting them. There are two correct ways to use a
long form option with argument:

--switch=value
--switch value

This case *does not work*:

--switch= value

(At least on my machine, the switch is presumed to have an empty-string
value and then the value is seen as the next command line item.)
So we have to stay far away from any documentation layout that even
hints that that's the way to do it.

Well, looking at the detailed option list, it looks fine:

-D directory
--pgdata=directory

It is only at the top where we see the problem because -D/--pgdata is a
required argument and there are necesary spaces because we are showing
both -D and --pgdata followed by a single argument. The original patch
creator added '=' to be consistent with the syntax used below.

The bottom line is that there are many doc cases where this is used:

-D directory
--pgdata directory

(no '='), so we should decide what we want in the docs.

We could do:

initdb [option...] -D directory
initdb [option...] --pgdata=directory

but showing two lines just to show short and long options seems silly
because they do the same thing.

I think we can use '=' in the detail option docs and not use '=' in the
summary at the top, but we should decide on a consistent approach, which
we don't have now.

Also, keep in mind that the --help output often shows '=', e.g. from
pg_dump:

Right. I think we should leave those alone, though, if only because
changing them will cause a lot of pain for translators and it's not
worth it. The syntax shown in those messages is correct, it's just not
the whole truth. The SGML documentation is telling a different subset
of the truth, and I'm OK with that too. Since "the truth" about what
you can say does vary for different people depending on the local getopt
library, I can't get too excited about trying to document every case
that might possibly work.

OK.

Does professionally produced documentation have as many inconsistencies?
It seems one turns up everytime I go to change the docs.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:

Well, looking at the detailed option list, it looks fine:

-D directory
--pgdata=directory

It is only at the top where we see the problem because -D/--pgdata is a
required argument and there are necesary spaces because we are showing
both -D and --pgdata followed by a single argument. The original patch
creator added '=' to be consistent with the syntax used below.

The bottom line is that there are many doc cases where this is used:

-D directory
--pgdata directory

(no '='), so we should decide what we want in the docs.

Right. I think it's fine if the syntax summary shows only those cases,
especially if the detailed option list shows that "=" is possible too.
What is important to me is that the summary not suggest illegal syntaxes
to people.

Does professionally produced documentation have as many inconsistencies?

Hard to say. We have the problem that our docs were made by a lot of
people over a long period of time, so inconsistencies are a fact of
life. "Pro" documentation might be more consistent if it's written by a
smaller group of people over a shorter period of time...

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

Well, looking at the detailed option list, it looks fine:

-D directory
--pgdata=directory

It is only at the top where we see the problem because -D/--pgdata is a
required argument and there are necessary spaces because we are showing
both -D and --pgdata followed by a single argument. The original patch
creator added '=' to be consistent with the syntax used below.

The bottom line is that there are many doc cases where this is used:

-D directory
--pgdata directory

(no '='), so we should decide what we want in the docs.

Right. I think it's fine if the syntax summary shows only those cases,
especially if the detailed option list shows that "=" is possible too.
What is important to me is that the summary not suggest illegal syntaxes
to people.

Of course, the open question is do we prefer '=' to be used in the
detailed descriptions.

Does professionally produced documentation have as many inconsistencies?

Hard to say. We have the problem that our docs were made by a lot of
people over a long period of time, so inconsistencies are a fact of
life. "Pro" documentation might be more consistent if it's written by a
smaller group of people over a shorter period of time...

We probably have higher quality but lower consistency.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Wed, Mar 9, 2011 at 11:08 AM, Bruce Momjian <bruce@momjian.us> wrote:

Hard to say.  We have the problem that our docs were made by a lot of
people over a long period of time, so inconsistencies are a fact of
life.  "Pro" documentation might be more consistent if it's written by a
smaller group of people over a shorter period of time...

We probably have higher quality but lower consistency.

Isn't consistency part of quality? I think on the whole that our docs
are excellent in both quality and consistency. There are things that
I'm not happy about, but this particular issue seems like the sort of
thing that's not really worth spending effort on. I think the
portions of our docs that could still use some work are the newer
portions, such as the Hot Standby docs, which still feel a little
rough compared to some other places - sort of a laundry list of things
that will and won't work (UUID generators?). I'd rather see us invest
time in general copy editing than spend a lot of time creating an
unnecessary and possibly confusing consistency with regards to
something like this.

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

Robert Haas wrote:

On Wed, Mar 9, 2011 at 11:08 AM, Bruce Momjian <bruce@momjian.us> wrote:

Hard to say. ?We have the problem that our docs were made by a lot of
people over a long period of time, so inconsistencies are a fact of
life. ?"Pro" documentation might be more consistent if it's written by a
smaller group of people over a shorter period of time...

We probably have higher quality but lower consistency.

Isn't consistency part of quality? I think on the whole that our docs
are excellent in both quality and consistency. There are things that
I'm not happy about, but this particular issue seems like the sort of
thing that's not really worth spending effort on. I think the
portions of our docs that could still use some work are the newer
portions, such as the Hot Standby docs, which still feel a little
rough compared to some other places - sort of a laundry list of things
that will and won't work (UUID generators?). I'd rather see us invest
time in general copy editing than spend a lot of time creating an
unnecessary and possibly confusing consistency with regards to
something like this.

Well, new docs will get their regular run-over and should look fine
eventually.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Wed, 3/9/11, Robert Haas <robertmhaas@gmail.com> wrote:

From: Robert Haas <robertmhaas@gmail.com>
Subject: Re: [DOCS] Improve initdb and pg_controldata manual pages
To: "Bruce Momjian" <bruce@momjian.us>
Cc: "Tom Lane" <tgl@sss.pgh.pa.us>, "PostgreSQL-documentation" <pgsql-docs@postgresql.org>
Date: Wednesday, March 9, 2011, 12:21 PM

On Wed, Mar 9, 2011 at 11:08 AM, Bruce Momjian <bruce@momjian.us> wrote:

Hard to say.  We have the problem that our docs were made by a lot of
people over a long period of time, so inconsistencies are a fact of
life.  "Pro" documentation might be more consistent if it's written by a
smaller group of people over a shorter period of time...

We probably have higher quality but lower consistency.

Isn't consistency part of quality?  I think on the whole that our docs
are excellent in both quality and consistency.  There are things that
I'm not happy about, but this particular issue seems like the sort of
thing that's not really worth spending effort on.  I think the
portions of our docs that could still use some work are the newer
portions, such as the Hot Standby docs, which still feel a little
rough compared to some other places - sort of a laundry list of things
that will and won't work (UUID generators?).  I'd rather see us invest
time in general copy editing than spend a lot of time creating an
unnecessary and possibly confusing consistency with regards to
something like this.

--
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

I have to agree with Bruce M. that the docs are in need of some work. I think there are two or more viewpoints.

The docs should contain the detailed information concerning postgresql functions, with no omissions.

The docs should be well formatted so that the PDF files created are clear and understandable.

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. 

Consider this example as typical of what I forwarded to Bruce M. a while back.   Some people have ebook readers and do want to read the PDF version of the docs via their ebook readers.

------------------

p.MsoNormal, li.MsoNormal, div.MsoNormal { margin: 0in 0in 0.0001pt; font-size: 12pt; font-family: "Times New Roman"; }filtered { margin: 1in 1.25in; }div.Section1 { }Regards
 Leslie
Mr. Leslie Satenstein
40 years in IT and going strong.
Yesterday was a good day, today is a better day,
and tomorrow will be even better.---

Excerpts from Leslie S Satenstein's message of mié mar 09 22:43:19 -0300 2011:

I have to agree with Bruce M. that the docs are in need of some work.
I think there are two or more viewpoints.

I don't think you're going to find anyone to state that the docs are
perfect. Most people will say that they're “pretty good”, but agree
that improvements are still possible.

The docs should contain the detailed information concerning postgresql
functions, with no omissions.

No disagreement on this, but maybe there are corner cases.

The docs should be well formatted so that the PDF files created are
clear and understandable.

No disagreement on this either. I was even thinking a couple of days
ago that it might be good to have PDFs in other page sizes, smaller than
A4; say a typical book size. That would perhaps display better on a
ebook reader. (On the readers I've seen, full-page PDFs are annoying to
browse: fonts are too small, or you have to scroll).

Also, we still have program output, tables or code samples that are too
wide to fit a page. Those need to be fixed too.

Another thing I've considered is to format Postgres table output as
Docbook tables instead of ASCII art. Perhaps that would render better.
But that needs to be explored. (And of course psql would need a docbook
output mode to facilitate doc writing).

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.

Not being a native english speaker, I can't help you here.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

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 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