* Make a remark about avoiding unnecessary changes in interfaces

* Improve wording
Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi>

---

 Documentation/stable_api_nonsense.txt |   16 ++++++++++------

 1 files changed, 10 insertions(+), 6 deletions(-)
diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt

index 847b342..e644099 100644

--- a/Documentation/stable_api_nonsense.txt

+++ b/Documentation/stable_api_nonsense.txt

@@ -19,7 +19,7 @@ Executive Summary

 You think you want a stable kernel interface, but you really do not, and

 you don't even know it.  What you want is a stable running driver, and

 you get that only if your driver is in the main kernel tree.  You also

-get lots of other good benefits if your driver is in the main kernel

+get lots of other benefits if your driver is in the main kernel

 tree, all of which has made Linux into such a strong, stable, and mature

 operating system which is the reason you are using it in the first

 place.

@@ -68,11 +68,11 @@ consider the following facts about the Linux kernel:

     There is no way that binary drivers from one architecture will run

     on another architecture properly.
-Now a number of these issues can be addressed by simply compiling your

-module for the exact specific kernel configuration, using the same exact

+Now, a number of these issues can be addressed by simply compiling your

+module for the same kernel configuration, using the same

 C compiler that the kernel was built with.  This is sufficient if you

 want to provide a module for a specific release version of a specific

-Linux distribution.  But multiply that single build by the number of

+Linux distribution. However, multiply that single build by the number of

 different Linux distributions and the number of different supported

 releases of the Linux distribution and you quickly have a nightmare of

 different build options on different releases.  Also realize that each

@@ -93,7 +93,7 @@ keep a Linux kernel dri...
[ message continues ]

This is actually not correct. Sometimes interfaces are changed

without good reason or the for reasons that turn out to be incorrect.
-Andi

--

You messed with the "two space" rule, and changed the word unecessarily
It's not so much as a "risk" as it is what always seems to happen.  So I
No, their claim is a valid one, it's not "false".  However we are not

going to do anything about it, and as such, we don't need this kind of

wording to get people worried about it even more.
So, care to redo the patch?
Also note, there are other translations of this text already, so if you

want to change phrases like this, you might want to cc: those

maintainers as well to get their input.
thanks,
greg k-h

--

CC'ing Andi as he commented also..
The places I corrected were somewhat unreadable English in my opinion.

The problem with this text is mostly

style that breaks common sense rules how to write simple sentences.

Documentation should not try to represent its writer but convey 
Do you want preserve both "exact specific" and "same exact"? Imo,

"same exact C compiler" is just bad language, because C compilers are 
Imo, that statement is very odd. The meaning of it has to be guessed.
No, it's definitely more "risk" than "ability" because "ability" should

refer to a positive property. Here "ability" is used to refer to a
How about this (scrap the whole paragraph):
Changing an interface can be delicate work and it can take significant

amount of developer effort. Therefore, an interface is not changed
OK.
--

Heikki Orsila			Barbie's law:

heikki.orsila@iki.fi		"Math is hard, let's go shopping!"

http://www.iki.fi/shd

--

I strongly disagree with this.  If you are reading documentation, you

should at least be intertained a bit, and if you take the "flavor" of
Hm, but you understood the idea conveyed here, right?  That's the

important issue, we can argue about the exact structure of words all
Why do you feel this paragraph is needed at all?
thanks,
greg k-h

--

This is my last counter argument. Based on this I'll submit a new patch

that is less intrusive.
I hope we agree that by definition the success of documentation is

measured by its ability to convey ideas. So the basic disagreement is

"simple English" versus "some flavor of English".

"entertainment value" is there only to keep the person reading, but 
Some people may feel there is nothing to prevent constant changes. This

paragraph tries to assure it is not the case. Actually, the whole point

of this documentation is to comfort others.
PS. Off topic: I think documentation is a very important topic for Linux

systems in general (there is lot to be improved!). I wonder how many

bugs in programs could be avoided by writing good man pages. For

example, many people tend to get select() wrong, and I suspect it's

partly because the man page is not as good as it could be. An example

of good man page would Davide Libenzi's epoll that has an FAQ for common

questions and an example of suggested usage. Good examples drive

developers for solutions that are known to work in practice.
--

Heikki Orsila			Barbie's law:

heikki.orsila@iki.fi		"Math is hard, let's go shopping!"

http://www.iki.fi/shd

--

Actually, it does. It is perfectly idiomatic English.
"Use the exact same C compiler." -> OK, idiomatic

"Use the same exact C compiler." -> OK, idiomatic

"Use the exactly same C compiler." -> very awkward

"Use exactly the same C compiler." -> formally correct
http://www.bartleby.com/68/24/2324.html

--

Mathematics is the supreme nostalgia of our time.
--

Forgot to CC Greg.
- Heikki

--