[FFmpeg-devel] [PATCH] doc/filters: add "Notes on filtergraph escaping" section

[Stefano Sabatini]

Should help to clarify escaping issues in the filtergraph syntax. In
particular, should address trac ticket #1813.
---
 doc/filters.texi |   35 +++++++++++++++++++++++++++++++++++
 1 files changed, 35 insertions(+), 0 deletions(-)

diff --git a/doc/filters.texi b/doc/filters.texi
index 51ed89f..cbe1022 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -191,6 +191,41 @@ Follows a BNF description for the filtergraph syntax:
 @var{FILTERGRAPH}      ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
 @end example
 
+ at section Notes on filtergraph escaping
+
+Some filter arguments requires the use of special characters,
+typically @code{:} to separate key=values in a named options list. In
+this case the user should perform a double level escaping. For example
+if a literal string is embedded in drawtext:
+ at example
+this is a 'string': may contain one, or more, special characters
+ at end example
+
+Since @code{:} is special in the drawtext filter arguments syntax, it
+needs to be escaped, so you get:
+ at example
+drawtext=text=this is a \'string\'\: may contain one, or more, special characters
+ at end example
+
+A second level of escaping is required when embedding the filter
+descriptions in a filtergraph description, in order to escape all the
+filtergraph special characters, so it becomes:
+ at example
+drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
+ at end example
+
+See the @ref{quoting_and_escaping} section for more information about
+the escaping rules adopted by FFmpeg.
+
+Finally an additional level of escaping may be needed when writing the
+filtergraph description in a shell command, which depends on the
+escaping rule of the adopted shell. For example, assuming that
+ at code{\} is special and needs to be escaped with another @code{\}, the
+previous strings will finally result in:
+ at example
+-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
+ at end example
+
 @c man end FILTERGRAPH DESCRIPTION
 
 @chapter Audio Filters
-- 
1.7.5.4