[FFmpeg-devel] [PATCH] doc/ffmpeg: fix/extend documentation for the -filter option

[Stefano Sabatini]

---
 doc/ffmpeg.texi |   26 +++++++++++++++-----------
 ffmpeg_opt.c    |    6 +++---
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 57c5a1c..c39afe3 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -334,10 +334,18 @@ Stop writing to the stream after @var{framecount} frames.
 Use fixed quality scale (VBR). The meaning of @var{q} is
 codec-dependent.
 
+ at anchor{filter_option}
 @item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream})
+Create a filtergraph and use it to filter the stream.
 @var{filter_graph} is a description of the filter graph to apply to
-the stream. Use @code{-filters} to show all the available filters
-(including also sources and sinks).
+the stream, and must have a single input and a single output of the
+same type of the stream. In the filtergraph, the input is associated
+to the label @code{in}, and the output to the label @code{out}. See
+the ffmpeg-filters manual for more information about the filtergraph
+syntax.
+
+Use @code{-filters} to show all the available filters (including also
+sources and sinks).
 
 See also the @option{-filter_complex} option if you want to create filter graphs
 with multiple inputs and/or outputs.
@@ -487,11 +495,8 @@ stream
 Set the ISO 639 language code (3 letters) of the current video stream.
 
 @item -vf @var{filter_graph} (@emph{output})
- at var{filter_graph} is a description of the filter graph to apply to
-the input video.
-Use the option "-filters" to show all the available filters (including
-also sources and sinks).  This is an alias for @code{-filter:v}.
-
+Create a filtergraph and use it to filter the stream.
+This is an alias for @code{-filter:v}, see @ref{filter_option,,the -filter option}.
 @end table
 
 @section Advanced Video Options
@@ -608,10 +613,8 @@ Set the audio codec. This is an alias for @code{-codec:a}.
 Set the audio sample format. Use @code{-sample_fmts} to get a list
 of supported sample formats.
 @item -af @var{filter_graph} (@emph{output})
- at var{filter_graph} is a description of the filter graph to apply to
-the input audio.
-Use the option "-filters" to show all the available filters (including
-also sources and sinks).  This is an alias for @code{-filter:a}.
+Create a filtergraph and use it to filter the stream.
+This is an alias for @code{-filter:a}, see @ref{filter_option,,the -filter option}.
 @end table
 
 @section Advanced Audio options:
@@ -954,6 +957,7 @@ Specify Timecode for writing. @var{SEP} is ':' for non drop timecode and ';'
 ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
 @end example
 
+ at anchor{filter_complex_option}
 @item -filter_complex @var{filtergraph} (@emph{global})
 Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
 outputs. For simple graphs -- those with one input and one output of the same
diff --git a/ffmpeg_opt.c b/ffmpeg_opt.c
index 38ffd42..c98e030 100644
--- a/ffmpeg_opt.c
+++ b/ffmpeg_opt.c
@@ -2463,7 +2463,7 @@ const OptionDef options[] = {
     { "profile",        HAS_ARG | OPT_EXPERT | OPT_PERFILE,          { .func_arg = opt_profile },
         "set profile", "profile" },
     { "filter",         HAS_ARG | OPT_STRING | OPT_SPEC,             { .off = OFFSET(filters) },
-        "set stream filterchain", "filter_list" },
+        "set stream filtergraph", "filter_graph" },
     { "reinit_filter",  HAS_ARG | OPT_INT | OPT_SPEC,                { .off = OFFSET(reinit_filters) },
         "reinit filtergraph on input parameter changes", "" },
     { "filter_complex", HAS_ARG | OPT_EXPERT,                        { .func_arg = opt_filter_complex },
@@ -2537,7 +2537,7 @@ const OptionDef options[] = {
     { "vstats_file",  OPT_VIDEO | HAS_ARG | OPT_EXPERT ,                         { opt_vstats_file },
         "dump video coding statistics to file", "file" },
     { "vf",           OPT_VIDEO | HAS_ARG  | OPT_PERFILE,                        { .func_arg = opt_video_filters },
-        "video filters", "filter list" },
+        "set video filters", "filter_graph" },
     { "intra_matrix", OPT_VIDEO | HAS_ARG | OPT_EXPERT  | OPT_STRING | OPT_SPEC, { .off = OFFSET(intra_matrices) },
         "specify intra matrix coeffs", "matrix" },
     { "inter_matrix", OPT_VIDEO | HAS_ARG | OPT_EXPERT  | OPT_STRING | OPT_SPEC, { .off = OFFSET(inter_matrices) },
@@ -2582,7 +2582,7 @@ const OptionDef options[] = {
     { "channel_layout", OPT_AUDIO | HAS_ARG  | OPT_EXPERT | OPT_PERFILE,           { .func_arg = opt_channel_layout },
         "set channel layout", "layout" },
     { "af",             OPT_AUDIO | HAS_ARG  | OPT_PERFILE,                        { .func_arg = opt_audio_filters },
-        "audio filters", "filter list" },
+        "set audio filters", "filter_graph" },
 
     /* subtitle options */
     { "sn",     OPT_SUBTITLE | OPT_BOOL | OPT_OFFSET, { .off = OFFSET(subtitle_disable) },
-- 
1.7.9.5