doc: Libavfilter English cleanup
On Thu, Apr 03, 2014 at 02:35:22PM +0200, Katerina Barone-Adesi wrote:
> This change aims to standardize the English used in the libavfilter
> documentation, describing the same thing in the same way more often,
> and significantly reduce the amount of outright errors, including
> run-on sentences and sentence fragments.
This sentence illustrates why starting a sentence with "this sentence"
feels awkward and redundant. I feel the same about "this change". :)
Thanks for tackling this. I have had proofreading the docs on my todo
list for longer than I can remember, but never found the time.
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -101,12 +101,12 @@ for those automatically inserted scalers by prepending
> @var{LINKLABEL} ::= "[" @var{NAME} "]"
> @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
> -@var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
> +@var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
Sounds suspiciously like a German false friend. I bet a beer that
git blame will confirm :)
> @@ -161,29 +161,29 @@ avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex
> amix=inputs=3:duration=firs
> @item longest
> -Duration of longest input. (default)
> +The duration of longest input. (default)
>
> @item shortest
> -Duration of shortest input.
> +The duration of shortest input.
>
> @item first
> -Duration of first input.
> +The duration of first input.
Shouldn't it be "of the foo input"?
> @@ -327,32 +322,32 @@ Enable stretching/squeezing the data to make it match
> the timestamps. Disabled
> @item min_delta
> -Minimum difference between timestamps and audio data (in seconds) to trigger
> -adding/dropping samples. Default value is 0.1. If you get non-perfect sync
> with
> -this filter, try setting this parameter to 0.
> +The minimum difference between timestamps and audio data (in seconds) to
> trigger
> +adding/dropping samples. The default value is 0.1. If you get an imperfect
> +sync with this filter, try setting this parameter to 0.
s/an// ?
> @item first_pts
> -Assume the first pts should be this value. The time base is 1 / sample rate.
> -This allows for padding/trimming at the start of stream. By default, no
> -assumption is made about the first frame's expected pts, so no padding or
> +Assume that the first PTS should be this value. The time base is 1 / sample
> +rate. This allows for padding/trimming at the start of stream. By default, no
> +assumption is made about the first frame's expected PTS, so no padding or
"start of the stream" I think.
> @@ -368,13 +363,13 @@ Same as @var{end}, except this option sets the end
> timestamp in samples instead
> @item start_sample
> -Number of the first sample that should be passed to output.
> +The number of the first sample that should be passed to output.
s/should be passed to output/should be output/ ?
> @@ -453,39 +448,39 @@ index, starting with zero and increasing by one for
> each mapping.
>
> If no mapping is present, the filter will implicitly map input channels to
> -output channels preserving index.
> +output channels, preserving indices.
I tend to prefer "indexes".
> -To fix a 5.1 WAV improperly encoded in AAC's native channel order
> +Fix a 5.1 WAV improperly encoded in AAC's native channel order:
> @example
> avconv -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
> @end example
IMO the previous version sounds better and makes the two paragraphs
less run-on.
> @@ -495,24 +490,25 @@ may be overridden (by @code{0/out-dBn}). Typical values
> for the transfer
>
> @item soft-knee
> -Set the curve radius in dB for all joints. Defaults to 0.01.
> +Set the curve radius in dB for all joints. It defaults to 0.01.
IMO better: .. joints (default: 0.01).
> @item gain
> -Set additional gain in dB to be applied at all points on the transfer
> function.
> -This allows easy adjustment of the overall gain. Defaults to 0.
> +Set the additional gain in dB to be applied at all points on the transfer
> +function. This allows for easy adjustment of the overall gain.
> +It defaults to 0.
same
Don't add trailing whitespace, it is forbidden.
> @@ -921,71 +918,71 @@ the center of the input image.
>
> -# crop the central input area with size 2/3 of the input video
> +# Crop the central input area with size 2/3 of the input video:
> "crop=out_w=2/3*in_w:out_h=2/3*in_h"
What I said on IRC mostly. I also feel these should be consistent, but
I'd not go down the colon route. I read this as source code comments,
which kind of imply referring to what follows, i.e. the next line.
This applies to all similar such changes.
> @@ -1221,38 +1218,38 @@ For more information about libfreetype, check:
>
> @section fade
>
> -Apply fade-in/out effect to input video.
> +Apply a fade-in/out effect to input video.
".. to the input video" methinks?
> @item type
> -The effect type -- can be either "in" for fade-in, or "out" for a fade-out
> +The effect type can be either "in" for a fade-in, or "out" for a fade-out.
> effect.
WTH stray typo was that?
> -# fade in first 25 frames and fade out last 25 frames of a 1000-frame video
> +# Fade in the first 25 frames and fade out the last 25 frames of an
> 1000-frame video:
> fade=type=in:start_frame=0:nb_frames=25,
> fade=type=out:start_frame=975:nb_frames=25
I think "a" instead of "an" was correct before.
> @@ -1350,40 +1347,40 @@ framerate and processing will stop when the shorter
> video ends. Please note
> @example
> -# Convert left and right views into a frame sequential video.
> +# Convert left and right views into a frame sequential video:
I think it should be "frame-sequential", so while you're changing the
line anyway...
> @@ -1392,18 +1389,18 @@ avconv -i LEFT -i RIGHT -filter_complex
> [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/
> @item filter_name
> -directories specified by the colon separated list in @env{FREIOR_PATH},
> +directories specified by the colon separated list in @env{FREIOR_PATH}.
colon-separated
> @@ -1451,29 +1448,29 @@ This filter is designed for playback only. Do not
> use it prior to
> @item radius
> The neighborhood to fit the gradient to. A larger radius makes for smoother
.. fit the gradient in?
> @@ -1481,35 +1478,35 @@ gradfun=1.2
>
> -High precision/quality 3d denoise filter. This filter aims to reduce
> -image noise producing smooth images and making still images really
> +This is a high precision/quality 3d denoise filter. This filter aims to
> reduce
> +image noise, producing smooth images and making still images really
> still. It should enhance compressibility.
s/This filter/it/ I would say.
> @@ -1614,32 +1611,32 @@ expression
>
> -# set a constant alpha channel value on input
> +# Set a constant alpha channel value on input:
> format=rgba,lutrgb=a="maxval-minval/2"
on the input
> -# correct luminance gamma by a 0.5 factor
> +# Correct luminance gamma by a 0.5 factor:
> lutyuv=y=gammaval(0.5)
by a factor of 0.5
> @@ -1659,18 +1656,18 @@ This filter accepts the following parameters:
>
> @item pix_fmts
> -A '|'-separated list of pixel format names, for example
> +A '|'-separated list of pixel format names, such as
> "pix_fmts=yuv420p|monow|rgb24".
trailing whitespace
> @@ -1732,22 +1729,22 @@ The default value for @var{struct_el} is
> "3x3+0x0/rect".
> # *
> # ***
> # *****
> # ***
> # *
> -# the specified cols and rows are ignored (but not the anchor point
> coordinates)
> +# The specified cols and rows are ignored (but not the anchor point
> coordinates):
Let's get rid of the contractions while we're at it and write "columns"
and "rows".
> @@ -1766,16 +1763,16 @@ Smooth the input video.
>
> -@var{param1}, @var{param2}, @var{param3}, and @var{param4} are
> -parameters whose meanings depend on smooth type. @var{param1} and
> +The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
> +depend on smooth type. @var{param1} and
Depend on the smooth type.
> @@ -1805,28 +1802,28 @@ The parameters are expressions containing the
> following parameters:
> @item pass
> -pass through the main input
> +Pass through the main input.
Shouldn't it be "Pass the main input through."?
> @@ -1834,28 +1831,28 @@ pass through the main input
>
> -# insert 2 different transparent PNG logos (second logo on bottom
> +# Insert 2 different transparent PNG logos (second logo on bottom
> # right corner):
Go figure, there was a colon comment there already. This would have
to be changed the other way around :)
> @@ -2419,62 +2410,62 @@ The input video is not modified.
>
> -A description of each shown parameter follows:
> +This filter accepts the following parameters:
trailing whitespace
> @@ -2565,39 +2554,39 @@ l.r l.L
>
> @item start_frame
> -Number of the first frame that should be passed to output.
> +The number of the first frame that should be passed to output.
.. to the output.
> @@ -2962,7 +2951,7 @@ Set the video duration of the sourced video. The
> accepted syntax is:
> @end example
> -See also the function @code{av_parse_time()}.
> +See also: the @code{av_parse_time()} function.
IMO better: Also see the @code{av_parse_time()} function.
> --- a/doc/libavfilter.texi
> +++ b/doc/libavfilter.texi
> @@ -31,33 +31,33 @@ input --> split --> fifo -----------------------> overlay
> --> output
>
> -There exist so-called @var{source filters} that do not have a video
> -input, and we expect in the future some @var{sink filters} that will
> -not have video output.
> +There are so-called @var{source filters} that do not take video
> +input, and we expect that some @var{sink filters} will
> +not have video output, eventually.
While this is infinitely better English, it does not seem to convey the
future part of the previous wording quite as precisely. Do you disagree?
Diego
_______________________________________________
libav-devel mailing list
[email protected]
https://lists.libav.org/mailman/listinfo/libav-devel
