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.

diff --git a/filter_common.c b/filter_common.c
index 787255af51a6441516a3a90f9cbe1e9f79808c1a..2616c9bdfc940a3415ef6e5abd3a446d4e859b7e 100644 (file)
--- 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 d8d56c03faa42e86a0c2d7862adb72a0b4603f04..3a441db1fa42f16d701dfa7492cf4bbaf22744f9 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 12574dbada6ce84ca6ab7a571b4919923d80dfaa..671fc01c7f6b4269d30c7214d8ec29fef7cfb4e6 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, \
        }

diff --git a/m4/gengetopt/afh.m4 b/m4/gengetopt/afh.m4
index beb846961b79dde7b7bdbdf9663c671b5857e080..6fd4ab6921b4654bead1b0386e38b5711d8e4333 100644 (file)
--- 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 2c34c4decd9072cc8176f194854eb102895d9d08..f4da9d992c8ffc078710a95e182a764433e9ddf8 100644 (file)
--- 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 54b2c0cb3f105259a26a68f9329f05ae09c70704..04b4963d3a9fbe6bc342ffa808ae6f33a8a168fa 100644 (file)
--- 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 f3907bf42b8eee1b273050940b976a25faff0f70..2d4d4ce6ca5166355fa99bdbf28884a2a213daff 100644 (file)
--- 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 4deb58b7e2fcc3e20d79e2aa7d1e4736d0a298d0..ccee4ee62f5fc23903857f9ba29e0b470792548a 100644 (file)
--- 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 736d70727d6d643e543a8911da4c73ce209d65e6..2865900e7a4fb00d362e5714faa732aed2f18f63 100644 (file)
--- 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 5522a56dc0af4b10bcf0dfcd3172e426a0ee174c..7bae3435d19f20ed0a4f496b947cd1195e17bad5 100644 (file)
--- 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 23f7c1e65bd7e5aeb23b14a478278596b417bed9..a14b59c0aa4d2299659b18d71af4364c9f8fd6df 100644 (file)
--- 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 739e4f0290fa3b39152cfb5fa5d6291f5619321f..8c701a03987fe6c8e21c25a40475483b6d0bd7f7 100644 (file)
--- 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 0e556dd78c950c00ad4e8d154cded212a9e93a73..f8191fe003bec99957155d71c8ef5a5be694376b 100644 (file)
--- 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 da7a27e2c632032ccce20a528e685bf3dd7a58a1..8b81975b36a0a3ba4f08bf21af39c8a9e946ea43 100644 (file)
--- 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 560d55aa5f3ad18a1a72a52631e3c11aef3add45..045b8657236b57ed58b8ececdd8cd183481acb53 100644 (file)
--- 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 c7337beb3a61989460067e4916bab1f6e3eabd27..baf6ecdb974a72ec7ceb8058d13e2264e1b448ad 100644 (file)
--- 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 bafd325bdea98d831db842ff08931815754aec53..af1ca1452b2e82e6172831bdfdadc9d01e546b3a 100644 (file)
--- 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 7544d77d1ebf518a903b8e0cef2d0a704c8bc581..b8ece39d9809a85dfa4e3e0d7b09afefd2475954 100644 (file)
--- 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 aa8ef4530a00bd2230670e1c90ed2945c06e7dd0..a6425b3e7f296485101c52e8dc5fa72a9acac355 100644 (file)
--- 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 3aaba17ab0417c21f9f0d11c14d7864d7202de0b..352bea5bc3cfe2e0d2d431c2e4b7c0fb1f31f60f 100644 (file)
--- 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 2d49b406637596994b4edb6f45d556fc6b1f985c..5add6f2e6e340f5eacd4260d33e4166522751261 100644 (file)
--- 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 230e8388e16cb06843a2fa3680f22a160081cf88..ea41f562fe504e00d0be096b83f174d4dc41129d 100644 (file)
--- 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 a42889721cb5521e43b9965d71a45fd1738fef5c..9e84dcfcea04934a7f5a2f3f776d5afabe0b6bc1 100644 (file)
--- 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 c7b89fe4981bb0dad0ea997b057e3611dd762f7e..086c9c0a5c73049630bda211a8433ddfebba3963 100644 (file)
--- 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 33dd6674e032d1f930034ca767edc4411e80ec78..4f4af4b0c41182d21faecf888926488bb372095e 100644 (file)
--- 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 d1293a02150fa287841875588c81a273f4617b20..6596d9340acb8f6746e01b13031c9c3d018d151e 100644 (file)
--- 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 78c3257d59838cf61e664868fe5761d858c83a2a..48770d974dc495f205a1538367511600fee97281 100644 (file)
--- 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 c022bc8f24c83d6ed490cde57159d64b7e571538..8b13f457a1480a3f430b31c478d5237ae9a0ba61 100644 (file)
--- 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 fe745917a0e1743733dfb1876bcb89952ca9e322..2ea8a5992034419cf0375bae43851172c136b765 100644 (file)
--- 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 b61b938459e447294024190b61cc091489660b32..33ef8be60d0a5fa04e2acd4d21f9b9ad7fc75d2a 100644 (file)
--- 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);
        }
 }