[FFmpeg-cvslog] doc/filters: propose solutions to avoid shell escaping

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Sun Mar 26 17:47:52 2023 +0200| [7792f53e5e66eb3a340e93af12ab80c4a197e6b7] | committer: Stefano Sabatini

doc/filters: propose solutions to avoid shell escaping

Reference drawtext textfile option and ffmpeg -filter_complex_script
and -filter_script as possible solutions to avoid shell escaping.

Address issue:
http://trac.ffmpeg.org/ticket/9008

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=7792f53e5e66eb3a340e93af12ab80c4a197e6b7
---

 doc/ffmpeg.texi  |  2 ++
 doc/filters.texi | 22 +++++++++++++++++-----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 6baf51bf0a..adfc2726ff 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -769,6 +769,7 @@ syntax.
 See the @ref{filter_complex_option,,-filter_complex option} if you
 want to create filtergraphs with multiple inputs and/or outputs.
 
+ at anchor{filter_script option}
 @item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
 This option is similar to @option{-filter}, the only difference is that its
 argument is the name of the file from which a filtergraph description is to be
@@ -1978,6 +1979,7 @@ The default is the number of available CPUs.
 Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
 outputs. Equivalent to @option{-filter_complex}.
 
+ at anchor{filter_complex_script option}
 @item -filter_complex_script @var{filename} (@emph{global})
 This option is similar to @option{-filter_complex}, the only difference is that
 its argument is the name of the file from which a complex filtergraph
diff --git a/doc/filters.texi b/doc/filters.texi
index b397100ff8..1c9d523340 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -282,6 +282,18 @@ previous string will finally result in:
 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
 @end example
 
+In order to avoid cumbersome escaping when using a commandline tool accepting a
+filter specification as input, it is advisable to avoid direct inclusion of the
+filter or options specification in the shell.
+
+For example, in case of the @ref{drawtext,,drawtext filter}, you might prefer to
+use the @option{textfile} option in place of @option{text} to specify the text
+to render.
+
+When using the @command{ffmpeg} tool, you might consider to use the
+ at ref{filter_script option,,-filter_script option,ffmpeg} or
+ at ref{filter_complex_script option,,-filter_complex_script option,ffmpeg}.
+
 @chapter Timeline editing
 
 Some filters support a generic @option{enable} option. For the filters
@@ -12359,11 +12371,11 @@ braces is a function name, possibly followed by arguments separated by ':'.
 If the arguments contain special characters or delimiters (':' or '@}'),
 they should be escaped.
 
-Note that they probably must also be escaped as the value for the
- at option{text} option in the filter argument string and as the filter
-argument in the filtergraph description, and possibly also for the shell,
-that makes up to four levels of escaping; using a text file avoids these
-problems.
+Note that they probably must also be escaped as the value for the @option{text}
+option in the filter argument string and as the filter argument in the
+filtergraph description, and possibly also for the shell, that makes up to four
+levels of escaping; using a text file with the @option{textfile} option avoids
+these problems.
 
 The following functions are available: