Improve help/man page of para_filter.

This patch makes para_filter to tie together the help texts from
all its filters.

diff --git a/Makefile.in b/Makefile.in
index 9e60b0df1f399b94bc1c90c7915366bb083fa970..9e78b67dabb8e924f003a21ef0c87f2078568410 100644 (file)
--- a/Makefile.in
+++ b/Makefile.in
@@ -116,6 +116,7 @@ grab_client.cmdline.h grab_client.cmdline.c: grab_client.ggo
                audioc.ggo) O="--unamed-opts=command";; \
                fsck.ggo) O="--unamed-opts=table";; \
                afh.ggo) O="--unamed-opts=audio_file";; \
+               filter.ggo) O="--no-handle-help";; \
        esac; \
        if test $< != fsck.ggo; then O="$$O --conf-parser "; fi; \
        gengetopt $$O \
@@ -143,6 +144,10 @@ man/man1/para_audiod.1: para_audiod audiod_command_list.man
        mkdir -p man/man1
        help2man -h --detailed-help -N -i audiod_command_list.man ./para_audiod > $@
 
+man/man1/para_filter.1: para_filter
+       mkdir -p man/man1
+       help2man -h --detailed-help -N ./$< > $@
+
 man/man1/%.1: %
        mkdir -p man/man1
        help2man -N ./$< > $@

diff --git a/aacdec_filter.c b/aacdec_filter.c
index 956f338db741586e7ee784d2e3523a41783fbf25..8eddc0e71566d7c9cb816a5d52d70e5d35bb5b84 100644 (file)
--- a/aacdec_filter.c
+++ b/aacdec_filter.c
@@ -14,6 +14,7 @@
 
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "error.h"
 #include "string.h"

diff --git a/amp_filter.c b/amp_filter.c
index 2f05260157de9e7103d1a717812981773489fd59..f6e22059e3f2432a2c1c69751415e789569b4fe7 100644 (file)
--- a/amp_filter.c
+++ b/amp_filter.c
@@ -10,6 +10,7 @@
 #include "amp_filter.cmdline.h"
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "string.h"
 #include "error.h"
@@ -92,9 +93,17 @@ static void amp_open(struct filter_node *fn)
  */
 void amp_filter_init(struct filter *f)
 {
+       struct amp_filter_args_info dummy;
+
+       amp_cmdline_parser_init(&dummy);
        f->open = amp_open;
        f->close = amp_close;
        f->convert = amp_convert;
-       f->print_help = amp_cmdline_parser_print_help;
        f->parse_config = amp_parse_config;
+       f->help = (struct ggo_help) {
+               .purpose = amp_filter_args_info_purpose,
+               .usage = amp_filter_args_info_usage,
+               .short_help = amp_filter_args_info_help,
+               .detailed_help = amp_filter_args_info_detailed_help
+       };
 }

diff --git a/amp_filter.ggo b/amp_filter.ggo
index 1849dc3ab4fcc3e6e2ad8dbeddf93931978cbd8e..865df3ac4048b330daf9055ffb47c2b1a2999eb3 100644 (file)
--- a/amp_filter.ggo
+++ b/amp_filter.ggo
@@ -1,6 +1,5 @@
-section "The amplify filter"
-
 option "amp" a
+#~~~~~~~~~~~~~
 "amplification value"
 int typestr="number"
 default="32"
@@ -10,12 +9,9 @@ details="
        which the amplitude of the audio stream is multiplied. The
        formula for the scaling factor is
 
-               factor = 1 + amp / 64
+               factor = 1 + amp / 64.
 
-       amp value       scaling factor
-       ~~~~~~~~~       ~~~~~~~~~~~~~~
-       0               1
-       32              1.5
-       64              2
-       128             3
+       For example, an amplifiction value of zero results in a
+       scaling factor of one while an amplification value of 64
+       means to double the volume.
 "

diff --git a/audiod.c b/audiod.c
index b9bd852aeba0ee3c65f9eec62ed6de977d41126a..80d14c485c63106a476ec7d52d4f511163576747 100644 (file)
--- a/audiod.c
+++ b/audiod.c
@@ -15,6 +15,7 @@
 #include "list.h"
 #include "sched.h"
 #include "recv.h"
+#include "ggo.h"
 #include "filter.h"
 #include "grab_client.cmdline.h"
 #include "grab_client.h"

diff --git a/audiod_command.c b/audiod_command.c
index fe8143ba928651e1aef5ccdb22d70e4200f0672f..27ef63caea22f9af45d9a951a5df39d1cb078210 100644 (file)
--- a/audiod_command.c
+++ b/audiod_command.c
@@ -14,6 +14,7 @@
 #include "list.h"
 #include "close_on_fork.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "grab_client.cmdline.h"
 #include "grab_client.h"

diff --git a/compress_filter.c b/compress_filter.c
index bf129b4ad13b939ec7ceb7cbbd2cf6d3e9563225..658983915fa7849e647d044646f202b3b095fbd9 100644 (file)
--- a/compress_filter.c
+++ b/compress_filter.c
@@ -14,6 +14,7 @@
 #include "compress_filter.cmdline.h"
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "string.h"
 #include "error.h"
@@ -120,9 +121,17 @@ static void open_compress(struct filter_node *fn)
  */
 void compress_filter_init(struct filter *f)
 {
+       struct compress_filter_args_info dummy;
+
+       compress_cmdline_parser_init(&dummy);
        f->open = open_compress;
        f->close = close_compress;
        f->convert = compress;
-       f->print_help = compress_cmdline_parser_print_help;
        f->parse_config = compress_parse_config;
+       f->help = (struct ggo_help) {
+               .purpose = compress_filter_args_info_purpose,
+               .usage = compress_filter_args_info_usage,
+               .short_help = compress_filter_args_info_help,
+               .detailed_help = compress_filter_args_info_detailed_help
+       };
 }

diff --git a/compress_filter.ggo b/compress_filter.ggo
index 3f4f8e2ea8ccabc745bc1770809b96e43063b728..74dcbc0332753e1011962a62c9dbe961881b4d1f 100644 (file)
--- a/compress_filter.ggo
+++ b/compress_filter.ggo
@@ -1,7 +1,37 @@
-section "The dynamic audio range compressor"
+option "blocksize" b
+#~~~~~~~~~~~~~~~~~~~
+"adjust block size"
+int typestr="number"
+default="15"
+optional
+details = "
+       Larger blocksize means fewer volume adjustments per time unit.
+"
 
-option "blocksize" b "larger blocksize means fewer volume adjustments per time unit" int typestr="number" default="15" optional
-option "aggressiveness" a "controls the maximum amount to amplify by" int typestr="number" default="4" optional
-option "inertia" i "how much inertia ramping has" int typestr="number" default="6" optional
-option "target_level" t "target signal level (0-32768)" int typestr="number" default="20000" optional
-option "damp" d "if non-zero, scale down after normalizing" int typestr="number" default="0" optional
+option "aggressiveness" a
+#~~~~~~~~~~~~~~~~~~~~~~~~
+ "controls the maximum amount to amplify by"
+int typestr="number"
+default="4"
+optional
+
+option "inertia" i
+#~~~~~~~~~~~~~~~~~
+ "how much inertia ramping has"
+ int typestr="number"
+default="6"
+optional
+
+option "target_level" t
+#~~~~~~~~~~~~~~~~~~~~~~
+"target signal level (0-32768)"
+int typestr="number"
+default="20000"
+optional
+
+option "damp" d
+#~~~~~~~~~~~~~~
+"if non-zero, scale down after normalizing"
+int typestr="number"
+default="0"
+optional

diff --git a/configure.ac b/configure.ac
index 4eb8c5436ca9b0a7d9f3d068d2f9c6c3af050d61..2429bfbdf2512ca482bb81ba3641c336e6d09010 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -83,7 +83,7 @@ daemon stat crypt http_send close_on_fork ipc acl afh fade amp_filter
 dccp_send fd user_list chunk_queue afs osl aft mood score attribute blob ringbuffer
 playlist sha1 rbtree sched audiod grab_client filter_common wav_filter compress_filter
 http_recv dccp_recv recv_common write_common file_write audiod_command
-client_common recv stdout filter stdin audioc write client fsck exec send_common"
+client_common recv stdout filter stdin audioc write client fsck exec send_common ggo"
 
 all_executables="server recv filter audioc write client fsck afh"
 
@@ -96,7 +96,7 @@ receivers=" http dccp"
 senders=" http dccp"
 
 filter_cmdline_objs="filter.cmdline compress_filter.cmdline amp_filter.cmdline"
-filter_errlist_objs="filter_common wav_filter compress_filter filter string stdin stdout sched fd amp_filter"
+filter_errlist_objs="filter_common wav_filter compress_filter filter string stdin stdout sched fd amp_filter ggo"
 filter_ldflags=""
 filters=" compress wav amp"
 
@@ -110,7 +110,7 @@ audiod_cmdline_objs="audiod.cmdline grab_client.cmdline compress_filter.cmdline
 audiod_errlist_objs="audiod signal string daemon stat net
        time grab_client filter_common wav_filter compress_filter amp_filter http_recv dccp_recv
        recv_common fd sched write_common file_write audiod_command crypt
-       client_common"
+       client_common ggo"
 audiod_ldflags=""
 audiod_audio_formats=""
 

diff --git a/error.h b/error.h
index 89910a47cd028c0eeb851b428bf08afca928e8b2..37ff48a9463780220cd7e02b431d622080a432a4 100644 (file)
--- a/error.h
+++ b/error.h
@@ -28,6 +28,7 @@ DEFINE_ERRLIST_OBJECT_ENUM;
 #define IPC_ERRORS
 #define DCCP_SEND_ERRORS
 #define HTTP_SEND_ERRORS
+#define GGO_ERRORS
 
 
 extern const char **para_errlist[];

diff --git a/filter.c b/filter.c
index b97bdaaa3cbc9de39d62573da476495c73cc3e6a..0ffb723e218793a2ac69f4d905b643adb04667c3 100644 (file)
--- a/filter.c
+++ b/filter.c
@@ -11,6 +11,7 @@
 #include "filter.cmdline.h"
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "string.h"
 #include "stdin.h"
@@ -94,15 +95,44 @@ err:
        return ret;
 }
 
+__noreturn static void print_help_and_die(void)
+{
+       int i, d = conf.detailed_help_given;
+       const char **p = d? filter_args_info_detailed_help
+               : filter_args_info_help;
+
+       printf_or_die("%s\n\n", FILTER_CMDLINE_PARSER_PACKAGE "-"
+               FILTER_CMDLINE_PARSER_VERSION);
+       printf_or_die("%s\n\n", filter_args_info_usage);
+       for (; *p; p++)
+               printf_or_die("%s\n", *p);
+
+       printf_or_die("\nAvailable filters: \n\t");
+       FOR_EACH_SUPPORTED_FILTER(i)
+               printf_or_die("%s%s", i? " " : "", filters[i].name);
+       printf_or_die("\n\n");
+
+       FOR_EACH_SUPPORTED_FILTER(i) {
+               struct filter *f = filters + i;
+
+               if (!f->help.short_help)
+                       continue;
+               printf_or_die("Options for %s:\n", f->name);
+               ggo_print_help(&f->help, d);
+       }
+       exit(0);
+}
+
 static int parse_config(int argc, char *argv[])
 {
        static char *cf; /* config file */
        struct stat statbuf;
-       int i;
 
        if (filter_cmdline_parser(argc, argv, &conf))
                return -E_FILTER_SYNTAX;
        HANDLE_VERSION_FLAG("filter", conf);
+       if (conf.help_given || conf.detailed_help_given)
+               print_help_and_die();
        if (!cf) {
                char *home = para_homedir();
                cf = make_message("%s/.paraslash/filter.conf", home);
@@ -118,15 +148,7 @@ static int parse_config(int argc, char *argv[])
                if (filter_cmdline_parser_config_file(cf, &conf, &params))
                        return -E_FILTER_SYNTAX;
        }
-       if (!conf.list_filters_given)
-               return 1;
-       printf("available filters: ");
-       FOR_EACH_SUPPORTED_FILTER(i)
-               printf("%s%s%s", i? " " : "", filters[i].name,
-                       filters[i].parse_config? "*": "");
-       printf("\nFilters marked with \"*\" have further command line options. Try\n"
-               "\tpara_filter -f '<filtername> -h'\nfor more information.\n");
-       exit(EXIT_SUCCESS);
+       return 1;
 }
 
 /**

diff --git a/filter.ggo b/filter.ggo
index 111e87c698bcfb33441f47d971cb94e02b5ef5fd..5376a6f8c73996c8e85444cfb781f1b755b03911 100644 (file)
--- a/filter.ggo
+++ b/filter.ggo
@@ -1,17 +1,24 @@
-option "loglevel" l "set loglevel (0-6)" int typestr="level" default="4" optional
-option "filter" f "Specify filter.
+option "loglevel" l
+#~~~~~~~~~~~~~~~~~~
+ "set loglevel (0-6)"
+int typestr="level"
+default="4"
+optional
 
-May be given multiple times to 'pipe' the stream
-through arbitrary many filters in an efficient
-way.  The same filter may appear more than once,
-order matters.
+option "filter" f
+#~~~~~~~~~~~~~~~~
+"Specify filter."
+string typestr="filter_spec"
+optional
+multiple
+details="
+       May be given multiple times to 'pipe' the stream through
+       arbitrary many filters in an efficient way.  The same filter
+       may appear more than once, order matters.
 
-Filter options may be specified for each '-f'
-option separately. Note that you will have to
-quote these options like this:
+       Filter options may be specified for each '-f' option
+       separately. Note that you will have to quote these options
+       like this:
 
-       -f 'compress --inertia 5 --damp 2'
+               -f 'compress --inertia 5 --damp 2'
 "
-string typestr="filter_spec" optional multiple
-
-option "list_filters" L "print list of available filters and exit" flag off

diff --git a/filter.h b/filter.h
index 39cec9ba03f4cbee46497b43fda7bdebc7b63dbb..0c3ac70834b6c3909bd59bc87b9121811c6d3620 100644 (file)
--- a/filter.h
+++ b/filter.h
@@ -183,13 +183,6 @@ struct filter {
         * by the open() function.
         */
        void (*close)(struct filter_node *fn);
-       /**
-        * Print the help text for this filter and exit.
-        *
-        * This is optional and it is not necessary to initialize this pointer if
-        * the filter does not have a help text.
-        */
-       void (*print_help)(void);
        /**
         * A pointer to the filter's command line parser.
         *
@@ -203,6 +196,8 @@ struct filter {
         * argv. On failure, a negative paraslash error code must be returned.
         */
        int (*parse_config)(int argc, char **argv, void **config);
+
+       struct ggo_help help;
 };
 
 void close_filters(struct filter_chain *fc);

diff --git a/filter_common.c b/filter_common.c
index 29d6c957498216a9cec77b6ccd4a7f03b65385aa..45f576050c6f34a56dfb8f6cfff495478466f212 100644 (file)
--- a/filter_common.c
+++ b/filter_common.c
@@ -13,6 +13,7 @@
 #include "list.h"
 #include "sched.h"
 #include "fd.h"
+#include "ggo.h"
 #include "filter.h"
 #include "error.h"
 #include "string.h"

diff --git a/ggo.c b/ggo.c
new file mode 100644 (file)
index 0000000..55f1043
--- /dev/null
+++ b/ggo.c
@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file ggo.c Function for printing help. */
+
+
+#include "para.h"
+#include "ggo.h"
+
+__printf_1_2 void printf_or_die(const char *fmt, ...)
+{
+       va_list argp;
+       int ret;
+
+       va_start(argp, fmt);
+       ret = vprintf(fmt, argp);
+       va_end(argp);
+       if (ret >= 0)
+               return;
+       fprintf(stderr, "%s: %s\n", __FUNCTION__, strerror(errno));
+}
+
+void ggo_print_help(struct ggo_help *help, int detailed_help)
+{
+       const char **p;
+
+       if (!help)
+               return;
+       if (detailed_help)
+               p = help->detailed_help;
+       else
+               p = help->short_help;
+       if (!p)
+               return;
+       p += 3; /* skip -h and -V */
+       for (; *p; p++)
+               printf_or_die("\t%s\n", *p);
+}

diff --git a/ggo.h b/ggo.h
new file mode 100644 (file)
index 0000000..40723ea
--- /dev/null
+++ b/ggo.h
@@ -0,0 +1,9 @@
+struct ggo_help {
+       const char *purpose;
+       const char *usage;
+       const char **short_help;
+       const char **detailed_help;
+};
+
+void ggo_print_help(struct ggo_help *help, int detailed_help);
+void printf_or_die(const char *fmt, ...);

diff --git a/grab_client.c b/grab_client.c
index 77d3616d2c2e41b3caf32f5fea13d54cf778642b..b9d70147bb63de054005be4eb17f13e5ae42ee43 100644 (file)
--- a/grab_client.c
+++ b/grab_client.c
@@ -18,6 +18,7 @@
 #include "grab_client.cmdline.h"
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "grab_client.h"
 #include "audiod.h"

diff --git a/mp3dec_filter.c b/mp3dec_filter.c
index aa2ab510240e448c410dddc90fb445e471859445..8fa7094480285b5768c1f0cf991a559e13a5f1c7 100644 (file)
--- a/mp3dec_filter.c
+++ b/mp3dec_filter.c
@@ -10,6 +10,7 @@
 #include "mp3dec_filter.cmdline.h"
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "error.h"
 #include <mad.h>
@@ -150,8 +151,17 @@ err:
  */
 void mp3dec_filter_init(struct filter *f)
 {
+       struct mp3dec_filter_args_info dummy;
+
+       mp3dec_cmdline_parser_init(&dummy);
        f->open = mp3dec_open;
        f->convert = mp3dec;
        f->close = mp3dec_close;
        f->parse_config = mp3dec_parse_config;
+       f->help = (struct ggo_help) {
+               .purpose = mp3dec_filter_args_info_purpose,
+               .usage = mp3dec_filter_args_info_usage,
+               .short_help = mp3dec_filter_args_info_help,
+               .detailed_help = mp3dec_filter_args_info_detailed_help
+       };
 }

diff --git a/oggdec_filter.c b/oggdec_filter.c
index 689fc7aac57739ba23989616d4e8cbfb1ed761b1..7c79fd50a403423621ece3f10f335925642690bc 100644 (file)
--- a/oggdec_filter.c
+++ b/oggdec_filter.c
@@ -11,6 +11,7 @@
 #include "oggdec_filter.cmdline.h"
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "error.h"
 #include "string.h"
@@ -195,9 +196,17 @@ err:
  */
 void oggdec_filter_init(struct filter *f)
 {
+       struct oggdec_filter_args_info dummy;
+
+       oggdec_cmdline_parser_init(&dummy);
        f->open = ogg_open;
        f->close = ogg_close;
        f->convert = ogg_convert;
-       f->print_help = oggdec_cmdline_parser_print_help;
        f->parse_config = oggdec_parse_config;
+       f->help = (struct ggo_help) {
+               .purpose = oggdec_filter_args_info_purpose,
+               .usage = oggdec_filter_args_info_usage,
+               .short_help = oggdec_filter_args_info_help,
+               .detailed_help = oggdec_filter_args_info_detailed_help
+       };
 }

diff --git a/oggdec_filter.ggo b/oggdec_filter.ggo
index f088b9379b39104eaf30fdabeb8acd442f9cd904..e2d653d7dafc8674ea95eff31197597284ae29e3 100644 (file)
--- a/oggdec_filter.ggo
+++ b/oggdec_filter.ggo
@@ -16,6 +16,6 @@ int typestr="kilobyte"
 default="16"
 optional
 details="
-       The oggdec filter waits until at least that many bytes are available
-       in the input buffer.
+       On startup, defer decoding until that many kilobytes are
+       available in the input buffer.
 "

diff --git a/wav_filter.c b/wav_filter.c
index 3fce556d5d1ecb514b0cffeec869103ff0bec178..d30b018de4f6f1a8554e1619ba7e97486d7c7b3e 100644 (file)
--- a/wav_filter.c
+++ b/wav_filter.c
@@ -10,6 +10,7 @@
 
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "string.h"
 #include "portable_io.h"