add docs for -A, additional docs for --cue

diff --git a/doc/html/documentation.html b/doc/html/documentation.html
index 7e9c5d2..b07004d 100644 (file)
--- a/doc/html/documentation.html
+++ b/doc/html/documentation.html
@@ -423,7 +423,8 @@
                                        <span class="argument">--cue=4.1</span> : decode from track 4, index 1 to the end of the stream<br />
                                        <span class="argument">--cue=4.1-</span> : decode from track 4, index 1 to the end of the stream<br />
                                        <span class="argument">--cue=-4.1</span> : decode from the beginning of the stream up to, but not including, track 4, index 1<br />
-                                       <span class="argument">--cue=2.1-2.4</span> : decode from track 2, index 1, up to, but not including, track 2, index 4
+                                       <span class="argument">--cue=2.1-2.4</span> : decode from track 2, index 1, up to, but not including, track 2, index 4<br />
+                                       <span class="argument">--cue=9.1-10.1</span> : decode from track 9 the way it would be played on a CD player; this works even if the CD has no 10th track.
                                </td>
                        </tr>
                        <tr>
@@ -728,6 +729,19 @@
                        </tr>
                        <tr>
                                <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
+                                       <a name="flac_options_apodization" />
+                                       <span class="argument">-A "function"</span>, <span class="argument">--apodization="function"</span>
+                               </td>
+                               <td>
+                                       Window audio data with given the apodization function.  The functions are: bartlett, bartlett_hann, blackman, blackman_harris_4term_92db, connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall, rectangle, triangle, tukey(P), welch.<br />
+                                       For gauss(STDDEV), STDDEV is the standard deviation (0&lt;STDDEV&lt;=0.5).<br />
+                                       For tukey(P), P specifies the fraction of the window that is tapered (0&lt;=P&lt;=1; P=0 corresponds to "rectangle" and P=1 corresponds to "hann").<br />
+                                       More than one -A option (up to 32) may be used.  Any function that is specified erroneously is silently dropped.  The encoder chooses suitable defaults in the absence of any -A options; any -A option specified replaces the default(s).<br />
+                                       When more than one function is specified, then for every subframe the encoder will try each of them separately and choose the window that results in the smallest compressed subframe.  Multiple functions can greatly increase the encoding time.<br />
+                               </td>
+                       </tr>
+                       <tr>
+                               <td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
                                        <a name="flac_options_max_lpc_order" />
                                        <span class="argument">-l #</span>, <span class="argument">--max-lpc-order=#</span>
                                </td>

diff --git a/man/flac.sgml b/man/flac.sgml
index 122cdb0..e959e84 100644 (file)
--- a/man/flac.sgml
+++ b/man/flac.sgml
@@ -310,7 +310,9 @@
                    don't exist, the start of the stream (for the start
                    point) or end of the stream (for the end point) will be
                    used.  The cuepoints are merely translated into sample
-                   numbers then used as --skip and --until.</para>
+                   numbers then used as --skip and --until.  A CD track can
+                   always be cued by, for example, --cue=9.1-10.1 for track
+                   9, even if the CD has no 10th track.</para>
                </listitem>
              </varlistentry>
 
@@ -615,6 +617,33 @@
              </varlistentry>
 
              <varlistentry>
+               <term><option>-A</option> <replaceable>function</replaceable>, <option>--apodization</option>=<replaceable>function</replaceable></term>
+
+               <listitem>
+                 <para>Window audio data with given the apodization function.
+                   The functions are: bartlett, bartlett_hann, blackman,
+                   blackman_harris_4term_92db, connes, flattop, gauss(STDDEV),
+                   hamming, hann, kaiser_bessel, nuttall, rectangle, triangle,
+                   tukey(P), welch.</para>
+                 <para>For gauss(STDDEV), STDDEV is the standard deviation
+                   (0&lt;STDDEV&lt;=0.5).</para>
+                 <para>For tukey(P), P specifies the fraction of the window that
+                   is tapered (0&lt;=P&lt;=1; P=0 corresponds to "rectangle" and
+                   P=1 corresponds to "hann").</para>
+                 <para>More than one -A option (up to 32) may be used.  Any
+                   function that is specified erroneously is silently dropped.
+                   The encoder chooses suitable defaults in the absence of any
+                   -A options; any -A option specified replaces the default(s).
+                   </para>
+                 <para>When more than one function is specified, then for every
+                   subframe the encoder will try each of them separately and
+                   choose the window that results in the smallest compressed
+                   subframe.  Multiple functions can greatly increase the
+                   encoding time.</para>
+               </listitem>
+             </varlistentry>
+
+             <varlistentry>
                <term><option>-l</option> <replaceable>#</replaceable>, <option>--max-lpc-order</option>=<replaceable>#</replaceable></term>
 
                <listitem>

diff --git a/src/flac/main.c b/src/flac/main.c
index c6ff5f1..1e5d59e 100644 (file)
--- a/src/flac/main.c
+++ b/src/flac/main.c
@@ -1363,6 +1363,9 @@ void show_explain()
        printf("                               point) or after it (for the end point) will be\n");
        printf("                               used.  The cuepoints are merely translated into\n");
        printf("                               sample numbers then used as --skip and --until.\n");
+       printf("                               A CD track can always be cued by, for example,\n");
+       printf("                               --cue=9.1-10.1 for track 9, even if the CD has\n");
+       printf("                               no 10th track.\n");
        printf("encoding options:\n");
        printf("  -V, --verify                 Verify a correct encoding by decoding the\n");
        printf("                               output in parallel and comparing to the\n");
@@ -1444,8 +1447,9 @@ void show_explain()
        printf("                                     triangle, tukey(P), welch.  More than one\n");
        printf("                                     may be specified but encoding time is a\n");
        printf("                                     multiple of the number of functions since\n");
-       printf("                                     they are each tried in turn.  The default\n");
-       printf("                                     is \"hann\". \n");
+       printf("                                     they are each tried in turn.  The encoder\n");
+       printf("                                     chooses suitable defaults in the absence\n");
+       printf("                                     of any -A options.\n");
        printf("  -l, --max-lpc-order=#              Max LPC order; 0 => only fixed predictors\n");
        printf("  -p, --qlp-coeff-precision-search   Do exhaustive search of LP coefficient\n");
        printf("                                     quantization (expensive!); overrides -q;\n");