[FFmpeg-devel] [PATCH] Document the preset files system

[The Wanderer]

Stefano Sabatini wrote:

> Hi,
> as in subject.
> 
> BTW, currently ffmpeg looks for preset files in these directories:
> 
>     const char *base[3]= { getenv("HOME"),
>                            "/usr/local/share",
>                            "/usr/share",
>                          };
> 
> I think it would make sense to also look in $prefix/share/ffmpeg, for example
> if I install in /opt/ then it should look in /opt/share/ffmpeg (this
> will also require to export the prefix value in config.h).

FTLIW, this would also make sense to me.

> + at section Preset files
> +
> +Preset files are specified with the @code{vpre}, @code{apre} and
> + at code{spre} options.
> +
> +Preset files contains a sequence of @var{option}=@var{value} pairs,
> +one for each line, which specify a sequence of options which would be
> +awkward to specify on command line. Also, preset files support #
> +comments starting at the beginning of the line. Check the
> + at file{ffpresets} directory in the FFmpeg source tree for examples.

Pluralization inconsistency - you want either "Preset files contain" or
"A preset file contains".

"on the command line"

Do we expect everyone using this feature to be able to understand
immediately what "# comments" means? It took me a second or so in this
case, by virtue of the coincidence that the symbol appears at the end of
its own line and so I did not immediately interpret it as having
semantic meaning.

> +Preset files should be terminated by the @code{.ffpreset} suffix. When
> +specifying a preset file on commandline you can specify just the name
> +without prefix, for example @code{libx264-max}, in this case ffmpeg
> +will search a file named @file{libx264-max.ffpreset} in the
> + at file{$HOME/.ffmpeg}, @file{/usr/local/share/ffmpeg} and
> + at file{/usr/share/ffmpeg} directories in this order.

"on the command line"

Too much commage in the second sentence; needs rephrasing. Something
like

"When specifying a preset file on the command line, you can specify just
the name without a prefix. For example, specifying @code{libx264-max}
tells ffmpeg to search for a file named @file{libx264-max.ffpreset} in
the @file{$HOME/.ffmpeg}, @file{/usr/local/share/ffmpeg} and
@file{/usr/share/ffmpeg} directories in that order."

might do.

> +If a file is not found applying the previous rule, then ffmpeg will
> +search a file named @var{CODEC_NAME}- at var{ARG}.ffpreset in the above
> +mentioned directories, where @var{CODEC_NAME} is the name of the
> +currently selected codec with the type specified by the command
> +prefix. For example the argument @code{max} will correspond to the
> +file @file{libx264-max.ffpreset} if the currently selected codec is
> + at code{libx264}.

"If a file is not found applying the previous rule" - for one thing this
is ungrammatical (something to do with the verb tense), for another it
seems somewhere between unclear and misleading to me. Am I correct that
it would be equally accurate to say "If no file is specified on the
command line"?

"will search a file" -> "will search for a file"

"above mentioned" -> either "above-mentioned" or (possibly less
standard) "abovementioned"

Beyond that I can't really improve this, largely because I don't
understand it well enough for the degree of rewriting it would require.
(I think it's talking about automatically choosing a preset based on the
specified codec name and on something else, but I have no real idea what
the else is from a user perspective, and I don't see where in the code
this paragraph comes from in the first place.)

Honestly, I would prefer to rewrite (and reorganize) these last three
paragraphs entirely, if I were certain that I understood them correctly.

-- 
       The Wanderer

Warning: Simply because I argue an issue does not mean I agree with any
side of it.

Secrecy is the beginning of tyranny.