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

[The Wanderer]

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:

>>> s/widely depend/depend/ IMO at least
>> 
>> If not, then at the very least "widely" is almost certainly not the
>> correct word to use. I'll think about it... the correct term here
>> is somewhat obscure, at least in terms of how readily it springs to
>> mind.
> 
> How about
> 
> The choice of video codec depends on several factors, some of which
> vary widely due to personal taste and technical constraints.

I'm still not completely happy about that, since what is actually meant
is that "which video codec is best to (use,choose) depends on" et cetera
(not a phrase I'd want to commit, too awkward), but it would indeed be
an improvement on the latter half of the sentence.

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

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

>>> Google is used as a verb here, so no capitalization.
>> 
>> Not necessarily - it can be valid to capitalize it even in that
>> form.
> 
> Probably.  Again this feels like an issue of personal taste/style to
> me. I'd go for the lowercase version since I consider it the most
> common form and it makes sense to me.

I don't mind that, really - just pointing out that neither form is
necessarily inherently more correct than the other. If we use the verb
multiple times in the docs we should standardize on one usage, but which
one it is probably makes little difference.

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

(...somehow I've forgotten how I thought that was relevant...)

> Of course I still review stuff and comment, especially the language
> part since I have some English skills and for a long time we did not
> have a native speaker reviewing as well.
> 
> Sometimes there are situations where you just have to choose between
> two equivalent alternatives A and B to go with one and be consistent
> throughout.  In that case the ball stops at the maintainer to make a
> decision.
> 
> For a long time this has been me, but I'm trying to take input from
> all sides into account and decide after considering all arguments.
> Plus, I'm willing to share duties and given that I have far less time
> now than I used to have I'm happy for everybody that helps me out.
> 
> What does this long-winded speech amount to?  'In charge' is not a
> fixed position, you're no less competent in English than I am, on the
> contrary, and if you keep doing more review work than I do, you might
> end up taking over the maintainership in that area.  I won't stand in
> the way.

I don't know if I'd necessarily want to, or if it would be a good idea
given the cycles of activity and laxity in which my reviewing has tended
to go (I have fully *fifty* marked documentation commits to review or
otherwise revisit in my backlog, dating back to September of '04, and I
don't think I've ever gotten to even one of them), but I'm glad to have
been made aware of the possibility. We've disagreed, and I've been ruled
down, on enough policy points in the past that I'm not quite sure how
I'd want to handle them if I did wind up taking over... but that's the
sort of bridge that can wait to burn till after being crossed.

And I'm aware that "in charge" is not especially fixed or especially
formal; that's why I put it in quotes in the first place. 'Sall good.

> BTW, maybe we should fix some of the style guidelines in writing.

It might not be a bad idea... is there an existing file to which such
could appropriately be added, or would we need to create a new one?
(DOCS/tech/documentation-style-guidelines.txt? DOCS/README.maintainers?
Something else?)

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