From: Andre Noll Date: Wed, 2 Apr 2008 23:11:42 +0000 (+0200) Subject: Rewrite audiod help text. X-Git-Tag: v0.3.2~14 X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=1afd45b1b5c80e73c017ef27c54f0696a40f4e33;p=paraslash.git Rewrite audiod help text. --- diff --git a/Makefile.in b/Makefile.in index 1ae7ce6a..e9c498c1 100644 --- a/Makefile.in +++ b/Makefile.in @@ -139,7 +139,7 @@ man/man1/para_server.1: para_server $(server_command_lists) man/man1/para_audiod.1: para_audiod audiod_command_list.man mkdir -p man/man1 - help2man -N -i audiod_command_list.man ./para_audiod > $@ + help2man -h --detailed-help -N -i audiod_command_list.man ./para_audiod > $@ man/man1/%.1: % mkdir -p man/man1 diff --git a/NEWS b/NEWS index f6fcba9d..11e78f5e 100644 --- a/NEWS +++ b/NEWS @@ -4,6 +4,7 @@ NEWS ---------------------------------------------- 0.3.2 (to be announced) "probabilistic parity" ---------------------------------------------- +The new para_afh executable, scheduling and documentation improvements. - new ls option: -lc (list chunk table) - new executable: para_afh, the stand-alone audio file handler tool @@ -11,6 +12,7 @@ NEWS also reduces the memory usage of commands that produce large amounts of output. - major scheduler and audiod cleanups. + - more detailed and much nicer man pages. --------------------------------------- 0.3.1 (2008-02-23) "liquid interaction" diff --git a/audiod.ggo b/audiod.ggo index e25caa24..41af85e9 100644 --- a/audiod.ggo +++ b/audiod.ggo @@ -1,188 +1,215 @@ -section "general options" -#~~~~~~~~~~~~~~~~~~~~~~~~ +######################### +section "General options" +######################### -option "user" u -#~~~~~~~~~~~~~~ - -"run as user 'name'. Read the output of -'para_server -h' for more information on this -option." - - string typestr="name" - optional - -option "group" g -#~~~~~~~~~~~~~~~ - -"set group id to 'group'. Read the output of -'para_server -h' for more information on this -option." - - string typestr="group" - optional +text " + These options are identical to their counterparts in para_server + and are discussed in detail there. +" option "loglevel" l #~~~~~~~~~~~~~~~~~~ +"set loglevel (1-6)" +int typestr="level" +default="4" +optional -"set loglevel (0-6)" - - int typestr="level" - default="4" - optional +option "logfile" L +#~~~~~~~~~~~~~~~~~ +"where to write log output" +string typestr="filename" +optional option "daemon" d #~~~~~~~~~~~~~~~~ - "run as background daemon" +flag off +dependon="logfile" - flag off - +option "user" u +#~~~~~~~~~~~~~~ +"run as the given user" +string typestr="name" +optional -option "force" F +option "group" g #~~~~~~~~~~~~~~~ +"set group id" +string typestr="group" +optional -"force startup even if -socket exists" - - flag off - -option "logfile" L -#~~~~~~~~~~~~~~~~~ - -"(default=stdout/stderr)" +######################## +section "Audiod options" +######################## - string typestr="filename" - optional +option "force" F +#~~~~~~~~~~~~~~~ +"force startup" +flag off +details=" + If this flag is not given, para_audiod refuses to start if the + well-known socket file (see the --socket option) already exists + because this usually means that para_audiod is already running + and listening on that socket. After a crash or if para_audiod + received a SIGKILL signal, a stale socket file might remain and + you have to use --force once to force startup of para_audiod. +" option "mode" m #~~~~~~~~~~~~~~ - -"mode to use on startup (on/off/sb)" - - string typestr="mode" - default="on" - optional +"startup mode" +string typestr="mode" +default="on" +optional +details=" + Para_audiod supports three modes of operation: On, off and + standby (sb). This option selects the mode that should be + used on startup. If para_audiod operates in \"on\" mode, it + will connect to para_server in order to receive its status + information. If para_server announces the availability of an + audio stream, para_audiod will automatically download, decode + and play the audio stream according to the given stream I/O + options, see below. + + In \"standby\" mode, para_audiod will only receive the + status information from para_server but will not download + the audio stream. + + In \"off\" mode, para_audiod does not connect para_server at + all, but still listens on the local socket for connections. +" option "socket" s - -"well-known socket to listen on -(default=/var/paraslash/audiod_sock.)" - - string typestr="filename" - optional +#~~~~~~~~~~~~~~~~ +"well-known socket" +string typestr="filename" +optional +details=" + Para_audiod uses a \"well-known\" socket to listen + on for connections from para_audioc. This socket is a + special file in the file system; its location defaults to + /var/paraslash/audiod_sock.. + + para_audioc, the client program used to connect to para_audiod, + opens this socket in order to talk to para_audiod. If the + default value for para_audiod is changed, para_audioc must be + instructed to use also \"filename\" for connecting para_audiod. +" option "user_allow" - #~~~~~~~~~~~~~~~~~~~~ - -"allow this user to connect to para_audiod. -May be specified multiple times. If not -specified at all, all users are allowed to -connect." - - int typestr="uid" - default="-1" - optional - multiple - +"allow thus uid" +int typestr="uid" +default="-1" +optional +multiple +details=" + Allow the user identified by \"uid\" to connect to para_audiod. + May be specified multiple times. If not specified at all, + all users are allowed to connect. + + This feature requires unix socket credentials and is currently + only supported on Linux systems. On other operating systems, + the option is silently ignored and all local users are allowed + to connect to para_audiod. +" option "clock_diff_count" - #~~~~~~~~~~~~~~~~~~~~~~~~~~ +"sync clock on startup" +int typestr="count" +default="0" +optional +details=" + Check the clock difference between the host running para_server + and the local host running para_audiod that many times before + starting any stream I/0. Set this to non-zero for non-local + setups if the clocks of these two hosts are not syncronized + by ntp or similar. +" -"check the clock difference between -server_host (the host running para_server) -and the local host (running para_audiod) -that many times before starting any stream -I/0. Set this to non-zero for non-local -setups if the clocks of these two hosts are -not syncronized by ntp or similar." - - int typestr="count" - default="0" - optional - - -section "stream i/o options." -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +############################# +section "Stream I/O options" +############################# option "receiver" r #~~~~~~~~~~~~~~~~~~ - -"Select receiver. May be given multiple -times, once for each supported audio format. -'receiver_spec' consists of an audio format and -the receiver name, separated by a colon, and -any options for that receiver, seperated by -whitespace. If any receiver options are -present, the whole receiver argument must be -quoted. - -Example: - --r 'mp3:http -i www.paraslash.org -p 8009' +"select receiver" +string typestr="receiver_spec" +default="http" +optional +multiple +details=" + This option may be given multiple times, once for each + supported audio format. The \"receiver_spec\" consists of + an audio format and the receiver name, separated by a colon, + and any options for that receiver, seperated by whitespace. + If any receiver options are present, the whole receiver + argument must be quoted. + + Example: + + -r 'mp3:http -i my.host.org -p 8009' " - string typestr="receiver_spec" - default="http" - optional - multiple - option "no_default_filters" D #~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"Configure filters manually. If (and only -if) this option is set, the --filter options -take effect. Otherwise, the compiled-in -default filters mp3dec, oggdec and aacdec are -activated for mp3, ogg, aac streams respectively." - - flag off - +"Configure filters manually" +flag off +details=" + If (and only if) this option is set, the --filter options + (see below) take effect. Otherwise, the compiled-in default + filters mp3dec, oggdec and aacdec are activated for mp3, ogg, + aac streams respectively. +" option "filter" f #~~~~~~~~~~~~~~~~ +"Use non-default filters" +string typestr="filter_spec" +optional +multiple +dependon="no_default_filters" +details=" + This option may be given multiple times. The \"filter_spec\" + consists of an audio format, the name of the filter, and any + options for that filter. Mote that order matters. -"Select filter(s) manually. May be given -multiple times. filter_spec consists of an -audio format, the name of the filter, and any -options for that filter. + Examples: -Examples: - -f 'mp3:mp3dec' - -f 'mp3:compress --inertia 5 --damp 2' + --filter 'mp3:mp3dec' -Note that these options are ignored by default, -see --no_default_filters." - -string typestr="filter_spec" optional multiple + --filter 'mp3:compress --inertia 5 --damp 2' +" option "writer" w -#~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"Specify stream writer. - -May be given multiple times, even multiple -times for the same audio format. Default -value is 'alsa' for all supported audio -formats. Example: +#~~~~~~~~~~~~~~~~ +"Specify stream writer." +string typestr="writer_spec" +optional +multiple +details=" + May be given multiple times, even multiple times for the same + audio format. Default value is \"alsa\" for all supported + audio formats. Example: - -w 'aac:osx' + --writer 'aac:osx' " - string typestr="writer_spec" - optional - multiple - option "stream_delay" - #~~~~~~~~~~~~~~~~~~~~~~ - -"Time to add to para_server's start_time. - -Amount of time to be added to the server, before data is sent to -the writer. Useful for syncronizing the audio output of clients." - - int typestr="milliseconds" - default="200" - optional +"time for client sync" +int typestr="milliseconds" +default="200" +optional +details=" + Add the given amount of milliseconds to the stream start time + announced by para_server and do not send data to the writer + before that time (modulo clock difference). + + This is useful mainly for syncronizing the audio output of + different clients. +"