Merge pull request #17 from davide-scola/0.x-improve_help_text

[0.x] Manual pages

.gitignore

@@ -42,4 +42,5 @@ grenache-announce
 #
 # Distribution
 #
+*.1
 *.tar.*

Makefile.am

@@ -18,7 +18,7 @@
 
 ACLOCAL_AMFLAGS = -I m4
 
-GRC_SUBDIRS = . src tests
+GRC_SUBDIRS = . doc src tests
 
 SUBDIRS = $(GRC_SUBDIRS)
 DIST_SUBDIRS = $(GRC_SUBDIRS) include m4

configure.ac

@@ -15,9 +15,9 @@ dnl implied. See the License for the specific language governing permissions
 dnl and limitations under the License.
 
 AC_PREREQ(2.69)
-AC_INIT([grenache-cli], [0.6.1], [[email protected]])
+AC_INIT([grenache-cli], [0.7.0], [[email protected]])
 
-AC_SUBST([VERSION], [0.6.1])
+AC_SUBST([VERSION], [0.7.0])
 AC_SUBST([SB], [`$srcdir/shtool echo -n -e %B`])
 AC_SUBST([EB], [`$srcdir/shtool echo -n -e %b`])
 
@@ -58,6 +58,7 @@ AC_PROG_LN_S
 AC_PROG_MAKE_SET
 AC_PROG_LIBTOOL
 AC_PROG_AWK
+AM_MISSING_PROG([HELP2MAN], [help2man])
 
 AX_PROG_JQ
 AX_PROG_CAT
@@ -180,6 +181,7 @@ AX_MSG_BOLD([Writing output files])
 
 AC_CONFIG_FILES([ \
   Makefile \
+  doc/Makefile \
   m4/Makefile \
   include/Makefile \
   src/Makefile \

doc/Makefile.am

@@ -0,0 +1,32 @@
+############################################################################
+# This file is part of Grenache Command Line Interface.                    #
+#                                                                          #
+# Copyright (C) 2017, 2018 Davide Scola <[email protected]>              #
+#                                                                          #
+# Licensed under the Apache License,  Version 2.0 (the "License"); you may #
+# not use this file except in  compliance with the License. You may obtain #
+# a copy of the License at                                                 #
+#                                                                          #
+#       http://www.apache.org/licenses/LICENSE-2.0                         #
+#                                                                          #
+# Unless  required by  applicable law  or agreed  to in  writing, software #
+# distributed  under the  License  is  distributed on  an  "AS IS"  BASIS, #
+# WITHOUT  WARRANTIES  OR  CONDITIONS  OF  ANY  KIND,  either  express  or #
+# implied. See the License for the specific language governing permissions #
+# and limitations under the License.                                       #
+############################################################################
+
+dist_man1_MANS = \
+grenache-get.1 \
+grenache-put.1 \
+grenache-keygen.1 \
+grenache-lookup.1 \
+grenache-announce.1
+
+MAINTAINERCLEANFILES = \
+$(dist_man1_MANS)
+
+%.1: $(top_srcdir)/src/%.in $(top_srcdir)/doc/Makefile.am
+	$(HELP2MAN) --no-info --output=$@ --version-string="$(PACKAGE_VERSION)" \
+		--name="manual page for $(notdir $(basename $<)) ($(PACKAGE_NAME)) $(PACKAGE_VERSION) on $(host_cpu)-$(host_os)" \
+		"${SHELL} $(basename $<)$(EXEEXT)"

src/grenache-announce.in

@@ -33,21 +33,25 @@ JQ_ARGV=(--unbuffered -r)
 # Show program's help.
 function show_help {
   @CAT@ <<_EOF
-Usage:
-    ${ME##*/} [OPTIONS] <service>... -- announce a service on the DHT.
+${ME##*/} announces a service on the DHT
 
-    Options:
+Usage: ${ME##*/} [OPTION]... [SERVICE]...
 
-        -d, --delimiter         Set the service/port delimiter
-        -g, --grape             Set the Grape hostname
-        -j, --json              Use JSON as data serializer
-        -p, --port              Set the Grape port number
-        -t, --tls               Enable TLS
+Options:
+    -d, --delimiter            Set the service,port delimiter
+    -g, --grape                Set the Grape hostname
+    -j, --json                 Use JSON as data serializer
+    -p, --port                 Set the Grape port number
+    -t, --tls                  Enable TLS
 
-        -h, --help              Show this message
-        -V, --version           Show version information
+    -h, --help                 Show help message
+    -V, --version              Show version information
 
-    The order of the specified options is not relevant.
+Examples:
+    ${ME##*/}          Announce services from stdin
+    ${ME##*/} -d/      The same thing, but use / as delimiter
+
+Report bugs to <@PACKAGE_BUGREPORT@>.
 _EOF
 
   exit 1
@@ -56,12 +60,14 @@ _EOF
 # Show program's version.
 function show_version {
   @CAT@ <<_EOF
-${WHOAMI##*/} (@host_cpu@-@host_os@) @PACKAGE_NAME@/@PACKAGE_VERSION@
+${WHOAMI##*/} (@PACKAGE_NAME@) @PACKAGE_VERSION@ for @host_cpu@-@host_os@
+
 Copyright (C) 2017, 2018 Davide Scola <@PACKAGE_BUGREPORT@>
 This is free software; see the  source for copying conditions.  There is
 NO warranty;  not even for  MERCHANTABILITY or FITNESS FOR  A PARTICULAR
 PURPOSE.
 
+Written by Davide Scola.
 _EOF
 
   exit 1

src/grenache-get.in

@@ -31,24 +31,28 @@ QUERY='select(.v) | .v'
 # Show program's help.
 function show_help {
   @CAT@ <<_EOF
-Usage:
-    ${ME##*/} [OPTIONS] <value> -- send a GET request to the DHT
+${ME##*/} sends a GET request to the DHT
 
-    Options:
+Usage: ${ME##*/} [OPTION]... HASH
 
-        -g, --grape             Set the Grape hostname
-        -i. --id                Get the id of sending node
-        -p, --port              Set the Grape port number
-        -t, --tls               Enable TLS
-        -r, --raw               Get the raw response message
-        -s, --salt              Set salt for this request
-        -v, --value             Get the stored value
-        -w, --write             Get the write token
+Options:
+    -g, --grape                Set the Grape hostname
+    -i. --id                   Get the id of sending node
+    -p, --port                 Set the Grape port number
+    -t, --tls                  Enable TLS
+    -r, --raw                  Get the raw response message
+    -s, --salt                 Set salt for this request
+    -v, --value                Get the stored value
+    -w, --write                Get the write token
 
-        -h, --help              Show this message
-        -V, --version           Show version information
+    -h, --help                 Show help message
+    -V, --version              Show version information
 
-    The order of the specified options is not relevant.
+Examples:
+    ${ME##*/} foo           Read value whose hash is foo from the DHT
+    ${ME##*/} -s bar foo    The same thing, using bar as salt
+
+Report bugs to <@PACKAGE_BUGREPORT@>.
 _EOF
 
   exit 1
@@ -57,12 +61,14 @@ _EOF
 # Show program's version.
 function show_version {
   @CAT@ <<_EOF
-${WHOAMI##*/} (@host_cpu@-@host_os@) @PACKAGE_NAME@/@PACKAGE_VERSION@
+${WHOAMI##*/} (@PACKAGE_NAME@) @PACKAGE_VERSION@ for @host_cpu@-@host_os@
+
 Copyright (C) 2017, 2018 Davide Scola <@PACKAGE_BUGREPORT@>
 This is free software; see the  source for copying conditions.  There is
 NO warranty;  not even for  MERCHANTABILITY or FITNESS FOR  A PARTICULAR
 PURPOSE.
 
+Written by Davide Scola.
 _EOF
 
   exit 1

src/grenache-keygen.in

@@ -27,17 +27,21 @@ OVERWRITE='no'
 # Show program's help.
 function show_help {
   @CAT@ <<_EOF
-Usage:
-    ${ME##*/} [OPTIONS] -- creates your grenache-cli keypair.
+${ME##*/} generates and manages authentication keys
 
-    Options:
+Usage: ${ME##*/} [OPTION]...
 
-        -f, --force             Overwrite existing keypair
+Options:
+    -f, --force                Overwrite existing keypair
 
-        -h, --help              Show this message
-        -V, --version           Show version information
+    -h, --help                 Show help message
+    -V, --version              Show version information
 
-    The order of the specified options is not relevant.
+Examples:
+    ${ME##*/}            Create a new keypair
+    ${ME##*/} -f         The same thing, but overwrites the existing one
+
+Report bugs to <@PACKAGE_BUGREPORT@>.
 _EOF
 
   exit 1
@@ -46,12 +50,14 @@ _EOF
 # Show program's version.
 function show_version {
   @CAT@ <<_EOF
-${WHOAMI##*/} (@host_cpu@-@host_os@) @PACKAGE_NAME@/@PACKAGE_VERSION@
+${WHOAMI##*/} (@PACKAGE_NAME@) @PACKAGE_VERSION@ for @host_cpu@-@host_os@
+
 Copyright (C) 2017, 2018 Davide Scola <@PACKAGE_BUGREPORT@>
 This is free software; see the  source for copying conditions.  There is
 NO warranty;  not even for  MERCHANTABILITY or FITNESS FOR  A PARTICULAR
 PURPOSE.
 
+Written by Davide Scola.
 _EOF
 
   exit 1

src/grenache-lookup.in

@@ -36,23 +36,27 @@ readonly LOOKUP_RANDOM=8
 # Show program's help.
 function show_help {
   @CAT@ <<_EOF
-Usage:
-    ${ME##*/} [OPTIONS] <service>... -- lookup a service in the DHT.
+${ME##*/} looks for a service in the DHT
 
-    Options:
+Usage: ${ME##*/} [OPTION]... SERVICE...
 
-        -a, --all               Pick all peers in list
-        -f, --first             Pick the first peer in list
-        -g, --grape             Set the Grape hostname
-        -l, --last              Pick the last peer in list
-        -p, --port              Set the Grape port number
-        -r, --random            Pick a random peer in list
-        -t, --tls               Enable TLS
+Options:
+   -a, --all                     Pick all peers in list
+   -f, --first                   Pick the first peer in list
+   -g, --grape                   Set the Grape hostname
+   -l, --last                    Pick the last peer in list
+   -p, --port                    Set the Grape port number
+   -r, --random                  Pick a random peer in list
+   -t, --tls                     Enable TLS
 
-        -h, --help              Show this message
-        -V, --version           Show version information
+   -h, --help                    Show help message
+   -V, --version                 Show version information
 
-    The order of the specified options is not relevant.
+Examples:
+    ${ME##*/} 'foo'        Pick a random peer that provides the foo service 
+    ${ME##*/} -a 'foo'     The same thing, but retreive all peers
+
+Report bugs to <@PACKAGE_BUGREPORT@>.
 _EOF
 
   exit 1
@@ -61,12 +65,14 @@ _EOF
 # Show program's version.
 function show_version {
   @CAT@ <<_EOF
-${WHOAMI##*/} (@host_cpu@-@host_os@) @PACKAGE_NAME@/@PACKAGE_VERSION@
+${WHOAMI##*/} (@PACKAGE_NAME@) @PACKAGE_VERSION@ for @host_cpu@-@host_os@
+
 Copyright (C) 2017, 2018 Davide Scola <@PACKAGE_BUGREPORT@>
 This is free software; see the  source for copying conditions.  There is
 NO warranty;  not even for  MERCHANTABILITY or FITNESS FOR  A PARTICULAR
 PURPOSE.
 
+Written by Davide Scola.
 _EOF
 
   exit 1

src/grenache-put.in

@@ -33,23 +33,27 @@ SEQUENCE="$(@DATE@ '+%s%6N')"
 # Show program's help.
 function show_help {
   @CAT@ <<_EOF
-Usage:
-    ${ME##*/} [OPTIONS] <value>... -- send a PUT request to the DHT
+${ME##*/} sends a PUT request to the DHT
 
-    Options:
+Usage: ${ME##*/} [OPTION]... VALUE
 
-        -c, --cas               Set the compare and swap number
-        -g, --grape             Set the Grape hostname
-        -m, --mutable           Send a mutable PUT request
-        -n, --number            Set the sequence number of this PUT request
-        -p, --port              Set the Grape port number
-        -s, --salt              Set salt for this request
-        -t, --tls               Enable TLS
+Options:
+   -c, --cas                  Set the compare and swap number
+   -g, --grape                Set the Grape hostname
+   -m, --mutable              Send a mutable PUT request
+   -n, --number               Set the sequence number of this PUT request
+   -p, --port                 Set the Grape port number
+   -s, --salt                 Set salt for this request
+   -t, --tls                  Enable TLS
 
-        -h, --help              Show this message
-        -V, --version           Show version information
+   -h, --help                 Show help message
+   -V, --version              Show version information
 
-    The order of the specified options is not relevant.
+Examples:
+    ${ME##*/} 'foo'        Store the value foo to the DHT
+    ${ME##*/} -m 'foo'     The same thing, but as mutable value
+
+Report bugs to <@PACKAGE_BUGREPORT@>.
 _EOF
 
   exit 1
@@ -58,12 +62,14 @@ _EOF
 # Show program's version.
 function show_version {
   @CAT@ <<_EOF
-${WHOAMI##*/} (@host_cpu@-@host_os@) @PACKAGE_NAME@/@PACKAGE_VERSION@
+${WHOAMI##*/} (@PACKAGE_NAME@) @PACKAGE_VERSION@ for @host_cpu@-@host_os@
+
 Copyright (C) 2017, 2018 Davide Scola <@PACKAGE_BUGREPORT@>
 This is free software; see the  source for copying conditions.  There is
 NO warranty;  not even for  MERCHANTABILITY or FITNESS FOR  A PARTICULAR
 PURPOSE.
 
+Written by Davide Scola.
 _EOF
 
   exit 1