Merge branch 'refs/heads/t/doc'
authorAndre Noll <maan@tuebingen.mpg.de>
Sun, 6 May 2018 08:54:47 +0000 (10:54 +0200)
committerAndre Noll <maan@tuebingen.mpg.de>
Sun, 6 May 2018 08:55:52 +0000 (10:55 +0200)
Some minor documentation improvements. Cooking for four months.

* refs/heads/t/doc:
  Fix bad grammar "allows <infinitive>".
  doc: Move filter examples to man page.
  doc: Move sender examples to manual page.

13 files changed:
NEWS.md
m4/lls/audioc.suite.m4
m4/lls/filter.suite.m4
m4/lls/include/log-timing.m4
m4/lls/play.suite.m4
m4/lls/server.suite.m4
m4/lls/server_cmd.suite.m4
mp.c
sched.c
sideband.h
vss.c
web/download.in.html
web/manual.md

diff --git a/NEWS.md b/NEWS.md
index 4fd9dcb..9ced85e 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -8,6 +8,8 @@ NEWS
 - para_gui no longer waits up to one second to update the screen when
 the geometry of the terminal changes.
 
+- Minor documentation improvements.
+
 ----------------------------------------
 0.6.1 (2017-09-23) "segmented iteration"
 ----------------------------------------
index 1c037bc..6ad8c71 100644 (file)
@@ -6,9 +6,9 @@ version-string = GIT_VERSION()
        purpose = communicate with para_audiod through a local socket
        non-opts-name = [command [options]]
        [description]
-               The client program to control para_audiod at runtime. It allows to
-               enable/disable streaming, to receive status info, or to grab the
-               audio stream at any point of the decoding process.
+               The client program to control para_audiod at runtime. It can
+               enable/disable streaming, receive status info, or grab the audio
+               stream at any point of the decoding process.
 
                If no command is given, para_audioc enters interactive mode.
        [/description]
index 0cd69eb..376e875 100644 (file)
@@ -4,9 +4,9 @@ version-string = GIT_VERSION()
 [supercommand para_filter]
        purpose = decode or process audio data from STDIN to STDOUT
        [description]
-               This program allows to specify a chain of filters which transform the
-               audio stream read from STDIN. A common mode of operation is to decode
-               an mp3 file with the mp3dec filter, but many other filters exist which
+               This program transforms the audio stream read from STDIN by chaining
+               one or more filters. A common mode of operation is to decode an
+               mp3 file with the mp3dec filter, but many other filters exist which
                transform the audio stream in different ways.
        [/description]
        m4_include(common-option-section.m4)
@@ -35,3 +35,15 @@ version-string = GIT_VERSION()
                        through all given filters (in a single thread without copying the
                        data). The same filter may appear more than once, and order matters.
                [/help]
+[section Examples]
+       .IP \(bu 4
+       Decode a wma file to wav format:
+       .EX
+       \       para_filter -f wmadec -f wav < file.wma > file.wav
+       .EE
+       .IP \(bu 4
+       Amplify a raw audio file by a factor of 1.5:
+       .EX
+       \       para_filter -f amp --amp 32 < foo.raw > bar.raw
+       .EE
+[/section]
index a7364e1..ba19be9 100644 (file)
@@ -3,7 +3,7 @@
        summary = show milliseconds in log messages
        [help]
                Selecting this option causes milliseconds to be included in
-               the log message output. This allows to measure the interval
+               the log message output. This allows measuring of the interval
                between log messages in milliseconds which is useful for
                identifying timing problems.
        [/help]
index 0fbba0c..4af2a05 100644 (file)
@@ -7,8 +7,8 @@ version-string = GIT_VERSION()
        purpose = command line audio player
        non-opts-name = <audio_file>...
        [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
+               para_play operates either in command mode or in insert mode. In insert
+               mode it presents a prompt and allows the user to enter commands like
                stop, play, pause etc. In command mode the current audio file and the
                playback position are shown and the program reads single key strokes
                from stdin. Keys may be mapped to commands so that the configured
index 5bba85d..6ffdc00 100644 (file)
@@ -159,10 +159,10 @@ version-string = GIT_VERSION()
                summary = make the http access control list a whitelist
                [help]
                        The default is to use blacklists, i.e. connections to the http sender
-                       are allowed unless the connecting host matches a pattern given by a
-                       http-access option. This allows to use access control the other way
-                       round: Connections are denied from hosts which are not explicitly
-                       allowed by one or more http-access options.
+                       are allowed unless the connecting host matches a pattern given by
+                       a http-access option. This option allows using access control lists
+                       the other way round: Connections are denied from hosts which are not
+                       explicitly allowed by one or more http-access options.
                [/help]
        [option http-access]
                summary = add an entry to the http access control list
@@ -247,9 +247,9 @@ version-string = GIT_VERSION()
                        (path MTU) of an incoming connection, i.e. on the largest packet size
                        that can be transmitted without causing fragmentation.
 
-                       This option allows to use a value less than the MPS in order to
-                       fine-tune application performance. Values greater than the MPS of an
-                       incoming connection can not be set.
+                       This option allows values less than the MPS in order to fine-tune
+                       application performance. Values greater than the MPS of an incoming
+                       connection can not be set.
                [/help]
        [option dccp-data-slices-per-group]
                summary = the number of non-redundant slices per FEC group
index 9378b7c..96ce530 100644 (file)
@@ -407,20 +407,45 @@ aux_info_prefix = Permissions:
 
 [subcommand sender]
        purpose = control paraslash senders
-       synopsis = [sender cmd [arguments]]
+       synopsis = [sender subcmd [arguments]]
        aux_info = VSS_READ | VSS_WRITE
        [description]
-               Send a command to a specific sender. The following commands are
-               available, but not all senders support every command.
+               This command executes a subcommand for the given sender, which is
+               one of "http", "dccp" or "udp". Various subcommands exist to print
+               information about the sender, to activate and deactivate the sender,
+               and to change the access permissions and targets. The following
+               subcommands are available:
 
-                      help, on, off, add, delete, allow, deny, status.
+                      help, status, on, off, allow, deny, add, delete.
 
-               The help command prints the help text of the given sender. If no
-               command is given the list of available senders is shown.
+               All senders support the first four commands. The "allow" and "deny"
+               commands are supported by the http and the dccp senders while "add"
+               and "delete" are only supported by the udp sender. If no sender is
+               given, the list of available senders is shown.
 
-               Example:
+               Examples:
+
+               Get help for the udp sender (contains further examples):
+
+                       sender udp help
+
+               Show the access control list and the number of connected clients of
+               the http sender:
+
+                       sender http status
+
+               Senders may be activated and deactivated independently of each
+               other. The following command switches off the dccp sender:
+
+                       sender dccp off
+
+               Add an UDP unicast for a client to the target list of the UDP sender:
+
+                       sender udp add client.foo.org
+
+               Start UDP multicast, using the default multicast address:
 
-                       para_client sender http help
+                       sender udp add 224.0.1.38
 
        [/description]
 
diff --git a/mp.c b/mp.c
index c5702c6..bade05b 100644 (file)
--- a/mp.c
+++ b/mp.c
@@ -6,7 +6,7 @@
  * This file contains the public and the private API of the flex/bison based
  * mood parser.
  *
- * The public API (at the bottom of the file) allows to parse the same mood
+ * The public API (at the bottom of the file) allows parsing the same mood
  * definition many times in an efficient manner.
  *
  * The first function to call is \ref mp_init(), which analyzes the given mood
@@ -61,8 +61,8 @@ struct mp_context {
  *
  * This function turns a generalized C99 string literal like "xyz\n" into a C
  * string (containing the three characters 'x', 'y' and 'z', followed by a
- * newline character and the terminating zero byte). The function allows to
- * specify different quote characters so that, for example, regular expression
+ * newline character and the terminating zero byte). The function receives
+ * quote characters as an argument so that, for example, regular expression
  * patterns enclosed in '/' can be parsed as well. To parse a proper string
  * literal, one has to pass two double quotes as the second argument.
  *
diff --git a/sched.c b/sched.c
index 4fc65b4..a290394 100644 (file)
--- a/sched.c
+++ b/sched.c
@@ -168,7 +168,7 @@ again:
  * \param tptr Identifies the task to reap.
  *
  * This function is similar to wait(2) in that it returns information about a
- * terminated task and allows to release the resources associated with the
+ * terminated task which allows releasing the resources associated with the
  * task. Until this function is called, the terminated task remains in a zombie
  * state.
  *
index 3023c7b..6973b84 100644 (file)
@@ -97,7 +97,7 @@ struct sb_context;
 /**
  * The type of a sideband transformation.
  *
- * The sideband API allows to filter all data through an arbitrary
+ * The sideband API allows the filtering of data through an arbitrary
  * transformation, which is useful for crypto purposes. The transformation may
  * either transform the data in place, or return a pointer to a new buffer
  * which contains the transformed source buffer. The internal sideband
diff --git a/vss.c b/vss.c
index 13a8e25..8b850fe 100644 (file)
--- a/vss.c
+++ b/vss.c
@@ -298,7 +298,7 @@ static int initialize_fec_client(struct fec_client *fc, struct vss_task *vsst)
        if (fcp->init_fec) {
                /*
                 * Set the maximum slice size to the Maximum Packet Size if the
-                * transport protocol allows to determine this value. The user
+                * transport protocol allows determination of this value. The user
                 * can specify a slice size up to this value.
                 */
                ret = fcp->init_fec(fc->sc);
index 1ca8a4d..9ef92b7 100644 (file)
@@ -15,8 +15,8 @@ provided at this point. There are several ways to download the source:
 
                <p> The repository contains the full history of the
                project since 2006, all work in progress and the source
-               code for the web pages. Choosing this option allows to
-               check out any of the four integration branches maint,
+               code for the web pages. Choosing this option allows the
+               checkout of any of the four integration branches maint,
                master, next, pu (see the
 
                <a href="manual.html#Git.branches">Git branches</a>
@@ -68,7 +68,7 @@ provided at this point. There are several ways to download the source:
                        <a href="http://git.tuebingen.mpg.de/paraslash.git">gitweb</a>
 
                page contains a snapshot link for each revision. This
-               allows to get a specific revision without downloading
+               allows getting a specific revision without downloading
                the full history.
 
        </li>
index fb3a05f..04c716a 100644 (file)
@@ -230,9 +230,9 @@ compatible with arbitrary HTTP streaming sources (e.g. icecast).
 In addition to the three network streaming modes, para_recv can also
 operate in local (afh) mode. In this mode it writes the content of
 an audio file on the local file system in complete chunks to stdout,
-optionally 'just in time'. This allows to cut an audio file without
-first decoding it, and it enables third-party software which is unaware
-of the particular audio format to send complete frames in real time.
+optionally 'just in time'. This allows cutting audio files without
+decoding, and it enables third-party software which is unaware of
+the particular audio format to send complete frames in real time.
 
 <h3> para_filter </h3>
 
@@ -1541,27 +1541,6 @@ currently running server process.
 
        para_client si
 
-The sender command of para_server prints information about senders,
-like the various access control lists, and it allows to (de-)activate
-senders and to change the access permissions at runtime.
-
--> List all senders
-
-       para_client sender
-
--> Obtain general help for the sender command:
-
-       para_client help sender
-
--> Get help for a specific sender (contains further examples):
-
-       s=http # or dccp or udp
-       para_client sender $s help
-
--> Show status of the http sender
-
-       para_client sender http status
-
 By default para_server activates both the HTTP and th DCCP sender on
 startup. This can be changed via command line options or para_server's
 config file.
@@ -1570,13 +1549,6 @@ config file.
 
        para_server -h
 
-All senders share the "on" and "off" commands, so senders may be
-activated and deactivated independently of each other.
-
--> Switch off the http sender:
-
-       para_client sender http off
-
 -> Receive a DCCP stream using CCID2 and write the output into a file:
 
        host=foo.org; ccid=2; filename=bar
@@ -1587,20 +1559,11 @@ receiver has its own set of command line options and its own command
 line parser, so arguments for the dccp receiver must be protected
 from being interpreted by para_recv.
 
--> Start UDP multicast, using the default multicast address:
-
-       para_client sender udp add 224.0.1.38
-
 -> Receive FEC-encoded multicast stream and write the output into a file:
 
        filename=foo
        para_recv -r udp > $filename
 
--> Add an UDP unicast for a client to the target list of the UDP sender:
-
-       t=client.foo.org
-       para_client sender udp add $t
-
 -> Receive this (FEC-encoded) unicast stream:
 
        filename=foo
@@ -1778,7 +1741,7 @@ These filters are rather simple and do not modify the audio stream at
 all. The wav filter is only useful with para_filter and in connection
 with a decoder. It asks the decoder for the number of channels and the
 sample rate of the stream and adds a Microsoft wave header containing
-this information at the beginning. This allows to write wav files
+this information at the beginning. This allows writing wav files
 rather than raw PCM files (which do not contain any information about
 the number of channels and the sample rate).
 
@@ -1792,17 +1755,6 @@ Both filters require almost no additional computing time, even when
 operating on uncompressed audio streams, since data buffers are simply
 "pushed down" rather than copied.
 
-Examples
---------
-
--> Decode an mp3 file to wav format:
-
-       para_filter -f mp3dec -f wav < file.mp3 > file.wav
-
--> Amplify a raw audio file by a factor of 1.5:
-
-       para_filter -f amp --amp 32 < foo.raw > bar.raw
-
 ======
 Output
 ======
@@ -1852,8 +1804,8 @@ emulation for backwards compatibility. This API is rather simple but
 also limited. For example only one application can open the device
 at any time. The OSS writer is activated by default on BSD Systems.
 
-- *FILE*. The file writer allows to capture the audio stream and
-write the PCM data to a file on the file system rather than playing
+- *FILE*. The file writer allows capturing the audio stream and
+writing the PCM data to a file on the file system rather than playing
 it through a sound device. It is supported on all platforms and is
 always compiled in.