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

[Nicolas George]

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.
+
 If the option value itself is a list of items (e.g. the @code{format} filter
 takes a list of pixel formats), the items in the list are usually separated by
 @samp{|}.
-- 
2.13.2