[FFmpeg-devel] [PATCH] doc/encoders: add libvorbis doc

[Stefano Sabatini]

On date Friday 2013-10-18 17:07:27 -0700, Timothy Gu encoded:
> Signed-off-by: Timothy Gu <timothygu99 at gmail.com>
> ---
>  doc/encoders.texi | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
> 
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index a96c1fc..ed61516 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -771,6 +771,56 @@ respectively. The default is 0 (cutoff disabled).
>  
>  @end table
>  
> + at section libvorbis
> +
> +libvorbis encoder wrapper.
> +
> +Requires the presence of the libvorbisenc headers and library during
> +configuration. You need to explicitly configure the build with
> + at code{--enable-libvorbis}.
> +
> + at subsection Options
> +

> +The following is an option mapping table describing options supported
> +by the libvorbis wrapper, and their @command{oggenc}-equivalent
> +in parentheses.

I prefer this (simpler and more direct):

The following options are supported by the libvorbis wrapper. The
@command{oggenc}-equivalent of the options are listed in parentheses.

(you can skip the first sentence)

> +
> +To get a more accurate and extensive documentation of the libvorbis
> +options, consult the libvorbisenc's and @command{oggenc}'s documentations.

Possibly provide a link to the project website, and while at it also a
link to oggenc(1) manual.

> +
> + at table @option
> + at item b (@emph{-b})
> +Set bitrate expressed in bits/s for ABR. @command{oggenc} @option{-b} is
> +expressed in kilobits/s.
> +
> + at item q (@emph{-q})
> +Set constant quality setting for VBR. The value should be a float
> +number in the range of -1.0 to 10.0. The higher the value, the better
> +the quality. The default value is @samp{3.0}.
> +
> +This option is valid only using the @command{ffmpeg} command-line tool.
> +For library interface users, use @option{global_quality}.
> +

> + at item cutoff (@emph{--advanced-encode-option lowpass_frequency=@var{N}})

I'm not sure the renderer support nested markup.

> +Set cutoff bandwidth in Hz. @command{oggenc}'s related option is
> +expressed in kHz.The default value is @samp{0} (cutoff disabled).

Nit: kHz._The...

Also I prefer: Set cutoff bandwidth in Hz, a value of 0 disable
cutoff. @command{oggenc}'s related option is expressed in kHz. The
default value is @samp{0} (cutoff disabled).

> +
> + at item minrate (@emph{-m})
> +Set minimum bitrate expressed in bits/s. @command{oggenc} @option{-m} is
> +expressed in kilobits/s.
> +
> + at item maxrate (@emph{-M})
> +Set maximum bitrate expressed in bits/s. @command{oggenc} @option{-M} is
> +expressed in kilobits/s. This only has effect on ABR mode.
> +

> + at item iblock (@emph{--advanced-encode-option impulse_noisetune=@var{N}})

Same here, verify that nested markup works, otherwise you can use impulse_noisetune=N

> +Set noise floor bias for impulse blocks. The value is a float number from
> +-15.0 to 0.0. A negative bias instructs the encoder to pay special attention
> +to the crispness of transients in the encoded audio. The tradeoff for better
> +transient response is a higher bitrate.
> +
> + at end table
> +

LGTM otherwise.
-- 
FFmpeg = Friendly & Fundamental Maxi Peaceful Elected Gladiator