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-requ...@ffmpeg.org with subject "unsubscribe".
