added ffplay documentation - added automatic man page generation for ffmpeg, ffserver and ffplay

Originally committed as revision 2136 to svn://svn.ffmpeg.org/ffmpeg/trunk

1 files changed, 103 insertions, 81 deletions

diff --git a/doc/ffmpeg-doc.texi b/doc/ffmpeg-doc.texi
index 3af1afe55f..7d7c7d4013 100644
--- a/doc/ffmpeg-doc.texi
+++ b/doc/ffmpeg-doc.texi
@@ -22,19 +22,21 @@ video on the fly with a high quality polyphase filter.
 
 @chapter Quick Start
 
+@c man begin EXAMPLES
 @section Video and Audio grabbing
 
- FFmpeg can use a video4linux compatible video source and any Open Sound
-  System audio source:
+FFmpeg can use a video4linux compatible video source and any Open Sound
+System audio source:
+
 @example
-  ffmpeg /tmp/out.mpg 
+ffmpeg /tmp/out.mpg 
 @end example
 
-  Note that you must activate the right video source and channel before
-  launching ffmpeg. You can use any TV viewer such as xawtv
-  (@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
-  good. You must also set correctly the audio recording levels with a
-  standard mixer.
+Note that you must activate the right video source and channel before
+launching ffmpeg. You can use any TV viewer such as xawtv
+(@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
+good. You must also set correctly the audio recording levels with a
+standard mixer.
 
 @section Video and Audio file format conversion
 
@@ -45,109 +47,115 @@ Examples:
 * You can input from YUV files:
 
 @example
-  ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
+ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
 @end example
 
-  It will use the files: 
+It will use the files: 
 @example
-       /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
-       /tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
+/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
+/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
 @end example
 
-  The Y files use twice the resolution of the U and V files. They are
-  raw files, without header. They can be generated by all decent video
-  decoders. You must specify the size of the image with the '-s' option
-  if ffmpeg cannot guess it.
+The Y files use twice the resolution of the U and V files. They are
+raw files, without header. They can be generated by all decent video
+decoders. You must specify the size of the image with the @option{-s} option
+if ffmpeg cannot guess it.
 
 * You can input from a RAW YUV420P file:
 
 @example
-  ffmpeg -i /tmp/test.yuv /tmp/out.avi
+ffmpeg -i /tmp/test.yuv /tmp/out.avi
 @end example
 
-  The RAW YUV420P is a file containing RAW YUV planar, for each frame first
-  come the Y plane followed by U and V planes, which are half vertical and
-  horizontal resolution.
+The RAW YUV420P is a file containing RAW YUV planar, for each frame first
+come the Y plane followed by U and V planes, which are half vertical and
+horizontal resolution.
 
 * You can output to a RAW YUV420P file:
 
 @example
-  ffmpeg -i mydivx.avi -o hugefile.yuv
+ffmpeg -i mydivx.avi -o hugefile.yuv
 @end example
 
 * You can set several input files and output files:
 
 @example
-  ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
+ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
 @end example
 
-  Convert the audio file a.wav and the raw yuv video file a.yuv
-  to mpeg file a.mpg
+Convert the audio file a.wav and the raw yuv video file a.yuv
+to mpeg file a.mpg
 
 * You can also do audio and video conversions at the same time:
 
 @example
-  ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
+ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
 @end example
 
-  Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
+Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
 
 * You can encode to several formats at the same time and define a
-  mapping from input stream to output streams:
+mapping from input stream to output streams:
 
 @example
-  ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
+ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
 @end example
 
-  Convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
-  file:index' specify which input stream is used for each output
-  stream, in the order of the definition of output streams.
+Convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
+file:index' specify which input stream is used for each output
+stream, in the order of the definition of output streams.
 
 * You can transcode decrypted VOBs
 
 @example
-  ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
+ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
 @end example
 
-  This is a typical DVD ripper example, input from a VOB file, output
-  to an AVI file with MPEG-4 video and MP3 audio, note that in this
-  command we use B frames so the MPEG-4 stream is DivX5 compatible, GOP
-  size is 300 that means an INTRA frame every 10 seconds for 29.97 fps
-  input video.  Also the audio stream is MP3 encoded so you need LAME
-  support which is enabled using @code{--enable-mp3lame} when
-  configuring.  The mapping is particularly useful for DVD transcoding
-  to get the desired audio language.
+This is a typical DVD ripper example, input from a VOB file, output
+to an AVI file with MPEG-4 video and MP3 audio, note that in this
+command we use B frames so the MPEG-4 stream is DivX5 compatible, GOP
+size is 300 that means an INTRA frame every 10 seconds for 29.97 fps
+input video.  Also the audio stream is MP3 encoded so you need LAME
+support which is enabled using @code{--enable-mp3lame} when
+configuring.  The mapping is particularly useful for DVD transcoding
+to get the desired audio language.
 
-  NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
+NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
+@c man end
 
 @chapter Invocation
 
 @section Syntax
 
- The generic syntax is:
+The generic syntax is:
 
 @example 
-  ffmpeg [[options][-i input_file]]... {[options] output_file}...
+@c man begin SYNOPSIS
+ffmpeg [[options][@option{-i} @var{input_file}]]... @{[options] @var{output_file}@}...
+@c man end
 @end example
-  If no input file is given, audio/video grabbing is done.
+@c man begin DESCRIPTION
+If no input file is given, audio/video grabbing is done.
 
-  As a general rule, options are applied to the next specified
-  file. For example, if you give the '-b 64' option, it sets the video
-  bitrate of the next file. Format option may be needed for raw input
-  files.
+As a general rule, options are applied to the next specified
+file. For example, if you give the @option{-b 64} option, it sets the video
+bitrate of the next file. Format option may be needed for raw input
+files.
 
-  By default, ffmpeg tries to convert as losslessly as possible: it
-  uses the same audio and video parameter for the outputs as the one
-  specified for the inputs.
+By default, ffmpeg tries to convert as losslessly as possible: it
+uses the same audio and video parameter for the outputs as the one
+specified for the inputs.
+@c man end
 
+@c man begin OPTIONS
 @section Main options
 
-@table @samp
+@table @option
 @item -L
 show license
 @item -h
-                  show help
-@item -formats            
+show help
+@item -formats
 show available formats, codecs, protocols, ...
 @item -f fmt              
 force format
@@ -173,13 +181,11 @@ set the copyright
 @item -comment string     
 set the comment
 
-@item -b bitrate          
-set video bitrate (in kbit/s)
 @end table
 
 @section Video Options
 
-@table @samp
+@table @option
 @item -s size             
 set frame size                       [160x128]
 @item -r fps           
@@ -203,7 +209,7 @@ select two pass log file name
 
 @section Audio Options
 
-@table @samp
+@table @option
 @item -ab bitrate         
 set audio bitrate (in kbit/s)
 @item -ar freq    
@@ -218,7 +224,7 @@ set audio bitrate (in kbit/s)
 
 @section Advanced options
 
-@table @samp
+@table @option
 @item -map file:stream    
 set input stream mapping
 @item -g gop_size         
@@ -264,6 +270,22 @@ calculate PSNR of compressed frames
 @item -vstats             
 dump video coding statistics to file
 @end table
+@c man end
+
+@ignore
+
+@setfilename ffmpeg
+@settitle FFmpeg video converter
+
+@c man begin SEEALSO
+ffserver(1), ffplay(1) and the html documentation of @file{ffmpeg}.
+@c man end
+
+@c man begin AUTHOR
+Fabrice Bellard
+@c man end
+
+@end ignore
 
 @section Protocols
 
@@ -272,47 +294,47 @@ to the standard output.
 
 ffmpeg handles also many protocols specified with the URL syntax.
 
- Use 'ffmpeg -formats' to have a list of the supported protocols.
+Use 'ffmpeg -formats' to have a list of the supported protocols.
 
- The protocol @code{http:} is currently used only to communicate with
- ffserver (see the ffserver documentation). When ffmpeg will be a
- video player it will also be used for streaming :-)
+The protocol @code{http:} is currently used only to communicate with
+ffserver (see the ffserver documentation). When ffmpeg will be a
+video player it will also be used for streaming :-)
 
 @chapter Tips
 
 @itemize
 @item For streaming at very low bit rate application, use a low frame rate
-  and a small gop size. This is especially true for real video where
-  the Linux player does not seem to be very fast, so it can miss
-  frames. An example is:
+and a small gop size. This is especially true for real video where
+the Linux player does not seem to be very fast, so it can miss
+frames. An example is:
 
 @example
-  ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
+ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
 @end example
 
 @item  The parameter 'q' which is displayed while encoding is the current
-  quantizer. The value of 1 indicates that a very good quality could
-  be achieved. The value of 31 indicates the worst quality. If q=31
-  too often, it means that the encoder cannot compress enough to meet
-  your bit rate. You must either increase the bit rate, decrease the
-  frame rate or decrease the frame size.
+quantizer. The value of 1 indicates that a very good quality could
+be achieved. The value of 31 indicates the worst quality. If q=31
+too often, it means that the encoder cannot compress enough to meet
+your bit rate. You must either increase the bit rate, decrease the
+frame rate or decrease the frame size.
 
 @item If your computer is not fast enough, you can speed up the
-  compression at the expense of the compression ratio. You can use
-  '-me zero' to speed up motion estimation, and '-intra' to disable
-  completely motion estimation (you have only I frames, which means it
-  is about as good as JPEG compression).
+compression at the expense of the compression ratio. You can use
+'-me zero' to speed up motion estimation, and '-intra' to disable
+completely motion estimation (you have only I frames, which means it
+is about as good as JPEG compression).
 
 @item To have very low bitrates in audio, reduce the sampling frequency
-  (down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
+(down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
 
 @item To have a constant quality (but a variable bitrate), use the option
-  '-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
-  quality).
+'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
+quality).
 
 @item When converting video files, you can use the '-sameq' option which
-  uses in the encoder the same quality factor than in the decoder. It
-  allows to be almost lossless in encoding.
+uses in the encoder the same quality factor than in the decoder. It
+allows to be almost lossless in encoding.
 
 @end itemize