pingdb-doc.diff

diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
new file mode 100644
index df84054..01810ab
*** a/doc/src/sgml/ref/allfiles.sgml
--- b/doc/src/sgml/ref/allfiles.sgml
*************** Complete list of usable sgml source file
*** 178,183 ****
--- 178,184 ----
  <!ENTITY pgReceivexlog      SYSTEM "pg_receivexlog.sgml">
  <!ENTITY pgResetxlog        SYSTEM "pg_resetxlog.sgml">
  <!ENTITY pgRestore          SYSTEM "pg_restore.sgml">
+ <!ENTITY pingdb             SYSTEM "pingdb.sgml">
  <!ENTITY postgres           SYSTEM "postgres-ref.sgml">
  <!ENTITY postmaster         SYSTEM "postmaster.sgml">
  <!ENTITY psqlRef            SYSTEM "psql-ref.sgml">
diff --git a/doc/src/sgml/ref/pingdb.sgml b/doc/src/sgml/ref/pingdb.sgml
new file mode 100644
index ...0ce4d01
*** a/doc/src/sgml/ref/pingdb.sgml
--- b/doc/src/sgml/ref/pingdb.sgml
***************
*** 0 ****
--- 1,188 ----
+ <!--
+ doc/src/sgml/ref/pingdb.sgml
+ PostgreSQL documentation
+ -->
+ 
+ <refentry id="app-pingdb">
+  <refmeta>
+   <refentrytitle><application>pingdb</application></refentrytitle>
+   <manvolnum>1</manvolnum>
+   <refmiscinfo>Application</refmiscinfo>
+  </refmeta>
+ 
+  <refnamediv>
+   <refname>pingdb</refname>
+   <refpurpose>checks the connection status of a <productname>PostgreSQL</productname> server</refpurpose>
+  </refnamediv>
+ 
+  <indexterm zone="app-pingdb">
+   <primary>pingdb</primary>
+  </indexterm>
+ 
+  <refsynopsisdiv>
+   <cmdsynopsis>
+    <command>pingdb</command>
+    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
+    <arg rep="repeat"><replaceable>option</replaceable></arg>
+   </cmdsynopsis>
+  </refsynopsisdiv>
+ 
+ 
+  <refsect1 id="app-pingdb-description">
+   <title>Description</title>
+   <para>
+    <application>pingdb</application> is a utility for checking the connection
+    status of a <productname>PostgreSQL</productname> database server. The exit
+    status specifies the result of the connection check.
+   </para>
+  </refsect1>
+ 
+  <refsect1 id="app-pingdb-options">
+   <title>Options</title>
+ 
+     <variablelist>
+ 
+     <varlistentry>
+       <term><option>-d <replaceable class="parameter">dbname</replaceable></></term>
+       <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></></term>
+       <listitem>
+       <para>
+        Specifies the name of the database to connect to.
+       </para>
+       <para>
+        If this parameter contains an <symbol>=</symbol> sign or starts
+        with a valid <acronym>URI</acronym> prefix
+        (<literal>postgresql://</literal>
+        or <literal>postgres://</literal>), it is treated as a
+        <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
+       </para>
+       </listitem>
+     </varlistentry>
+ 
+      <varlistentry>
+        <term><option>-h <replaceable class="parameter">hostname</replaceable></></term>
+        <term><option>--host=<replaceable class="parameter">hostname</replaceable></></term>
+        <listitem>
+        <para>
+        Specifies the host name of the machine on which the
+        server is running. If the value begins
+        with a slash, it is used as the directory for the Unix-domain
+        socket.
+        </para>
+        </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
+        <term><option>-p <replaceable class="parameter">port</replaceable></></term>
+        <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
+        <listitem>
+        <para>
+        Specifies the TCP port or the local Unix-domain
+        socket file extension on which the server is listening for
+        connections. Defaults to the value of the <envar>PGPORT</envar>
+        environment variable or, if not set, to the port specified at
+        compile time, usually 5432.
+        </para>
+        </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
+        <term><option>-U <replaceable class="parameter">username</replaceable></></term>
+        <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
+        <listitem>
+        <para>
+        Connect to the database as the user <replaceable
+        class="parameter">username</replaceable> instead of the default.
+        </para>
+        </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
+       <term><option>-v</option></term>
+       <term><option>--verbose</option></term>
+       <listitem>
+        <para>
+         Enables verbose mode. Will output the result of the operation as well as the
+         connection parameters used.
+        </para>
+       </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
+       <term><option>-V</></term>
+       <term><option>--version</></term>
+        <listitem>
+         <para>
+          Print the <application>pingdb</application> version and exit.
+         </para>
+        </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
+       <term><option>-?</></term>
+       <term><option>--help</></term>
+       <listitem>
+        <para>
+         Show help about <application>pingdb</application> command line
+         arguments, and exit.
+        </para>
+       </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+ 
+  <refsect1>
+   <title>Exit Status</title>
+ 
+   <para>
+    <application>pingdb</application> returns 0 to the shell if the server
+    is accepting connections normally, 1 if the server is rejecting
+    connections (for example during startup), 2 if there was no response to the
+    connection attempt, and 3 if no attempt was made (for example due to invalid
+    parameters).
+   </para>
+  </refsect1>
+ 
+  <refsect1>
+   <title>Environment</title>
+ 
+   <para>
+    <command>pingdb</command>, like most other <productname>PostgreSQL</>
+    utilities,
+    also uses the environment variables supported by <application>libpq</>
+    (see <xref linkend="libpq-envars">).
+   </para>
+  </refsect1>
+ 
+  <refsect1 id="app-pingdb-notes">
+   <title>Notes</title>
+ 
+   <para>
+    The options <option>--dbname</> and <option>--username</> can be used to avoid gratuitous
+    error messages in the logs, but are not necessary for proper functionality.
+   </para>
+  </refsect1>
+ 
+  <refsect1 id="app-pingdb-examples">
+   <title>Examples</title>
+ 
+   <para>
+    Standard Usage:
+    <screen>
+     <prompt>$</prompt> <userinput>pingdb</userinput>
+     <prompt>$</prompt> <userinput>echo $?</userinput>
+     <computeroutput>0</computeroutput>
+    </screen>
+   </para>
+ 
+   <para>
+    To run in verbose mode with connection parameters:
+    <screen>
+     <prompt>$ </prompt><userinput>pingdb -v -h localhost</userinput>
+     <computeroutput>localhost:5432 - Accepting Connections</computeroutput>
+    </screen>
+   </para>
+ 
+  </refsect1>
+ 
+ </refentry>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
new file mode 100644
index 0872168..e0b6604
*** a/doc/src/sgml/reference.sgml
--- b/doc/src/sgml/reference.sgml
***************
*** 225,230 ****
--- 225,231 ----
     &pgDumpall;
     &pgReceivexlog;
     &pgRestore;
+    &pingdb;
     &psqlRef;
     &reindexdb;
     &vacuumdb;