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

[Michael Niedermayer]

On Thu, Aug 10, 2017 at 01:46:27PM +0200, Nicolas George wrote:
> It does not mean that we intend to break the order of options
> at a whim, but it gives us more freedom to make necessary
> changes without extra unnecessary burden while giving stability
> to users that require it.
> 
> Signed-off-by: Nicolas George <george at nsup.org>
> ---
>  Changelog        | 3 +++
>  doc/filters.texi | 5 +++++
>  2 files changed, 8 insertions(+)
> 
> 
> Another argument that I did not think to bring up earlier: with this change,
> it becomse similar to GNU long options or Vim commands: users can shorten
> the commands or options, as long as it is not ambiguous; but new options or
> commands can make it ambiguous, requiring a longer prefix, so long-term
> scripts must be written with the full name. Users are perfectly aware about
> it and do not fuss over it because they understand this small price is
> necessary for evolution.
> 
> 
> diff --git a/Changelog b/Changelog
> index c797d68a36..78286e3606 100644
> --- a/Changelog
> +++ b/Changelog
> @@ -32,6 +32,9 @@ version <next>:
>  - unpremultiply video filter
>  - tlut2 video filter
>  - floodfill video filter
> +- The order of options in filters is no longer considered stable. If
> +  long-term stability is necessary (i.e. for scripts), use named options
> +  (e.g. overlay=50:100 -> overlay=x=50:y=100).
>  
>  version 3.3:
>  - CrystalHD decoder moved to new decode API
> diff --git a/doc/filters.texi b/doc/filters.texi
> index eedc7b5896..470ffa60a1 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -161,6 +161,11 @@ follow the same constraints order of the previous point. The following
>  
>  @end itemize
>  
> +Future evolutions of filters may require inserting new options or changing
> +their order, especially for the non-essential options, and that would break
> +options given without their name. For that reason, uses that require
> +stability should favor the @var{key=value} notation.

Please limit the notes in filters.texi and Changelog to the filters and
options you intend to change.

thanks

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

Frequently ignored answer#1 FFmpeg bugs should be sent to our bugtracker. User
questions about the command line tools should be sent to the ffmpeg-user ML.
And questions about how to use libav* should be sent to the libav-user ML.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: Digital signature
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20170810/ae47da2b/attachment.sig>