Robert Haas wrote:
> On Thu, Jul 22, 2010 at 1:41 AM, Fujii Masao <masao.fu...@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 <br...@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>
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
