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

[Michael Niedermayer]

On Thu, Dec 13, 2012 at 11:44:49AM +0100, Stefano Sabatini wrote:
> On date Thursday 2012-12-13 02:30:09 +0100, Michael Niedermayer encoded:
> > On Thu, Dec 13, 2012 at 12:41:24AM +0100, Stefano Sabatini wrote:
> > > On date Wednesday 2012-12-12 21:24:19 +0100, Clément Bœsch encoded:
> [...]
> > > > >  @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?
> > 
> 
> > The user should be able to copy and paste examples from his web
> > browser, man page viewer or other tool to his terminal
> > and they should work.
> 
> As I explained, this is not always possible.

It is, you can show multiple examples.

You could fix the parser & escaping

Or if you want to show just one example then this should work with
the most common shell(s).
Changing examples that work with the most common shell to examples
that work nowhere is not good

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

I have never wished to cater to the crowd; for what I know they do not
approve, and what they approve I do not know. -- Epicurus
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121213/ed3620f9/attachment.asc>