[MPlayer-DOCS] CVS: main/DOCS/man/en mplayer.1,1.648,1.649

[The Wanderer]

Diego Biurrun wrote:

> The Wanderer writes:
> 
>> I should have done this a little earlier, and saved an unnecessary
>> CVS commit...
> 
> No problem. I am a strong believer in incremental improvements as
> opposed to "try to get things right immediately".

Yes, I've observed that by now; it's just the nitpicking perfectionist
minimize-unnecessary-effort part of me which complains. (Because I *had*
seen the patch on the list, and comments thereon; I just hadn't gone
through to add my own.)

>> Diego Biurrun CVS wrote:
>> 
>>> -switch to fixed quantizer mode and specify the quantizer to be used
>>> +Switch to fixed quantizer mode and specify the quantizer to be used.
>> 
>> Possibly "fixed-quantizer"; this is perhaps arguable.
> 
> I tend to disagree, we would have to write "constant-bitrate" then as
> well, wouldn't we?

Probably, since that is AFAICT the technically correct form. The fact
that it is the expansion of a well-known acronym helps with grouping in
that respect, however, and might qualify it for an exception.

In any case, I did note that this was arguable; I leave the decision to
you.

>>> -This option does not deinterlace video, it encodes it field-based
>>> -(default: off).
>>> +This option does not deinterlace video, it encodes it field-based.
>>
>> It could just be a quirk of technical terminology with which I am
>> unfamiliar, but the latter part of this sentence does not feel
>> grammatical. I think that what is meant is something along the
>> lines of "according to a field-based scheme" or "in a field-based
>> manner", but I'm not sure.
>> 
>> In any case, you want to use "but rather encodes it", to avoid
>> repeating "it" with different intended antecedents.
> 
> Yes, this is clumsy, but I think more radical surgery is needed.
> 
> How about
> 
>   .B interlacing
>   Encode the fields of interlaced video material.
>   Turn this option on for interlaced content.
> 
> instead of
> 
>   .B interlacing
>   For interlaced video material, turn this option on.
>   .I Note:
>   This option does not deinterlace video, it encodes it field-based.
> 
> ?

That works, and has the advantage of being more clear; now I actually
understand what it's talking about. <grin>

>>> -use 4 motion vectors per macro-block, might give better compression at the
>>> -cost of a slower encoding (default: off).
>>> +Use 4 motion vectors per macro-block, might give better compression at the
>>> +cost of a slower encoding.
>>
>> As I understand it, that's "macroblock". I'm also not happy with
>> the phrasing of the rest, in terms of the pauses; I'd suggest
>> either "macroblock, which might give" or "macroblock; this might
>> give", and "but results in a slower encoding process" or similar.
> 
> I settled for
> 
>   Use 4 motion vectors per macroblock.
>   This might give better compression but slows down encoding.

I still think you need a comma before the "but", but this is otherwise
good.

>>> -create a bitstream that can be decoded delay-free (default: off)
>>> +Create a bitstream that can be decoded delay-free.
>>
>> "that" > "which", say my instincts. This also is not cleanly
>> phrased otherwise, but I'm not sure how to fix it without sounding
>> awkward.
> 
> 
> I don't have a better idea as well.

Part of the problem is that I don't know exactly what the option does
(which probably just means that this *does* need to be rephrased)... my
first thought is to say "without adding any delay", or something
similar, but I don't see how that makes any sense from a technical
perspective.

>>> -Enable Global Motion Compensation, which makes XviD generate Sprite
>>> -Frames which best describe Pan/Zoom/Rotating images.
>>> +Enable Global Motion Compensation, which makes XviD generate special
>>> +frames (GMC-frames) which best describe Pan/Zoom/Rotating images.
>>>  The decision whether to activate this option or not to save bits
>>>  depends highly on the video material.
>>
>> This still feels fairly awkward, but I don't have suggestions to
>> fix it offhand.
> 
> How about
> 
>   Enable Global Motion Compensation, which makes XviD generate special
>   frames (GMC-frames) which are well suited for Pan/Zoom/Rotating images.
> 
> ?

That's fine for the first sentence, but IIRC I included the second
because it is also not quite right, and this doesn't change that.

How about something like "Whether or not the use of this option will
save bits is highly dependent on the source material."? That's still not
perfect, but I think it's better.

>> (It probably doesn't help that I leave for a job interview in an
>> hour.)
> 
> How did it go?

As far as I could tell... the first part I couldn't tell, the
interviewer was the type of Hispanic whom I find almost unreadable. The
second part, however, seemed to go fairly well, and they tell me I'll
know one way or another by early in the week (possibly even Monday).

I used my activity, such as it is, on these lists as part of my
credentials... I was pleased to note that one of the people, at least,
did appear to have heard of MPlayer. <grin>

>> There are many other small "rubs me the wrong way" grammar things
>> which I snipped, primarily in lines not changed by this patch; it
>> might be a good idea to give the whole thing a grammatical
>> once-over, but I'm not sure I could provide better suggestions in
>> all (or even necessarily most) cases, and it might approach the
>> level of unnecessary fiddling.
> 
> Yes, the man page should get a thorough review for correctness, ease
> of understanding and wording/spelling.

Quite true, but at the time I wrote that, it had slipped my mind that
what I was commenting on was the man page. <grin>

> I have done this some time ago on paper but never found the time to
> commit it, I'm in the process of doing this right now.  Once this is
> finished we can tackle another round of review.

Yes, acknowledged, and in fact I knew it already; the paragraph was
mainly for the sake of the completeness of this set of comments.

-- 
       The Wanderer

Warning: Simply because I argue an issue does not mean I agree with any
side of it.

A government exists to serve its citizens, not to control them.