From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id ED4474AC16 for ; Thu, 16 May 2024 11:25:23 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 80B6968D44F; Thu, 16 May 2024 14:25:21 +0300 (EEST) 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 50E9C68B02D for ; Thu, 16 May 2024 14:25:15 +0300 (EEST) Received: from 5.f.3.0.5.d.d.e.2.7.f.f.9.7.2.c.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:c279:ff72:edd5:3f5] helo=andrews-2024-laptop.sayers) by painless-a.thn.aa.net.uk with smtp (Exim 4.96) (envelope-from ) id 1s7ZEY-004ndy-1d for ffmpeg-devel@ffmpeg.org; Thu, 16 May 2024 12:25:14 +0100 Date: Thu, 16 May 2024 12:25:07 +0100 From: Andrew Sayers To: FFmpeg development discussions and patches Message-ID: References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240515155446.3589239-1-ffmpeg-devel@pileofstuff.org> <20240515155446.3589239-4-ffmpeg-devel@pileofstuff.org> <5de1288a-c548-447f-9f78-faa609764068@lynne.ee> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <5de1288a-c548-447f-9f78-faa609764068@lynne.ee> Subject: Re: [FFmpeg-devel] [PATCH v4 3/4] all: Link to "context" from all contexts with documentation 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 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: On Wed, May 15, 2024 at 06:46:19PM +0200, Lynne via ffmpeg-devel wrote: > On 15/05/2024 17:54, Andrew Sayers wrote: > > Some headings needed to be rewritten to accomodate the text, > > (hopefully) without changing the meaning. > > --- > > libavcodec/aac/aacdec.h | 2 +- > > libavcodec/aacenc.h | 2 +- > > libavcodec/ac3enc.h | 2 +- > > libavcodec/amfenc.h | 2 +- > > libavcodec/atrac.h | 2 +- > > libavcodec/avcodec.h | 3 ++- > > libavcodec/bsf.h | 2 +- > > libavcodec/cbs.h | 2 +- > > libavcodec/d3d11va.h | 3 +-- > > libavcodec/h264dsp.h | 2 +- > > libavcodec/h264pred.h | 2 +- > > libavcodec/mediacodec.h | 2 +- > > libavcodec/mpegaudiodec_template.c | 2 +- > > libavcodec/pthread_frame.c | 4 ++-- > > libavcodec/qsv.h | 6 ++++-- > > libavcodec/sbr.h | 2 +- > > libavcodec/smacker.c | 2 +- > > libavcodec/vdpau.h | 3 ++- > > libavcodec/videotoolbox.h | 5 +++-- > > libavfilter/avfilter.h | 2 +- > > libavformat/avformat.h | 3 ++- > > libavformat/avio.h | 3 ++- > > libavutil/audio_fifo.h | 2 +- > > libavutil/hwcontext.h | 21 ++++++++++++--------- > > libavutil/hwcontext_cuda.h | 2 +- > > libavutil/hwcontext_d3d11va.h | 4 ++-- > > libavutil/hwcontext_d3d12va.h | 6 +++--- > > libavutil/hwcontext_drm.h | 2 +- > > libavutil/hwcontext_dxva2.h | 4 ++-- > > libavutil/hwcontext_mediacodec.h | 2 +- > > libavutil/hwcontext_opencl.h | 4 ++-- > > libavutil/hwcontext_qsv.h | 4 ++-- > > libavutil/hwcontext_vaapi.h | 6 +++--- > > libavutil/hwcontext_vdpau.h | 2 +- > > libavutil/hwcontext_vulkan.h | 4 ++-- > > libavutil/lfg.h | 2 +- > > 36 files changed, 66 insertions(+), 57 deletions(-) > > I still don't like this part. There's no reason to link this everywhere when > no one will be bothered to. The document alone is enough IMO. Readers who don't already know the word "context" need a sign that it's a word they need to pay attention to. For example, I come from an OOP background where the word "object" is used so widely, it simply never comes up. In fact, I'm probably not the only person who followed the link to AVClass instead, which just makes FFmpeg look like a failed attempt at OOP if you don't know about contexts. Linking widely lets an attentive reader see this *before* they get the wrong end of the stick, and gives an overwhelmed newbie enough hints that this is a word they need to pay attention to. To underline the previous point - an attentive reader could probably make do with e.g. just links from AVClass and a handful of the most popular contexts. But newbies are often inefficient learners who need many reminders before they stop paying attention to random things. So linking as widely as possible makes the project more accessible to people with less experience. _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".