[MPlayer-dev-eng] Lots of stuff for NUT

[The Wanderer]

On 12/31/2005 09:53 AM, Diego Biurrun wrote:

> On Sat, Dec 31, 2005 at 04:27:59PM +0200, Oded Shimon wrote:
> 
>> Documenters - spelling fixes? grammar fixes? better suggestions for
>> explanations?
> 
> Here we go...

I missed seeing this at first, but here we are. I'll go to the main
(later) post after piggybacking here for a moment.

>> +    real_back_ptr must point to a position so a syncpoint startcode begins
>> +    within the next 8 bytes, and such that this syncpoint is the closest
>> +    syncpoint so one keyframe for this stream lies between that syncpoint
>> +    and the current syncpoint.
> 
> As a rule of thumb, try using shorter sentences. If your sentence
> spans more than 3 lines, cut it at least in half.
> 
> Here's my not-yet-perfect suggestion, I hope I haven't munged the
> intended meaning.
> 
>   real_back_ptr must point to a position within 8 bytes of a syncpoint startcode.
>   This syncpoint should/must be the closest syncpoint so one stream keyframe lies
>   between it and the current syncpoint.

I would prefer "such that" rather than "so" in this context, because
"so" can also mean "as a consequence of the fact that " rather than
"causing it to be the case that"

>> +    Note back_ptr can be zero, when the frame immdiately following is a
> 
> Note that, immEdiately

Actually, adding a colon ("Note:") could work just as well for the
former of these.

>> +    syncpoints MUST be placed immediately before a keyframe if more
>> +    than max_distance passed since previous keyframe of the same stream,
>> +    unless the timestamp to be set for this syncpoint is identical to the
>> +    last syncpoints's timestamp. In which case, the syncpoint is to be put
>> +    immediately BEFORE the timestamp will change. (So it will still have
>> +    the same timestamp)
> 
> since the previous keyframe, syncpoint's
> 
> You can never start a sentence with "in which case" IMO.

Agreed. Likewise, it is bad form (albeit less so) to begin a sentence
with "So" as you have done in the parentheses.

>>+    When EOR is set, all back_ptr's for this stream are set to zero.
> 
> back_ptrs

Ordinarily I simply abhor any misuse of the apostrophe on plurals and
possessives - but this case is a little ambiguous, because of the need
to distinguish between the name of the 'variable' and the pluralizing
's'. Because of the technical context, the tendency is to interpret
terms containing underscores and condensed words such as "ptr" as
literal variable names, and adding the plural in this way is likely to
throw people off (at least momentarily). The problem could be avoided in
this instance by saying something like "every back_ptr for this stream
is set to zero" (or, if you're describing a thing which is to be done at
that point rather than a thing which will already have been done by that
point, "must be set to zero"). Failing that, the somewhat aesthetically
poor solution of simply enclosing the 'variable' name in quotes (single
or double) could suffice.

I'll try to get to the main patch soon (as in, today. Don't wait up for
me if I manage to miss it, though.).

-- 
       The Wanderer

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

Secrecy is the beginning of tyranny.