From 48f1fc440eb53b0efb7c1beaba396e81b8bcb1ab Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sun, 7 Apr 2013 02:31:51 +0000
Subject: [PATCH] Provide "purpose" texts.

This text will be printed right after the program name in the --help
output. For para_afh, the inline text becomes redundant, so this text
is removed.

Each executable gets a purpose text, and for receivers, filters,
writers the purpose will be printed as part of the help output of
para_audiod, para_filter. para_recv and para_write.
---
 filter_common.c                  |  3 ++-
 ggo.c                            |  2 ++
 ggo.h                            |  7 ++++++-
 m4/gengetopt/afh.m4              | 10 ++--------
 m4/gengetopt/afh_recv.m4         |  2 ++
 m4/gengetopt/alsa_write.m4       |  2 ++
 m4/gengetopt/amp_filter.m4       |  2 ++
 m4/gengetopt/ao_write.m4         |  2 ++
 m4/gengetopt/audioc.m4           |  2 ++
 m4/gengetopt/audiod.m4           |  2 ++
 m4/gengetopt/client.m4           |  2 ++
 m4/gengetopt/compress_filter.m4  |  2 ++
 m4/gengetopt/dccp_recv.m4        |  2 ++
 m4/gengetopt/fade.m4             |  2 ++
 m4/gengetopt/file_write.m4       |  2 ++
 m4/gengetopt/filter.m4           |  2 ++
 m4/gengetopt/gui.m4              |  2 ++
 m4/gengetopt/http_recv.m4        |  2 ++
 m4/gengetopt/mp3dec_filter.m4    |  2 ++
 m4/gengetopt/oss_write.m4        |  2 ++
 m4/gengetopt/osx_write.m4        |  2 ++
 m4/gengetopt/play.m4             |  2 ++
 m4/gengetopt/prebuffer_filter.m4 |  2 ++
 m4/gengetopt/recv.m4             |  2 ++
 m4/gengetopt/resample_filter.m4  |  2 ++
 m4/gengetopt/server.m4           |  2 ++
 m4/gengetopt/udp_recv.m4         |  2 ++
 m4/gengetopt/write.m4            |  2 ++
 recv_common.c                    |  3 ++-
 write_common.c                   |  3 ++-
 30 files changed, 64 insertions(+), 12 deletions(-)

diff --git a/filter_common.c b/filter_common.c
index 787255af..2616c9bd 100644
--- a/filter_common.c
+++ b/filter_common.c
@@ -122,7 +122,8 @@ void print_filter_helps(unsigned flags)
 
 		if (!f->help.short_help)
 			continue;
-		printf_or_die("\nOptions for %s:", f->name);
+		printf_or_die("\nOptions for %s (%s):", f->name,
+			f->help.purpose);
 		ggo_print_help(&f->help, flags);
 	}
 }
diff --git a/ggo.c b/ggo.c
index d8d56c03..3a441db1 100644
--- a/ggo.c
+++ b/ggo.c
@@ -41,6 +41,8 @@ void ggo_print_help(struct ggo_help *help, unsigned flags)
 
 	if (flags & GPH_PRINT_NAME_VERSION)
 		printf_or_die("%s\n", version_single_line(help->prefix));
+	if (help->purpose && (flags & GPH_PRINT_PURPOSE))
+		printf_or_die("\n%s\n", help->purpose);
 	if (help->usage && (flags & GPH_PRINT_USAGE))
 		printf_or_die("\n%s\n", help->usage);
 	if (help->description && (flags & GPH_PRINT_DESCRIPTION))
diff --git a/ggo.h b/ggo.h
index 12574dba..671fc01c 100644
--- a/ggo.h
+++ b/ggo.h
@@ -16,6 +16,8 @@ struct ggo_help {
 	const char **short_help;
 	/** Like \a short_help, plus the \a details section. */
 	const char **detailed_help;
+	/** The purpose text as specified in the ggo file. */
+	const char *purpose;
 	/** Generated by gengetopt and exported via the *.cmdline.h file. */
 	const char *usage;
 	/** The description text given in the .ggo file. */
@@ -37,11 +39,13 @@ enum ggo_print_help_flags {
 	GPH_PRINT_USAGE = 1 << 2,
 	/** Print the description text. */
 	GPH_PRINT_DESCRIPTION = 1 << 3,
+	/** Print the purpose text. */
+	GPH_PRINT_PURPOSE = 1 << 4,
 };
 
 /** Used to print the normal help of programs (--help) */
 #define GPH_STANDARD_FLAGS \
-	(GPH_PRINT_NAME_VERSION | GPH_PRINT_USAGE)
+	(GPH_PRINT_NAME_VERSION | GPH_PRINT_PURPOSE | GPH_PRINT_USAGE)
 
 /** Additional information for --detailed-help. */
 #define GPH_STANDARD_FLAGS_DETAILED \
@@ -59,6 +63,7 @@ enum ggo_print_help_flags {
 		.prefix = #_prefix, \
 		.short_help = _prefix ## _args_info_help, \
 		.detailed_help = _prefix ## _args_info_detailed_help, \
+		.purpose = _prefix ## _args_info_purpose, \
 		.usage = _prefix ## _args_info_usage, \
 		.description = _prefix ## _args_info_description, \
 	}
diff --git a/m4/gengetopt/afh.m4 b/m4/gengetopt/afh.m4
index beb84696..6fd4ab69 100644
--- a/m4/gengetopt/afh.m4
+++ b/m4/gengetopt/afh.m4
@@ -1,14 +1,8 @@
 args "--unamed-opts=audio_file --no-handle-version"
 
-include(header.m4)
-<qu>
-text "
-para_afh, the audio format handler tool, is a simple program for analyzing
-audio files. It prints technical information about the given audio file to
-stdout.
-"
-</qu>
+purpose "Print information about audio file(s)."
 
+include(header.m4)
 include(loglevel.m4)
 
 <qu>
diff --git a/m4/gengetopt/afh_recv.m4 b/m4/gengetopt/afh_recv.m4
index 2c34c4de..f4da9d99 100644
--- a/m4/gengetopt/afh_recv.m4
+++ b/m4/gengetopt/afh_recv.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Make an audio stream from a local file."
+
 description "
 	The afh (audio format handler) receiver can be used to write
 	selected parts of the given audio file without decoding
diff --git a/m4/gengetopt/alsa_write.m4 b/m4/gengetopt/alsa_write.m4
index 54b2c0cb..04b4963d 100644
--- a/m4/gengetopt/alsa_write.m4
+++ b/m4/gengetopt/alsa_write.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Native ALSA output plugin."
+
 include(header.m4)
 
 <qu>
diff --git a/m4/gengetopt/amp_filter.m4 b/m4/gengetopt/amp_filter.m4
index f3907bf4..2d4d4ce6 100644
--- a/m4/gengetopt/amp_filter.m4
+++ b/m4/gengetopt/amp_filter.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Amplify the decoded audio stream."
+
 option "amp" a
 #~~~~~~~~~~~~~
 "amplification value"
diff --git a/m4/gengetopt/ao_write.m4 b/m4/gengetopt/ao_write.m4
index 4deb58b7..ccee4ee6 100644
--- a/m4/gengetopt/ao_write.m4
+++ b/m4/gengetopt/ao_write.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin for libao."
+
 include(header.m4)
 <qu>
 
diff --git a/m4/gengetopt/audioc.m4 b/m4/gengetopt/audioc.m4
index 736d7072..2865900e 100644
--- a/m4/gengetopt/audioc.m4
+++ b/m4/gengetopt/audioc.m4
@@ -1,5 +1,7 @@
 args "--unamed-opts=command --conf-parser --no-handle-version"
 
+purpose "Communicate with para_audiod through a local socket."
+
 include(header.m4)
 <qu>
 option "socket" s
diff --git a/m4/gengetopt/audiod.m4 b/m4/gengetopt/audiod.m4
index 5522a56d..7bae3435 100644
--- a/m4/gengetopt/audiod.m4
+++ b/m4/gengetopt/audiod.m4
@@ -1,5 +1,7 @@
 args "--no-handle-help --no-handle-version --conf-parser"
 
+purpose "Connect to para_server, receive, decode and play audio streams."
+
 include(header.m4)
 define(CURRENT_PROGRAM,para_audiod)
 define(DEFAULT_CONFIG_FILE,~/.paraslash/audiod.conf)
diff --git a/m4/gengetopt/client.m4 b/m4/gengetopt/client.m4
index 23f7c1e6..a14b59c0 100644
--- a/m4/gengetopt/client.m4
+++ b/m4/gengetopt/client.m4
@@ -1,5 +1,7 @@
 args "--unamed-opts=command --no-handle-error --conf-parser --no-handle-version"
 
+purpose "Communicate with para_server through the paraslash control port."
+
 include(header.m4)
 define(CURRENT_PROGRAM,para_client)
 define(DEFAULT_CONFIG_FILE,~/.paraslash/client.conf)
diff --git a/m4/gengetopt/compress_filter.m4 b/m4/gengetopt/compress_filter.m4
index 739e4f02..8c701a03 100644
--- a/m4/gengetopt/compress_filter.m4
+++ b/m4/gengetopt/compress_filter.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Dynamically adjust the volume of an audio stream."
+
 option "blocksize" b
 #~~~~~~~~~~~~~~~~~~~
 "adjust block size"
diff --git a/m4/gengetopt/dccp_recv.m4 b/m4/gengetopt/dccp_recv.m4
index 0e556dd7..f8191fe0 100644
--- a/m4/gengetopt/dccp_recv.m4
+++ b/m4/gengetopt/dccp_recv.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Receive a DCCP audio stream."
+
 option "host" i
 "ip or host"
 string default="localhost"
diff --git a/m4/gengetopt/fade.m4 b/m4/gengetopt/fade.m4
index da7a27e2..8b81975b 100644
--- a/m4/gengetopt/fade.m4
+++ b/m4/gengetopt/fade.m4
@@ -1,5 +1,7 @@
 args "--conf-parser --no-handle-version"
 
+purpose "An alarm clock and volume-fader for OSS and ALSA."
+
 include(header.m4)
 define(CURRENT_PROGRAM,para_fade)
 define(DEFAULT_CONFIG_FILE,~/.paraslash/fade.conf)
diff --git a/m4/gengetopt/file_write.m4 b/m4/gengetopt/file_write.m4
index 560d55aa..045b8657 100644
--- a/m4/gengetopt/file_write.m4
+++ b/m4/gengetopt/file_write.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin that writes to a local file."
+
 option "filename" f
 #~~~~~~~~~~~~~~~~~~
 "specify output file name"
diff --git a/m4/gengetopt/filter.m4 b/m4/gengetopt/filter.m4
index c7337beb..baf6ecdb 100644
--- a/m4/gengetopt/filter.m4
+++ b/m4/gengetopt/filter.m4
@@ -1,5 +1,7 @@
 args "--no-handle-help --no-handle-version --conf-parser"
 
+purpose "Decode or process audio data from STDIN to STDOUT."
+
 include(header.m4)
 include(loglevel.m4)
 <qu>
diff --git a/m4/gengetopt/gui.m4 b/m4/gengetopt/gui.m4
index bafd325b..af1ca145 100644
--- a/m4/gengetopt/gui.m4
+++ b/m4/gengetopt/gui.m4
@@ -1,5 +1,7 @@
 args "--conf-parser --no-handle-version"
 
+purpose "Show para_audiod status in a curses window."
+
 include(header.m4)
 define(CURRENT_PROGRAM,para_gui)
 define(DEFAULT_CONFIG_FILE,~/.paraslash/gui.conf)
diff --git a/m4/gengetopt/http_recv.m4 b/m4/gengetopt/http_recv.m4
index 7544d77d..b8ece39d 100644
--- a/m4/gengetopt/http_recv.m4
+++ b/m4/gengetopt/http_recv.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Receive an HTTP audio stream."
+
 include(header.m4)
 
 <qu>
diff --git a/m4/gengetopt/mp3dec_filter.m4 b/m4/gengetopt/mp3dec_filter.m4
index aa8ef453..a6425b3e 100644
--- a/m4/gengetopt/mp3dec_filter.m4
+++ b/m4/gengetopt/mp3dec_filter.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Decode an mp3 stream."
+
 include(header.m4)
 
 <qu>
diff --git a/m4/gengetopt/oss_write.m4 b/m4/gengetopt/oss_write.m4
index 3aaba17a..352bea5b 100644
--- a/m4/gengetopt/oss_write.m4
+++ b/m4/gengetopt/oss_write.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin for the Open Sound System."
+
 option "device" d
 #~~~~~~~~~~~~~~~~
 "set PCM device"
diff --git a/m4/gengetopt/osx_write.m4 b/m4/gengetopt/osx_write.m4
index 2d49b406..5add6f2e 100644
--- a/m4/gengetopt/osx_write.m4
+++ b/m4/gengetopt/osx_write.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin for Mac OS coreaudio."
+
 section "osx options"
 #####################
 
diff --git a/m4/gengetopt/play.m4 b/m4/gengetopt/play.m4
index 230e8388..ea41f562 100644
--- a/m4/gengetopt/play.m4
+++ b/m4/gengetopt/play.m4
@@ -1,5 +1,7 @@
 args "--unamed-opts=audio_file --no-handle-version --conf-parser --no-handle-help"
 
+purpose "Command line audio player."
+
 description "para_play operates either in command mode or in insert
 mode. In insert mode it presents a prompt and allows to enter commands
 like stop, play, pause etc. In command mode the current audio file
diff --git a/m4/gengetopt/prebuffer_filter.m4 b/m4/gengetopt/prebuffer_filter.m4
index a4288972..9e84dcfc 100644
--- a/m4/gengetopt/prebuffer_filter.m4
+++ b/m4/gengetopt/prebuffer_filter.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Delay processing of an audio stream."
+
 option "duration" d
 #~~~~~~~~~~~~~~~~~~
 "prebuffer time"
diff --git a/m4/gengetopt/recv.m4 b/m4/gengetopt/recv.m4
index c7b89fe4..086c9c0a 100644
--- a/m4/gengetopt/recv.m4
+++ b/m4/gengetopt/recv.m4
@@ -1,5 +1,7 @@
 args "--no-handle-help --no-handle-version"
 
+purpose "A command line HTTP/DCCP/UDP stream grabber."
+
 include(header.m4)
 include(loglevel.m4)
 
diff --git a/m4/gengetopt/resample_filter.m4 b/m4/gengetopt/resample_filter.m4
index 33dd6674..4f4af4b0 100644
--- a/m4/gengetopt/resample_filter.m4
+++ b/m4/gengetopt/resample_filter.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Transform raw audio to a different sample rate."
+
 include(header.m4)
 
 option "converter" C
diff --git a/m4/gengetopt/server.m4 b/m4/gengetopt/server.m4
index d1293a02..6596d934 100644
--- a/m4/gengetopt/server.m4
+++ b/m4/gengetopt/server.m4
@@ -1,5 +1,7 @@
 args "--conf-parser --no-handle-version"
 
+purpose "Manage and stream audio files."
+
 include(header.m4)
 define(CURRENT_PROGRAM,para_server)
 define(DEFAULT_CONFIG_FILE,~/.paraslash/server.conf)
diff --git a/m4/gengetopt/udp_recv.m4 b/m4/gengetopt/udp_recv.m4
index 78c3257d..48770d97 100644
--- a/m4/gengetopt/udp_recv.m4
+++ b/m4/gengetopt/udp_recv.m4
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Receive an UDP audio stream."
+
 option "host" i
 "ip or host to receive udp packets from"
 string default="224.0.1.38"
diff --git a/m4/gengetopt/write.m4 b/m4/gengetopt/write.m4
index c022bc8f..8b13f457 100644
--- a/m4/gengetopt/write.m4
+++ b/m4/gengetopt/write.m4
@@ -1,5 +1,7 @@
 args "--no-handle-help --no-handle-version"
 
+purpose "Play wav or raw audio."
+
 include(header.m4)
 include(loglevel.m4)
 
diff --git a/recv_common.c b/recv_common.c
index fe745917..2ea8a599 100644
--- a/recv_common.c
+++ b/recv_common.c
@@ -106,7 +106,8 @@ void print_receiver_helps(unsigned flags)
 		struct receiver *r = receivers + i;
 		if (!r->help.short_help)
 			continue;
-		printf_or_die("\nOptions for %s:", r->name);
+		printf_or_die("\n%s: %s", r->name,
+			r->help.purpose);
 		ggo_print_help(&r->help, flags);
 	}
 }
diff --git a/write_common.c b/write_common.c
index b61b9384..33ef8be6 100644
--- a/write_common.c
+++ b/write_common.c
@@ -136,7 +136,8 @@ void print_writer_helps(unsigned flags)
 
 		if (!w->help.short_help)
 			continue;
-		printf_or_die("\nOptions for %s:", writer_names[i]);
+		printf_or_die("\n%s: %s", writer_names[i],
+			w->help.purpose);
 		ggo_print_help(&w->help, flags);
 	}
 }
-- 
2.39.2