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

[Nicolas George]

Le quartidi 24 thermidor, an CCXXV, Clement Boesch a écrit :
> That looks like it has a marginal effect in this particular case. I'd

I would not have proposed something worse.

> agree with just documenting it in the Changelog and still not making it
> "the rule" (that is, NAK on the doc patch). Also please bump minor or
> micro.

Ok.

> If other people insist on compatibility, I'd suggest the following:
> 
> In ff_framesync2_init(), run av_opt_find() with "eof_action", "shortest"
> and "repeatlast" on parent (AVFilterContext); if you can't find the option
> you fallback on the framesync opts values. Then you wrap the fields and
> options in the filters with ifdefery, and announce the future breakage in
> doc/APIchanges.
> 
> I don't think that's worth the hassle (even though I don't think that's
> much more work), but people may disagree.

I will not oppose if somebody does it, but I think it would be a waste
of time.

> 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").
> 
> 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.

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.

Regards,

-- 
  Nicolas George