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>

diff --git a/doc/usage/echo.rst b/doc/usage/echo.rst
new file mode 100644 (file)
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 6f49652758f494b3a714f2207116fdc35f4adfc4..317db3b449a71dda10e5bfbf40cdd84f3e47a3d7 100644 (file)
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -17,6 +17,7 @@ Shell commands
    bootefi
    bootmenu
    button
+   echo
    exit
    for
    mbr