Merge pull request #2 from minfrin/debian

Debian packaging - considerations

ChangeLog

@@ -1,4 +1,8 @@
 
+CHanges with v1.0.3
+
+  *) Switch from help2man to txt2man. [Graham Leggett]
+
 Changes with v1.0.2
 
   *) Add help2man to debian packaging build dependencies.

Makefile.am

@@ -1,10 +1,12 @@
 
+ACLOCAL_AMFLAGS = -I m4
+
 bin_PROGRAMS = retry
 retry_SOURCES = retry.c
 
-EXTRA_DIST = retry.spec debian/changelog debian/compat debian/control debian/copyright debian/docs debian/dirs debian/rules debian/source/format
+EXTRA_DIST = retry.spec
 dist_man_MANS = retry.1
 
 retry.1: retry.c $(top_srcdir)/configure.ac
-	which help2man && help2man -n "Repeat command until a criteria is met, usually success." ./retry > retry.1 || true
+	which txt2man && ./retry --help | txt2man -d 1 -t "${PACKAGE_NAME}" -r "${PACKAGE_NAME}-${PACKAGE_VERSION}" > retry.1 || true
 

configure.ac

@@ -2,8 +2,9 @@
 # Process this file with autoconf to produce a configure script.
 
 AC_PREREQ(2.61)
-AC_INIT(retry, 1.0.2, minfrin@sharp.fm)
+AC_INIT(retry, 1.0.3, minfrin@sharp.fm)
 AC_CONFIG_AUX_DIR(build-aux)
+AC_CONFIG_MACRO_DIRS([m4])
 AM_INIT_AUTOMAKE([dist-bzip2])
 LT_INIT
 AC_CONFIG_FILES([Makefile retry.spec])

retry.c

@@ -1,5 +1,5 @@
 /**
- *    (C) 2020 Graham Leggett
+ *    Copyright (C) 2020 Graham Leggett <minfrin@sharp.fm>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -71,41 +71,98 @@ typedef struct pump_t {
 
 static int help(const char *name, const char *msg, int code)
 {
+    const char *n;
+
+    n = strrchr(name, '/');
+    if (!n) {
+        n = name;
+    }
+    else {
+        n++;
+    }
+
     fprintf(code ? stderr : stdout,
-            "%sUsage: %s [-v] [-h] [-u until] [-w while] command ...\n"
+            "%s\n"
+            "\n"
+            "NAME\n"
+            "  %s - Repeat command until a criteria is met, usually success.\n"
+            "\n"
+            "SYNOPSIS\n"
+            "  %s [-v] [-h] [-u until] [-w while] command ...\n"
+            "\n"
+            "DESCRIPTION\n"
+            "\n"
+            "  The tool repeats the given command until the command is successful,\n"
+            "  backing off with a configurable delay between each attempt.\n"
+            "\n"
+            "  Retry captures stdin into memory as the data is passed to the repeated\n"
+            "  command, and this captured stdin is then replayed should the command\n"
+            "  be repeated. This makes it possible to embed the retry tool into shell\n"
+            "  pipelines.\n"
+            "\n"
+            "  Retry captures stdout into memory, and if the command was successful\n"
+            "  stdout is passed on to stdout as normal, while if the command was\n"
+            "  repeated stdout is passed to stderr instead. This ensures that output\n"
+            "  is passed to stdout once and once only.\n"
+            "\n"
+            "OPTIONS\n"
+            "  -d seconds, --delay=seconds  The number of seconds to back off\n"
+            "    after each attempt.\n"
+            "\n"
+            "  -m message, --message=message  A message to include in the notification\n"
+            "    when repeat has backed off. Defaults to the\n"
+            "    command name.\n"
+            "\n"
+            "  -t times, --times=times  The number of times to retry\n"
+            "    the command. By default we try forever.\n"
+            "\n"
+            "  -u criteria, --until=criteria  Keep repeating the command until any one\n"
+            "    of the comma separated criteria is met.\n"
+            "    Options include 'success', 'true', 'fail',\n"
+            "    'false', an integer or a range of integers.\n"
+            "    Default is 'success'.\n"
+            "\n"
+            "  -w criteria, --while=criteria  Keep repeating the command while any one\n"
+            "    of the comma separated criteria is met.\n"
+            "    Options include 'success', 'true', 'fail',\n"
+            "    'false', an integer or a range of integers.\n"
+            "\n"
+            "  -h, --help  Display this help message.\n"
+            "\n"
+            "  -v, --version  Display the version number.\n"
+            "\n"
+            "RETURN VALUE\n"
+            "  The retry tool returns the return code from the\n"
+            "  command being executed, once the criteria is reached.\n"
+            "\n"
+            "  If the command was interrupted with a signal, the return\n"
+            "  code is the signal number plus 128.\n"
+            "\n"
+            "  If the command could not be executed, or if the options\n"
+            "  are invalid, the status 1 is returned.\n"
+            "\n"
+            "EXAMPLES\n"
+            "  In this basic example, we repeat the command forever.\n"
             "\n"
-            "The tool repeats the given command until the command is successful,"
-            "backing off with a configurable delay between each attempt.\n"
+            "\t~$ retry --until=success false\n"
+            "\tretry: 'false' returned 1, backing off for 10 seconds and trying again...\n"
+            "\tretry: 'false' returned 1, backing off for 10 seconds and trying again...\n"
+            "\tretry: 'false' returned 1, backing off for 10 seconds and trying again...\n"
+            "\t^C\n"
             "\n"
-            "Retry captures stdin into memory as the data is passed to the repeated\n"
-            "command, and this captured stdin is then replayed should the command\n"
-            "be repeated. This makes it possible to embed the retry tool into shell\n"
-            "pipelines.\n"
+            "  In this more complex example, each invocation of curl is\n"
+            "  retried until curl succeeds, at which point stdout is\n"
+            "  passed once and once only to the next element in the\n"
+            "  pipeline.\n"
             "\n"
-            "Retry captures stdout into memory, and if the command was successful\n"
-            "stdout is passed on to stdout as normal, while if the command was\n"
-            "repeated stdout is passed to stderr instead. This ensures that output\n"
-            "is passed to stdout once and once only."
+            "\t~$ retry curl --fail http://localhost/entities | \\\\ \n"
+            "\tjq ... | \\\\ \n"
+            "\tretry curl --fail -X POST http://localhost/resource | \\\\ \n"
+            "\tlogger -t resource-init\n"
             "\n"
-            "  -d seconds, --delay=seconds\tThe number of seconds to back off\n"
-            "\t\t\t\tafter each attempt.\n"
-            "  -m message, --message=message\tA message to include in the notification\n"
-            "\t\t\t\twhen repeat has backed off. Defaults to the\n"
-            "\t\t\t\tcommand name.\n"
-            "  -t times, --times=times\tThe number of times to retry\n"
-            "\t\t\t\tthe command. By default we try forever.\n"
-            "  -u criteria, --until=criteria\tKeep repeating the command until any one\n"
-            "\t\t\t\tof the comma separated criteria is met.\n"
-            "\t\t\t\tOptions include 'success', 'true', 'fail',\n"
-            "\t\t\t\t'false', an integer or a range of integers.\n"
-            "\t\t\t\tDefault is 'success'.\n"
-            "  -w criteria, --while=criteria\tKeep repeating the command while any one\n"
-            "\t\t\t\tof the comma separated criteria is met.\n"
-            "\t\t\t\tOptions include 'success', 'true', 'fail',\n"
-            "\t\t\t\t'false', an integer or a range of integers.\n"
-            "  -h, --help\t\t\tDisplay this help message.\n"
-            "  -v, --version\t\t\tDisplay the version number.\n"
-            "", msg ? msg : "", name);
+            "AUTHOR\n"
+            "  Graham Leggett <minfrin@sharp.fm>\n"
+            "", msg ? msg : "", n, n);
     return code;
 }
 

retry.spec.in

@@ -8,7 +8,7 @@ License:   ASL 2.0
 Group:     Applications/System
 Source:    https://github.com/minfrin/%{name}/releases/download/%{name}-%{version}/%{name}-%{version}.tar.bz2
 URL:       https://github.com/minfrin/%{name}
-BuildRequires: help2man, gcc, autoconf, automake, libtool
+BuildRequires: gcc, autoconf, automake, libtool
 
 %define    __libtoolize /bin/true