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

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>
@@ -726,6 +727,19 @@
 					Exhaustive model search (expensive!).  Normally the encoder estimates the best model to use and encodes once based on the estimate.  With an exhaustive model search, the encoder will generate subframes for every order and use the smallest.  If the max LPC order is high this can significantly increase the encode time but can shave off another 0.5%.
 				</td>
 			</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" />

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>
 
@@ -614,6 +616,33 @@
 		</listitem>
 	      </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>
 

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");