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

[Stefano Sabatini]

On date Wednesday 2012-10-31 19:10:40 +0100, Clément Bœsch encoded:
> 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 :)

Patch pushed, with the suggested addition, thanks for the review.
-- 
FFmpeg = Frenzy Formidable Merciless Powered Evil Gargoyle