[FFmpeg-devel] [PATCH 2/2] doc/filters: Reformat scale filter doc

[Stefano Sabatini]

On date Saturday 2013-08-03 16:27:53 -0700, Timothy Gu encoded:
> ITU-R BT.470-6 is superseded in 2005. Its successor, BT.470-7, is just a
> wrapper to BT.1700 and BT.1701-1. It turns out that 1700 and 1701-1 has some
> overlapping parts, but with different names. As a result, I add 1700 and
> 1701-1, and keep 470-6 because of its popularity.
> ---
>  doc/filters.texi | 106 ++++++++++++++++++++++++++++++++++---------------------
>  1 file changed, 66 insertions(+), 40 deletions(-)

Can't apply this one (it probably depends on another patch).

> 
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 0adec4b..13ee4b2 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -6294,33 +6294,45 @@ Scale (resize) the input video, using the libswscale library.
>  The scale filter forces the output display aspect ratio to be the same
>  of the input, by changing the output sample aspect ratio.
>  
> +If the input image format is different from the format requested by
> +the next filter, the scale filter will convert the input to the
> +requested format.
> +
> + at subsection Options
>  The filter accepts the following options:
>  
>  @table @option
>  @item width, w
> -Set the output video width expression. Default value is @code{iw}. See
> -below for the list of accepted constants.
> -
>  @item height, h
> -Set the output video height expression. Default value is @code{ih}.
> -See below for the list of accepted constants.
> +Set the output video dimension expression. Default value is the input
> +dimension.
> +
> +If the value is 0, the input width is used for the output.
> +
> +If one of the values is -1, the scale filter will use a value that
> +maintains the aspect ratio of the input image, calculated from the
> +other specified dimension. If both of them are -1, the input size is
> +used
> +
> +See below for the list of accepted constants for use in the dimension
> +expression.
>  
>  @item interl
> -Set the interlacing. It accepts the following values:
> +Set the interlacing mode. It accepts the following values:
>  
> - at table @option
> + at table @samp
>  @item 1
> -force interlaced aware scaling
> +Force interlaced aware scaling.
>  
>  @item 0
> -do not apply interlaced scaling
> +Do not apply interlaced scaling.
>  
>  @item -1
> -select interlaced aware scaling depending on whether the source frames
> -are flagged as interlaced or not
> +Select interlaced aware scaling depending on whether the source frames
> +are flagged as interlaced or not.
>  @end table
>  
> -Default value is @code{0}.
> +Default value is @samp{0}.
>  
>  @item flags
>  Set libswscale scaling flags. If not explictly specified the filter
> @@ -6333,44 +6345,69 @@ form @var{width}x at var{height}.
>  @item in_color_matrix
>  @item out_color_matrix
>  Set in/output YCbCr colorspace type.
> +
>  This allows the autodetected value to be overridden as well as allows forcing
>  a specific value used for the output and encoder.
> +
>  If not specified, the colorspace type depends on the pixel format.
> +
> +Possible values:
> +
>  @table @samp
>  @item auto
> -Choose automatically
> +Choose automatically.
>  
>  @item bt709
> -ITU Rec BT709
> +Format conforming to International Telecommunication Union (ITU)
> +Recommendation BT.709.

"Format" is probably not the best term to use. I suggest: "Set
colorspace conforming to...", here and below.
>  
>  @item fcc
> -United States Federal Communications Commission Title 47 Code of
> -Federal Regulations (2003) 73.682 (a)
> +Format conforming to the United States Federal Communications Commission

> +(FCC) Code of Federal Regulations (CFR) Title 47 (2003) §73.682 (a).
                                                           ^

Please double check that the non-ascii char is correctly rendered in
MAN and HTML output, we had issues in the past (then our current
toolchain sucks, but that's a separate issue), just skip it in case of
problems.

>  
>  @item bt601
> -ITU Rec BT601
> -ITU-R Rec. BT.470-6 System B, G
> -Society of Motion Picture and Television Engineers 170M (2004)
> +Format conforming to:
> +
> + at itemize
> + at item
> +ITU Recommendation BT.601,
> +
> + at item
> +ITU-R Rec. BT.1700 (2005) 625 PAL system and 625-line SECAM system,
> +
> + at item
> +ITU Radiocommunication Sector (ITU-R) Rec. BT.1701-1 (2005) Systems B,
> +B1, and G,
> +
> + at item
> +ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G, and
> +
> + at item
> +Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004.
> +

Not sure, this may be overkill, also it probably belongs to a separate
non-reformatting patch, since it's adding content.

Alos, in a list you're entitled to drop the ending "," at the end of
each item.

> + at end itemize
>  
>  @item smpte240m
> -Society of Motion Picture and Television Engineers 240M
> +Format conforming to SMPTE ST 240:1999.
>  @end table
>  
>  @item in_range
>  @item out_range
>  Set in/output YCbCr sample range.
> +
>  This allows the autodetected value to be overridden as well as allows forcing
> -a specific value used for the output and encoder.
> -If not specified, the range depends on the pixel format.
> +a specific value used for the output and encoder. If not specified, the
> +range depends on the pixel format. Possible values:
> +

>  @table @samp
>  @item auto
> -Choose automatically
> +Choose automatically.
>  
>  @item jpeg/full/pc
> -Full range (0-255 in case of 8bit luma)
> +Full range (0-255 in case of 8-bit luma).
>  
>  @item mpeg/tv
> -"Mpeg" range (16-235 in case of 8bit luma)
> +"MPEG" range (16-235 in case of 8-bit luma).
>  @end table

Nit: Set full range ... Set MPEG range for grammatical consistency.

[...]

Looks good otherwise.
-- 
FFmpeg = Foolish Fanciful Maxi Ponderous Earthshaking Gigant