[FFmpeg-devel] [PATCH] doc/ffmpeg: mention both ffpreset/avpreset in documentation, remove superfluous example

[Werner Robitza]

ffmpeg looks for both .ffpreset and .avpreset files depending on whether the
-[avsf]pre or -pre option is used. Added two sections for each type of preset
including the rules according to which files are searched.

(Notably, the lookup order is swapped for avpreset files, because it first
looks for <codec>_<arg>.avpreset and then for <arg>.avpreset.)

This removes the section explaining -pre only, which was under "Examples",
where it did not really make sense.

Signed-off-by: Werner Robitza <werner.robitza at gmail.com>
---
 doc/ffmpeg.texi | 40 ++++++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 16 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 6de5004..396c623 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -1214,7 +1214,10 @@ awkward to specify on the command line. Lines starting with the hash
 ('#') character are ignored and are used to provide comments. Check
 the @file{presets} directory in the FFmpeg source tree for examples.
 
-Preset files are specified with the @code{vpre}, @code{apre},
+There are two types of preset files: ffpreset and avpreset files.
+
+ at subsection ffpreset files
+ffpreset files are specified with the @code{vpre}, @code{apre},
 @code{spre}, and @code{fpre} options. The @code{fpre} option takes the
 filename of the preset instead of a preset name as input and can be
 used for any kind of codec. For the @code{vpre}, @code{apre}, and
@@ -1239,6 +1242,26 @@ directories, where @var{codec_name} is the name of the codec to which
 the preset file options will be applied. For example, if you select
 the video codec with @code{-vcodec libvpx} and use @code{-vpre 1080p},
 then it will search for the file @file{libvpx-1080p.ffpreset}.
+
+ at subsection avpreset files
+avpreset files are specified with the @code{pre} option. They work similar to
+ffpreset files, but they only allow encoder- specific options. Therefore, an
+ at var{option}=@var{value} pair specifying an encoder cannot be used.
+
+When the @code{pre} option is specified, ffmpeg will look for files with the
+suffix .avpreset in the directories @file{$AVCONV_DATADIR} (if set), and
+ at file{$HOME/.avconv}, and in the datadir defined at configuration time (usually
+ at file{PREFIX/share/ffmpeg}), in that order.
+
+First ffmpeg searches for a file named @var{codec_name}- at var{arg}.avpreset in
+the above-mentioned directories, where @var{codec_name} is the name of the codec
+to which the preset file options will be applied. For example, if you select the
+video codec with @code{-vcodec libvpx} and use @code{-pre 1080p}, then it will
+search for the file @file{libvpx-1080p.avpreset}.
+
+If no such file is found, then ffmpeg will search for a file named
+ at var{arg}.avpreset in the same directories.
+
 @c man end OPTIONS
 
 @chapter Tips
@@ -1285,21 +1308,6 @@ quality).
 @chapter Examples
 @c man begin EXAMPLES
 
- at section Preset files
-
-A preset file contains a sequence of @var{option=value} pairs, one for
-each line, specifying a sequence of options which can be specified also on
-the command line. Lines starting with the hash ('#') character are ignored and
-are used to provide comments. Empty lines are also ignored. Check the
- at file{presets} directory in the FFmpeg source tree for examples.
-
-Preset files are specified with the @code{pre} option, this option takes a
-preset name as input.  FFmpeg searches for a file named @var{preset_name}.avpreset in
-the directories @file{$AVCONV_DATADIR} (if set), and @file{$HOME/.ffmpeg}, and in
-the data directory defined at configuration time (usually @file{$PREFIX/share/ffmpeg})
-in that order.  For example, if the argument is @code{libx264-max}, it will
-search for the file @file{libx264-max.avpreset}.
-
 @section Video and Audio grabbing
 
 If you specify the input format and device then ffmpeg can grab video
-- 
1.9.3 (Apple Git-50)