diff --git a/doc/user/client-reference.xml b/doc/user/client-reference.xml
index c95879354124e9fcc86943a2cdbdb2be235f937a..bf5b996f9cf1c9bd6ccf9764d54222c3a17c94e8 100644
--- a/doc/user/client-reference.xml
+++ b/doc/user/client-reference.xml
@@ -35,7 +35,7 @@ Option is one of the following (in alphabetical order by the long form of the op
Syntax: short form: <code>-a <replaceable>port-number</replaceable></code>
long form: <code>--a[dmin-port] [=] <replaceable>port-number</replaceable></code>.
Effect: Client will look for the server on the port designated by port-number.
- Notes: The administrative port is normally set to 33015 in the server configuration file.
+ Notes: This is the <quote>administrative</quote> port. The default value is 33015.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -56,7 +56,7 @@ Option is one of the following (in alphabetical order by the long form of the op
long form: <code>--c[at] <replaceable>file-name</replaceable></code>.
Effect: Client will print the contents of the write-ahead log or snapshot designated by file-name.
Example: <code>--cat /tarantool_user/work_dir/00000000000000000018.xlog</code>
- Notes: The client stops after displaying the contents.
+ Notes: The client stops after displaying the contents. There is also a way to use --cat for Lua statements.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -88,7 +88,7 @@ Option is one of the following (in alphabetical order by the long form of the op
long form: <code>--fr[om] <replaceable>log-sequence-number</replaceable></code>.
Effect: Play only what has a a log sequence number greater than or equal to log-sequence-number.
Example: <code>--from 55</code>
- Notes: see also --play and --to.
+ Notes: See also --play and --to.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -98,13 +98,13 @@ Option is one of the following (in alphabetical order by the long form of the op
long form: <code>--hea[der]</code>.
Effect: Add a header if --format=raw.
Example: <code>--header</code>
- Notes: the default is 'no header'.
+ Notes: The default is 'no header'.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-help" xreflabel="client-reference-help">--help</term>
<listitem><para>
- Syntax: short form: (none)
+ Syntax: short form: <code>-?</code>
long form: <code>--hel[p]</code>.
Effect: Client displays a help message including a list of options.
Example: <code>--help</code>
@@ -118,7 +118,7 @@ Option is one of the following (in alphabetical order by the long form of the op
long form: <code>--ho[st] [=] <replaceable>host-name</replaceable></code>.
Effect: Client will look for the server on the computer designated by host-name.
Example: <code>--host = 127.0.0.1</code>
- Notes: default value is localhost.
+ Notes: The default value is localhost.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -137,7 +137,7 @@ Option is one of the following (in alphabetical order by the long form of the op
long form: <code>--po[rt] [=] <replaceable>port-number</replaceable></code>.
Effect: Client will look for the server on the port designated by port-number.
Example: <code>--port = 33013</code>
- Notes: default value is 33013.
+ Notes: This is the <quote>read/write data</quote> port. The default value is 33013.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -165,13 +165,13 @@ Option is one of the following (in alphabetical order by the long form of the op
long form: <code>--t[o] <replaceable>log-sequence-number</replaceable></code>.
Effect: Play only what has a log sequence number less than or equal to log-sequence-number.
Example: <code>--to 66</code>
- Notes: see also --play and --from.
+ Notes: See also --play and --from.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-version" xreflabel="client-reference-version">--version</term>
<listitem><para>
- Syntax: short form: <code>-v</code>
+ Syntax: short form: <code>-V</code>
long form: <code>--v[ersion]</code>.
Effect: Client displays version information.
Example: <code>--version</code>
@@ -231,9 +231,10 @@ a newline (line feed).
<varlistentry>
<term xml:id="client-reference-call" xreflabel="client-reference-call">CALL</term>
<listitem><para>
- Syntax: <code>CALL <replaceable>procedure-identifier</replaceable> ()</code>.
+ Syntax: <code>CALL <replaceable>procedure-identifier</replaceable> ()</code>.
Effect: The client tells the server to execute the procedure identified by procedure-identifier.
Example: <code>CALL proc50()</code>.
+ Notes: The client sends to the server's read/write data port.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -242,7 +243,7 @@ a newline (line feed).
Syntax: <code>DELETE FROM <replaceable>tuple-set-name</replaceable> WHERE <replaceable>field-name</replaceable> = <replaceable>literal</replaceable></code>.
Effect: Client tells server to delete the tuple identified by the WHERE clause.
Example: <code>DELETE FROM t0 WHERE k0='a'</code>.
- Notes: field-name must identify the primary key.
+ Notes: field-name must identify the primary key. The client sends to the server's read/write data port after converting from SQL to binary protocol.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -251,7 +252,7 @@ a newline (line feed).
Syntax: <code>E[XIT]</code>.
Effect: The tarantool program stops.
Example: <code>EXIT</code>.
- Notes: same as QUIT.
+ Notes: The QUIT statement does the same thing. The client sends nothing to the server.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -260,14 +261,16 @@ a newline (line feed).
Syntax: <code>H[ELP]</code>.
Effect: Client displays a message including a list of possible statements.
Example: <code>HELP</code>.
+ Notes: The client sends nothing to the server.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-insert" xreflabel="client-reference-insert">INSERT</term>
<listitem><para>
Syntax: <code>INSERT [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
- Effect: Client tells server to add the tuple consisting of the literal values.
+ Effect: The client tells the server to add the tuple consisting of the literal values.
Example: <code>INSERT INTO t0 VALUES ('a',0)</code>.
+ Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -282,40 +285,43 @@ a newline (line feed).
<term xml:id="client-reference-lua" xreflabel="client-reference-lua">LUA</term>
<listitem><para>
Syntax: <code>LUA <replaceable>token</replaceable> [<replaceable>token</replaceable>...]</code>.
- Effect: Client tells server to execute the tokens as Lua statements.
+ Effect: The client tells the server to execute the tokens as Lua statements.
Example: <code>LUA "hello".." world"</code>.
+ Notes: The client sends to the server's read/write data port.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-notee" xreflabel="client-reference-notee">NOTEE</term>
<listitem><para>
Syntax: <code>NOTEE</code>.
- Effect: Client ceases to write to a file, thus canceling the effect of the TEE statement.
+ Effect: The client ceases to write to a file, thus canceling the effect of the TEE statement.
Example: <code>NOTEE</code>.
+ Notes: The client sends nothing to the server.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-ping" xreflabel="client-reference-ping">PING</term>
<listitem><para>
Syntax: <code>PING</code>.
- Effect: Client sends a ping to the server.
+ Effect: The client sends a ping to the server.
Example: <code>PING</code>.
+ Notes: The client sends to the server's read/write data port.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-quit" xreflabel="client-reference-quit">QUIT</term>
<listitem><para>
Syntax: <code>Q[UIT]</code>.
- Effect: The client stops.
+ Effect: The client stops. This statement is handled entirely by the client.
Example: <code>QUIT</code>.
- Notes: same as EXIT.
+ Notes: The EXIT statement does the same thing. The client sends nothing to the server.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-reload" xreflabel="client-reference-reload">RELOAD</term>
<listitem><para>
Syntax: <code>RELOAD CONFIGURATION</code>.
- Effect: Client tells server to re-read the configuration file.
+ Effect: The client tells the server to re-read the configuration file.
Example: <code>RELOAD CONFIGURATION</code>.
Notes: The client sends to the server's administrative port.
</para></listitem>
@@ -324,16 +330,17 @@ a newline (line feed).
<term xml:id="client-reference-replace" xreflabel="client-reference-replace">REPLACE</term>
<listitem><para>
Syntax; <code>REPLACE [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
- Effect: Client tells server to add the tuple consisting of the literal values.
+ Effect: The client tells the server to add the tuple consisting of the literal values.
Example: <code>REPLACE INTO t0 VALUES ('a',0)</code>.
Notes: REPLACE and INSERT are the same, except that INSERT will return an error if a tuple already exists with the same primary key.
+ The client sends to the server's read/write data port after converting from SQL to binary protocol.
</para></listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-save" xreflabel="client-reference-save">SAVE</term>
<listitem><para>
Syntax: <code>SAVE COREDUMP | SNAPSHOT</code>.
- Effect: Client tells server to save the designated object.
+ Effect: The client tells the server to save the designated object.
Example: <code>SAVE SNAPSHOT</code>.
Notes: The client sends to the server's administrative port.
</para></listitem>
@@ -344,6 +351,7 @@ a newline (line feed).
Syntax: <code>SELECT * FROM <replaceable>tuple-set-identifier</replaceable> WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [AND|OR <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] [LIMIT <replaceable>numeric-literal</replaceable> [,<replaceable>numeric-literal</replaceable>]</code>].
Effect: Client tells server to find the tuple or tuples identified in the WHERE clause.
Example: <code>SELECT * FROM t0 WHERE k0 = 5 AND k1 = 7 LIMIT 1</code>.
+ Notes: The client sends to the server's read/write data port.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -361,7 +369,18 @@ a newline (line feed).
The string must be a value in single quotes.
Effect: string becomes end-of-statement delimiter, so newline alone is not treated as end of statement.
Example: <code>SETOPT DELIMITER = '!'</code>.
- </para></listitem>
+ Notes: The client sends nothing to the server.
+ </para>
+ <para>
+ Syntax: <code>SETOPT PAGER = <replaceable>string-literal</replaceable></code>.
+ The string must be a value in single quotes.
+ Effect: string becomes the pager that will be invoked for subsequent commands;
+ usually the values are '/usr/bin/less' or '/bin/more' for the common
+ Linux pagers.
+ Example: <code>SETOPT PAGER = '/usr/bin/less'</code>.
+ Notes: The client sends nothing to the server.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
<term xml:id="client-reference-show" xreflabel="client-reference-show">SHOW</term>
@@ -369,7 +388,7 @@ a newline (line feed).
Syntax: <code>SHOW CONFIGURATION | FIBER | INFO | INJECTIONS | PALLOC | PLUGINS | SLAB | STAT</code>.
Effect: The client asks the server for information about environment or statistics.
Example: <code>SHOW INFO</code>.
- Notes: The client sends to the administrative port.
+ Notes: The client sends to the server's administrative port.
SHOW INJECTIONS is only available in debug mode.
</para></listitem>
</varlistentry>
@@ -379,7 +398,7 @@ a newline (line feed).
Syntax: <code>TEE <replaceable>string-literal</replaceable></code>.
Effect: The client begins logging in the file identified by string-literal.
Example: <code>TEE '/home/tarantool_user/log.txt'</code>.
- Notes: TEE may also be set up via an option on the command line.
+ Notes: TEE may also be set up via an option on the command line. The client sends nothing to the server.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -388,6 +407,7 @@ a newline (line feed).
Syntax: <code>UPDATE <replaceable>tuple-set-identifier</replaceable> SET <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [,<replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable></code>.
Effect: Client tells server to change the tuple identified in the WHERE clause.
Example: <code>UPDATE t1 SET k1= 'K', k2 = 7 WHERE k0 = 0</code>.
+ Notes: The client sends to the server's read/write data port after converting from SQL to binary protocol.
</para></listitem>
</varlistentry>
</variablelist>
@@ -399,6 +419,62 @@ For a condensed Backus-Naur Form [BNF] description of some of the statements, se
<link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
</para>
+<para>
+<bridgehead renderas="sect4">Modes</bridgehead>
+Depending how one combines the tarantool client's options, there are in effect three modes of operation:
+<quote>interactive</quote>, <quote>print and play</quote>, or <quote>replication</quote> mode.
+</para>
+<para>
+In <emphasis>interactive</emphasis> mode, one types statements and gets results.
+One can specify a statement file when starting
+(<code>tarantool < file_name</code>)
+or one can specify a statement file with the LOADFILE statement:
+(<code>LOADFILE file_name</code>), but typically the statements
+are typed in by the user following prompts.
+Here is an example of an interactive-mode tarantool client session:
+
+<programlisting>
+<prompt>$ </prompt>tarantool
+localhost> <userinput>INSERT INTO t0 VALUES ('X-1',100)</userinput>
+Insert OK, 1 rows affected
+localhost> <userinput>INSERT INTO t0 VALUES ('X-2',200,'On Order')</userinput>
+Insert OK, 1 rows affected
+localhost> <userinput>INSERT INTO t0 VALUES ('X-3',300,'')</userinput>
+Insert OK, 1 rows affected
+localhost> <userinput>UPDATE t0 SET k1 = 300 WHERE k0 = 'X-1'</userinput>
+Update OK, 1 rows affected
+localhost> <userinput>DELETE FROM t0 WHERE k0 = 'X-2'</userinput>
+Delete OK, 1 rows affected
+localhost> <userinput>SELECT * FROM t0 WHERE k0 = 'X-1'</userinput>
+Select OK, 1 rows affected
+['X-1', 300]
+localhost> <userinput>EXIT</userinput>
+<prompt>$ </prompt>
+</programlisting>
+
+</para>
+<para>
+In <emphasis>print and play</emphasis> mode,
+one uses --cat and --play and --from and --to and --space options
+to print write-ahead-log contents, or to send write-ahead-log
+contents to the server.
+Here is an example of a print-and-play-mode tarantool client session:
+<programlisting>
+<prompt>$ </prompt>tarantool --cat /home/user1/tarantool_test/work_dir/00000000000000000005.xlog --from 22 --to 26
+Insert, lsn: 22, time: 1385327353.345869, len: 33, space: 0, cookie: 127.0.0.1:44787 ['X-1', 100]
+Insert, lsn: 23, time: 1385327353.346745, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-2', 200, 8243105135088135759]
+Insert, lsn: 24, time: 1385327353.347352, len: 34, space: 0, cookie: 127.0.0.1:44787 ['X-3', 300, '']
+Update, lsn: 25, time: 1385327353.348209, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-1']
+Delete, lsn: 26, time: 1385327353.348879, len: 28, space: 0, cookie: 127.0.0.1:44787 ['X-2']
+<prompt>$ </prompt>
+</programlisting>
+</para>
+<para>
+In <emphasis>replication</emphasis> mode,
+one connects as a replica, and then writes
+a binary log to a file.
+</para>
+
</appendix>
<!--