[FFmpeg-devel] [PATCH] doc/filters: do not assume shell escaping in select examples

[Stefano Sabatini]

On date Wednesday 2012-12-12 21:24:19 +0100, Clément Bœsch encoded:
> On Tue, Dec 11, 2012 at 11:42:51PM +0100, Stefano Sabatini wrote:
> > We assume that the filter specified is the string passed as
> > filtergraph. Possibly less confusing, since the shell escaping is
> > shell-dependent.
> > ---
> >  doc/filters.texi |   12 ++++++------
> >  1 file changed, 6 insertions(+), 6 deletions(-)
> > 
> > diff --git a/doc/filters.texi b/doc/filters.texi
> > index cea6384..54d73b2 100644
> > --- a/doc/filters.texi
> > +++ b/doc/filters.texi
> > @@ -4751,37 +4751,37 @@ select=0
> >  @item
> >  Select only I-frames:
> >  @example
> > -select='eq(pict_type\,I)'
> > +select='eq(pict_type,I)'
> >  @end example
> >  
> >  @item
> >  Select one frame every 100:
> >  @example
> > -select='not(mod(n\,100))'
> > +select='not(mod(n,100))'
> >  @end example
> >  
> >  @item
> >  Select only frames contained in the 10-20 time interval:
> >  @example
> > -select='gte(t\,10)*lte(t\,20)'
> > +select='gte(t,10)*lte(t,20)'
> >  @end example
> >  
> >  @item
> >  Select only I frames contained in the 10-20 time interval:
> >  @example
> > -select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
> > +select='gte(t,10)*lte(t,20)*eq(pict_type,I)'
> >  @end example
> >  
> >  @item
> >  Select frames with a minimum distance of 10 seconds:
> >  @example
> > -select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
> > +select='isnan(prev_selected_t)+gte(t-prev_selected_t,10)'
> >  @end example
> >  
> >  @item
> >  Use aselect to select only audio frames with samples number > 100:
> >  @example
> > -aselect='gt(samples_n\,100)'
> > +aselect='gt(samples_n,100)'
> >  @end example
> 

> I don't think that's less confusing. At least it won't be for users
> expecting escaping issue. In the current situation, reading these
> examples, users are aware about the ',' and related filtergraph escaping
> that might be needed (and actually is, most of the time). If you remove
> them from example, they will have a hard time trying to figure out what's
> wrong.

I know that this is controversial, but the current examples are
confusing in a different way. What is the user expected to write?

-af aselect='gt(samples_n\,100)'
or
-af "aselect='gt(samples_n\,100)'"
?

The first syntax assumes that the user is passing the string to a
shell (not true for programmatic use), and is also assuming that the
shell is bash or sh-like and supports a specific type of escaping.

Thus I rather prefer:
aselect='gt(samples_n,100)'

which will have to be escaped in *sh as:
-af "aselect='gt(samples_n,100)'"

and doesn't assume the use of a shell (or of a particular shell).
-- 
FFmpeg = Faithful Fundamentalist Mega Pure Extensive Glue