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

Nicolas George george at nsup.org
Fri Aug 11 11:50:21 EEST 2017

Le quartidi 24 thermidor, an CCXXV, Michael Niedermayer a écrit :
> First, I dont think a single developer should declare a whole class of
> interfaces spaning the areas other developers work on unstable against
> one or more objections from them. Or if one has that right then everyone
> else should as well.

So they post a patch on the mailing-list and everybody can discuss it.
That is the way it is supposed to work, and that is exactly what I did.
Are you accusing me of perverting the process or something, or is this
paragraph here only to muddy things more?

> I maintain several filters and clearly stated that this doc-text does not
> apply to them.

Well, good for you. Keep the options on your filter in order. I do not
intend to prevent you from doing so. What are you fussing about?

> order or inserting options in the middle.
> In fact with a unstable order there is no benefit from adding options
> in the middle, noone could reliably use the new order.
> as in if you link to libavfilter 99.123 you can write a:b:c , if you
> link to libavfilter 99.124 you can write a:c:b. Update your distro
> package and it could change in otherwise unchanged applications.

Everybody is already aware of that.

> and none of this in the example above is neccesarily a syntax error
> and gives an error message. the different order could just give
> different results. thats bad design

Yes, that is bad design. And that applies to somebody misremembering
a:c:b when it should have been a:b:c: the whole shorthand notation was
bad design from the start. Thanks for making my point for me.

> I like to re iterate, i do not agree to declaring the option order
> of the filters i maintain as unstable.

You re-iterate, but you do not bring new arguments to the discussion. I
have brought many and you have not addressed half of them. I can
re-state them if you have forgotten.

> Also there is no long list, just a entry in the changelog and in the
> documentation of the specific filter which was changed.

You fail to see from a user's point of view. Try, for one second, to
imagine you are a simple user learning how to use that tool. You read in
the documentation that this filter has stable shorthand notation, and
this one not, this other yes, these two no, and these five give no
information at all. What will you remember? Which filter is stable and
which is not? No, you will remember not to use the shorthand notation,
because writing "x=", "y=" even when it is not necessary is easier than
remembering when it is necessary and when it is not.

Having exceptions and categories is worse than having everything
declared unstable.

> I think we both agree that this is a rare event. And i would argue
> it is NOT a event specific to the shorthand interface. Am i not
> correct that you would similarly change the named interface if a
> cleanup you do benefits from it ?

No, you are not correct at all. Quite the contrary, I have already
explained why it is not true.

The users want stability, I know that. They have it: the named options.
Since they have something that will always work, I can propose to break
something that is just a convenience to type a few less keys. I would
not propose to break the named interface, because there is no backup
stable interface.


  Nicolas George

More information about the ffmpeg-devel mailing list