Provide "purpose" texts.
authorAndre Noll <maan@systemlinux.org>
Sun, 7 Apr 2013 02:31:51 +0000 (02:31 +0000)
committerAndre Noll <maan@systemlinux.org>
Thu, 13 Jun 2013 16:29:03 +0000 (18:29 +0200)
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.

30 files changed:
filter_common.c
ggo.c
ggo.h
m4/gengetopt/afh.m4
m4/gengetopt/afh_recv.m4
m4/gengetopt/alsa_write.m4
m4/gengetopt/amp_filter.m4
m4/gengetopt/ao_write.m4
m4/gengetopt/audioc.m4
m4/gengetopt/audiod.m4
m4/gengetopt/client.m4
m4/gengetopt/compress_filter.m4
m4/gengetopt/dccp_recv.m4
m4/gengetopt/fade.m4
m4/gengetopt/file_write.m4
m4/gengetopt/filter.m4
m4/gengetopt/gui.m4
m4/gengetopt/http_recv.m4
m4/gengetopt/mp3dec_filter.m4
m4/gengetopt/oss_write.m4
m4/gengetopt/osx_write.m4
m4/gengetopt/play.m4
m4/gengetopt/prebuffer_filter.m4
m4/gengetopt/recv.m4
m4/gengetopt/resample_filter.m4
m4/gengetopt/server.m4
m4/gengetopt/udp_recv.m4
m4/gengetopt/write.m4
recv_common.c
write_common.c

index 787255a..2616c9b 100644 (file)
@@ -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 d8d56c0..3a441db 100644 (file)
--- 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 12574db..671fc01 100644 (file)
--- 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, \
        }
index beb8469..6fd4ab6 100644 (file)
@@ -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>
index 2c34c4d..f4da9d9 100644 (file)
@@ -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
index 54b2c0c..04b4963 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Native ALSA output plugin."
+
 include(header.m4)
 
 <qu>
index f3907bf..2d4d4ce 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Amplify the decoded audio stream."
+
 option "amp" a
 #~~~~~~~~~~~~~
 "amplification value"
index 4deb58b..ccee4ee 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin for libao."
+
 include(header.m4)
 <qu>
 
index 736d707..2865900 100644 (file)
@@ -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
index 5522a56..7bae343 100644 (file)
@@ -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)
index 23f7c1e..a14b59c 100644 (file)
@@ -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)
index 739e4f0..8c701a0 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Dynamically adjust the volume of an audio stream."
+
 option "blocksize" b
 #~~~~~~~~~~~~~~~~~~~
 "adjust block size"
index 0e556dd..f8191fe 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Receive a DCCP audio stream."
+
 option "host" i
 "ip or host"
 string default="localhost"
index da7a27e..8b81975 100644 (file)
@@ -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)
index 560d55a..045b865 100644 (file)
@@ -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"
index c7337be..baf6ecd 100644 (file)
@@ -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>
index bafd325..af1ca14 100644 (file)
@@ -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)
index 7544d77..b8ece39 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Receive an HTTP audio stream."
+
 include(header.m4)
 
 <qu>
index aa8ef45..a6425b3 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Decode an mp3 stream."
+
 include(header.m4)
 
 <qu>
index 3aaba17..352bea5 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin for the Open Sound System."
+
 option "device" d
 #~~~~~~~~~~~~~~~~
 "set PCM device"
index 2d49b40..5add6f2 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Output plugin for Mac OS coreaudio."
+
 section "osx options"
 #####################
 
index 230e838..ea41f56 100644 (file)
@@ -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
index a428897..9e84dcf 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Delay processing of an audio stream."
+
 option "duration" d
 #~~~~~~~~~~~~~~~~~~
 "prebuffer time"
index c7b89fe..086c9c0 100644 (file)
@@ -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)
 
index 33dd667..4f4af4b 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-version --no-help"
 
+purpose "Transform raw audio to a different sample rate."
+
 include(header.m4)
 
 option "converter" C
index d1293a0..6596d93 100644 (file)
@@ -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)
index 78c3257..48770d9 100644 (file)
@@ -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"
index c022bc8..8b13f45 100644 (file)
@@ -1,5 +1,7 @@
 args "--no-handle-help --no-handle-version"
 
+purpose "Play wav or raw audio."
+
 include(header.m4)
 include(loglevel.m4)
 
index fe74591..2ea8a59 100644 (file)
@@ -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);
        }
 }
index b61b938..33ef8be 100644 (file)
@@ -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);
        }
 }