[FFmpeg-user] "documented implicitly" part 2 [was: Re: Problem while converting DNG sequnece to video file]

[Jim DeLaHunt]

On 2020-08-21 03:28, Nicolas George wrote:

> Jim DeLaHunt (12020-08-20):
>> Nicolas, do you remember this?
>>
>> On 2020-05-01 03:01, Nicolas George wrote [1]:
>>> Carl Eugen Hoyos (12020-05-01):
>>>>> -The desired output frame rate. The default is @code{25}.
>>>>> +The output frame rate, in frames per second. May be an integer, real, or
>>>>> +rational number, or an abbreviation. The default is @code{25}.
>>>> I seriously wonder who really profits from this change but it may be ok.
>>> I would argue: lazy beginners.
>>> …
> Now that you mention, it, I remember. The fact that I did not find it
> while searching my archives is caused by a misconfiguration of Git in
> your end:
>
> From: list+ffmpeg-dev at jdlh.com
> From: Jim DeLaHunt <list+ffmpeg-dev at jdlh.com>
>
>> I will observe that you didn't actually review the documentation patch which
>> led to that thread. You just latched on to Carl Eugen's "who really profits"
>> comment, and complained. That patch was not my only experience submitting a
>> documentation improvement and having the FFmpeg project's antibodies reject
>> it. But it did vividly clarify for me what the project values and what it
>> does not.
> I stand by my assessment, and reading a little more of your proposal and
> your attitude in this discussion confirms that you have the wrong
> attitude to both submitting patches and writing documentation.
> …[snip]…


Nicholas, I do not intend to relitigate a review of my patch rewriting 
the "fps" filter documentation[1] on the ffmpeg-user list. But also, I 
think your message gives a false impression of what blocked that patch, 
and I don't want to leave that false impression unchallenged.

> There are many components, filters and others, that take a frame rate
> option.…The proper way to document this option is to explain the syntax of a
> frame rate at a central place, along with the syntax of a video size,
> the syntax of a duration, etc., and to have a link to there in the
> documentation of each option using that syntax.…


I actually agree 80% with you about how to document common options like 
frame rate or PTS, in an ideal situation. They should be well documented 
in a central location. Individual filter docs should link to the common 
documentation. We might have minor differences of opinion about whether 
to briefly spell out acronyms in the filter doc as part of the link. We 
could come to some compromise on that. I will observe that present 
FFmpeg documentation is not an idea situation. There is nothing to link 
to for most of the terms in the "fps" filter doc (e.g. PTS). You 
suggested adding all those other pieces: glossary, completing frame 
rate, etc. That grows the scope of the patch, and is against the 
development policy, "Do not commit unrelated changes together" [2]. But 
we could come to a compromise about that also.

What blocked the "fps" filter doc patch boiled down to two substantive 
objections[3]: 1. objection to a 6-times difference in completeness and 
length. 2. objection to places where new doc claimed different 
functionality than old doc. My claim that old doc was wrong about what 
the code did, and new doc was correct. A few developers raised objection 
#1. One developer reviewed the doc patch and raised objection #2. As far 
as I know, neither that developer nor anyone else read the `vf_fps.c` 
code[4] to determine whether the old doc or the new doc was correct. 
And, no other developer cared to give the patch a substantive review, or 
offer a different ruling on objections #1 and #2.


> And this is where we come to your approach to submitting patches: you
> were told, in a very succinct way, that you were wrong. You were
> expected to understand how, but you were welcome to ask clarification. I
> would have explained what I just explained, and pointed that the
> documentation for the syntax of a frame rate already exists:
> http://ffmpeg.org/ffmpeg-all.html#Video-rate


I believe this summary misrepresents the objections that blocked the 
patch. The obstacle was not linking to #Video-rate. It was the patch's 
completeness, and correction of mistaken descriptions[3] (or excessive 
length, and misreading the vf_fps.c, for those who disagree with me). 
The lack of other developers giving a review, and lack of feedback 
saying "it would be OK with these corrections", gave me no confidence of 
clearing the objections.

Now, the ffmpeg-user list is not the place to discuss patches. If there 
is a developer who has become interested in that patch, let me know, and 
I'll take this back to ffmpeg-devel.


> … But instead, you attacked.…


I disagree with your word "attack". I would say I respectfully pushed 
back. And I did not push back against feedback on the merits of the 
patch. I pushed back[5] against your condescending label of the 
documentation audience as "lazy beginners"[6].

I still think the documentation should serve the needs of FFmpeg users 
who are not digital video experts, and who haven't read the FFmpeg 
documentation from end to end. And you used the word "lazy" again just 
now. I guess we still disagree about who the FFmpeg documentation is 
for. That disagreement is indeed a reasonable subject for the 
ffmpeg-user list.

And by the way,

> …The fact that I did not find it while searching my archives is
> caused by a misconfiguration of Git in your end:
> … From: Jim DeLaHunt<list+ffmpeg-dev at jdlh.com>


I take "misconfiguration" as a casual insult, which is unnecessary, 
unhelpful for collaboration, and does not live up to the "Be friendly 
and respectful" rule of the Code of Conduct. It is also mistaken: I 
intentionally subscribe a different email address to ffmpeg-devel than 
to ffmpeg-user, and intentionally use the ffmpeg-devel address on my 
patches. So could you please avoid such casual insults? We have so many 
more substantive things to disagree on.

        —Jim DeLaHunt, software engineer, Vancouver, Canada


[1] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261811.html

[2] http://ffmpeg.org/developer.html#Patches_002fCommitting

[3] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261983.html

[4] 
https://github.com/FFmpeg/FFmpeg/blob/1128aa875367f66ac11adc30364d5652919a2591/libavfilter/vf_fps.c

[5] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261986.html

[6] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261821.html