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

[Diego Biurrun]

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".

Most everything committed as you suggested except where explicitly
noted below.  I committed everything since I want to work some more on
the man page later today, some things could still be improved further
as noted below.

> 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?

> > -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.

?

> > -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.

> > -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.

> > -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.

?

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

How did it go?

> > +.I WARNING:
> > +The bitstream created is outside any MPEG-4 profile!
> > +This means it most likely won't be decoded by anything else than XviD.
> 
> Suggest "decodable" instead of "decoded". Also, at minimum, you want
> "other than" instead of "else than"; there is a whole argument about
> valid usages there, but it isn't worth getting into that now.

I settled for

  This means it most likely won't be decodable by anything except XviD.

> 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.

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.

Diego