[FFmpeg-cvslog] r11225 - trunk/libavformat/avformat.h

[Diego Biurrun]

On Mon, Dec 17, 2007 at 12:34:05PM +0100, Michael Niedermayer wrote:
> On Mon, Dec 17, 2007 at 10:53:07AM +0100, Diego Biurrun wrote:
> > On Mon, Dec 17, 2007 at 02:38:19AM +0100, Michael Niedermayer wrote:
> > > On Sun, Dec 16, 2007 at 11:40:05PM +0000, M?ns Rullg?rd wrote:
> > > > Diego Biurrun <diego at biurrun.de> writes:
> > > > 
> > > > > On Sun, Dec 16, 2007 at 10:52:23PM +0000, M?ns Rullg?rd wrote:
> > > > >> Michael Niedermayer <michaelni at gmx.at> writes:
> > > > >> 
> > > > >> > On Sun, Dec 16, 2007 at 06:22:09PM +0100, Diego Biurrun wrote:
> > > > >> >> On Sat, Dec 15, 2007 at 05:54:59PM +0100, michael wrote:
> > > > >> >> > 
> > > > >> >> > Log:
> > > > >> >> > document how to free the result of av_alloc_format_context()
> > > > >> >> > 
> > > > >> >> > --- trunk/libavformat/avformat.h	(original)
> > > > >> >> > +++ trunk/libavformat/avformat.h	Sat Dec 15 17:54:58 2007
> > > > >> >> > @@ -569,7 +569,11 @@ int av_open_input_file(AVFormatContext *
> > > > >> >> > +/**
> > > > >> >> > + * Allocate an AVFormatContext.
> > > > >> >> > + * can be freed with av_free() but dont forget to free everything you
> > > > >> >> > + * explicitly allocated as well!
> > > > >> >> 
> > > > >> >> Could you please make an effort to avoid obvious misspellings ("dont")?
> > > > >> >> It took some work to fix these things up in FFmpeg and it would be a
> > > > >> >> pity to let it go to waste again.
> > > > >> >
> > > > >> > feel free to improve the precommit check script
> > > > >> 
> > > > >> I have to say, this attitude of yours is starting to get quite tiresome.
> > > > >
> > > > > Very much so.  I don't understand why you are such a complete perfectionist
> > > > > about what code is acceptable for FFmpeg and at the same time disregard
> > > > > the quality of the (Doxygen) documentation.
> > > 
> > > because "dont" is as readable with as well as without some little speck
> > > between n and t, buggy, slow, bloated, ... code though has a quite noticeable
> > > effect, take a look at our bugtracker how many bugs are there about spelling
> > > and grammer and how many are there about other things
> > 
> > There have been numerous (as in infinite) complaints about lack of FFmpeg
> > documentation, both developer docs and user docs.
> 
> lack yes, spelling errors ... no
> this thread wasnt about lack but spelling errors ...

This thread is about easy-to-avoid spelling/grammar errors that feel
wanton and lack of punctuation.  This is a difference for me.

> > "Dont" may be as readable to you as "do not" and maybe it is to others
> > that have gotten used to reading your prose, but it sure does not extend
> > to the general case.  Especially not to people with poor English skill.
> > Unfortunately most readers are not native speakers and have to struggle
> > quite a bit to understand even good written English.
> 
> then why is it that you and mans are the only ones complaining?
> i dont remember anyone with poor english skill ever complaining. its
> rather the opposite the ones with good skill complain ...
> it gives one the feeling that good skill is needed to notice such
> errors and that comprehensibility isnt part of it ...

Now that others have spoken it should be clear that good skill is not
required to notice such errors.  Good English skill helps to parse bad
English.  Please do not forget this, people with poor English skills
generally have much more trouble detecting typos and errors as such and
still comprehend what is written.

> > Nevertheless - wantonly - refusing to punctuate is not something that
> > does not affect readability.  Leaving out periods and commas turns your
> > prose into a hard-to-decipher mess.  Believe me, I read your stuff, I
> > have often enough struggled with it.  If this is your preferred way of
> > writing emails, well, I won't be able to reform you.  But if you write
> > Doxygen comments etc. this way, then you damage their comprehensibility.
> 
> i never intentionally ommited ., from a doxygen comment, that said iam certain
> you can find many missing, you blame me for my less than perfect english skill
> ?
> what is it that you are trying to achive with these attacks? keep me from
> writing doxy comments and more verbose commit messages? because that frankly
> is the only thing you might achive

I am absolutely not trying to blame you for your English skill nor
attack you.  Nothing could be further from the truth.  I think I made a
respectful and polite request:

  Could you please make an effort to avoid obvious misspellings ("dont")?
  It took some work to fix these things up in FFmpeg and it would be a
  pity to let it go to waste again.

Somehow it all went downhill from there since we're all so prone to
flamage.  I'll try to be more explicit about what I would and would not
like to achieve now.

What I would like to see are simple things that should not require any
real effort from your side:

- Capitalize the first word of a sentence.
- End each sentence with a period.
- Try to use commas where appropriate.
- Drop the weird contractions you are so fond of (theres, isnt, dont, ..).
  This could easily be done by using long forms, which are better style.
- Avoid a handful of your most common typos (misSunderstand, gUrantee,
  grammEr, succeS, visSual, immedIATEly, spaTial, ..), I could make a
  list if you want.

Note that this would take your English to an entirely new level without
much work.  I do not expect or request perfection or going out of your
way to address these issues, just a modicum of effort.

> > > i prefer to concentrate on fixing things which do matter to our developers and
> > > users, over things which dont
> > > and belive it or not reading everything twice to fix spelling capitalization
> > > and all that takes time, time i could spent fixing some issues
> > 
> > It also takes me time to doublecheck my commits, time I could spend
> > fixing other issues.  Diligence always takes time, but it's worth
> > it.
> > 
> > I can claim with some confidence that I can write English at near native
> > levels yet I always reread any documentation I write two or three times
> > to make sure it's correct and understandable.
> > 
> > So how much time are we talking about and what percentage of the time
> > you take to write Doxygen documentation would it take to expand a
> > condensed "dont" into "do not"?  We are talking about typing two more
> > characters.  This is not asking much.
> 
> first i dont like doing the work of a pre commit check script, second
> iam a volunteer and having to reread doxygen comments 3 times to spot
> 2/3 of these problems is not fun, i already reread them many times to
> make them correct and comprehensible. also even if i do reread it 3 times
> theres a good chance someone of the grammer nazis will rewrite it anyway
> and they love doing this work (=its fun for them) and they need less
> time than i do to reach the 2/3 correct point

I'm not asking you to reread it three extra times.  From what you wrote
above I got the impression that you do not reread the docs you create.
My point was that it is perfectly normal even for good writers to reread
the documentation they produce.  Thus I'm not asking for anything out of
the ordinary, just for a normal documentation writing workflow.

Now if you already reread your docs, I'm sure you can tune your eyes to
catch silly typos during one of those passes :)

> you are asking me to do work iam not good at, which i dont like, which
> others are good at and which others like and you ask me to it volunteerly
> i think theres a flaw in this reasoning
> normally its "you want X you do the work and maintain it" in free software ...

I am a volunteer as well.  Your reasoning is flawed.  By the same token
I could demand that you do code cleanups yourself, after all "you are
pedantic about improving already working code, so do the work yourself".

But this is beside the point.  FFmpeg is a team effort.  Everybody
should contribute in the areas they are good at, but this is not an
excuse to be sloppy in areas where one has weaknesses.  You get
annoyed when people keep forgetting basic things you taught them
in your reviews, don't you?

> > However, the main problem I have is the attitude you are telegraphing by
> > refusing to give in on this issue.  "I do whatever damn well I want and
> > consider right; I don't give a damn what others think about the issue."
> 
> but these others are just you and mans ...

I think it should be clear now that it's not just us two.  Also don't
forget that not everybody will speak up.

> [...]
> > > also ive a suggestion, ill be more carefull with my spelling and you fix
> > > a few issues on our bugtracker (and no i dont mean closing invalid ones but
> > > real bugfixes which require a change of the C code)
> > > i think that would be fair, it would require each of us to do something
> > > we dont commonly do
> > 
> > Does that apply to me or Mans?
> 
> you

Do you think that I do not contribute enough to FFmpeg?  That I do not
work much on the C code should be a positive thing for you.  After all
this leaves you more time to work on the stuff you enjoy (C code) when
things you like less are addressed by others...

Anyway, issue 280 fixed, issue 169 assigned :)

Diego