[FFmpeg-devel] [PATCH 01/16] doc/filters: document the unstability of the shorthand options notation.

[Alexander Strasser]

Hi all,

sorry for jumping into the discussion late. I think it is very
important though. Please pardon me if I missed anything from
the previous discussions on this topic.


On 2017-08-11 23:34 +0200, Nicolas George wrote:
> Le quartidi 24 thermidor, an CCXXV, Clement Boesch a écrit :

[...]

> > BTW, now that I think about it, how about this:
> > 
> > We add a flag to AVOption such as AV_OPT_FLAG_FILTER_STABLE_SHORTHAND and
> > flag all the options that we believe won't need to move in the future and
> > for which we can always rely on (typically x and y in overlay, or w and h
> > in scale).
> > 
> > Then we simply warn the user for every shorthand use of other options
> > ("using short-hand form with '<option>' may cause issue in the future as
> > it could be swapped around").

Besides AV_OPT_FLAG_FILTER_STABLE_SHORTHAND being an awfully long name
for it, I think it is a good idea.

Maybe even explicitly marking the options that can be used without name
and have a stable order and not allowing the others to be used without
name would be even better. Documentation should clearly indicate for
which options the name could be omitted. I guess we would have to come 
up with a clean notation for that, but that shouldn't be too hard.


> > That way, we:
> > 
> > - give clear visibility of the instability of (some of) the shorthands
> > - affect only marginal uses (that is, late options because we are
> >   generally going to flag the few first ones)
> > - gain flexibility to indeed swap around the options at will in the future
> >   (we initially wait for a release or two such that the users gets aware
> >   of their potential misuses with the introduced warning)
> > - keep shorthands useful for the most essential cases
> > - provide trust on the current use of shorthands.
> 
> It looks nice on principle, but I think you forget one consideration
> about convenience: learning which option is stable and which is not
> requires more effort than just putting the names of the options always.
> So as soon as we acknowledge that some options are not stable with
> shorthand, it becomes more convenient to use the names, and any
> mitigation scheme that can be implemented will just be mostly unused.

I do not think so. For many use cases *not* using named options will
clearly be more attractive, e.g. only one stupid and simple example is
vf fps.

I think if it is not allowed (like I suggested above) to give some
arguments with the shorthand notation, this will support the use cases
where using the shorthand notation is most useful and convenient.


> Think of it that way: if we had designed the filters with an
> AVOption-based system from the start instead of going for a simple
> string and a custom parser, same as every time, would we have
> implemented the shorthand system? No, we would just have used the
> standard key=value:key=value... parser. The shorthand system only exists
> because we thought we could get away with parsing the filters options
> with sscanf(opt_str, "%d:%d", &w, &h) and we did not have the
> clairvoyance to make a clean break when switching to AVOption.

To me this reads like a huge over simplification, though it is
partially correct. But I strongly believe the shorthand notation
was always much more than a side effect of choosing the wrong
way to implement things.


  Alexander