[MPlayer-DOCS] [PATCH] XviD documentation reaching almost completeness

[Diego Biurrun]

Guillaume POIRIER writes:
> I took some time this morning to have a close look at
> libmpcodecs/ve_xvid4.c and libmpcodecs/ve_xvid.c
> I updated all options, with a note on whether the option exists or
> changed in XviD 1.0, and added all the options that never made it to the
> man page.
> All options are now documented, apart from Aspect Ratio options that
> will be in the near future.

Great news!

> @@ -6033,6 +6037,9 @@
>  For high bitrates, you will find that MPEG quantization preserves more detail.
>  For low bitrates, the smoothing of H.263 will give you less block noise.
>  When using custom matrices, MPEG must be used.
> +.I WARNING:
> +This option is deprecated in XviD-1.0.x, and is remplaced by the quant_type

has been replaced

> +by any MPEG4 decoder besides libavcodec or XviD (2pass mode only).
> +.I WARNING:
> +This option is deprecated in XviD-1.0.x.

(2pass mode only) should be added to the option name.  You are missing
a .br before the warning.

> +.TP
> +.B greyscale
> +Make XviD discard chroma planes so the encoded video is greyscale only.
> +Note that this does not speed up encoding, it just prevents chroma data
> +from being written in the last stage of encoding.
> +.
> +.TP
> +.B debug\ \ 
> +Save per-frame statistics in ./xvid.dbg.
> +This is NOT the 2pass control file.

Don't use uppercase to emphasize, use markup such as .B or .I or just
leave it lowercase.  I'd also put the second sentence in parentheses
so it's clearer that it refers to ./xvid.dbg.

> +.B quant_type=<h263|mpeg>
> +Sets the type of quantizer to use.
> +For high bitrates, you will find that MPEG quantization preserves more detail.
> +For low bitrates, the smoothing of H.263 will give you less block noise.
> +When using custom matrices, MPEG must be used.

I'm not sure if we shouldn't write mpeg and h263 here since the text
refers to the parameters passed to XviD.  It's not completely clear in
which way it is meant to be understood, though.

> +.B quant_intra_matrix=<filename>
> +Load a custom intra matrix file.
> +You can build such file with xvid4conf's matrix editor.

such a file

> +.TP
> +.B quant_inter_matrix=<filename>
> +Load a custom inter matrix file.
> +You can build such file with xvid4conf's matrix editor.

such a file

> +High values make RC compensate very hard the overflow, this can have a

High values make RC compensate the overflow very hard

> +.B container_frame_overhead=<0..>
> +Most of the time users express their target bitrate for video w/o taking
> +care of the video container overhead.
> +This small but (mostly) constant overhead can make the target file size
> +is not respected (oversized result).

This small but (mostly) constant overhead can cause the target file size
to be exceeded.

> +We decided to allow users to set the amount of overhead per frame the
> +container generates (give only an average per frame).

(Give only an average per frame.)

> +0 has a special meaning, it lets XviD uses its own default values

use

> +(default: 24 (AVI frame average overhead per frame in bytes)).

I dislike nested parentheses, how about

(default: 24 - AVI frame average overhead per frame in bytes)

You should be able to leave out the bytes as well.  That the parameter
specifies bytes should be mentioned above.

It's great to see the XviD encoding options finally approaching
complete documentation.

Diego