[FFmpeg-devel] [PATCH 2/3] doc/filters: propose solutions to avoid shell escaping

[Gyan Doshi]

On 2023-03-26 11:04 pm, Stefano Sabatini wrote:
> Reference drawtext textfile option and ffmpeg -filter_complext_script
> and -filter_script as solutils to avoid shell escaping.

Typos:  `-filter_complext_script` and `solutils`.

Rest: LGTM.

Regards,
Gyan

>
> Address issue:
> http://trac.ffmpeg.org/ticket/9008
> ---
>   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:
>