On 2020-05-01 03:01, Nicolas George wrote:
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.
Non-beginners already know what a frame rate is, it completely basic
stuff.
Nicolas, I strongly disagree with the term "lazy beginners". This points
to a much larger question: who is the FFmpeg documentation for?
FFmpeg is used by a lot of people. A few of them are FFmpeg core
developers, who have read the ffmpeg/ source code top to bottom. A few
more are experts in digital video, who have worked deeply with the
terminology of the MPEG-2 or H.264 specs. But a lot are ordinary people
who just want to fix a video, or convert a file format, or connect to a
camera. They are doing other things with their life than spending many
hours learning the ffmpeg/ code and MPEG terminology.
This does not make them "lazy". What a condescending thing to say!
And, even though a term like "frame rate" brings up an intuitive
meaning, it is reasonable that different people might have different
intuitive meanings. There is value to stating the meaning explicitly.
One thing that geniuses sometimes do is explain the simple things
clearly, so that everyone gets the same meaning, and has a strong
foundation to build on. For FFmpeg documentation to define fundamental
terms is not weakness.
Does this project want the documentation to be for all the FFmpeg users?
Then it must aim to make it meaningful, even to beginners.
Beginners who want to achieve something by themselves will peruse
https://ffmpeg.org/ffmpeg-all.html#Video-rate and now know what a frame
rate is.
Which ordinary user, coming to FFmpeg to accomplish a task rather than
to learn all about FFmpeg's source code, will read
https://ffmpeg.org/ffmpeg-all.html from top to bottom until they come
across the #Video-rate section? Note that the existing *fps* filter doc
does not link to #Video-rate. How do you expect a beginner to find
FFmpeg's definition of basic terms? The doc lacks a Glossary, it lacks
a Concepts Guide, it lacks a Tutorial, it lacks systematic cross
references from terms used to definitions.
So what you are saying is, the documentation is not for "lazy"
beginners, it is only for beginners who are willing to pay the time to
read the doc top to bottom, or to get a PhD in MPEG. And that excludes
many, many FFmpeg users.
If we want to enhance this, we just have to make sure the doc for every
AV_OPT_TYPE_VIDEO_RATE option has a link to #Video-rate. Nothing more.
I will agree with you on the value of links from parameters to sections
explaining the details of the types and values of that parameter. Note
that my patch to the *fps* doc includes such a link. Note also that not
every potential target of such a link includes an anchor: video filter
/settb/ does not, for example.
I think those links are helpful, but not sufficient.
Duplicating the explanations is a waste of everybody's time.
It is not a waste of time for the user who comes to FFmpeg wanting to
get a task completed. But who is the FFmpeg documentation for? Is it for
those users? Or is it just for the FFmpeg core developers? When you say
"everybody", who do you include?
(I dream of a system where the doc would be not in a separate tree but
built as part of the library, and links like that happen automatically.)
Regards,
Best regards,
—Jim DeLaHunt, software engineer, Vancouver, Canada
_______________________________________________
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".
