Improve help/man page of para_filter.
authorAndre Noll <maan@systemlinux.org>
Sat, 6 Dec 2008 11:09:17 +0000 (12:09 +0100)
committerAndre Noll <maan@systemlinux.org>
Sat, 6 Dec 2008 11:09:17 +0000 (12:09 +0100)
This patch makes para_filter to tie together the help texts from
all its filters.

21 files changed:
Makefile.in
aacdec_filter.c
amp_filter.c
amp_filter.ggo
audiod.c
audiod_command.c
compress_filter.c
compress_filter.ggo
configure.ac
error.h
filter.c
filter.ggo
filter.h
filter_common.c
ggo.c [new file with mode: 0644]
ggo.h [new file with mode: 0644]
grab_client.c
mp3dec_filter.c
oggdec_filter.c
oggdec_filter.ggo
wav_filter.c

index 9e60b0d..9e78b67 100644 (file)
@@ -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 ./$< > $@
index 956f338..8eddc0e 100644 (file)
@@ -14,6 +14,7 @@
 
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "error.h"
 #include "string.h"
index 2f05260..f6e2205 100644 (file)
@@ -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
+       };
 }
index 1849dc3..865df3a 100644 (file)
@@ -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.
 "
index b9bd852..80d14c4 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"
index fe8143b..27ef63c 100644 (file)
@@ -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"
index bf129b4..6589839 100644 (file)
@@ -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
+       };
 }
index 3f4f8e2..74dcbc0 100644 (file)
@@ -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
index 4eb8c54..2429bfb 100644 (file)
@@ -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 89910a4..37ff48a 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[];
index b97bdaa..0ffb723 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;
 }
 
 /**
index 111e87c..5376a6f 100644 (file)
@@ -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
index 39cec9b..0c3ac70 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);
index 29d6c95..45f5760 100644 (file)
@@ -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, ...);
index 77d3616..b9d7014 100644 (file)
@@ -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"
index aa2ab51..8fa7094 100644 (file)
@@ -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
+       };
 }
index 689fc7a..7c79fd5 100644 (file)
@@ -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
+       };
 }
index f088b93..e2d653d 100644 (file)
@@ -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.
 "
index 3fce556..d30b018 100644 (file)
@@ -10,6 +10,7 @@
 
 #include "list.h"
 #include "sched.h"
+#include "ggo.h"
 #include "filter.h"
 #include "string.h"
 #include "portable_io.h"