Обсуждение: Improve initdb and pg_controldata manual pages
I have applied the attached patch to improve the initdb and pg_controldata manual pages. Patch from gabrielle <gorthx@gmail.com>. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 04f047b..e3fdebd 100644 *** a/doc/src/sgml/ref/initdb.sgml --- b/doc/src/sgml/ref/initdb.sgml *************** PostgreSQL documentation *** 22,30 **** <refsynopsisdiv> <cmdsynopsis> <command>initdb</command> ! <arg rep="repeat"><replaceable>option</></arg> <group choice="plain"> ! <arg>--pgdata </arg> <arg>-D </arg> <replaceable>directory</replaceable> </group> --- 22,30 ---- <refsynopsisdiv> <cmdsynopsis> <command>initdb</command> ! <arg rep="repeat"><replaceable>option</replaceable></arg> <group choice="plain"> ! <arg>--pgdata=</arg> <arg>-D </arg> <replaceable>directory</replaceable> </group> *************** PostgreSQL documentation *** 186,201 **** </varlistentry> <varlistentry> ! <term><option>-X <replaceable class="parameter">directory</replaceable></option></term> ! <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term> <listitem> <para> ! This option specifies the directory where the transaction log ! should be stored. </para> </listitem> </varlistentry> - <varlistentry> <term><option>-U <replaceable class="parameter">username</replaceable></option></term> <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> --- 186,199 ---- </varlistentry> <varlistentry> ! <term><option>--pwfile=<replaceable>filename</></option></term> <listitem> <para> ! Makes <command>initdb</command> read the database superuser's password ! from a file. The first line of the file is taken as the password. </para> </listitem> </varlistentry> <varlistentry> <term><option>-U <replaceable class="parameter">username</replaceable></option></term> <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> *************** PostgreSQL documentation *** 226,239 **** </varlistentry> <varlistentry> ! <term><option>--pwfile=<replaceable>filename</></option></term> <listitem> <para> ! Makes <command>initdb</command> read the database superuser's password ! from a file. The first line of the file is taken as the password. </para> </listitem> </varlistentry> </variablelist> </para> --- 224,239 ---- </varlistentry> <varlistentry> ! <term><option>-X <replaceable class="parameter">directory</replaceable></option></term> ! <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term> <listitem> <para> ! This option specifies the directory where the transaction log ! should be stored. </para> </listitem> </varlistentry> + </variablelist> </para> diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml index 50b1909..d39b6e1 100644 *** a/doc/src/sgml/ref/pg_controldata.sgml --- b/doc/src/sgml/ref/pg_controldata.sgml *************** PostgreSQL documentation *** 22,27 **** --- 22,28 ---- <refsynopsisdiv> <cmdsynopsis> <command>pg_controldata</command> + <arg><replaceable class="parameter">option</replaceable></arg> <arg><replaceable class="parameter">datadir</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index 307f66b..608749f 100644 *** a/doc/src/sgml/ref/pg_ctl-ref.sgml --- b/doc/src/sgml/ref/pg_ctl-ref.sgml *************** PostgreSQL documentation *** 499,520 **** <title>Starting the Server</title> <para> ! To start up a server: <screen> <prompt>$</prompt> <userinput>pg_ctl start</userinput> </screen> </para> <para> ! An example of starting the server, and waiting until the server is ! accepting connection: <screen> <prompt>$</prompt> <userinput>pg_ctl -w start</userinput> </screen> </para> <para> ! For a server using port 5433, and running without <function>fsync</function>, use: <screen> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput> --- 499,520 ---- <title>Starting the Server</title> <para> ! To start the server: <screen> <prompt>$</prompt> <userinput>pg_ctl start</userinput> </screen> </para> <para> ! To start the server, waiting until the server is ! accepting connections: <screen> <prompt>$</prompt> <userinput>pg_ctl -w start</userinput> </screen> </para> <para> ! To start the server using port 5433, and running without <function>fsync</function>, use: <screen> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput> *************** PostgreSQL documentation *** 530,536 **** <prompt>$</prompt> <userinput>pg_ctl stop</userinput> </screen> The <option>-m</option> option allows control over ! <emphasis>how</emphasis> the server shuts down. </para> </refsect2> --- 530,539 ---- <prompt>$</prompt> <userinput>pg_ctl stop</userinput> </screen> The <option>-m</option> option allows control over ! <emphasis>how</emphasis> the server shuts down: ! <screen> ! <prompt>$</prompt> <userinput>pg_ctl stop -m fast</userinput> ! </screen> </para> </refsect2> *************** PostgreSQL documentation *** 557,563 **** </para> <para> ! To restart using port 5433 and disable <function>fsync</> upon restart: <screen> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput> </screen> --- 560,566 ---- </para> <para> ! To restart using port 5433, disabling <function>fsync</> upon restart: <screen> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput> </screen> diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index 4437bf8..d332cba 100644 *** a/doc/src/sgml/ref/postgres-ref.sgml --- b/doc/src/sgml/ref/postgres-ref.sgml *************** PostgreSQL documentation *** 66,74 **** The <command>postgres</command> command can also be called in single-user mode. The primary use for this mode is during bootstrapping by <xref linkend="app-initdb">. Sometimes it is used ! for debugging or disaster recovery (but note that running a single-user server is not truly suitable for debugging the server, since no ! realistic interprocess communication and locking will happen). When invoked in single-user mode from the shell, the user can enter queries and the results will be printed to the screen, but in a form that is more useful --- 66,74 ---- The <command>postgres</command> command can also be called in single-user mode. The primary use for this mode is during bootstrapping by <xref linkend="app-initdb">. Sometimes it is used ! for debugging or disaster recovery; note that running a single-user server is not truly suitable for debugging the server, since no ! realistic interprocess communication and locking will happen. When invoked in single-user mode from the shell, the user can enter queries and the results will be printed to the screen, but in a form that is more useful *************** PostgreSQL documentation *** 413,420 **** <term><option>-P</option></term> <listitem> <para> ! Ignore system indexes when reading system tables (but still update ! the indexes when modifying the tables). This is useful when recovering from damaged system indexes. </para> </listitem> --- 413,420 ---- <term><option>-P</option></term> <listitem> <para> ! Ignore system indexes when reading system tables, but still update ! the indexes when modifying the tables. This is useful when recovering from damaged system indexes. </para> </listitem> *************** PostgreSQL documentation *** 763,775 **** <para> To start <command>postgres</command> with a specific ! port: <screen> <prompt>$</prompt> <userinput>postgres -p 1234</userinput> </screen> ! This command will start up <command>postgres</command> ! communicating through the port 1234. In order to connect to this ! server using <application>psql</>, you would need to run it as <screen> <prompt>$</prompt> <userinput>psql -p 1234</userinput> </screen> --- 763,773 ---- <para> To start <command>postgres</command> with a specific ! port, e.g. 1234: <screen> <prompt>$</prompt> <userinput>postgres -p 1234</userinput> </screen> ! To connect to this server using <application>psql</>, specify this port with the -p option: <screen> <prompt>$</prompt> <userinput>psql -p 1234</userinput> </screen>
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:
|
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 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