From fafc6f716ade3527643015b04b6b7ebf182bd004 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 20 Dec 2020 13:37:25 -0500
Subject: [PATCH] Doc: improve description of pgbench script weights.

Point out the workaround to be used if you want to write a script
file name that includes "@".  Clean up the text a little.

Fabien Coelho, additional wordsmithing by me

Discussion: https://postgr.es/m/1c4e81550d214741827a03292222db8d@G08CNEXMBPEKD06.g08.fujitsu.local
---
 doc/src/sgml/ref/pgbench.sgml | 44 +++++++++++++++++++++--------------
 1 file changed, 27 insertions(+), 17 deletions(-)

diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index a0eeb71baca..49acb8ad37d 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -269,15 +269,19 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
       <term><option>--builtin</>=<replaceable>scriptname[@weight]</></term>
       <listitem>
        <para>
-        Add the specified built-in script to the list of executed scripts.
-        An optional integer weight after <literal>@</> allows to adjust the
-        probability of drawing the script.  If not specified, it is set to 1.
-        Available built-in scripts are: <literal>tpcb-like</>,
-        <literal>simple-update</> and <literal>select-only</>.
+        Add the specified built-in script to the list of scripts to be executed.
+        Available built-in scripts are: <literal>tpcb-like</literal>,
+        <literal>simple-update</literal> and <literal>select-only</literal>.
         Unambiguous prefixes of built-in names are accepted.
-        With special name <literal>list</>, show the list of built-in scripts
+        With the special name <literal>list</literal>, show the list of built-in scripts
         and exit immediately.
        </para>
+       <para>
+        Optionally, write an integer weight after <literal>@</literal> to
+        adjust the probability of selecting this script versus other ones.
+        The default weight is 1.
+        See below for details.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -331,10 +335,16 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
       <term><option>--file=</><replaceable>filename[@weight]</></term>
       <listitem>
        <para>
-        Add a transaction script read from <replaceable>filename</> to
-        the list of executed scripts.
-        An optional integer weight after <literal>@</> allows to adjust the
-        probability of drawing the test.
+        Add a transaction script read from <replaceable>filename</replaceable>
+        to the list of scripts to be executed.
+       </para>
+       <para>
+        Optionally, write an integer weight after <literal>@</literal> to
+        adjust the probability of selecting this script versus other ones.
+        The default weight is 1.
+        (To use a script file name that includes an <literal>@</literal>
+        character, append a weight so that there is no ambiguity, for
+        example <literal>filen@me@1</literal>.)
         See below for details.
        </para>
       </listitem>
@@ -700,14 +710,14 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
   <title>What is the <quote>Transaction</> Actually Performed in <application>pgbench</application>?</title>
 
   <para>
-   <application>pgbench</> executes test scripts chosen randomly
+   <application>pgbench</application> executes test scripts chosen randomly
    from a specified list.
-   They include built-in scripts with <option>-b</> and
-   user-provided custom scripts with <option>-f</>.
-   Each script may be given a relative weight specified after a
-   <literal>@</> so as to change its drawing probability.
-   The default weight is <literal>1</>.
-   Scripts with a weight of <literal>0</> are ignored.
+   The scripts may include built-in scripts specified with <option>-b</option>
+   and user-provided scripts specified with <option>-f</option>.
+   Each script may be given a relative weight specified after an
+   <literal>@</literal> so as to change its selection probability.
+   The default weight is <literal>1</literal>.
+   Scripts with a weight of <literal>0</literal> are ignored.
  </para>
 
   <para>