doc: document echo command

Provide a man-page for the echo command.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>

2 files changed, 66 insertions, 0 deletions

diff --git a/doc/usage/echo.rst b/doc/usage/echo.rst
new file mode 100644
index 0000000..861abdf
--- /dev/null
+++ b/doc/usage/echo.rst
@@ -0,0 +1,65 @@
+echo command
+============
+
+Synopsis
+--------
+
+::
+
+    echo [-n] [args ...]
+
+Description
+-----------
+
+The echo command prints its arguments to the console separated by spaces.
+
+-n
+    Do not print a line feed after the last argument.
+
+args
+    Arguments to be printed. The arguments are evaluated before being passed to
+    the command.
+
+Examples
+--------
+
+Strings are parsed before the arguments are passed to the echo command:
+
+::
+
+    => echo "a" 'b' c
+    a b c
+    =>
+
+Observe how variables included in strings are handled:
+
+::
+
+    => setenv var X; echo "a)" ${var} 'b)' '${var}' c) ${var}
+    a) X b) ${var} c) X
+    =>
+
+
+-n suppresses the line feed:
+
+::
+
+    => echo -n 1 2 3; echo a b c
+    1 2 3a b c
+    => echo -n 1 2 3
+    1 2 3=>
+
+A more complex example:
+
+::
+
+    => for i in a b c; do for j in 1 2 3; do echo -n "${i}${j}, "; done; echo; done;
+    a1, a2, a3,
+    b1, b2, b3,
+    c1, c2, c3,
+    =>
+
+Return value
+------------
+
+The return value $? is always set to 0 (true).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 6f49652..317db3b 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -17,6 +17,7 @@ Shell commands
    bootefi
    bootmenu
    button
+   echo
    exit
    for
    mbr