From patchwork Thu Aug 10 11:46:27 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicolas George X-Patchwork-Id: 4671 Delivered-To: ffmpegpatchwork@gmail.com Received: by 10.103.46.211 with SMTP id u202csp2306786vsu; Thu, 10 Aug 2017 04:46:49 -0700 (PDT) X-Received: by 10.28.207.77 with SMTP id f74mr7704019wmg.166.1502365609568; Thu, 10 Aug 2017 04:46:49 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1502365609; cv=none; d=google.com; s=arc-20160816; b=xKu26rZLdCYZib1vzfRP1hAqB2Pnpo0Ydodbt2a2CpeuBDPqFtHHrs9Rxa/bfltrpD WDSxLlYf62epmdY1QMAK2DT/Cpj5IdDUvQbXOCPwuMzUoABQgt7cG8sEXD8loDa1YYcy E1b8jz5Gaup/ifNACMVRt8MGJcqjHRHx6bXr1pT1pnzcqMa9H+XhI57VCyb4gp9yiD6O jd3X206G3Fjv9TBdDQ/+/oSe13Zfx0Bkg9YZNOJQXzbaUhN/NnZJ5a7cqwMOk22uZCgU WQePg/ch2Yv3OcsVvAqnJUvWgYVlXdupqnbGlBzii8Fri4SBY+wEMhXYsM5DdgK3pii5 +L2A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:mime-version:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:message-id:date:to:from:delivered-to :arc-authentication-results; bh=c9I8lpNpRKSl0PnzMsggsmi3/i/WeoS/bGBwYvA5xGI=; b=tTOgh1/7sXUAfEd6mdctw/2jChmTkvY42IHHUIoETpIqN4REPPGs9JGmIiPrkrAeCo R2EnF6RgflUAY7G+oFJzlXwkXMJ9Kng0SuMPvUEc3+dq3m5Naod9NNPlkjLY+2uNN1D3 sl93Hvbk85kI+YbKdC9bBk3EGMqnXJJJOp2g12bD47d062EEH2QUzNJb+LyNgQq8O3ui Zo7c6ZLosW6/VgXnmUAHZ+iHnvi6NmDEBgw/GfIzPvjm5AeZMxA4Nvgz2RavzX4/lTev FEbL1+5ZnkXxLdUFf0QXTuLDwXJVwxYSBw08gBV+t6gJLC+pnLatAFJAmY5MSzJu6kBJ m8Xw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id b37si5194923wrb.338.2017.08.10.04.46.49; Thu, 10 Aug 2017 04:46:49 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id B1B08689BF3; Thu, 10 Aug 2017 14:46:43 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from nef2.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 425806899EB for ; Thu, 10 Aug 2017 14:46:43 +0300 (EEST) Received: from phare.normalesup.org (phare.normalesup.org [129.199.129.80]) by nef2.ens.fr (8.13.6/1.01.28121999) with ESMTP id v7ABkjL2043647 for ; Thu, 10 Aug 2017 13:46:45 +0200 (CEST) Received: by phare.normalesup.org (Postfix, from userid 1001) id 3BD47E00FB; Thu, 10 Aug 2017 13:46:45 +0200 (CEST) From: Nicolas George To: ffmpeg-devel@ffmpeg.org Date: Thu, 10 Aug 2017 13:46:27 +0200 Message-Id: <20170810114642.26779-1-george@nsup.org> X-Mailer: git-send-email 2.13.2 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (nef2.ens.fr [129.199.96.32]); Thu, 10 Aug 2017 13:46:45 +0200 (CEST) Subject: [FFmpeg-devel] [PATCH 01/16] doc/filters: document the unstability of the shorthand options notation. X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches MIME-Version: 1.0 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" 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 --- 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 : - 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{|}.