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

[Diego Biurrun]

On Tue, Dec 27, 2005 at 11:44:43AM -0500, The Wanderer wrote:
> On 12/27/2005 06:58 AM, Diego Biurrun wrote:
> 
> >On Tue, Dec 27, 2005 at 10:35:00AM +0100, Guillaume Poirier CVS wrote:
> >
> >>+  Choosing the video codec to use depends on several factors, some of
> >>+  which widely depend on personal taste and technical constraints.
> >
> >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.

> >>+  What's more, beginning to use a new codec requires that you spend some
> >>+  time becoming familiar with its available options, so that you know 
> >>what
> >
> >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.

> >>+  (beware: usually, not all MPEG-4 ASP features are supported).
> >
> >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.

> >>+  or Google around for more information.
> >
> >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.

> >>+  settings of the video codec (which doesn't mean you should not 
> >>experiment
> >
> >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?

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

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.

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

Diego