From patchwork Tue Jun 4 14:47:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 35137 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9183:0:b0:460:55fa:d5ed with SMTP id s3csp2743406vqg; Tue, 4 Jun 2024 07:49:42 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCV7+02XKn0W6FsozvcgN/Z30gNsLmJ5sQ6u4Ty4Tp+AsH3FGM5mdnivDsZ63GrBii1pyLgLDmkwXUAutjyMW1eRMUCdJicBSFd7Zw== X-Google-Smtp-Source: AGHT+IG5iD2RKzD8bmzaCyrDTGaFHkyvwnnIXUMOPCSeEGDLsVKVK6E+cPuXGjISePoX5kzA0A9S X-Received: by 2002:a50:9518:0:b0:57a:2e93:fe80 with SMTP id 4fb4d7f45d1cf-57a3638e699mr7940629a12.18.1717512582229; Tue, 04 Jun 2024 07:49:42 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717512582; cv=none; d=google.com; s=arc-20160816; b=RXQcrIp1B/3gF757NXm9ovxM/euCCZtoI8uQSkApHQb0UZUNTsiTuXty16/A9E58ed R7xjFD4xHH29szK+aPV8OdoixS+rO6TuRcfjbYuqzZ6kCBXGzC4Uqw29XvHD+o1BXZ05 tyChB9AX6Uq+xuhdevvLz5xZ/HdR1txskH+lxjlhvBnk1lxqRua7ToSMBv7YSp/EbRo7 21wK04nb7mde+9cgZUS3ZQ1DdCNGi/UmVn0uBGXofJrlD6irMvhhaap/gvlUP9OcJdBM c52WSC8r522Jw8zwmKfpS8mEZxi2sXxyir28TXYYTLP595Fn56y5/eG5waDFQNnR34SS CVfQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:references:in-reply-to:message-id :date:to:from:delivered-to; bh=iHaBtEdrpb1Qkkdm7zOFbgSy/qk/8crhlMHFi1Sx5D4=; fh=YOA8vD9MJZuwZ71F/05pj6KdCjf6jQRmzLS+CATXUQk=; b=hjVBZIQzdvyEl+A3ht8nel7xAmTakh9reXXlhMokN60X9HjpxvokZIcHIkhEbY7Xko wxw114e93nAxOp1TVhYCZ81UL6WLSV33u6LvPJoLRMY4Y8BRMlMXwdjGP2zzDEelU0Fp WwFnzIIaYcdQ3eeDM20Ba6lmlPJCZ5k1FDUwOqCbF9+Wup6kpX1Ifho7yWhHOzeWCsns 2/DU3TfZR81SlxtMriSLrRRuAPS8Lfqe06gVwOADQyUyU58ZsnV7fLjAm6mM+wG6tHlh jMmqwIIeIh/wzahqUJUAeClnlAY0xt3LJZ9b3kWeMavNq+StplDbcY706mgJLlMn7lj+ pkWA==; dara=google.com 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 4fb4d7f45d1cf-57a31ca5b00si5269938a12.531.2024.06.04.07.49.40; Tue, 04 Jun 2024 07:49:42 -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 8123E68D702; Tue, 4 Jun 2024 17:49:37 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 28D8C68D6BA for ; Tue, 4 Jun 2024 17:49:31 +0300 (EEST) Received: from 0.b.4.b.7.4.0.8.c.4.a.5.d.8.b.2.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:2b8d:5a4c:8047:b4b0] helo=andrews-2024-laptop.lan) by painless-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1sEVTe-007B97-18 for ffmpeg-devel@ffmpeg.org; Tue, 04 Jun 2024 15:49:30 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Tue, 4 Jun 2024 15:47:20 +0100 Message-ID: <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v6 0/4] doc: Explain what "context" means X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: mlIkImb40sUi I'm making a list of little documentation patches to submit as a set once this patchset is done. I've put Sw{r,s}Context on the list, and will think about their relationship to other opaque AVOptions-enabled structs as part of that. I don't see anything in that discussion that affects this patchset, so let's park that discussion for now. One thing we haven't talked about before, but is worth stating explicitly - smart people tend to conflate "I can't think of anything complex about X" with "there are no complex things about X", so this document needs to sell people on the complexity of each problem before laying out the solution. The AVOptions section is a particularly good example, tackling the implicit question "can't you just use `getopt`?" first then moving on to describe how it solves that problem. Some parts of the document function as responses to questions an FFmpeg developer would never think to ask, because why would you even think to compare AVOptions with getopt? This version emphasises how AVOptions should only be set during configuration. It avoids the words "reflection" and "introspection" altogether, because IMHO they imply an API that can be used in any stage of a struct's lifetime. Aside: this is the latest in a series of issues where it initially seemed like I was adding unnecessary terminology in places where it was confusing, but turned out to be a symptom of a fundamental misunderstanding on my part. If there's any such language remaining in this version, we should probably look for those misunderstandings first and worry about language second.