[FFmpeg-user] "documented implicitly" [was: Re: Why is format=rgb24 required after maskedmerge?]

[Jim DeLaHunt]

On 2020-08-19 10:53, Paul B Mahol wrote:
> On 8/19/20, Jim DeLaHunt <list+ffmpeg-user at jdlh.com> wrote:
>> On 2020-08-19 07:34, Paul B Mahol wrote:
>>> You are deeply confused about our filters.
>>> Any filter can change pixel formats to one that they accepts thus gbrp
>>> is picked instead of packed rgb, this is already documented
>>> implicitly.
>> Wow, "documented implicitly". This is such a classic FFmpeg project
>> statement. The role of documentation is to explain, explicitly, at a
>> suitable level of detail. What does "documented implicitly" even mean?
>>
>> I think this thread points out is that FFmpeg documentation is
>> inadequate. It is hard to prove a negative, but I suspect that the term
>> "pixel format" is not actually defined in the FFmpeg documentation. I
>> suspect that the statement, "Any filter can change pixel formats" is not
>> stated either. Certainly the maskedmerge filter documentation[1] doesn't
>> mention pixel formats at all, much less say what pixel formats the
>> filter sets for its output.
>>
>> …And yet "You are deeply confused about our filters". In other words, the
>> documentation has failed to explain to you what FFmpeg does, the project
>> has failed to write or welcome improved documentation, you do not
>> understand how FFmpeg works — and somehow this is your fault.
> http://ffmpeg.org/ffmpeg-filters.html#toc-Filtergraph-syntax-1
>
> mention it explicitly:
>
> Libavfilter will automatically insert scale filters where format
> conversion is required. It is possible to specify swscale flags for
> those automatically inserted scalers by prepending sws_flags=flags; to
> the filtergraph description.


This continues to be a great example of the FFmpeg project's approach to 
documentation.

1. A sentence about a library adding functional processing steps ("scale 
filters") in buried in a section entitled "syntax", amid paragraphs 
about syntax.

2. the "scale filters" name alludes to changing pixel counts, and the 
linked-to filter documentation[2] talks about "(resize) the input video" 
and about "the input image format" (without defining that term); it does 
not have a parameter for pixel formats or document the pixel formats it 
uses or sets or changes.

3. this reference to "scale filters" is supposed to be responsive to a 
thread about pixel formats.

4. no acknowledgement that the documentation might actually be less than 
perfect. Is it so hard to concede, "you have a point, the docs could be 
better here"?

[1] http://ffmpeg.org/ffmpeg-all.html#maskedmerge
[2] http://ffmpeg.org/ffmpeg-filters.html#scale