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

[The Wanderer]

Guillaume POIRIER wrote:

> Le mar 07/09/2004 à 14:34, The Wanderer a écrit :
> 
>> Guillaume POIRIER wrote:

>>> Heck... I'm not even sure! Using compensate that way still seem
>>> fairly unnatural to me.
>> 
>> Just consider it one of the quirks of the language; English has so
>> many special cases and context-based exceptions, it's hardly even
>> funny anymore.
> 
> Many thanks to the reviewers then... ;-) Lots of contributors, and
> few English native speaker?

Seems that way. I'm one of the few, but there's a lot I don't know about
the language from a formal standpoint; I just know what feels right and
what doesn't, I mostly don't know exactly why.

>>> You'll get also on the patch the 3 little babies that were
>>> previously marked "FIXME".
>> 
>> I missed noticing those...
> 
> ... I meant: they were marked as FIXME in "*round-0 'till 4" version
> of this patch. No biggie though!

Yes, and I meant I hadn't noticed them back then. We understood each
other. <grin>

>>> +This setting allows you to favorize or not, the use of B frames.
>>> +The higher the value, the higher the probability of B frames being used.
>>> +(default: 0)
>> 
>> "Favorize" isn't a word, at least not in English. Going by what I
>> think you mean, I'd suggest something like "This setting allows you
>> to specify what priority to place on the use of B frames.".
> 
> I corrected it your way.

Sorry to give you so many changes, so many times, but if Dominik's
version is accurate, it's a little less clunky than mine.

>>> +.B frame_drop_ratio=<0\-100>
>>> +XviD keeps track of block coding type (skipped, predicted, intra).
>>> +The skipped block counter can be used to choose whether a frame is so close
>>> +to its reference that it can be
>> 
>> I don't think "choose" is the verb you want in this case... but I
>> don't know what would be better. Diego? Any ideas?
> 
> I replaced it with "decide". I'm not sure if it makes a world of 
> difference though.

No, it doesn't; that was one of the alternates I'd considered and
rejected as no better. The problem, if I understand the description
correctly (and if not it probably does need rephrasing), is that the
counter itself is not the thing doing the choosing, or the deciding; it
simply affects the thing which does make the decision. As I said, I
don't know what would be good to use in this context; I think it will
probably have to be corrected post-commit.

>>> +The upper part of the curve is the set of values that are higher than
>>> +the curve average.
>>> +Think of that setting like a shrinking factor for the upper part of
>>> +the curve (default: 0).
>> 
>> "the setting" in this case.
> 
> Do you mean I should write "Think of the setting like..."
> ... That's what I understood (but find it odd), and corrected.

Yes. "That setting" would be appropriate for referring to another
setting than the one at hand; since you aren't, "the setting" should be
better.

>> There are many small things at which I could pick, but which I did
>> not point out, because this has stretched out long enough already;
>> if I decide that they really need to be corrected, I can go back
>> and do it myself later on, and avoid arguing hyphenation six times
>> as often as I need to.
> 
> Plus I had trouble keeping my patch "commit-able" against latest cvs,
> so I'm looking forward this is over ;-)

You and me both. <grin>

Anything not commented on, above, is probably fine.

> +.TP
> +.B bf_threshold=<-255\-255>
> +Sometimes B frames do not look good, and introduce artifacts when most of
> +the frame is static and some small zones have high motion (in a static
> +scene with a man talking, his mouth will probably look bad if what is
> +surrounding the man and his mouth is completely static).
> +This setting allows you to specify what priority to place on the use of
> +B frames.
> +This setting allows you to favorize or not, the use of B frames.

Ooops. Both phrasings are here. Looks like you added the new version,
but forgot to delete the old one.

> +.B curve_compression_high=<0\-100>
> +This setting control how much the upper part of the curve has to get
> +closer to the average bitrate value.

"controls"

Same thing immediately following, as before.

> +.B overflow_control_strength=<0\-100>
> +During pass 1 of 2-pass encoding, a scaled bitrate curve is computed.
> +The difference between that expected curve and the result obtained during
> +encoding is called overflow.
> +Obviously, the two pass Rate Controller tries to compensate for that overflow
> +distributing, it over next frames to be encoded.

Sorry, either I mistyped or you misinterpreted me. The comma goes before
"distributing", not after it - the comma should go immediately after the
final occurrence of "overflow".

> +.B max_overflow_improvement=<0\-100>
> +During the frame bit allocation, overflow control may increase the frame
> +size.
> +This parameter controls how much the overflow control is allowed to
> +increase the frame size in percent compared to the ideal curve allocation
> +(default: 5).

Hmmm. This doesn't look right, somehow; I think it's mainly the
placement of the bit about "percent". How about "This parameter
specifies the maximum percentage by which the overflow control is
allowed to increase the frame size, compared to the ideal curve
allocation"? That's not necessarily perfect, but I don't understand the
technical side of this well enough to suggest further changes and be
sure they won't break the meaning.

The following option, being phrased almost identically, has the same
problem.

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