[FFmpeg-devel] [PATCH 1/2] doc/encoders: Reformat libmp3lame doc

[Stefano Sabatini]

On date Tuesday 2013-08-13 12:43:20 -0700, Timothy Gu encoded:
> On Sat, Aug 10, 2013 at 5:19 AM, Timothy Gu <timothygu99 at gmail.com> wrote:
> > On Saturday, August 10, 2013, Stefano Sabatini wrote:
> >>
> >> On date Saturday 2013-08-03 16:56:41 -0700, Timothy Gu encoded:
> >> > ---
> >> >  doc/encoders.texi | 38 +++++++++++++++++++++++---------------
> >> >  1 file changed, 23 insertions(+), 15 deletions(-)
> >> >
> >> > diff --git a/doc/encoders.texi b/doc/encoders.texi
> >> > index 727549f..cdbe0bf 100644
> >> > --- a/doc/encoders.texi
> >> > +++ b/doc/encoders.texi
> >> > @@ -420,26 +420,34 @@ Requires the presence of the libmp3lame headers
> >> > and library during
> >> >  configuration. You need to explicitly configure the build with
> >> >  @code{--enable-libmp3lame}.
> >> >
> >> > - at subsection Option Mapping
> >> > + at subsection Options
> >> >
> >> > -The following options are supported by the libmp3lame wrapper,
> >> > -the LAME-equivalent options follow the FFmpeg ones.
> >>
> >> > +The following options are supported by the libmp3lame wrapper. The
> >>
> >> Trailing space.
> >>
> >> > + at command{lame}-equivalent of the options are listed in parentheses.
> >> >
> >> > - at multitable @columnfractions .2 .2
> >> > - at item FFmpeg            @tab LAME
> >> > - at item b                 @tab b
> >> > + at table @option
> >> > + at item b (@emph{-b})
> >> >  Set bitrate expressed in bits/s, LAME @code{bitrate} is expressed in
> >> >  kilobits/s.
> >> > - at item q                 @tab V
> >> > -Set quality setting for VBR.
> >> > - at item compression_level @tab q
> >> > -Set algorithm quality. Valid arguments are integers in the 0-9 range.
> >> > - at item reservoir         @tab N.A.
> >> > -Enable use of bit reservoir. LAME has this enabled by default.
> >> > - at item joint_stereo      @tab -m j
> >> > +
> >>
> >> > + at item q (@emph{-V})
> >> > +Set constant quality setting for VBR.
> >>
> >> I see no "q" option in libmp3lame, maybe it's better to use the
> >> libavcodec equivalent option (q is an ffmpeg tool specific option,
> >> this documentation strives to be generic enough for the library user).
> >
> >
> > What then? global_quality? Then it is confusing for tool users.
> 
> Ping the question

Basically there is no perfect solution to the riddle. What about:

@item q (@emph{-V})
Set constant quality setting for VBR. This option is valid only using
@command{ffmpeg} tool.

@item global_quality ...
?

I'm still unconfortable with the idea of showing an ffmpeg option
which does not correspond to a library option. Probably we should move
the q option to the library instead (let it override the
global_quality option if set). Also quality-related documentation in
the manual is sorely missing.
-- 
FFmpeg = Fast and Foolish Multimedia Picky Evil Geisha