[FFmpeg-devel] [PATCH] Document the preset files system
The Wanderer
inverseparadox
Mon Sep 29 02:27:31 CEST 2008
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.
More information about the ffmpeg-devel
mailing list