add tutorial

doc/html/changelog.html

@@ -113,6 +113,12 @@
 					<li>automake-1.10 fixes (<a href="https://sourceforge.net/tracker/index.php?func=detail&amp;aid=1791361&amp;group_id=13478&amp;atid=113478">SF #1791361</a> <a href="https://sourceforge.net/tracker/index.php?func=detail&amp;aid=1792179&amp;group_id=13478&amp;atid=113478">SF #1792179</a>).</li>
 				</ul>
 			</li>
+			<li>
+				documentation:
+				<ul>
+					<li>Added new <a href="documentation_tools_flac.html#tutorial">tutorial</a> section for <span class="commandname">flac</span>.</li>
+				</ul>
+			</li>
 			<li>
 				libraries:
 				<ul>

doc/html/documentation_tools_flac.html

@@ -52,6 +52,7 @@
 		<a name="toc"><font size="+1"><b><u>Table of Contents</u></b></font></a>
 		<ul>
 			<li><a href="#usage">General Usage</a></li>
+			<li><a href="#tutorial">Tutorial</a></li>
 			<li><a href="#general_options">General Options</a></li>
 			<li><a href="#analysis_options">Analysis Options</a></li>
 			<li><a href="#decoding_options">Decoding Options</a></li>
@@ -68,6 +69,8 @@
 		<br />
 		Before going into the full command-line description, a few other things help to sort it out: 1) <span class="commandname">flac</span> encodes by default, so you must use <b>-d</b> to decode; 2) the options <span class="argument">-0</span> .. <span class="argument">-8</span> (or <span class="argument">--fast</span> and <span class="argument">--best</span>) that control the compression level actually are just synonyms for different groups of specific encoding options (described later) and you can get the same effect by using the same options; 3) <span class="commandname">flac</span> behaves similarly to gzip in the way it handles input and output files.<br />
 		<br />
+		Skip to the <a href="#tutorial">tutorial</a> below for examples of some common tasks.<br />
+		<br />
 		<span class="commandname">flac</span> will be invoked one of four ways, depending on whether you are encoding, decoding, testing, or analyzing:
 		<ul>
 			<li>
@@ -122,6 +125,56 @@
 		<span class="commandname">flac</span> has been tuned so that the default settings yield a good speed vs. compression tradeoff for many kinds of input.  However, if you are looking to maximize the compression rate or speed, or want to use the full power of FLAC's metadata system, see <a href="documentation_format_overview.html">About the FLAC Format</a>.<br />
 		<br />
 
+		<a name="tutorial"><font size="+1"><b><u>Tutorial</u></b></font></a><br />
+		<br />
+		Some common <b>encoding</b> tasks using <span class="commandname">flac</span>:<br />
+		<br />
+		<tt><b>flac abc.wav</b></tt><br />
+		Encode <tt>abc.wav</tt> to <tt>abc.flac</tt> using the default compression setting.  <tt>abc.wav</tt> is not deleted.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_delete_input_file">--delete-input-file</a> abc.wav</b></tt><br />
+		Like above, except <tt>abc.wav</tt> is deleted if there were no errors.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_delete_input_file">--delete-input-file</a> <a href="#flac_options_warnings_as_errors">-w</a> abc.wav</b></tt><br />
+		Like above, except <tt>abc.wav</tt> is deleted if there were no errors or warnings.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_best">--best</a> abc.wav</b></tt><br />
+		Encode <tt>abc.wav</tt> to <tt>abc.flac</tt> using the highest compression setting.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_verify">--verify</a> abc.wav</b></tt><br />
+		Encode <tt>abc.wav</tt> to <tt>abc.flac</tt> and internally decode <tt>abc.flac</tt> to make sure it matches <tt>abc.wav</tt>.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_output_name">-o</a> my.flac abc.wav</b></tt><br />
+		Encode <tt>abc.wav</tt> to <tt>my.flac</tt>.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_tag">-T</a> "TITLE=Bohemian Rhapsody" -T "ARTIST=Queen" abc.wav</b></tt><br />
+		Encode <tt>abc.wav</tt> and add some tags at the same time to <tt>abc.flac</tt>.<br />
+		<br />
+		<tt><b>flac *.wav</b></tt><br />
+		Encode all .wav files in the current directory.  NOTE: <a href="faq.html#tools__wildcards_on_windows">Wildcards on Windows</a><br />
+		<br />
+		<tt><b>flac abc.aiff</b></tt><br />
+		Encode <tt>abc.aiff</tt> to <tt>abc.flac</tt>.<br />
+		<br />
+		<tt><b>flac abc.flac <a href="#flac_options_force">--force</a></b></tt><br />
+		This one's a little tricky: notice that <span class="commandname">flac</span> is in encode mode by default (you have to specify <span class="argument">-d</span> to decode) so this command actually recompresses <tt>abc.flac</tt> back to <tt>abc.flac</tt>.  <span class="argument"><a href="#flac_options_force">--force</a></span> is needed to make sure you really want to overwrite <tt>abc.flac</tt> with a new version.  Why would you want to do this?  It allows you to recompress an existing FLAC file with (usually) higher compression options or a newer version of FLAC and preserve all the metadata like tags too.<br />
+		<br />
+
+		Some common <b>decoding</b> tasks using <span class="commandname">flac</span>:<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_decode">-d</a> abc.flac</b></tt><br />
+		Decode <tt>abc.flac</tt> to <tt>abc.wav</tt>.  <tt>abc.flac</tt> is not deleted.  NOTE: Without <span class="argument"><a href="#flac_options_decode">-d</a></span> it means re-encode <tt>abc.flac</tt> to <tt>abc.flac</tt> (see above).<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_decode">-d</a> <a href="#flac_options_force_aiff_format">--force-aiff-format</a> abc.flac</b></tt><br />
+		<tt><b>flac <a href="#flac_options_decode">-d</a> <a href="#flac_options_output_name">-o</a> abc.aiff abc.flac</b></tt><br />
+		Two different ways of decoding <tt>abc.flac</tt> to <tt>abc.aiff</tt> (AIFF format).  <tt>abc.flac</tt> is not deleted.<br />
+		<br />
+		<tt><b>flac <a href="#flac_options_decode">-d</a> <a href="#flac_options_decode_through_errors">-F</a> abc.flac</b></tt><br />
+		Decode <tt>abc.flac</tt> to <tt>abc.wav</tt> and don't abort if errors are found (useful for recovering as much as possible from corrupted files).<br />
+		<br />
+		<span class="commandname">flac</span> has many other useful options, described below.<br />
+		<br />
+
 		<table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td>
 		<table width="100%" border="1" bgcolor="#EEEED4">
 			<tr>