Re: little mistakes in HS/SR

Robert Haas wrote:
> On Thu, Jul 22, 2010 at 1:41 AM, Fujii Masao <masao.fujii@gmail.com> wrote:
> > We should enclose -1 with <literal> tag.
>
> A quick survey of the documentation as a whole suggests that we
> enclose -1 with <literal> in a few places but more commonly we don't.
> I have no position on whether we should do it or not, but maybe we
> should try to be consistent throughout the docs?  Or at least have a
> consistent rule for deciding what to do in a particular case?

Excellent question.  I went through the documentation and removed
<literal> tags where appropriate --- there are cases where we are
referencing an actual number, and there <literal> makes sense.  Applied
patch attached.

I think the larger question is whether we should say "zero" for 0 and
"one" for 1, etc.  Prose typography suggests we should, but for
technical manuals, I am not sure.  Ideas?

--
  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/advanced.sgml b/doc/src/sgml/advanced.sgml
index 9cb7173..11859b4 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -533,7 +533,7 @@ WHERE pos < 3;
 </programlisting>

     The above query only shows the rows from the inner query having
-    <literal>rank</> less than <literal>3</>.
+    <literal>rank</> less than 3.
    </para>

    <para>
diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index bb4657e..b3ecda5 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -259,7 +259,7 @@ SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';

   If any dimension is written as a slice, i.e., contains a colon, then all
   dimensions are treated as slices.  Any dimension that has only a single
-  number (no colon) is treated as being from <literal>1</>
+  number (no colon) is treated as being from 1
   to the number specified.  For example, <literal>[2]</> is treated as
   <literal>[1:2]</>, as in this example:

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index dcbb2c8..62830cb 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -835,8 +835,8 @@ SELECT pg_stop_backup();
     GNU <application>tar</> return an error code indistinguishable from
     a fatal error if a file was truncated while <application>tar</> was
     copying it.  Fortunately, GNU <application>tar</> versions 1.16 and
-    later exit with <literal>1</> if a file was changed during the backup,
-    and <literal>2</> for other errors.
+    later exit with 1 if a file was changed during the backup,
+    and 2 for other errors.
    </para>

    <para>
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 09152e6..eda82c5 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1455,7 +1455,7 @@
    return the cast destination type as their result type.  A cast
    function can have up to three arguments.  The second argument,
    if present, must be type <type>integer</>; it receives the type
-   modifier associated with the destination type, or <literal>-1</>
+   modifier associated with the destination type, or -1
    if there is none.  The third argument,
    if present, must be type <type>boolean</>; it receives <literal>true</>
    if the cast is an explicit cast, <literal>false</> otherwise.
@@ -6541,8 +6541,7 @@
        OID of the object within its system catalog, or null if the
        object is not a general database object.
        For advisory locks it is used to distinguish the two key
-       spaces (<literal>1</> for an int8 key, <literal>2</> for two
-       int4 keys).
+       spaces (1 for an int8 key, 2 for two int4 keys).
       </entry>
      </row>
      <row>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index a7bb2cd..a2c0494 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -921,7 +921,7 @@ omicron         bryanh                  guest1
       <term><literal>include_realm</literal></term>
       <listitem>
        <para>
-        If set to <literal>1</>, the realm name from the authenticated user
+        If set to 1, the realm name from the authenticated user
         principal is included in the system user name that's passed through
         user name mapping (<xref linkend="auth-username-maps">). This is
         useful for handling users from multiple realms.
@@ -992,7 +992,7 @@ omicron         bryanh                  guest1
       <term><literal>include_realm</literal></term>
       <listitem>
        <para>
-        If set to <literal>1</>, the realm name from the authenticated user
+        If set to 1, the realm name from the authenticated user
         principal is included in the system user name that's passed through
         user name mapping (<xref linkend="auth-username-maps">). This is
         useful for handling users from multiple realms.
@@ -1161,7 +1161,7 @@ omicron         bryanh                  guest1
       <term><literal>include_realm</literal></term>
       <listitem>
        <para>
-        If set to <literal>1</>, the realm name from the authenticated user
+        If set to 1, the realm name from the authenticated user
         principal is included in the system user name that's passed through
         user name mapping (<xref linkend="auth-username-maps">). This is
         useful for handling users from multiple realms.
@@ -1372,7 +1372,7 @@ omicron         bryanh                  guest1
       <term><literal>ldaptls</literal></term>
       <listitem>
        <para>
-        Set to <literal>1</> to make the connection between PostgreSQL and the
+        Set to 1 to make the connection between PostgreSQL and the
         LDAP server use TLS encryption. Note that this only encrypts
         the traffic to the LDAP server — the connection to the client
         will still be unencrypted unless SSL is used.
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 68c9462..d2a6445 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3709,7 +3709,7 @@ FROM pg_stat_activity;
         A value of zero logs all temporary file information, while positive
         values log only files whose size is greater than or equal to
         the specified number of kilobytes.  The
-        default setting is <literal>-1</>, which disables such logging.
+        default setting is -1, which disables such logging.
         Only superusers can change this setting.
        </para>
       </listitem>
@@ -4228,8 +4228,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       <listitem>
        <para>
         Specifies the cost delay value that will be used in automatic
-        <command>VACUUM</> operations.  If <literal>-1</> is
-        specified, the regular
+        <command>VACUUM</> operations.  If -1 is specified, the regular
         <xref linkend="guc-vacuum-cost-delay"> value will be used.
         The default value is 20 milliseconds.
         This parameter can only be set in the <filename>postgresql.conf</>
@@ -4248,7 +4247,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       <listitem>
        <para>
         Specifies the cost limit value that will be used in automatic
-        <command>VACUUM</> operations.  If <literal>-1</> is specified (which is the
+        <command>VACUUM</> operations.  If -1 is specified (which is the
         default), the regular
         <xref linkend="guc-vacuum-cost-limit"> value will be used.  Note that
         the value is distributed proportionally among the running autovacuum
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 28ee62a..2bbada0 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -3705,8 +3705,8 @@ substring('foobar' from 'o(.)b')   <lineannotation>o</lineannotation>
      match, the <replaceable>source</> string is returned with the
      <replaceable>replacement</> string substituted for the matching
      substring.  The <replaceable>replacement</> string can contain
-     <literal>\</><replaceable>n</>, where <replaceable>n</> is <literal>1</>
-     through <literal>9</>, to indicate that the source substring matching the
+     <literal>\</><replaceable>n</>, where <replaceable>n</> is 1
+     through 9, to indicate that the source substring matching the
      <replaceable>n</>'th parenthesized subexpression of the pattern should be
      inserted, and it can contain <literal>\&</> to indicate that the
      substring matching the entire pattern should be inserted.  Write
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 31db9ac..94d5ae8 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1913,7 +1913,7 @@ LOG:  database system is ready to accept read only connections
      advised to select a larger value of <varname>max_locks_per_transaction</>,
      perhaps as much as twice the value of the parameter on
      the primary server. You need not consider this at all if
-     your setting of <varname>max_prepared_transactions</> is <literal>0</>.
+     your setting of <varname>max_prepared_transactions</> is 0.
     </para>
    </listitem>
   </itemizedlist>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3824588..7131fb4 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5331,7 +5331,7 @@ int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
       function can only grow the tuples array one tuple at a time.  But any
       field of any existing tuple can be modified in any order.  If a value at
       <parameter>field_num</parameter> already exists, it will be overwritten.
-      If <parameter>len</parameter> is <literal>-1</literal> or
+      If <parameter>len</parameter> is -1 or
       <parameter>value</parameter> is <symbol>NULL</>, the field value
       will be set to an SQL null value.  The
       <parameter>value</parameter> is copied into the result's private storage,
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 5161c8c..4a989df 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2007,7 +2007,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    certificates of the certificate authorities (<acronym>CA</acronym>s)
    you trust in the file <filename>root.crt</filename> in the data
    directory, and set the <literal>clientcert</literal> parameter
-   to <literal>1</literal> on the appropriate <literal>hostssl</> line(s) in
+   to 1 on the appropriate <literal>hostssl</> line(s) in
    <filename>pg_hba.conf</>.
    A certificate will then be requested from the client during
    SSL connection startup.  (See <xref linkend="libpq-ssl"> for a
@@ -2025,7 +2025,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    The <literal>clientcert</literal> option in <filename>pg_hba.conf</> is
    available for all authentication methods, but only for rows specified as
    <literal>hostssl</>.  When <literal>clientcert</literal> is not specified
-   or is set to <literal>0</>, the server will still verify presented client
+   or is set to 0, the server will still verify presented client
    certificates against <filename>root.crt</filename> if that file exists
    — but it will not insist that a client certificate be presented.
   </para>
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index bb11680..fcee74f 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -1199,7 +1199,7 @@ int SPI_getargcount(SPIPlanPtr <parameter>plan</parameter>)
     The count of expected arguments for the <parameter>plan</parameter>.
     If the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
     <varname>SPI_result</varname> is set to <symbol>SPI_ERROR_ARGUMENT</symbol>
-    and <literal>-1</literal> is returned.
+    and -1 is returned.
   </para>
  </refsect1>
 </refentry>
diff --git a/doc/src/sgml/tsearch2.sgml b/doc/src/sgml/tsearch2.sgml
index c66459f..1933e2b 100644
--- a/doc/src/sgml/tsearch2.sgml
+++ b/doc/src/sgml/tsearch2.sgml
@@ -163,7 +163,7 @@
      due to failure to recreate the original <application>tsearch2</>
      objects.  These errors can be ignored, but this means you cannot
      restore the dump in a single transaction (eg, you cannot use
-     <application>pg_restore</>'s <literal>-1</> switch).
+     <application>pg_restore</>'s <option>-1</> switch).
     </para>
    </step>