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

[The Wanderer]

Guillaume POIRIER wrote:

> Le mar 07/09/2004 à 17:40, The Wanderer a écrit :
> 
>>Guillaume POIRIER wrote:
> 
>>>>> +.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.
> 
> I just can't find much informations on this setting... Most people
> say: don't touch! ... unless you're a developer.
> So how about documenting frame_drop_ratio that way:
> .B frame_drop_ratio=<0\-100>
> Don't touch! ;-) ...
> if you do, you'll probably screw up your video.
> If it doesn't, tell us how to use this parameter, and send a patch! ;-)
> 
> Ok, I'm just fooling around... This thread is just getting too darn
> long!

Agreed, it is, but - this actually isn't too bad of an idea. How about
leaving the current description unchanged, but adding a few lines
following it which say something like "The above description is unclear,
but we don't know to use this option. If you figure out how to use it
correctly, please tell us."?

(That would probably have to get Diego's okay, I think, because I don't
know what the standards are on personal pronouns in the man page.)

>>> +.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.
> 
> Those description have been all written again. Please check the
> patch.

The new descriptions are I think better, but you still use "This setting
allow" instead of "This setting allows". "Allow", "control" and similar
tenses of other verbs are correct only when applied to plural nouns;
since "setting" is singular here, it needs "allows".

(I may be too tired, or just under-educated... I don't remember what the
names of those two tenses are.)

> All changes are in the attached (round 9) patch...

This looks good. Correct the second point above and get either the okay
to use the first, or the okay to just leave the unknown description in
place, and I'd say commit it.

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