[MPlayer-DOCS] CVS: main/DOCS/xml/en encoding-guide.xml, 1.36, 1.37

[Guillaume Poirier]

The Wanderer wrote:
> On 12/27/2005 01:34 PM, Diego Biurrun wrote:
> 
>> On Tue, Dec 27, 2005 at 11:44:43AM -0500, The Wanderer wrote:
>>
>>> On 12/27/2005 06:58 AM, Diego Biurrun wrote:

[..]


>>>> IMO there are no unavailable options, so I'd drop 'available'
>>>> here.
>>>
>>>
>>> I rephrased this one extensively - the phrasing was intended to
>>> mean "the options it has available to be used". Perhaps "the
>>> options it provides" instead of "its available options"?
>>
>>
>> Yes, that's even better.
> 
> 
> I'll commit the change, along with any others which come from this
> subthread, if no one beats me to them.

Yes, please do. I'm no longer feeling competent to decide among the
different suggested fixes.


>>>> Capitalize both before and after the colon.
>>>
>>>
>>> I disagree at least about the former, because this parenthetical
>>> comment is in the middle of a sentence. If you had a construction
>>> of the form "Most A are X, but (look out) some are Y instead", you
>>> wouldn't want to capitalize "Look out", would you?
>>
>>
>> Not necessarily.  I guess this is a matter of personal taste.
>> Guillaume can commit whatever feels better to him.
> 
> 
> Agreed.

I think it somewhat depends on the length of the sentence, and if the
sentence is a full sentence with a subject and a verb, I don't mind
having it capitalized. In your example, I would not capitalize it since
it's too short, and there's no subject (that I can see).


>>>> Avoid short forms, some more are used in the text.
>>>
>>>
>>> I noticed a number of these in my commenting run - if I'd realized
>>> it was that important, I'd have pointed them out. I thought that
>>> the restriction on short forms applied primarily or solely to the
>>> man page, and that the rest of the documentation - the
>>> topic-specific guides in particular - was allowed to be somewhat
>>> more conversational?
>>
>>
>> I thought about this when I reviewed Guillaume's commit.
>>
>> AFAIU it is considered good style to avoid short forms in written
>> text, but on the other hand it is used as a stylistic device to make
>> texts a little less dry and more conversational.
>>
>> So yes, I assume the "no short forms" rule could or maybe should be
>> revisited.  What do you think?
> 
> 
> For the man page, which is intended to be dry and technical, I support
> avoiding short forms in pretty much all cases. For the various other
> guides, however - especially the ones which are intended to be a way to
> gently introduce the less experienced users to the ins and outs of
> advanced encoding and playback - it can sometimes be valuable to be less
> rigid, and I think it could be worth relaxing the rules there. (I've
> used the same basic guidelines in refraining from commenting on some
> aspects of previous commits to a few such guides, which were definitely
> more conversational than I'd have wanted to let by in the man page.)

I don't care too much about leaving the rule as it is or not. Just don't
expect me to conform with it in my initial proposed patches as I just
can't help using the contracted form. I usually remove them each time
Diego reminds that rule to me.


>>> I'll yield to your decision on the matter, however, since you do
>>> seem to be the one 'in charge'.
>>
>>
>> In a way, yes.  I used to be the only and nowadays I guess I'm still
>> the main documentation maintainer.  But MPlayer is largely a
>> meritocracy, so whoever does the work and/or is competent in a
>> particular area gets to make the decisions.
>>
>> For example Guillaume has taken over the MEncoder parts of the
>> documentation and I'm quite happy with the work he is doing.  I won't
>> interfere with what he does there content-wise, since I don't
>> believe in "You do the work, I get to decide and boss you around.".
> 
> 
> Oh, agreed, across the board. I'm quite good (or at least I'd like to
> think so) when it comes to reviewing, for grammar and spelling (and even
> meaning) and the like, but I'd have a devil of a time trying to write a
> good explanation of something to begin with even if I understood it in
> detail; Guillaume has done a very good basic job of doing almost exactly
> that on a number of occasions, including at least a few where I suspect
> he does *not* know the subject matter all that intimately.

I've built pretty much all my understanding of the technical details
involved in MPlayer and MEncoder myself by googling around, reading
articles and following ML threads. That means that I don't pretend that
I'm holding the truth. I'm just trying to share the information I got
here and there. I try as much as possible to double check the
informations by checking different sources, when available.

What I'm trying to get at is that I consider myself a mere Joe Six Pack
user who's just willing to help the community out.
So, you're quite all right, I don't know intimately most of the subjects
I talk about in the docs ;-P.

[..]

Guillaume