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

[Marton Balint]

On Tue, 8 Aug 2017, Gyan wrote:

> On Mon, Aug 7, 2017 at 11:11 PM, John Warburton <john at johnwarburton.net>
> wrote:
>
>
>> if an old FFmpeg script of mine breaks, as they have on a couple of
>> occasions, isn't it logical for a user of the command line to go
>> straight to the documentation, and the answer (and the fix) always
>> seems to be there?
>>
>
> If a modified filter with value-only arguments produces unexpected results,
> possible if the new option accepts same type/range as the older option in
> that position, then the user may be confounded as to why the filter is
> behaving differently. Same if the new option isn't accommodating and the
> command doesn't parse. This patch is being inserted in the docs up top, in
> the generic filtering section. The user is unlikely to look there for
> guidance, but in the section specific to the filter. So it may not be clear
> why the filter invocation fails, given the keys aren't present.

That is why I believe a breaking change such as the overlay filter 
option order change should be mentioned in the Changelog.

Regards,
Marton