[FFmpeg-devel] [PATCH 3/3] doc/filters: move scattered remark on av_strtod to a common location

[Ronald S. Bultje]

Hi,

On Thu, Nov 5, 2015 at 9:20 AM, Ganesh Ajjanagadde <gajjanagadde at gmail.com>
wrote:

> On Sun, Nov 1, 2015 at 11:57 AM, Ganesh Ajjanagadde
> <gajjanagadde at gmail.com> wrote:
> > All filters now use av_strtod for accepting floating point parameters.
> > There was an isolated remark on this, but the point applies generally
> > now.
> >
> > This moves the comment and suitably elaborates on it for additional
> > clarity. A link to the code for av_strtod is also provided for the
> > user's benefit.
> >
> > Signed-off-by: Ganesh Ajjanagadde <gajjanagadde at gmail.com>
> > ---
> >  doc/filters.texi | 10 ++++++----
> >  1 file changed, 6 insertions(+), 4 deletions(-)
> >
> > diff --git a/doc/filters.texi b/doc/filters.texi
> > index 15ea77a..0a20531 100644
> > --- a/doc/filters.texi
> > +++ b/doc/filters.texi
> > @@ -45,7 +45,11 @@ lower half the output generated by the
> @var{crop,vflip} filterchain.
> >
> >  Some filters take in input a list of parameters: they are specified
> >  after the filter name and an equal sign, and are separated from each
> other
> > -by a colon.
> > +by a colon. Floating point parameters may all accept an optional IS
> postfix,
> > +e.g 'K', 'M', 'G' for Kilo, Mega, Giga. If 'i' is appended after the
> postfix,
> > +powers of 2 are used instead of powers of 10. The 'B' postfix
> multiplies the
> > +value by 8, and can be appended after another postfix or used alone.
> See also
> > + at code{av_strtod}.
> >
> >  There exist so-called @var{source filters} that do not have an
> >  audio/video input, and @var{sink filters} that will not have audio/video
> > @@ -14371,9 +14375,7 @@ format is guessed from @var{movie_name} or by
> probing.
> >
> >  @item seek_point, sp
> >  Specifies the seek point in seconds. The frames will be output
> > -starting from this seek point. The parameter is evaluated with
> > - at code{av_strtod}, so the numerical value may be suffixed by an IS
> > -postfix. The default value is "0".
> > +starting from this seek point. The default value is "0".
> >
> >  @item streams, s
> >  Specifies the streams to read. Several streams can be specified,
> > --
> > 2.6.2
> >
>
> ping


So, let's assume I'm a user and I saw this new filter called "stuff" and it
has a parameter called "poke", which happens to be a float. If I go to the
website and look for "stuff" -> "poke", I'll see it's a value in a certain
range which means something. But I'll never see the "K" or "M" suffix
remark until I've read the full docs. Discoverability of this feature (in
the docs) is an issue now, and this patch does not fix it, in fact it makes
it slightly worse for the one parameter where it used to be discoverable
and now it isn't anymore.

Is there some way we can add "values can be marked with an IS suffix" as a
link in the docs, where link points to a section in the general avfilter
docs where it's explained a little more elaborate how this works (as you
just did, but with a header)? That way, it becomes discoverable for each
filter with a few more words per filter, without too much duplication.

(This is an issue before and after this patch, so it shouldn't affect
review of this patch, but I think it's sensible to bring up.)

Ronald