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

[Ganesh Ajjanagadde]

On Thu, Nov 5, 2015 at 9:47 AM, Ronald S. Bultje <rsbultje at gmail.com> wrote:
> 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.)

I like your idea. I had originally decided against it as it is a
maintenance burden: every filter will now need a link, and there are a
lot of filters. Furthermore, it is easily missed during filter docs
review, etc. Will wait for any further thoughts on this, else will
rework on your lines. Thanks.

>
> Ronald