From 1aaf532deabfa356c99abc80fc78d988ad1f1355 Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Tue, 28 Aug 2018 21:33:32 +0900
Subject: Rework option set of oid2name

oid2name has done little effort to keep an interface consistent with
other binary utilities:
- -H was used instead of -h/-host.  This option is now marked as
deprecated, still its output is accepted to be backward-compatible.
- -P has been removed from the code, and was still documented.
- All options gain long aliases, making connection options more similar
to other binaries.
- Document environment variables which could be used: PGHOST, PGPORT and
PGUSER.

A basic set of TAP tests is added on the way, and documentation is
cleaned up to be more consistent with other things.

Author: Tatsuro Yamada
Reviewed-by: Michael Paquier
Discussion: https://postgr.es/m/c7e7f25c-1747-cd0f-9335-390bc97b2db5@lab.ntt.co.jp
---
 doc/src/sgml/oid2name.sgml | 81 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 59 insertions(+), 22 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/oid2name.sgml b/doc/src/sgml/oid2name.sgml
index dd875281c81..c7ebd61c6bf 100644
--- a/doc/src/sgml/oid2name.sgml
+++ b/doc/src/sgml/oid2name.sgml
@@ -60,41 +60,48 @@
    <variablelist>
 
     <varlistentry>
-     <term><option>-f</option> <replaceable>filenode</replaceable></term>
-     <listitem><para>show info for table with filenode <replaceable>filenode</replaceable></para></listitem>
+     <term><option>-f <replaceable class="parameter">filenode</replaceable></option></term>
+     <term><option>--filenode=<replaceable class="parameter">filenode</replaceable></option></term>
+     <listitem><para>show info for table with filenode <replaceable>filenode</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-i</option></term>
-     <listitem><para>include indexes and sequences in the listing</para></listitem>
+     <term><option>--indexes</option></term>
+     <listitem><para>include indexes and sequences in the listing.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-o</option> <replaceable>oid</replaceable></term>
-     <listitem><para>show info for table with OID <replaceable>oid</replaceable></para></listitem>
+     <term><option>-o <replaceable class="parameter">oid</replaceable></option></term>
+     <term><option>--oid=<replaceable class="parameter">oid</replaceable></option></term>
+     <listitem><para>show info for table with OID <replaceable>oid</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-q</option></term>
-     <listitem><para>omit headers (useful for scripting)</para></listitem>
+     <term><option>--quiet</option></term>
+     <listitem><para>omit headers (useful for scripting).</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-s</option></term>
-     <listitem><para>show tablespace OIDs</para></listitem>
+     <term><option>--tablespaces</option></term>
+     <listitem><para>show tablespace OIDs.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-S</option></term>
+     <term><option>--system-objects</option></term>
      <listitem><para>include system objects (those in
       <option>information_schema</option>, <option>pg_toast</option>
-      and <option>pg_catalog</option> schemas)
+      and <option>pg_catalog</option> schemas).
      </para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-t</option> <replaceable>tablename_pattern</replaceable></term>
-     <listitem><para>show info for table(s) matching <replaceable>tablename_pattern</replaceable></para></listitem>
+     <term><option>-t <replaceable class="parameter">tablename_pattern</replaceable></option></term>
+     <term><option>--table=<replaceable class="parameter">tablename_pattern</replaceable></option></term>
+     <listitem><para>show info for table(s) matching <replaceable class="parameter">tablename_pattern</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
@@ -109,8 +116,9 @@
 
     <varlistentry>
      <term><option>-x</option></term>
+     <term><option>--extended</option></term>
      <listitem><para>display more information about each object shown: tablespace name,
-      schema name, and OID
+      schema name, and OID.
      </para></listitem>
     </varlistentry>
 
@@ -133,29 +141,34 @@
 
    <variablelist>
     <varlistentry>
-     <term><option>-d</option> <replaceable>database</replaceable></term>
-     <listitem><para>database to connect to</para></listitem>
+     <term><option>-d <replaceable class="parameter">database</replaceable></option></term>
+     <term><option>--dbname=<replaceable class="parameter">database</replaceable></option></term>
+     <listitem><para>database to connect to.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-H</option> <replaceable>host</replaceable></term>
-     <listitem><para>database server's host</para></listitem>
+     <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
+     <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
+     <listitem><para>database server's host.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-p</option> <replaceable>port</replaceable></term>
-     <listitem><para>database server's port</para></listitem>
+     <term><option>-H <replaceable class="parameter">host</replaceable></option></term>
+     <listitem><para>database server's host.  Use of this parameter is
+     <emphasis>deprecated</emphasis> as of
+     <productname>PostgreSQL</productname> 12.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-U</option> <replaceable>username</replaceable></term>
-     <listitem><para>user name to connect as</para></listitem>
+     <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
+     <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
+     <listitem><para>database server's port.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-P</option> <replaceable>password</replaceable></term>
-     <listitem><para>password (deprecated &mdash; putting this on the command line
-      is a security hazard)</para></listitem>
+     <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
+     <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
+     <listitem><para>user name to connect as.</para></listitem>
     </varlistentry>
 
    </variablelist>
@@ -188,6 +201,30 @@
   </para>
  </refsect1>
 
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   This utility, like most other <productname>PostgreSQL</productname>
+   utilities, also uses the environment variables supported by
+   <application>libpq</application> (see <xref linkend="libpq-envars"/>).
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Notes</title>
 
-- 
cgit v1.2.3