[FFmpeg-devel] [PATCH] doc/ffmpeg - rewrite Stream Selection chapter

[Gyan Doshi]

On 31-05-2018 04:35 AM, Michael Niedermayer wrote:

>> If a user consults the relevant parts of the documentation before execution,
>> they should be able to predict how the program will behave. If they do it
>> afterwards, they should understand what the program did. Even though FFmpeg
>> is an open source project, end users of the CLI tools aren't expected to
>> understand or dive into the source to grasp how the program behaves. It's
>> the job of the docs to convey descriptions of behaviour that will affect
>> what the end user expects the program to do. Do you disagree?
> 
> This will only work to some extend
> Different version will and probably do behave slightly different.

The docs on the website are only for git master.

> I still think its important to draw a line between what is
> A. intended to behave exactly as it does
> B. behaves one way and is just documented to do so.
> 
> Case A is much more likely to be conserved over time
> Case B may change in the implementation whenever it feels convenient to the
> developers i suspect ...

> in a few years this document is maybe still 70% accurate. It would be
> usefull if people today could have a good guess what part will be that 70%
> today, so they could write code that is future proof ...

Agreed. But that depends on the devs recording their intentions in 
writing. In this particular case, I don't see any TODO, FIXME or similar 
notes. The code has remained relatively the same for a few years now. If 
you know what the 70% is, in this case, I'll note that.

I'll add a disclaimer about ffmpeg being under active development and 
that the docs are maintained on a best-effort basis.

Regards,
Gyan