[PATCH] doc: add detail to the documentation for ffmpeg -map

[Mike Scheutzow]

Extend and clarify documentation for the ffmpeg -map options.

Patch by Mike Sheutzow with some addition by Stefano.
---
 doc/ffmpeg.texi |   42 +++++++++++++++++++++++++++++++++++++-----
 1 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index f0f3b65..040e01d 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -622,11 +622,43 @@ Synchronize read on input.
 @section Advanced options
 
 @table @option
- at item -map @var{input_stream_id}[:@var{sync_stream_id}]
-Set stream mapping from input streams to output streams.
-Just enumerate the input streams in the order you want them in the output.
- at var{sync_stream_id} if specified sets the input stream to sync
-against.
+ at item -map @var{input_file_id}. at var{input_stream_id}[:@var{sync_file_id}. at var{sync_stream_id}]
+
+Specify an input stream to be a source for the output file. An input
+stream is identified by two numbers: an input file index, specified by
+ at var{input_file_id}, and an input stream index within that file,
+specified by @var{input_stream_id}. Both start counting from 0.  If
+used, @var{sync_file_id}. at var{sync_stream_id} specifies which input
+stream is used as a presentation sync reference.
+
+The @code{-map} options must be specified just after the output file.
+If any @code{-map} options are used, the number of @code{-map} options
+on the command line must match the number of streams in the output
+file. The first @code{-map} option on the command line specifies the
+source for output stream 0, the second @code{-map} option specifies
+the source for output stream 1, etc.
+
+For example, if you have two streams in the first input file, these
+streams are identified by "0.0" and "0.1". You can use @code{-map} to
+select which one to map to the single stream of an output file. For
+example:
+ at example
+ffmpeg -i INPUT OUTPUT -map 0.1
+ at end example
+will map the input stream identified by "0.1" to the (single) output
+stream.
+
+For example, to select stream 2 from input file @file{A.mov}
+(specified by the identifier "0.2"), and stream 6 from input
+ at file{B.mov} (specified by the identifier "0.6"), and copy them to
+output file @file{out.mov}:
+ at example
+ffmpeg -i A.mov -i B.mov -vcodec copy -acodec copy out.mov -map 0.2 -map 1.6
+ at end example
+
+To add more streams to the output file, you can use the
+ at code{-newaudio}, @code{-newvideo}, @code{-newsubtitle} options.
+
 @item -map_meta_data @var{outfile}[, at var{metadata}]:@var{infile}[, at var{metadata}]
 Deprecated, use @var{-map_metadata} instead.
 
-- 
1.7.2.3


--YZ5djTAD1cGYuMQK--