From d37714eb11d2043fec88143394829fe0e722910a Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Thu, 30 Jul 2015 16:13:06 -0600
Subject: [PATCH] document placeholders in log.* api
---
doc/sphinx/reference/fun.rst | 20 +++--
doc/sphinx/reference/log.rst | 33 ++++----
doc/sphinx/reference/socket.rst | 128 +++++++++++++++-----------------
3 files changed, 85 insertions(+), 96 deletions(-)
diff --git a/doc/sphinx/reference/fun.rst b/doc/sphinx/reference/fun.rst
index 6fbbd21b6f..b51e968bd8 100644
--- a/doc/sphinx/reference/fun.rst
+++ b/doc/sphinx/reference/fun.rst
@@ -16,20 +16,18 @@ Standard ML, Haskell, or Erlang.
The full documentation is `On the luafun section of github`_.
However, the first chapter can be skipped because installation
-is already done, it's inside Tarantool. All that is needed is the usual require request.
+is already done, it's inside Tarantool. All that is needed is the usual :code:`require` request.
After that, all the operations described in the
Lua fun manual will work, provided they are preceded by the
-name returned by the require request.
+name returned by the :code:`require` request.
For example:
-.. code-block:: lua
-
- localhost> fun = require('fun')
- localhost> for _k, a in fun.range(3) do print(a) end
- 1
- 2
- 3
- ---
- ...
+ | :codenormal:`tarantool>` :codebold:`fun = require('fun')`
+ | :codenormal:`tarantool>` :codebold:`for _k, a in fun.range(3) do print(a) end`
+ | :codenormal:`1`
+ | :codenormal:`2`
+ | :codenormal:`3`
+ | :codenormal:`---`
+ | :codenormal:`...`
.. _On the luafun section of github: http://rtsisyk.github.io/luafun
diff --git a/doc/sphinx/reference/log.rst b/doc/sphinx/reference/log.rst
index 6ce6e77b95..52cf0ee005 100644
--- a/doc/sphinx/reference/log.rst
+++ b/doc/sphinx/reference/log.rst
@@ -23,6 +23,9 @@ system-generated by the server's internal code, or user-generated with the
``log_level_function_name``, and ``message``.
Output will not occur if ``log_level_function_name``
is for a type greater than :ref:`log_level <logger>`.
+ Messages may contain C-style format specifiers
+ %d or %s, so :samp:`log.error('...%d...%s',{x},{y})`
+ will work if x is a number and y is a string.
:return: nil
.. function:: logger_pid()
@@ -33,26 +36,22 @@ system-generated by the server's internal code, or user-generated with the
Example
=================================================
-.. code-block:: lua
-
- #From the shell:
- #Start the server, do some requests, exit, and display the log, thus:
- $ ~/tarantool/src/tarantool
- tarantool> box.cfg{log_level=3, logger='tarantool.txt'}
- tarantool> log = require('log')
- tarantool> log.error('Error')
- tarantool> log.info('Info')
- tarantool> os.exit()
- $ less tarantool.txt
+ | :codebold:`#From the shell:`
+ | :codebold:`#Start the server, do some requests, exit, and display the log, thus:`
+ | :codenormal:`$` :codebold:`~/tarantool/src/tarantool`
+ | :codenormal:`tarantool>` :codebold:`box.cfg{log_level=3, logger='tarantool.txt'}`
+ | :codenormal:`tarantool>` :codebold:`log = require('log')`
+ | :codenormal:`tarantool>` :codebold:`log.error('Error')`
+ | :codenormal:`tarantool>` :codebold:`log.info('Info %s', box.info.version)`
+ | :codenormal:`tarantool>` :codebold:`os.exit()`
+ | :codenormal:`$` :codebold:`less tarantool.txt`
The output from the less command will look approximately like this:
-.. code-block:: lua
-
- 2...0 [5257] main/101/interactive C> version 1.6.3-355-ga4f762d
- 2...1 [5257] main/101/interactive C> log level 3
- 2...1 [5261] main/101/spawner C> initialized
- 2...0 [5257] main/101/interactive [C]:-1 E> Error
+ | :codenormal:`2...0 [5257] main/101/interactive C> version 1.6.3-355-ga4f762d`
+ | :codenormal:`2...1 [5257] main/101/interactive C> log level 3`
+ | :codenormal:`2...1 [5261] main/101/spawner C> initialized`
+ | :codenormal:`2...0 [5257] main/101/interactive [C]:-1 E> Error`
The 'Error' line is visible in tarantool.txt preceded by the letter E.
The 'Info' line is not present because the log_level is 3.
diff --git a/doc/sphinx/reference/socket.rst b/doc/sphinx/reference/socket.rst
index d6ae0dbcec..9ad7f28849 100644
--- a/doc/sphinx/reference/socket.rst
+++ b/doc/sphinx/reference/socket.rst
@@ -115,11 +115,8 @@ the function invocations will look like ``sock:function_name(...)``.
:return: A table containing these fields: "host", "family", "type", "protocol", "port".
:rtype: table
- .. code-block:: lua
-
- tarantool> socket.getaddrinfo('tarantool.org', 'http')
-
- will return variable information such as
+ | :codenormal:`tarantool>` :codebold:`socket.getaddrinfo('tarantool.org', 'http')`
+ | will return variable information such as
.. code-block:: yaml
@@ -430,35 +427,32 @@ server and tarantool.org, then an HTTP "head" message is sent, and a response
is received: "``HTTP/1.1 200 OK``". This is not a useful way to communicate
with this particular site, but shows that the system works.
-
-.. code-block:: lua
-
- tarantool> socket = require('socket')
- ---
- ...
- tarantool> sock = socket.tcp_connect('tarantool.org', 80)
- ---
- ...
- tarantool> type(sock)
- ---
- - table
- ...
- tarantool> sock:error()
- ---
- - null
- ...
- tarantool> sock:send("HEAD / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")
- ---
- - true
- ...
- tarantool> sock:read(17)
- ---
- - "HTTP/1.1 200 OK\r\n"
- ...
- tarantool> sock:close()
- ---
- - true
- ...
+ | :codenormal:`tarantool>` :codebold:`socket = require('socket')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock = socket.tcp_connect('tarantool.org', 80)`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`type(sock)`
+ | :codenormal:`---`
+ | :codenormal:`- table`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock:error()`
+ | :codenormal:`---`
+ | :codenormal:`- null`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock:send("HEAD / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock:read(17)`
+ | :codenormal:`---`
+ | :codenormal:`- "HTTP/1.1 200 OK\r\n"`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock:close()`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use of a UDP socket on localhost
@@ -470,40 +464,38 @@ to ``sock_1``. Using ``sock_1``, receive a message. Display the received
message. Close both connections. |br| This is not a useful way for a
computer to communicate with itself, but shows that the system works.
-.. code-block:: lua
-
- tarantool> socket = require('socket')
- ---
- ...
- tarantool> sock_1 = socket('AF_INET', 'SOCK_DGRAM', 'udp')
- ---
- ...
- tarantool> sock_1:bind('127.0.0.1')
- ---
- - true
- ...
- tarantool> sock_2 = socket('AF_INET', 'SOCK_DGRAM', 'udp')
- ---
- ...
- tarantool> sock_2:sendto('127.0.0.1', sock_1:name().port,'X')
- ---
- - true
- ...
- tarantool> message = sock_1:recvfrom()
- ---
- ...
- tarantool> message
- ---
- - X
- ...
- tarantool> sock_1:close()
- ---
- - true
- ...
- tarantool> sock_2:close()
- ---
- - true
- ...
+ | :codenormal:`tarantool>` :codebold:`socket = require('socket')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock_1 = socket('AF_INET', 'SOCK_DGRAM', 'udp')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock_1:bind('127.0.0.1')`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock_2 = socket('AF_INET', 'SOCK_DGRAM', 'udp')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock_2:sendto('127.0.0.1', sock_1:name().port,'X')`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`message = sock_1:recvfrom()`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`message`
+ | :codenormal:`---`
+ | :codenormal:`- X`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock_1:close()`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`sock_2:close()`
+ | :codenormal:`---`
+ | :codenormal:`- true`
+ | :codenormal:`...`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use tcp_server to accept file contents sent with socat
--
GitLab