* Make a remark about avoiding unnecessary changes in interfaces
* Improve wording
Signed-off-by: Heikki Orsila <[email protected]>
---
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 driver that is not in the main kernel tree up to
date over time.
Linux kernel development is continuous and at a rapid pace, never
-stopping to slow down. As such, the kernel developers find bugs in
+slowing down. As such, the kernel developers find bugs in
current interfaces, or figure out a better way to do things. If they do
that, they then fix the current interfaces to work better. When they do
so, function names may change, structures may grow or shrink, and
@@ -116,7 +116,7 @@ issues:
This is in stark contrast to a number of closed source operating systems
which have had to maintain their older USB interfaces over time. This
-provides the ability for new developers to accidentally use the old
+has the risk for new developers to accidentally use the old
interfaces and do things in improper ways, causing the stability of the
operating system to suffer.
@@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
well as they can be (unused interfaces are pretty much impossible to
test for validity.)
+Some complain that kernel interfaces change too often for out-of-the-tree
+modules, but this claim is false. Changing an interface can be delicate work,
+and it can take significant amount of developer effort. Therefore, interfaces
+are not changed without a good reason.
What to do
----------
--
1.5.3.4.GIT
On Tue, Jan 29, 2008 at 01:09:59AM +0200, Heikki Orsila wrote:
> * Make a remark about avoiding unnecessary changes in interfaces
> * Improve wording
Forgot to CC Greg.
- Heikki
On Tue, Jan 29, 2008 at 01:09:59AM +0200, Heikki Orsila wrote:
> * Make a remark about avoiding unnecessary changes in interfaces
> * Improve wording
Well, "improve" is a bit judgemental :)
> @@ -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.
That change is fine.
> @@ -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
No, I want to emphasize the word "exact" here. It has to be 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
You messed with the "two space" rule, and changed the word unecessarily
in my opinion.
> 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 driver that is not in the main kernel tree up to
> date over time.
>
> Linux kernel development is continuous and at a rapid pace, never
> -stopping to slow down. As such, the kernel developers find bugs in
> +slowing down. As such, the kernel developers find bugs in
No, they never stop, I say leave it as is.
> @@ -116,7 +116,7 @@ issues:
>
> This is in stark contrast to a number of closed source operating systems
> which have had to maintain their older USB interfaces over time. This
> -provides the ability for new developers to accidentally use the old
> +has the risk for new developers to accidentally use the old
It's not so much as a "risk" as it is what always seems to happen. So I
don't like this change either.
> @@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
> well as they can be (unused interfaces are pretty much impossible to
> test for validity.)
>
> +Some complain that kernel interfaces change too often for out-of-the-tree
> +modules, but this claim is false. Changing an interface can be delicate work,
> +and it can take significant amount of developer effort. Therefore, interfaces
> +are not changed without a good reason.
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
[email protected] (Heikki Orsila) writes:
>
> +Some complain that kernel interfaces change too often for out-of-the-tree
> +modules, but this claim is false. Changing an interface can be delicate work,
> +and it can take significant amount of developer effort. Therefore, interfaces
> +are not changed without a good reason.
This is actually not correct. Sometimes interfaces are changed
without good reason or the for reasons that turn out to be incorrect.
-Andi
CC'ing Andi as he commented also..
On Mon, Jan 28, 2008 at 08:48:05PM -0800, Greg KH wrote:
> On Tue, Jan 29, 2008 at 01:09:59AM +0200, Heikki Orsila wrote:
> > * Make a remark about avoiding unnecessary changes in interfaces
> > * Improve wording
>
> Well, "improve" is a bit judgemental :)
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
the idea as well as possible.
> > @@ -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
>
> No, I want to emphasize the word "exact" here. It has to be the same.
Do you want preserve both "exact specific" and "same exact"? Imo,
"same exact C compiler" is just bad language, because C compilers are
always "exact". "exactly same C compiler" would do.
> > 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
>
> You messed with the "two space" rule, and changed the word unecessarily
> in my opinion.
>
> > 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 driver that is not in the main kernel tree up to
> > date over time.
> >
> > Linux kernel development is continuous and at a rapid pace, never
> > -stopping to slow down. As such, the kernel developers find bugs in
> > +slowing down. As such, the kernel developers find bugs in
>
> No, they never stop, I say leave it as is.
Imo, that statement is very odd. The meaning of it has to be guessed.
"never slowing down" is very simple and conveys the essential idea.
> > @@ -116,7 +116,7 @@ issues:
> >
> > This is in stark contrast to a number of closed source operating systems
> > which have had to maintain their older USB interfaces over time. This
> > -provides the ability for new developers to accidentally use the old
> > +has the risk for new developers to accidentally use the old
>
> It's not so much as a "risk" as it is what always seems to happen. So I
> don't like this change either.
No, it's definitely more "risk" than "ability" because "ability" should
refer to a positive property. Here "ability" is used to refer to a
"negative outcome".
> > @@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
> > well as they can be (unused interfaces are pretty much impossible to
> > test for validity.)
> >
> > +Some complain that kernel interfaces change too often for out-of-the-tree
> > +modules, but this claim is false. Changing an interface can be delicate work,
> > +and it can take significant amount of developer effort. Therefore, interfaces
> > +are not changed without a good reason.
>
> 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.
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
unless the change is regarded as very important by the developers.
> So, care to redo the patch?
Will try..
> 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.
OK.
--
Heikki Orsila Barbie's law:
[email protected] "Math is hard, let's go shopping!"
http://www.iki.fi/shd
On Tue, Jan 29, 2008 at 12:40:18PM +0200, Heikki Orsila wrote:
> CC'ing Andi as he commented also..
>
> On Mon, Jan 28, 2008 at 08:48:05PM -0800, Greg KH wrote:
> > On Tue, Jan 29, 2008 at 01:09:59AM +0200, Heikki Orsila wrote:
> > > * Make a remark about avoiding unnecessary changes in interfaces
> > > * Improve wording
> >
> > Well, "improve" is a bit judgemental :)
>
> 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
> the idea as well as possible.
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
the writer out of it entirely, it becomes quite boring and dry.
> > > @@ -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
> >
> > No, I want to emphasize the word "exact" here. It has to be the same.
>
> Do you want preserve both "exact specific" and "same exact"?
Both.
> Imo,
> "same exact C compiler" is just bad language, because C compilers are
> always "exact". "exactly same C compiler" would do.
No, "exactly same C compiler" doesn't parse well in English.
> > > 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
> >
> > You messed with the "two space" rule, and changed the word unecessarily
> > in my opinion.
> >
> > > 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 driver that is not in the main kernel tree up to
> > > date over time.
> > >
> > > Linux kernel development is continuous and at a rapid pace, never
> > > -stopping to slow down. As such, the kernel developers find bugs in
> > > +slowing down. As such, the kernel developers find bugs in
> >
> > No, they never stop, I say leave it as is.
>
> Imo, that statement is very odd. The meaning of it has to be guessed.
> "never slowing down" is very simple and conveys the essential idea.
Hm, but you understood the idea conveyed here, right? That's the
important issue, we can argue about the exact structure of words all
day, which will get us no where.
> > > @@ -116,7 +116,7 @@ issues:
> > >
> > > This is in stark contrast to a number of closed source operating systems
> > > which have had to maintain their older USB interfaces over time. This
> > > -provides the ability for new developers to accidentally use the old
> > > +has the risk for new developers to accidentally use the old
> >
> > It's not so much as a "risk" as it is what always seems to happen. So I
> > don't like this change either.
>
> No, it's definitely more "risk" than "ability" because "ability" should
> refer to a positive property. Here "ability" is used to refer to a
> "negative outcome".
Ok, fair enough, I can agree with that.
> > > @@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
> > > well as they can be (unused interfaces are pretty much impossible to
> > > test for validity.)
> > >
> > > +Some complain that kernel interfaces change too often for out-of-the-tree
> > > +modules, but this claim is false. Changing an interface can be delicate work,
> > > +and it can take significant amount of developer effort. Therefore, interfaces
> > > +are not changed without a good reason.
> >
> > 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.
>
> 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
> unless the change is regarded as very important by the developers.
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.
On Tue, Jan 29, 2008 at 05:15:00AM -0800, Greg KH wrote:
> 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
> the writer out of it entirely, it becomes quite boring and dry.
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
"complicated" sentences harm readability.
> > > > @@ -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
> > >
> > > No, I want to emphasize the word "exact" here. It has to be the same.
> >
> > Do you want preserve both "exact specific" and "same exact"?
>
> Both.
>
> > Imo,
> > "same exact C compiler" is just bad language, because C compilers are
> > always "exact". "exactly same C compiler" would do.
>
> No, "exactly same C compiler" doesn't parse well in English.
"Same exact C compiler" does not mean what you try to say.
> > > > 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
> > >
> > > You messed with the "two space" rule, and changed the word unecessarily
> > > in my opinion.
> > >
> > > > 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 driver that is not in the main kernel tree up to
> > > > date over time.
> > > >
> > > > Linux kernel development is continuous and at a rapid pace, never
> > > > -stopping to slow down. As such, the kernel developers find bugs in
> > > > +slowing down. As such, the kernel developers find bugs in
> > >
> > > No, they never stop, I say leave it as is.
> >
> > Imo, that statement is very odd. The meaning of it has to be guessed.
> > "never slowing down" is very simple and conveys the essential idea.
>
> Hm, but you understood the idea conveyed here, right? That's the
> important issue, we can argue about the exact structure of words all
> day, which will get us no where.
Right, this argument can't continue without other people's perspectives.
> Ok, fair enough, I can agree with that.
Good :)
> > > > @@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
> > > > well as they can be (unused interfaces are pretty much impossible to
> > > > test for validity.)
> > > >
> > > > +Some complain that kernel interfaces change too often for out-of-the-tree
> > > > +modules, but this claim is false. Changing an interface can be delicate work,
> > > > +and it can take significant amount of developer effort. Therefore, interfaces
> > > > +are not changed without a good reason.
> > >
> > > 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.
> >
> > 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
> > unless the change is regarded as very important by the developers.
>
> Why do you feel this paragraph is needed at all?
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:
[email protected] "Math is hard, let's go shopping!"
http://www.iki.fi/shd
On Tue, 2008-01-29 at 16:14 +0200, Heikki Orsila wrote:
> > > Imo,
> > > "same exact C compiler" is just bad language, because C compilers are
> > > always "exact". "exactly same C compiler" would do.
> >
> > No, "exactly same C compiler" doesn't parse well in English.
>
> "Same exact C compiler" does not mean what you try to say.
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.
On Wed, 30 Jan 2008 13:32:58 CST, Matt Mackall said:
> "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
"You are trapped in a maze of twisty little documentation patches, all pedantic"
:)