Further work on postmaster and postgres reference pages.

doc/src/sgml/ref/postgres-ref.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.20 2001/09/27 16:29:12 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.21 2001/11/25 01:11:36 tgl Exp $
 Postgres documentation
 -->
 
@@ -43,6 +43,7 @@ Postgres documentation
    </group>
    <arg>-S <replaceable>sort-mem</replaceable></arg>
    <arg>-W <replaceable>seconds</replaceable></arg>
+   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
    <arg choice="plain"><replaceable>database</replaceable></arg>
    <sbr>
    <!-- postmaster fork -->
@@ -67,6 +68,7 @@ Postgres documentation
    <arg>-S <replaceable>sort-mem</replaceable></arg>
    <arg>-v <replaceable>protocol-version</replaceable></arg>
    <arg>-W <replaceable>seconds</replaceable></arg>
+   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -87,8 +89,9 @@ Postgres documentation
    conceptually, since both <filename>postmaster</filename> and
    <filename>postgres</filename> are in fact the same program); it
    should not be invoked directly this way.  The first form invokes
-   the server directly in interactive mode.  The primary use for this
+   the server directly in interactive single-user mode.  The primary use
-   mode is for bootstrapping by <xref linkend="app-initdb">.
+   for this mode is during bootstrapping by <xref linkend="app-initdb">.
+   Sometimes it is used for debugging or disaster recovery.
   </para>
 
   <para>
@@ -138,8 +141,8 @@ Postgres documentation
     <para>
      The options <option>-A</option>, <option>-B</option>,
      <option>-c</option>, <option>-d</option>, <option>-D</option>,
-     and <option>-F</option> have the same meaning as with the <xref
+     <option>-F</option>, and <option>--name</> have the same meanings as
-     linkend="app-postmaster">.
+     for the <xref linkend="app-postmaster">.
     </para>
 
     <variablelist>
@@ -163,12 +166,10 @@ Postgres documentation
        <para>
 	Sends all debugging and error output to 
 	<replaceable class="parameter">filename</replaceable>.
-	If the backend is running under the <application>postmaster</application>,
+	If the backend is running under the
-	error messages are still sent to the frontend process as well as to
+	<application>postmaster</application>, this option is ignored,
-	<replaceable class="parameter">filename</replaceable>,
+	and the stderr inherited from the
-	but debugging output is sent to the controlling tty of the
+	<application>postmaster</application> is used.
-	<application>postmaster</application>
-	(since only one file descriptor can be sent to an actual file).
        </para>
       </listitem>
      </varlistentry>
@@ -177,7 +178,7 @@ Postgres documentation
       <term>-P</term>
       <listitem>
        <para>
-	Ignore system indexes to scan/update system tuples. The
+	Ignore system indexes while scanning/updating system tuples. The
 	<command>REINDEX</command> command for system tables/indexes
 	requires this option to be used.
        </para>
@@ -350,6 +351,46 @@ Postgres documentation
   </refsect2>
  </refsect1>
 
+ <refsect1>
+  <title>Usage</title>
+
+   <para>
+    Start a standalone backend with a command like
+<screen>
+<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
+</screen>
+    Provide the correct path to the database area with <option>-D</>, or
+    make sure that the environment variable <envar>PGDATA</> is set.
+    Also specify the name of the particular database you want to work in.
+   </para>
+
+   <para>
+    Normally, the standalone backend treats newline as the command
+    entry terminator; there is no intelligence about semicolons,
+    as there is in <application>psql</>.  To continue a command
+    across multiple lines, you must type backslash just before each
+    newline except the last one.
+   </para>
+
+   <para>
+    But if you use the <option>-N</> command line switch, then newline does
+    not terminate command entry.  The backend will read stdin until EOF, then
+    process the input as a single query string.  Backslash-newline is not
+    treated specially in this case.
+   </para>
+
+   <para>
+    The standalone backend does not have readline input processing
+    (no command history, for example).
+   </para>
+
+   <para>
+    To quit the backend, type EOF (control-D, usually).  If you've
+    used <option>-N</>, two consecutive EOFs are needed to exit.
+   </para>
+
+ </refsect1>
+
  <refsect1>
   <title>See Also</title>
 

doc/src/sgml/ref/postmaster.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.22 2001/11/25 01:05:37 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.23 2001/11/25 01:11:36 tgl Exp $
 Postgres documentation
 -->
 
@@ -36,6 +36,7 @@ Postgres documentation
    <arg>-o <replaceable>extra-options</replaceable></arg>
    <arg>-p <replaceable>port</replaceable></arg>
    <arg>-S</arg>
+   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
    <group><arg>-n</arg><arg>-s</arg></group>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -115,12 +116,8 @@ Postgres documentation
         Sets a named run-time parameter. Consult the
         <citetitle>Administrator's Guide</citetitle> for a list and
         descriptions.  Most of the other command line options are in
-        fact short forms of such a parameter assignment.
+        fact short forms of such a parameter assignment.  <option>-c</>
-       </para>
+	can appear multiple times to set multiple parameters.
-
-       <para>
-        These options may also be specified using the GNU-style long option
-        format, <option>--name=value</option>.
        </para>
       </listitem>
      </varlistentry>
@@ -131,7 +128,8 @@ Postgres documentation
        <para>
         Sets the debug level.  The higher this value is set, the more
         debugging output is written to the server log.  The default is
-        0, which means no debugging.  Values up to 4 make sense.
+        0, which means no debugging.  Values up to 4 are useful; higher
+	numbers produce no additional output.
        </para>
       </listitem>
      </varlistentry>
@@ -151,8 +149,8 @@ Postgres documentation
       <listitem>
        <para>
         Disables <function>fsync</function> calls for performance
-        improvement at the risk of data corruption.  Read the detailed
+        improvement, at the risk of data corruption in event of a
-        documentation before using this!
+	system crash.  Read the detailed documentation before using this!
        </para>
       </listitem>
      </varlistentry>
@@ -209,10 +207,12 @@ Postgres documentation
        <para>
 	Sets the maximum number of client connections that this
 	<application>postmaster</application> will accept.  By
-	default, this value is 32, but it can be set as high as 1024
+	default, this value is 32, but it can be set as high as your
-	if your system will support that many processes.  (Note that
+	system will support.  (Note that
 	<option>-B</option> is required to be at least twice
-	<option>-N</option>.)
+	<option>-N</option>.  See the <citetitle>Administrator's
+	Guide</citetitle> for a discussion of system resource requirements
+	for large numbers of client connections.)
        </para>
       </listitem>
      </varlistentry>
@@ -267,6 +267,15 @@ Postgres documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+      <listitem>
+       <para>
+        Sets a named run-time parameter; a shorter form of <option>-c</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </para>
 
@@ -417,7 +426,7 @@ StreamServerPort: cannot bind to port
    or <literal>SIGQUIT</literal> can be used.  The first will wait for
    all clients to terminate before quitting, the second will
    forcefully disconnect all clients, and the third will quit
-   immediately without lengthy shutdown, resulting in a recovery run
+   immediately without proper shutdown, resulting in a recovery run
    during restart.
   </para>
 
@@ -458,6 +467,26 @@ StreamServerPort: cannot bind to port
 <prompt>$</prompt> <userinput>psql</userinput>
 </screen>
   </para>
+
+  <para>
+   Named runtime parameters can be set in either of these styles:
+<screen>
+<prompt>$</prompt> <userinput>postmaster -c sort_mem=1234</userinput>
+<prompt>$</prompt> <userinput>postmaster --sort-mem=1234</userinput>
+</screen>
+   Either form overrides whatever setting might exist for <literal>sort_mem</>
+   in <filename>postgresql.conf</>.  Notice that underscores in parameter
+   names can be written as either underscore or dash on the command line.
+  </para>
+
+  <tip>
+  <para>
+   Except for short-term experiments,
+   it's probably better practice to edit the setting in
+   <filename>postgresql.conf</> than to rely on a command-line switch
+   to set a parameter.
+  </para>
+  </tip>
  </refsect1>
 </refentry>
 

doc/src/sgml/ref/reindex.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.6 2001/11/25 00:18:48 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.7 2001/11/25 01:11:36 tgl Exp $
 Postgres documentation
 -->
 
@@ -183,8 +183,10 @@ REINDEX
     <listitem>
      <para>
       Be aware that the standalone backend treats newline as the command
-      entry terminator, not semicolon; you can't continue commands across
+      entry terminator; there is no intelligence about semicolons,
-      lines, as you can in <application>psql</>.
+      as there is in <application>psql</>.  To continue a command
+      across multiple lines, you must type backslash just before each
+      newline except the last one.
       Also, you won't have any of the conveniences of readline processing
       (no command history, for example).
      </para>