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

[Stefano Sabatini]

On date Wednesday 2013-08-14 17:51:38 -0700, Timothy Gu encoded:
> ---
>  doc/encoders.texi | 58 +++++++++++++++++++++++++++++++++++++++----------------
>  1 file changed, 41 insertions(+), 17 deletions(-)
> 
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 585eae6..45f5b2c 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -420,26 +420,50 @@ 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
> + 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
> -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 table @option

> + at item b (@emph{-b})
> +Set bitrate expressed in bits/s for CBR. LAME @code{bitrate} is
> +expressed in kilobits/s. This option is valid only using
> + at command{ffmpeg} command-line tool.

the @command{ffmpeg} command-line tool.

> +
> + at item bit_rate (@emph{-b})
> +Set bitrate expressed in bits/s for CBR. LAME @code{bitrate} is
> +expressed in kilobits/s. This option is valid only using
> + at samp{libavcodec} library interface.

This is a bit confusing. The AVCodecContext fields is named
"bit_rate", but I think we should only mention the corresponding
AVOption here (which can be set via commandline or through the av_opt
interface), which is named "b". Thus I'd remove this part altogether.

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

> + at item global_quality (@emph{-V})
> +Set constant quality setting for VBR. This option is valid only using
> + at samp{libavcodec} library interface.

Skip the second part, since the user can decide to use global_quality
from the commandline as well. "q" is intended as a shortcut (sets
-flags +qscale, and expresses global quality using a more convenient
scale).

> +
> +The @option{b} and @option{q} are mutually exclusive, as they
> +both set the quality, but refer to two different encoding modes:
> +CBR and VBR. The default is CBR mode (i.e. @option{b} is set).
> +This also applies to @option{bit_rate} and @option{global_quality}.

This also seems a bit redundant in this specific context since it's
more related to the way the library works in general.

[...]

LGTM otherwise, thanks.
-- 
FFmpeg = Freak and Friendly Magnificient Prodigious EnGine