Add examples and help text for awesome-client (#2162)

This adds a -h|--help option to awesome-client. In addition it adds
examples to the awesome-client manpage.

manpages/awesome-client.1.de.txt

@@ -9,7 +9,7 @@ awesome-client - awesome Fenstermanager externe Befehlsschnittstelle
 SYNTAX
 -------
 
-awesome-client
+awesome-client [-h|--help] [command [command...]]
 
 BESCHREIBUNG
 ------------
@@ -24,6 +24,34 @@ Wenn 'rlwrap' installiert ist wird es benutzt, um eine readline-Kommandozeilenei
 
 Das Modul 'awful.remote' muss geladen sein, um diesen Befehl zu benutzen.
 
+EXAMPLES
+-------
+....
+$ awesome-client 'return 1+1, "Hello, world"\
+   double 2
+   string "Hello, world"
+
+# The following does not return anything on the command line,
+# but will show a notification.
+$ awesome-client '
+> naughty = require("naughty")
+> naughty.notify({
+> title="CLI Notification",
+> text="This is a notification sent from the command line!"})
+> '
+
+# Entering read-eval-print-loop mode
+# This mode will send every line to awesome, exactly the same as passing
+# multiple commands on the command line.
+$ awesome-client
+awesome# return 1+1
+   double 2
+awesome# return 1+1, "Hello, world"
+   double 2
+   string "Hello, world"
+awesome#
+....
+
 SIEHE AUCH
 ----------
 awesome(1) awesomerc(5)

manpages/awesome-client.1.es.txt

@@ -9,7 +9,7 @@ awesome-client - ejecución remota en el gestor de ventanas awesome
 SINOPSIS
 --------
 
-awesome-client
+awesome-client [-h|--help] [command [command...]]
 
 DESCRIPCIÓN
 -----------
@@ -28,6 +28,34 @@ readline.
 El módulo 'awful.remote' tiene que estar cargado para que este comando
 funcione.
 
+EXAMPLES
+-------
+....
+$ awesome-client 'return 1+1, "Hello, world"\
+   double 2
+   string "Hello, world"
+
+# The following does not return anything on the command line,
+# but will show a notification.
+$ awesome-client '
+> naughty = require("naughty")
+> naughty.notify({
+> title="CLI Notification",
+> text="This is a notification sent from the command line!"})
+> '
+
+# Entering read-eval-print-loop mode
+# This mode will send every line to awesome, exactly the same as passing
+# multiple commands on the command line.
+$ awesome-client
+awesome# return 1+1
+   double 2
+awesome# return 1+1, "Hello, world"
+   double 2
+   string "Hello, world"
+awesome#
+....
+
 VÉASE TAMBIÉN
 -------------
 awesome(1) awesomerc(5)

manpages/awesome-client.1.fr.txt

@@ -9,7 +9,7 @@ awesome-client - exécution à distance du gestionnaire de fenêtres awesome
 SYNOPSIS
 --------
 
-awesome-client
+awesome-client [-h|--help] [command [command...]]
 
 DESCRIPTION
 ------------
@@ -25,24 +25,48 @@ Si 'rlwrap' est installé, il sera utilisé pour fournir une interface en ligne
 
 Le module 'awful.remote' doit être chargé pour que cette commande fonctionne.
 
+EXAMPLES
+-------
+....
+$ awesome-client 'return 1+1, "Hello, world"\
+   double 2
+   string "Hello, world"
+
+# The following does not return anything on the command line,
+# but will show a notification.
+$ awesome-client '
+> naughty = require("naughty")
+> naughty.notify({
+> title="CLI Notification",
+> text="This is a notification sent from the command line!"})
+> '
+
+# Entering read-eval-print-loop mode
+# This mode will send every line to awesome, exactly the same as passing
+# multiple commands on the command line.
+$ awesome-client
+awesome# return 1+1
+   double 2
+awesome# return 1+1, "Hello, world"
+   double 2
+   string "Hello, world"
+awesome#
+....
+
 VOIR AUSSI
 ----------
-
 awesome(1) awesomerc(5)
 
 AUTEURS
 -------
-
 Julien Danjou <julien@danjou.info>
 
 WWW
 ---
-
 https://awesomewm.org
 
 TRADUCTION
 ----------
-
 Ce document est une traduction, réalisée par Jean-Luc Duflot <jl POING
 duflot CHEZ laposte POING net> le 20 février 2012.
 

manpages/awesome-client.1.it.txt

@@ -9,7 +9,7 @@ awesome-client - esecutore remoto per il gestore di finestre awesome
 SINOSSI
 -------
 
-awesome-client
+awesome-client [-h|--help] [command [command...]]
 
 DESCRIZIONE
 -----------
@@ -28,6 +28,34 @@ riga di comando per le funzionalità di readline.
 Il modulo 'awful.remote' deve essere caricato per far funzionare questo
 comando.
 
+EXAMPLES
+-------
+....
+$ awesome-client 'return 1+1, "Hello, world"\
+   double 2
+   string "Hello, world"
+
+# The following does not return anything on the command line,
+# but will show a notification.
+$ awesome-client '
+> naughty = require("naughty")
+> naughty.notify({
+> title="CLI Notification",
+> text="This is a notification sent from the command line!"})
+> '
+
+# Entering read-eval-print-loop mode
+# This mode will send every line to awesome, exactly the same as passing
+# multiple commands on the command line.
+$ awesome-client
+awesome# return 1+1
+   double 2
+awesome# return 1+1, "Hello, world"
+   double 2
+   string "Hello, world"
+awesome#
+....
+
 VEDI ANCHE
 ----------
 awesome(1) awesomerc(5)

manpages/awesome-client.1.ru.txt

@@ -9,7 +9,7 @@ awesome-client - удалённое управление потрясающим
 СИНОПСИС
 --------
 
-awesome-client
+awesome-client [-h|--help] [command [command...]]
 
 ОПИСАНИЕ
 --------
@@ -27,6 +27,34 @@ awesome через D-Bus. Если установлен «rlwrap», то он б
 В awesome должен быть загружен модуль «awful.remote», чтобы позволить удалённое
 выполнение кода.
 
+EXAMPLES
+-------
+....
+$ awesome-client 'return 1+1, "Hello, world"\
+   double 2
+   string "Hello, world"
+
+# The following does not return anything on the command line,
+# but will show a notification.
+$ awesome-client '
+> naughty = require("naughty")
+> naughty.notify({
+> title="CLI Notification",
+> text="This is a notification sent from the command line!"})
+> '
+
+# Entering read-eval-print-loop mode
+# This mode will send every line to awesome, exactly the same as passing
+# multiple commands on the command line.
+$ awesome-client
+awesome# return 1+1
+   double 2
+awesome# return 1+1, "Hello, world"
+   double 2
+   string "Hello, world"
+awesome#
+....
+
 СМОТРИ ТАКЖЕ
 ------------
 awesome(1) awesomerc(5)
@@ -41,6 +69,5 @@ https://awesomewm.org
 
 ПЕРЕВОД
 -------
-
 Это руководство переведено на русский язык Константином Степановым <kstep@p-nut.info>
 13 апреля 2011 года.

manpages/awesome-client.1.txt

@@ -9,7 +9,7 @@ awesome-client - awesome window manager remote execution
 SYNOPSIS
 --------
 
-awesome-client
+awesome-client [-h|--help] [command [command...]]
 
 DESCRIPTION
 -----------
@@ -19,11 +19,41 @@ It communicates with awesome via D-Bus, allowing remote execution of Lua code.
 
 USAGE
 -----
-awesome-client reads commands from standard input and sends them via D-Bus to awesome.
+awesome-client reads commands passed on the command line or from standard input
-If 'rlwrap' is installed, it will be used to provide a readline command line interface.
+and sends them via D-Bus to awesome.
+If 'rlwrap' is installed, it will be used to provide a readline command line
+interface.
 
 The 'awful.remote' module has to be loaded if you want this command to work.
 
+EXAMPLES
+-------
+....
+$ awesome-client 'return 1+1, "Hello, world"\
+   double 2
+   string "Hello, world"
+
+# The following does not return anything on the command line,
+# but will show a notification.
+$ awesome-client '
+> naughty = require("naughty")
+> naughty.notify({
+> title="CLI Notification",
+> text="This is a notification sent from the command line!"})
+> '
+
+# Entering read-eval-print-loop mode
+# This mode will send every line to awesome, exactly the same as passing
+# multiple commands on the command line.
+$ awesome-client
+awesome# return 1+1
+   double 2
+awesome# return 1+1, "Hello, world"
+   double 2
+   string "Hello, world"
+awesome#
+....
+
 SEE ALSO
 --------
 awesome(1) awesomerc(5)

utils/awesome-client

@@ -51,9 +51,32 @@ a_dbus_send()
     fi
 }
 
+print_help()
+{
+    echo "Usage: awesome-client [-h|--help] [command [command...]]
+awesome window manager remote execution
+
+awesome-client is a remote command line interface to awesome.
+It communicates with awesome via D-Bus, allowing remote execution of Lua code.
+
+Run without a command to enter REPL (read-eval-print-loop) mode.
+For examples see \`man awesome-client\`."
+}
+
 if [ $# -ne 0 ]
 then
-    for arg in "$@" ; do
+    # check for command-line arguments
+    ARGS=()
+    for arg in "$@"; do
+        if [ "$arg" = "-h" ] || [ "$arg" = "--help" ]; then
+            print_help
+            exit 0
+        else
+            ARGS+=("$arg")
+        fi
+    done
+    # run arguments
+    for arg in "$ARGS" ; do
         a_dbus_send "$arg"
     done
 elif [ -t 0 ]