pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedIncorrect 'literal' tags
4+ messages / 2 participants
[nested] [flat]
* Incorrect 'literal' tags
@ 2016-08-18 08:38 Alexander Law <exclusion@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Alexander Law @ 2016-08-18 08:38 UTC (permalink / raw)
To: pgsql-docs
Hello,
While translating docs I encountered an inconsistency with the
literal/replaceable Docbook tags.
I believe that the 'replaceable' tag should be used for keywords that
intended to be replaced with some values, but 'literal' is for literal
usage. But there are some places in the docs where 'literal' is used for
replaceable values. Patch attached.
Best regards,
Alexander
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments:
literal-replaceable.patch (text/x-patch, 3.2K) download
diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml
index fb3f32e..80c6f60 100644
--- a/doc/src/sgml/pgstandby.sgml
+++ b/doc/src/sgml/pgstandby.sgml
@@ -363,7 +363,7 @@ recovery_end_command = 'del C:\pgsql.trigger.5442'
The <literal>copy</> command on Windows sets the final file size
before the file is completely copied, which would ordinarily confuse
<application>pg_standby</application>. Therefore
- <application>pg_standby</application> waits <literal>sleeptime</>
+ <application>pg_standby</application> waits <replaceable>sleeptime</>
seconds once it sees the proper file size. GNUWin32's <literal>cp</>
sets the file size only after the file copy is complete.
</para>
diff --git a/doc/src/sgml/ref/pg_xlogdump.sgml b/doc/src/sgml/ref/pg_xlogdump.sgml
index 296f1ac..177caab 100644
--- a/doc/src/sgml/ref/pg_xlogdump.sgml
+++ b/doc/src/sgml/ref/pg_xlogdump.sgml
@@ -153,7 +153,7 @@ PostgreSQL documentation
<listitem>
<para>
Timeline from which to read log records. The default is to use the
- value in <literal>startseg</>, if that is specified; otherwise, the
+ value in <replaceable>startseg</>, if that is specified; otherwise, the
default is 1.
</para>
</listitem>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index f58da35..285608d 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -433,7 +433,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<term><option>--progress=</option><replaceable>sec</></term>
<listitem>
<para>
- Show progress report every <literal>sec</> seconds. The report
+ Show progress report every <replaceable>sec</> seconds. The report
includes the time since the beginning of the run, the tps since the
last report, and the transaction latency average and standard
deviation since the last report. Under throttling (<option>-R</>),
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index d9bce25..8a66ce7 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -830,7 +830,7 @@ testdb=>
<para>
Establishes a new connection to a <productname>PostgreSQL</>
server. The connection parameters to use can be specified either
- using a positional syntax, or using <literal>conninfo</> connection
+ using a positional syntax, or using <replaceable>conninfo</> connection
strings as detailed in <xref linkend="libpq-connstring">.
</para>
@@ -838,7 +838,7 @@ testdb=>
Where the command omits database name, user, host, or port, the new
connection can reuse values from the previous connection. By default,
values from the previous connection are reused except when processing
- a <literal>conninfo</> string. Passing a first argument
+ a <replaceable>conninfo</> string. Passing a first argument
of <literal>-reuse-previous=on</>
or <literal>-reuse-previous=off</literal> overrides that default.
When the command neither specifies nor reuses a particular parameter,
* Re: Incorrect 'literal' tags
@ 2016-08-23 16:45 Bruce Momjian <bruce@momjian.us>
parent: Alexander Law <exclusion@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Bruce Momjian @ 2016-08-23 16:45 UTC (permalink / raw)
To: Alexander Law <exclusion@gmail.com>; +Cc: pgsql-docs
On Thu, Aug 18, 2016 at 11:38:15AM +0300, Alexander Law wrote:
> Hello,
>
> While translating docs I encountered an inconsistency with the
> literal/replaceable Docbook tags.
>
> I believe that the 'replaceable' tag should be used for keywords that
> intended to be replaced with some values, but 'literal' is for literal
> usage. But there are some places in the docs where 'literal' is used for
> replaceable values. Patch attached.
Patch applied and backpatched to 9.6.
---------------------------------------------------------------------------
>
> Best regards,
> Alexander
>
> diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml
> index fb3f32e..80c6f60 100644
> --- a/doc/src/sgml/pgstandby.sgml
> +++ b/doc/src/sgml/pgstandby.sgml
> @@ -363,7 +363,7 @@ recovery_end_command = 'del C:\pgsql.trigger.5442'
> The <literal>copy</> command on Windows sets the final file size
> before the file is completely copied, which would ordinarily confuse
> <application>pg_standby</application>. Therefore
> - <application>pg_standby</application> waits <literal>sleeptime</>
> + <application>pg_standby</application> waits <replaceable>sleeptime</>
> seconds once it sees the proper file size. GNUWin32's <literal>cp</>
> sets the file size only after the file copy is complete.
> </para>
> diff --git a/doc/src/sgml/ref/pg_xlogdump.sgml b/doc/src/sgml/ref/pg_xlogdump.sgml
> index 296f1ac..177caab 100644
> --- a/doc/src/sgml/ref/pg_xlogdump.sgml
> +++ b/doc/src/sgml/ref/pg_xlogdump.sgml
> @@ -153,7 +153,7 @@ PostgreSQL documentation
> <listitem>
> <para>
> Timeline from which to read log records. The default is to use the
> - value in <literal>startseg</>, if that is specified; otherwise, the
> + value in <replaceable>startseg</>, if that is specified; otherwise, the
> default is 1.
> </para>
> </listitem>
> diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
> index f58da35..285608d 100644
> --- a/doc/src/sgml/ref/pgbench.sgml
> +++ b/doc/src/sgml/ref/pgbench.sgml
> @@ -433,7 +433,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
> <term><option>--progress=</option><replaceable>sec</></term>
> <listitem>
> <para>
> - Show progress report every <literal>sec</> seconds. The report
> + Show progress report every <replaceable>sec</> seconds. The report
> includes the time since the beginning of the run, the tps since the
> last report, and the transaction latency average and standard
> deviation since the last report. Under throttling (<option>-R</>),
> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
> index d9bce25..8a66ce7 100644
> --- a/doc/src/sgml/ref/psql-ref.sgml
> +++ b/doc/src/sgml/ref/psql-ref.sgml
> @@ -830,7 +830,7 @@ testdb=>
> <para>
> Establishes a new connection to a <productname>PostgreSQL</>
> server. The connection parameters to use can be specified either
> - using a positional syntax, or using <literal>conninfo</> connection
> + using a positional syntax, or using <replaceable>conninfo</> connection
> strings as detailed in <xref linkend="libpq-connstring">.
> </para>
>
> @@ -838,7 +838,7 @@ testdb=>
> Where the command omits database name, user, host, or port, the new
> connection can reuse values from the previous connection. By default,
> values from the previous connection are reused except when processing
> - a <literal>conninfo</> string. Passing a first argument
> + a <replaceable>conninfo</> string. Passing a first argument
> of <literal>-reuse-previous=on</>
> or <literal>-reuse-previous=off</literal> overrides that default.
> When the command neither specifies nor reuses a particular parameter,
>
> --
> Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Incorrect 'literal' tags
@ 2016-08-24 10:17 Alexander Law <exclusion@gmail.com>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 4+ messages in thread
From: Alexander Law @ 2016-08-24 10:17 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs
Hello,
>> I believe that the 'replaceable' tag should be used for keywords that
>> intended to be replaced with some values, but 'literal' is for literal
>> usage. But there are some places in the docs where 'literal' is used for
>> replaceable values. Patch attached.
> Patch applied and backpatched to 9.6.
Thanks!
I've found some more places where <literal> usage is incorrect. Patch attached.
Best regards,
Alexander
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments:
incorrect-literal-tags.patch (text/x-patch, 8.0K) download
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 5c8db97..4db9c81 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1227,8 +1227,8 @@ include_dir 'conf.d'
</para>
<para>
- If this is on, you should create users as <literal>username@dbname</>.
- When <literal>username</> is passed by a connecting client,
+ If this is on, you should create users as <replaceable>username@dbname</>.
+ When <replaceable>username</> is passed by a connecting client,
<literal>@</> and the database name are appended to the user
name and that database-specific user name is looked up by the
server. Note that when you create users with names containing
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6355300..5c1c4f6 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -13800,7 +13800,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
<entry>No</entry>
<entry>
multiple continuous percentile: returns an array of results matching
- the shape of the <literal>fractions</literal> parameter, with each
+ the shape of the <replaceable>fractions</replaceable> parameter, with each
non-null element replaced by the value corresponding to that percentile
</entry>
</row>
@@ -13845,7 +13845,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
<entry>No</entry>
<entry>
multiple discrete percentile: returns an array of results matching the
- shape of the <literal>fractions</literal> parameter, with each non-null
+ shape of the <replaceable>fractions</replaceable> parameter, with each non-null
element replaced by the input value corresponding to that percentile
</entry>
</row>
@@ -16850,7 +16850,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<para>
<function>pg_options_to_table</function> returns the set of storage
option name/value pairs
- (<literal>option_name</>/<literal>option_value</>) when passed
+ (<replaceable>option_name</>/<replaceable>option_value</>) when passed
<structname>pg_class</>.<structfield>reloptions</> or
<structname>pg_attribute</>.<structfield>attoptions</>.
</para>
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index c959146..62ae379 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -349,7 +349,7 @@ END;
<itemizedlist>
<listitem>
<para>
- The standard's <literal>AS <data type></literal> expression is not
+ The standard's <literal>AS <replaceable>data_type</></literal> expression is not
supported.
</para>
</listitem>
diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
index aff3792..a97ceab 100644
--- a/doc/src/sgml/ref/set_role.sgml
+++ b/doc/src/sgml/ref/set_role.sgml
@@ -127,7 +127,7 @@ SELECT SESSION_USER, CURRENT_USER;
<para>
<productname>PostgreSQL</productname>
- allows identifier syntax (<literal>"rolename"</literal>), while
+ allows identifier syntax (<literal>"<replaceable>rolename</>"</literal>), while
the SQL standard requires the role name to be written as a string
literal. SQL does not allow this command during a transaction;
<productname>PostgreSQL</productname> does not make this
diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml
index 4ac2128..96d279a 100644
--- a/doc/src/sgml/ref/set_session_auth.sgml
+++ b/doc/src/sgml/ref/set_session_auth.sgml
@@ -101,7 +101,7 @@ SELECT SESSION_USER, CURRENT_USER;
The SQL standard allows some other expressions to appear in place
of the literal <replaceable>user_name</replaceable>, but these options
are not important in practice. <productname>PostgreSQL</productname>
- allows identifier syntax (<literal>"username"</literal>), which SQL
+ allows identifier syntax (<literal>"<replaceable>username</>"</literal>), which SQL
does not. SQL does not allow this command during a transaction;
<productname>PostgreSQL</productname> does not make this
restriction because there is no reason to.
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index be5974a..5a70d7d 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -3622,10 +3622,10 @@ SELECT plainto_tsquery('supernovae stars');
</para>
<para>
- The optional parameter <literal>PATTERN</literal> can be the name of
+ The optional parameter <replaceable>PATTERN</replaceable> can be the name of
a text search object, optionally schema-qualified. If
- <literal>PATTERN</literal> is omitted then information about all
- visible objects will be displayed. <literal>PATTERN</literal> can be a
+ <replaceable>PATTERN</replaceable> is omitted then information about all
+ visible objects will be displayed. <replaceable>PATTERN</replaceable> can be a
regular expression and can provide <emphasis>separate</emphasis> patterns
for the schema and object names. The following examples illustrate this:
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index d8d2e9e..de6a466 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -204,8 +204,8 @@ SELECT clean_emp();
<para>
If an argument is of a composite type, then the dot notation,
- e.g., <literal>argname.fieldname</literal> or
- <literal>$1.fieldname</literal>, can be used to access attributes of the
+ e.g., <literal><replaceable>argname</>.<replaceable>fieldname</></literal> or
+ <literal>$1.<replaceable>fieldname</></literal>, can be used to access attributes of the
argument. Again, you might need to qualify the argument's name with the
function name to make the form with an argument name unambiguous.
</para>
@@ -527,7 +527,8 @@ LINE 1: SELECT new_emp().name;
Another option is to use
functional notation for extracting an attribute. The simple way
to explain this is that we can use the
- notations <literal>attribute(table)</> and <literal>table.attribute</>
+ notations <literal><replaceable>attribute</>(<replaceable>table</>)</>
+ and <literal><replaceable>table</>.<replaceable>attribute</></>
interchangeably.
<screen>
@@ -1305,12 +1306,15 @@ CREATE FUNCTION test(smallint, double precision) RETURNS ...
<para>
A function that takes a single argument of a composite type should
generally not have the same name as any attribute (field) of that type.
- Recall that <literal>attribute(table)</literal> is considered equivalent
- to <literal>table.attribute</literal>. In the case that there is an
+ Recall that <literal><replaceable>attribute</>(<replaceable>table</>)</literal>
+ is considered equivalent
+ to <literal><replaceable>table</>.<replaceable>attribute</></literal>.
+ In the case that there is an
ambiguity between a function on a composite type and an attribute of
the composite type, the attribute will always be used. It is possible
to override that choice by schema-qualifying the function name
- (that is, <literal>schema.func(table)</literal>) but it's better to
+ (that is, <literal><replaceable>schema</>.<replaceable>func</>(<replaceable>table</>)
+ </literal>) but it's better to
avoid the problem by not choosing conflicting names.
</para>
@@ -2818,7 +2822,7 @@ HeapTuple heap_form_tuple(TupleDesc tupdesc, Datum *values, bool *isnull)
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
</programlisting>
to build a <structname>HeapTuple</> given user data
- in C string form. <literal>values</literal> is an array of C strings,
+ in C string form. <parameter>values</parameter> is an array of C strings,
one for each attribute of the return row. Each C string should be in
the form expected by the input function of the attribute data
type. In order to return a null value for one of the attributes,
* Re: Incorrect 'literal' tags
@ 2016-08-25 01:12 Bruce Momjian <bruce@momjian.us>
parent: Alexander Law <exclusion@gmail.com>
0 siblings, 0 replies; 4+ messages in thread
From: Bruce Momjian @ 2016-08-25 01:12 UTC (permalink / raw)
To: Alexander Law <exclusion@gmail.com>; +Cc: pgsql-docs
On Wed, Aug 24, 2016 at 01:17:25PM +0300, Alexander Law wrote:
> Hello,
>
> >>I believe that the 'replaceable' tag should be used for keywords that
> >>intended to be replaced with some values, but 'literal' is for literal
> >>usage. But there are some places in the docs where 'literal' is used for
> >>replaceable values. Patch attached.
> >Patch applied and backpatched to 9.6.
>
> Thanks!
> I've found some more places where <literal> usage is incorrect. Patch attached.
Patch applied and backpatched to 9.6. Thanks.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2016-08-25 01:12 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2016-08-18 08:38 Incorrect 'literal' tags Alexander Law <exclusion@gmail.com>
2016-08-23 16:45 ` Bruce Momjian <bruce@momjian.us>
2016-08-24 10:17 ` Alexander Law <exclusion@gmail.com>
2016-08-25 01:12 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox