[FFmpeg-devel] [PATCH] doc/filters: re-edit notes on filtergraph escaping

[Stefano Sabatini]

State the escaping rules more explicitly, reword various sentences and
drop confusing quoting example.

Should fix trac issue #3334.
---
 doc/examples/filtering_audio.c |  1 -
 doc/examples/filtering_video.c |  1 -
 doc/filters.texi               | 54 +++++++++++++++++++-----------------------
 3 files changed, 25 insertions(+), 31 deletions(-)

diff --git a/doc/examples/filtering_audio.c b/doc/examples/filtering_audio.c
index 1568f60..2ceee6a 100644
--- a/doc/examples/filtering_audio.c
+++ b/doc/examples/filtering_audio.c
@@ -210,7 +210,6 @@ int main(int argc, char **argv)
         exit(1);
     }
 
-    avcodec_register_all();
     av_register_all();
     avfilter_register_all();
 
diff --git a/doc/examples/filtering_video.c b/doc/examples/filtering_video.c
index 0ac1cd4..67c8a8b 100644
--- a/doc/examples/filtering_video.c
+++ b/doc/examples/filtering_video.c
@@ -200,7 +200,6 @@ int main(int argc, char **argv)
         exit(1);
     }
 
-    avcodec_register_all();
     av_register_all();
     avfilter_register_all();
 
diff --git a/doc/filters.texi b/doc/filters.texi
index 242602c..af45972 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -217,29 +217,45 @@ Follows a BNF description for the filtergraph syntax:
 
 @section Notes on filtergraph escaping
 
-Some filter arguments require the use of special characters, typically
- at code{:} to separate key=value pairs in a named options list. In this
-case the user should perform a first level escaping when specifying
-the filter arguments. For example, consider the following literal
-string to be embedded in the @ref{drawtext} filter arguments:
+Filtergraph description composition entails several levels of
+escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
+section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
+information about the employed escaping procedure.
+
+A first level escaping affects the content of each filter option
+value, which may contain the special character @code{:} used to
+separate values, or one of the escaping characters @code{\'}.
+
+A second level escaping affects the whole filter description, which
+may contain the escaping characters @code{\'} or the special
+characters @code{[],;} used by the filtergraph description.
+
+Finally, when you specify a filtergraph on a shell commandline, you
+need to perform a third level escaping for the shell special
+characters contained within it.
+
+For example, consider the following string to be embedded in
+the @ref{drawtext} filter description @option{text} value:
 @example
 this is a 'string': may contain one, or more, special characters
 @end example
 
-Since @code{:} is special for the filter arguments syntax, it needs to
-be escaped, so you get:
+This string contains the @code{'} special escaping character, and the
+ at code{:} special character, so it needs to be escaped in this way:
 @example
 text=this is a \'string\'\: may contain one, or more, special characters
 @end example
 
 A second level of escaping is required when embedding the filter
-arguments in a filtergraph description, in order to escape all the
+description in a filtergraph description, in order to escape all the
 filtergraph special characters. Thus the example above becomes:
 @example
 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
 @end example
+(note that in addition to the @code{\'} escaping special characters,
+also @code{,} needs to be escaped).
 
-Finally an additional level of escaping may be needed when writing the
+Finally an additional level of escaping is needed when writing the
 filtergraph description in a shell command, which depends on the
 escaping rules of the adopted shell. For example, assuming that
 @code{\} is special and needs to be escaped with another @code{\}, the
@@ -248,26 +264,6 @@ previous string will finally result in:
 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
 @end example
 
-Sometimes, it might be more convenient to employ quoting in place of
-escaping. For example the string:
- at example
-Caesar: tu quoque, Brute, fili mi
- at end example
-
-Can be quoted in the filter arguments as:
- at example
-text='Caesar: tu quoque, Brute, fili mi'
- at end example
-
-And finally inserted in a filtergraph like:
- at example
-drawtext=text=\'Caesar: tu quoque\, Brute\, fili mi\'
- at end example
-
-See the ``Quoting and escaping'' section in the ffmpeg-utils manual
-for more information about the escaping and quoting rules adopted by
-FFmpeg.
-
 @chapter Timeline editing
 
 Some filters support a generic @option{enable} option. For the filters
-- 
1.8.1.2