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

[Clément Bœsch]

On Tue, Oct 30, 2012 at 10:52:47PM +0100, Stefano Sabatini wrote:
> On date Tuesday 2012-10-30 22:03:54 +0100, Stefano Sabatini encoded:
> > 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(-)
> 
> Bah, updated after auto-review, scrap the previous version from your
> hard-disk.
> -- 
> FFmpeg = Fanciful and Fostering Most Practical Enlightened God

> From e5762586e47bac5e9f280b895857c169d7ad6e9a Mon Sep 17 00:00:00 2001
> From: Stefano Sabatini <stefasab at gmail.com>
> Date: Tue, 30 Oct 2012 22:02:29 +0100
> Subject: [PATCH] doc/filters: add "Notes on filtergraph escaping" section
> 
> Should help to clarify escaping issues in the filtergraph syntax. In
> particular, should address trac ticket #1813.
> ---
>  doc/filters.texi |   37 +++++++++++++++++++++++++++++++++++++
>  1 files changed, 37 insertions(+), 0 deletions(-)
> 
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 937d11b..7c66b28 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -191,6 +191,42 @@ 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=value pairs in a named options
> +list. In this case the user should perform a double level
> +escaping. For example, consider the following literal string to be
> +embedded in the @ref{drawtext} filter arguments:
> + at example
> +this is a 'string': may contain one, or more, special characters
> + at end example
> +
> +Since @code{:} is special for the 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
> +description 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
> +

Eventually add a note saying you can avoid escaping the comma when
enclosing the value with quotes.

> +Finally an additional level of escaping may be needed when writing the
> +filtergraph description in a shell command, which depends on the
> +escaping rules of the adopted shell. For example, assuming that
> + at code{\} is special and needs to be escaped with another @code{\}, the
> +previous string will finally result in:
> + at example
> +-vf "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.
> +

This escaping is insane, but the patch LGTM :)

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121031/4b68b102/attachment.asc>