From 6442f07bb08eb6e557086587f997b1785ea18ef7 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Sat, 6 Dec 2008 12:09:17 +0100 Subject: [PATCH] Improve help/man page of para_filter. This patch makes para_filter to tie together the help texts from all its filters. --- Makefile.in | 5 +++++ aacdec_filter.c | 1 + amp_filter.c | 11 ++++++++++- amp_filter.ggo | 14 +++++--------- audiod.c | 1 + audiod_command.c | 1 + compress_filter.c | 11 ++++++++++- compress_filter.ggo | 42 ++++++++++++++++++++++++++++++++++++------ configure.ac | 6 +++--- error.h | 1 + filter.c | 42 ++++++++++++++++++++++++++++++++---------- filter.ggo | 33 ++++++++++++++++++++------------- filter.h | 9 ++------- filter_common.c | 1 + ggo.c | 41 +++++++++++++++++++++++++++++++++++++++++ ggo.h | 9 +++++++++ grab_client.c | 1 + mp3dec_filter.c | 10 ++++++++++ oggdec_filter.c | 11 ++++++++++- oggdec_filter.ggo | 4 ++-- wav_filter.c | 1 + 21 files changed, 202 insertions(+), 53 deletions(-) create mode 100644 ggo.c create mode 100644 ggo.h diff --git a/Makefile.in b/Makefile.in index 9e60b0df..9e78b67d 100644 --- 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 956f338d..8eddc0e7 100644 --- 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 2f052601..f6e22059 100644 --- 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 1849dc3a..865df3ac 100644 --- 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 b9bd852a..80d14c48 100644 --- 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 fe8143ba..27ef63ca 100644 --- 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 bf129b4a..65898391 100644 --- 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 3f4f8e2e..74dcbc03 100644 --- 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 4eb8c543..2429bfbd 100644 --- 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 89910a47..37ff48a9 100644 --- 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 b97bdaaa..0ffb723e 100644 --- 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, ¶ms)) 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 ' -h'\nfor more information.\n"); - exit(EXIT_SUCCESS); + return 1; } /** diff --git a/filter.ggo b/filter.ggo index 111e87c6..5376a6f8 100644 --- 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 39cec9ba..0c3ac708 100644 --- 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 29d6c957..45f57605 100644 --- 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 index 00000000..55f10430 --- /dev/null +++ b/ggo.c @@ -0,0 +1,41 @@ +/* + * Copyright (C) 2008 Andre Noll + * + * 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 index 00000000..40723ea9 --- /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 77d3616d..b9d70147 100644 --- 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 aa2ab510..8fa70944 100644 --- 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 @@ -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 689fc7aa..7c79fd50 100644 --- 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 f088b937..e2d653d7 100644 --- 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 3fce556d..d30b018d 100644 --- 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" -- 2.39.5