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.5