[FFmpeg-devel] [PATCH] doc/encoders: partially rewrite and reformat libx264 docs

[Stefano Sabatini]

On date Saturday 2013-07-20 16:11:04 -0700, Timothy Gu encoded:
> Format is based on the thread:
> "[PATCH] doc/encoders: Add libopus encoder doc" (06-28-2013)
> http://thread.gmane.org/gmane.comp.video.ffmpeg.devel/165368/
> 
> Also merge the two options section (Mapping and Private options).
> 
> Patch partially edited by Stefano Sabatini.
> ---
>  doc/codecs.texi   |   1 +
>  doc/encoders.texi | 419 ++++++++++++++++++++++++++++++++++++------------------
>  2 files changed, 280 insertions(+), 140 deletions(-)
> 
> diff --git a/doc/codecs.texi b/doc/codecs.texi
> index 4af8dcd..6ff2a65 100644
> --- a/doc/codecs.texi
> +++ b/doc/codecs.texi
> @@ -1,3 +1,4 @@
> + at anchor{codec-options}
>  @chapter Codec Options
>  @c man begin CODEC OPTIONS
>  
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index fb47586..00ed064 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -873,178 +873,317 @@ For more information about libvpx see:
>  
>  x264 H.264/MPEG-4 AVC encoder wrapper.
>  
> -Requires the presence of the libx264 headers and library during
> -configuration. You need to explicitly configure the build with
> +This encoder requires the presence of the libx264 headers and library
> +during configuration. You need to explicitly configure the build with
>  @code{--enable-libx264}.
>  
> -x264 supports an impressive number of features, including 8x8 and 4x4 adaptive
> -spatial transform, adaptive B-frame placement, CAVLC/CABAC entropy coding,
> -interlacing (MBAFF), lossless mode, psy optimizations for detail retention
> -(adaptive quantization, psy-RD, psy-trellis).
> +libx264 supports an impressive number of features, including 8x8 and
> +4x4 adaptive spatial transform, adaptive B-frame placement, CAVLC/CABAC
> +entropy coding, interlacing (MBAFF), lossless mode, psy optimizations
> +for detail retention (adaptive quantization, psy-RD, psy-trellis).
>  
> -The FFmpeg wrapper provides a mapping for most of them using global options
> -that match those of the encoders and provides private options for the unique
> -encoder options. Additionally an expert override is provided to directly pass
> -a list of key=value tuples as accepted by x264_param_parse.
> +Many libx264 encoder options are mapped to FFmpeg global codec
> +options, while unique encoder options are provided through private

> +options. Additionally the @option{x264opts} private options allows to

the @option{x264opts} and @option{x264-params} private options allow ...

> +pass a list of key=value tuples as accepted by the libx264
> + at code{x264_param_parse} function.
>  
> - at subsection Option Mapping
> +The x264 project website is at @url{http://www.videolan.org/developers/x264.html}.
> +
> + at subsection Options
>  
> -The following options are supported by the x264 wrapper, the x264-equivalent
> -options follow the FFmpeg ones.
> +The following options are supported by the libx264 wrapper. The
> + at command{x264}-equivalent options or values are listed in parentheses
> +for easy migration.
>  
> - at multitable @columnfractions .2 .2
> - at item b                 @tab bitrate
> -FFmpeg @code{b} option is expressed in bits/s, x264 @code{bitrate} in kilobits/s.
> - at item bf                @tab bframes
> -Maximum number of B-frames.
> - at item g                 @tab keyint
> -Maximum GOP size.
> - at item qmin              @tab qpmin
> - at item qmax              @tab qpmax
> - at item qdiff             @tab qpstep
> - at item qblur             @tab qblur
> - at item qcomp             @tab qcomp
> - at item refs              @tab ref
> - at item sc_threshold      @tab scenecut
> - at item trellis           @tab trellis
> - at item nr                @tab nr
> -Noise reduction.
> - at item me_range          @tab merange
> - at item me_method         @tab me
> - at item subq              @tab subme
> - at item b_strategy        @tab b-adapt
> - at item keyint_min        @tab keyint-min
> - at item coder             @tab cabac
> -Set coder to @code{ac} to use CABAC.
> - at item cmp               @tab chroma-me
> -Set to @code{chroma} to use chroma motion estimation.
> - at item threads           @tab threads
> - at item thread_type       @tab sliced_threads
> -Set to @code{slice} to use sliced threading instead of frame threading.
> - at item flags -cgop       @tab open-gop
> -Set @code{-cgop} to use recovery points to close GOPs.
> - at item rc_init_occupancy @tab vbv-init
> -Initial buffer occupancy.
> - at end multitable
> +To reduce the duplication of documentation, only the private options
> +and some others requiring special attention are documented here. For
> +the documentation of the undocumented generic options, see
> + at ref{codec-options}.
> +

> +To get a more accurate and extensive documentation of the libx264
> +options, for example default behaviors, invoke the command

Remove "for example default behaviors,", which sounds a bit awkward.

[...]

LGTM otherwise, thanks.
-- 
FFmpeg = Forgiving and Frightening Marvellous Prodigious Eretic Guru