Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-12-04 Thread Rob Landley

On 11/24/2013 12:02:30 AM, Alexandre Courbot wrote:

Hi Rob,

On Sun, Nov 24, 2013 at 8:31 AM, Rob Landley  wrote:
>> > Linus, I hope this can be merged during the -rc cycle of 3.13,  
since the
>> > gpiod_ interface is going to be introduced there. It would not  
make much

>> > sense for it to come without its documentation.
>>
>> You're right of course. I'll read through it and apply fixes on top
>> (or squash into your patch.)
>>
>> Formal stuff:
>> Don't we need an 00-INDEX file?
>> (Maybe Rob can tell whether this is desirable.)
>
>
> A 00-INDEX file wouldn't hurt, but it can always be added later. No  
reason
> to hold up the series for that. (I was using them to generate html  
indexes

> for kernel.org/doc but after the breakin they eliminated all non-git
> functionality so I haven't been able to update it since. They  
replaced
> kernel.org/doc/Documentation with a raw git checkout, and I expect  
them to
> replace kernel.org/doc/menuconfig with a raw git checkout any day  
now.)

>
> That said, a 00-INDEX file would let you know where to start  
reading to find
> the file with the intro paragraph at the start of the old file, the  
bit
> explaining what GPIO is. Here the first file alphabetically is  
"board.txt",
> and I have no idea why it's named that, given how it starts. (I was  
sort of
> hoping that somebody who already knows the subsystem would comment  
before I

> do. I have no way of knowing if this documentation is _right_.)

I actually submitted a patch that introduces a 00-INDEX file
yesterday. It's probably a few other gazillions mails under in your
inbox. ;)


I'm a couple weeks behind on my email. I'll get to it eventually. (My  
time's spread between a few too many projects these days...)


Most documentation goes in through the trees of the people whose  
subsystems it documents. I mostly catch the stuff that falls through  
the cracks. I'm somewhere between a librarian shelving abandoned books  
and a janitor.


...
> But I really don't have time to go through every paragraph like  
that, and
> was hoping the gpio guys would (or just sign off on it so I don't  
have

> to)...

I will make another pass and send an update (or a new version of the
patch maybe, since we are still in -rc1 - whatever is more convenient
to Linus). Hopefully early users of the new (oops) interface will send
fixes to the documentation as well, if only to improve my approximate
English.


It's not so much the english, it's that Documentation should be aimed  
at people who _don't_ already know this stuff. Since it tends to be  
written by people who _do_ already know the stuff (kinda hard to do the  
other way, although I've done it), this can be tricky to pull off. You  
have to maintain a "But what if this _wasn't_ a rhetorical question?"  
mindset and emulate a Virtual Newbie. (I suggest qemu for this.)


Still, thanks for taking a stab at it. Imperfect's better than  
obsolete...


Rob--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-12-04 Thread Rob Landley

On 11/24/2013 12:02:30 AM, Alexandre Courbot wrote:

Hi Rob,

On Sun, Nov 24, 2013 at 8:31 AM, Rob Landley r...@landley.net wrote:
  Linus, I hope this can be merged during the -rc cycle of 3.13,  
since the
  gpiod_ interface is going to be introduced there. It would not  
make much

  sense for it to come without its documentation.

 You're right of course. I'll read through it and apply fixes on top
 (or squash into your patch.)

 Formal stuff:
 Don't we need an 00-INDEX file?
 (Maybe Rob can tell whether this is desirable.)


 A 00-INDEX file wouldn't hurt, but it can always be added later. No  
reason
 to hold up the series for that. (I was using them to generate html  
indexes

 for kernel.org/doc but after the breakin they eliminated all non-git
 functionality so I haven't been able to update it since. They  
replaced
 kernel.org/doc/Documentation with a raw git checkout, and I expect  
them to
 replace kernel.org/doc/menuconfig with a raw git checkout any day  
now.)


 That said, a 00-INDEX file would let you know where to start  
reading to find
 the file with the intro paragraph at the start of the old file, the  
bit
 explaining what GPIO is. Here the first file alphabetically is  
board.txt,
 and I have no idea why it's named that, given how it starts. (I was  
sort of
 hoping that somebody who already knows the subsystem would comment  
before I

 do. I have no way of knowing if this documentation is _right_.)

I actually submitted a patch that introduces a 00-INDEX file
yesterday. It's probably a few other gazillions mails under in your
inbox. ;)


I'm a couple weeks behind on my email. I'll get to it eventually. (My  
time's spread between a few too many projects these days...)


Most documentation goes in through the trees of the people whose  
subsystems it documents. I mostly catch the stuff that falls through  
the cracks. I'm somewhere between a librarian shelving abandoned books  
and a janitor.


...
 But I really don't have time to go through every paragraph like  
that, and
 was hoping the gpio guys would (or just sign off on it so I don't  
have

 to)...

I will make another pass and send an update (or a new version of the
patch maybe, since we are still in -rc1 - whatever is more convenient
to Linus). Hopefully early users of the new (oops) interface will send
fixes to the documentation as well, if only to improve my approximate
English.


It's not so much the english, it's that Documentation should be aimed  
at people who _don't_ already know this stuff. Since it tends to be  
written by people who _do_ already know the stuff (kinda hard to do the  
other way, although I've done it), this can be tricky to pull off. You  
have to maintain a But what if this _wasn't_ a rhetorical question?  
mindset and emulate a Virtual Newbie. (I suggest qemu for this.)


Still, thanks for taking a stab at it. Imperfect's better than  
obsolete...


Rob--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-23 Thread Alexandre Courbot
Hi Rob,

On Sun, Nov 24, 2013 at 8:31 AM, Rob Landley  wrote:
>> > Linus, I hope this can be merged during the -rc cycle of 3.13, since the
>> > gpiod_ interface is going to be introduced there. It would not make much
>> > sense for it to come without its documentation.
>>
>> You're right of course. I'll read through it and apply fixes on top
>> (or squash into your patch.)
>>
>> Formal stuff:
>> Don't we need an 00-INDEX file?
>> (Maybe Rob can tell whether this is desirable.)
>
>
> A 00-INDEX file wouldn't hurt, but it can always be added later. No reason
> to hold up the series for that. (I was using them to generate html indexes
> for kernel.org/doc but after the breakin they eliminated all non-git
> functionality so I haven't been able to update it since. They replaced
> kernel.org/doc/Documentation with a raw git checkout, and I expect them to
> replace kernel.org/doc/menuconfig with a raw git checkout any day now.)
>
> That said, a 00-INDEX file would let you know where to start reading to find
> the file with the intro paragraph at the start of the old file, the bit
> explaining what GPIO is. Here the first file alphabetically is "board.txt",
> and I have no idea why it's named that, given how it starts. (I was sort of
> hoping that somebody who already knows the subsystem would comment before I
> do. I have no way of knowing if this documentation is _right_.)

I actually submitted a patch that introduces a 00-INDEX file
yesterday. It's probably a few other gazillions mails under in your
inbox. ;)

> Aforementioned first paragraph:
>> +This document explains how GPIOs can be assigned to given devices and
>> functions.
>> +Note that it only applies to the new descriptor-based interface. For a
>> +description of the deprecated integer-based GPIO interface please refer
>> to
>> +gpio-legacy.txt (actually, there is no real mapping possible with the old
>> +interface; you just fetch an integer from somewhere and request the
>> +corresponding GPIO.
>
>
> Here's how I'd rewrite that:
>
> "This document explains how to assign GPIOs to devices and functions using
> the descriptor-based GPIO interface. (For a description of the deprecated
> integer-based interface see gpio-legacy.txt.)"
>
> Some reasons:
>
> 1) The word "given" made me think "assigned to" and "given" were alternate
> ways of saying the same thing. I know what you mean, but had to read it
> twice to follow, and I don't think "given" adds anything here but potential
> confusion.
>
> 2) Describing an interface as "new" is problematic; it will stop being new
> long before the documentation is updated to stop calling it that. Either say
> which kernel version it was introduced in or don't.
>
> 3) Does the kernel still use the old one? Is it scheduled to be removed? Why
> was it deprecated? Should software that uses it be rewritten to use the new
> one? What kind of timetable are we talking about? If you're not going to
> answer obvious questions, don't open the can of worms of comparing them (at
> least not here).
>
> 4) Warnings against the old interface belong in the document describing the
> old interface. (The sentence fragment and unbalanced parentheses was just
> gravy.)

All good points. Guess I need to do another pass on the doc with them in mind.

> But I really don't have time to go through every paragraph like that, and
> was hoping the gpio guys would (or just sign off on it so I don't have
> to)...

I will make another pass and send an update (or a new version of the
patch maybe, since we are still in -rc1 - whatever is more convenient
to Linus). Hopefully early users of the new (oops) interface will send
fixes to the documentation as well, if only to improve my approximate
English.

Thanks,
Alex.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-23 Thread Rob Landley

On 11/18/2013 03:34:20 AM, Linus Walleij wrote:
On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot  
 wrote:


> The first version received zero feedback, hopefully this one will  
get more
> attention. :) Not much changes, just some more proofreading and the  
fixes
> and improvements that came from it. It looks ok as far as I am  
concerned.


Sorry I was swamped with other stuff...


I'm 8 gazillion messages behind myself.

Also Balsa's threading mode is broken so I tend to flag users when I'm  
in a hurry (alphabetical sort works) and when they change names  
midconversation I tend not to notice they've posted more on a topic.  
(Switching email clients is on my todo list.)


> Linus, I hope this can be merged during the -rc cycle of 3.13,  
since the
> gpiod_ interface is going to be introduced there. It would not make  
much

> sense for it to come without its documentation.

You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)

Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)


A 00-INDEX file wouldn't hurt, but it can always be added later. No  
reason to hold up the series for that. (I was using them to generate  
html indexes for kernel.org/doc but after the breakin they eliminated  
all non-git functionality so I haven't been able to update it since.  
They replaced kernel.org/doc/Documentation with a raw git checkout, and  
I expect them to replace kernel.org/doc/menuconfig with a raw git  
checkout any day now.)


That said, a 00-INDEX file would let you know where to start reading to  
find the file with the intro paragraph at the start of the old file,  
the bit explaining what GPIO is. Here the first file alphabetically is  
"board.txt", and I have no idea why it's named that, given how it  
starts. (I was sort of hoping that somebody who already knows the  
subsystem would comment before I do. I have no way of knowing if this  
documentation is _right_.)


Aforementioned first paragraph:

+This document explains how GPIOs can be assigned to given devices  
and functions.


+Note that it only applies to the new descriptor-based interface. For  
a
+description of the deprecated integer-based GPIO interface please  
refer to
+gpio-legacy.txt (actually, there is no real mapping possible with  
the old

+interface; you just fetch an integer from somewhere and request the
+corresponding GPIO.


Here's how I'd rewrite that:

"This document explains how to assign GPIOs to devices and functions  
using the descriptor-based GPIO interface. (For a description of the  
deprecated integer-based interface see gpio-legacy.txt.)"


Some reasons:

1) The word "given" made me think "assigned to" and "given" were  
alternate ways of saying the same thing. I know what you mean, but had  
to read it twice to follow, and I don't think "given" adds anything  
here but potential confusion.


2) Describing an interface as "new" is problematic; it will stop being  
new long before the documentation is updated to stop calling it that.  
Either say which kernel version it was introduced in or don't.


3) Does the kernel still use the old one? Is it scheduled to be  
removed? Why was it deprecated? Should software that uses it be  
rewritten to use the new one? What kind of timetable are we talking  
about? If you're not going to answer obvious questions, don't open the  
can of worms of comparing them (at least not here).


4) Warnings against the old interface belong in the document describing  
the old interface. (The sentence fragment and unbalanced parentheses  
was just gravy.)


But I really don't have time to go through every paragraph like that,  
and was hoping the gpio guys would (or just sign off on it so I don't  
have to)...


Rob--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-23 Thread Rob Landley

On 11/18/2013 03:34:20 AM, Linus Walleij wrote:
On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot  
acour...@nvidia.com wrote:


 The first version received zero feedback, hopefully this one will  
get more
 attention. :) Not much changes, just some more proofreading and the  
fixes
 and improvements that came from it. It looks ok as far as I am  
concerned.


Sorry I was swamped with other stuff...


I'm 8 gazillion messages behind myself.

Also Balsa's threading mode is broken so I tend to flag users when I'm  
in a hurry (alphabetical sort works) and when they change names  
midconversation I tend not to notice they've posted more on a topic.  
(Switching email clients is on my todo list.)


 Linus, I hope this can be merged during the -rc cycle of 3.13,  
since the
 gpiod_ interface is going to be introduced there. It would not make  
much

 sense for it to come without its documentation.

You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)

Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)


A 00-INDEX file wouldn't hurt, but it can always be added later. No  
reason to hold up the series for that. (I was using them to generate  
html indexes for kernel.org/doc but after the breakin they eliminated  
all non-git functionality so I haven't been able to update it since.  
They replaced kernel.org/doc/Documentation with a raw git checkout, and  
I expect them to replace kernel.org/doc/menuconfig with a raw git  
checkout any day now.)


That said, a 00-INDEX file would let you know where to start reading to  
find the file with the intro paragraph at the start of the old file,  
the bit explaining what GPIO is. Here the first file alphabetically is  
board.txt, and I have no idea why it's named that, given how it  
starts. (I was sort of hoping that somebody who already knows the  
subsystem would comment before I do. I have no way of knowing if this  
documentation is _right_.)


Aforementioned first paragraph:

+This document explains how GPIOs can be assigned to given devices  
and functions.


+Note that it only applies to the new descriptor-based interface. For  
a
+description of the deprecated integer-based GPIO interface please  
refer to
+gpio-legacy.txt (actually, there is no real mapping possible with  
the old

+interface; you just fetch an integer from somewhere and request the
+corresponding GPIO.


Here's how I'd rewrite that:

This document explains how to assign GPIOs to devices and functions  
using the descriptor-based GPIO interface. (For a description of the  
deprecated integer-based interface see gpio-legacy.txt.)


Some reasons:

1) The word given made me think assigned to and given were  
alternate ways of saying the same thing. I know what you mean, but had  
to read it twice to follow, and I don't think given adds anything  
here but potential confusion.


2) Describing an interface as new is problematic; it will stop being  
new long before the documentation is updated to stop calling it that.  
Either say which kernel version it was introduced in or don't.


3) Does the kernel still use the old one? Is it scheduled to be  
removed? Why was it deprecated? Should software that uses it be  
rewritten to use the new one? What kind of timetable are we talking  
about? If you're not going to answer obvious questions, don't open the  
can of worms of comparing them (at least not here).


4) Warnings against the old interface belong in the document describing  
the old interface. (The sentence fragment and unbalanced parentheses  
was just gravy.)


But I really don't have time to go through every paragraph like that,  
and was hoping the gpio guys would (or just sign off on it so I don't  
have to)...


Rob--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-23 Thread Alexandre Courbot
Hi Rob,

On Sun, Nov 24, 2013 at 8:31 AM, Rob Landley r...@landley.net wrote:
  Linus, I hope this can be merged during the -rc cycle of 3.13, since the
  gpiod_ interface is going to be introduced there. It would not make much
  sense for it to come without its documentation.

 You're right of course. I'll read through it and apply fixes on top
 (or squash into your patch.)

 Formal stuff:
 Don't we need an 00-INDEX file?
 (Maybe Rob can tell whether this is desirable.)


 A 00-INDEX file wouldn't hurt, but it can always be added later. No reason
 to hold up the series for that. (I was using them to generate html indexes
 for kernel.org/doc but after the breakin they eliminated all non-git
 functionality so I haven't been able to update it since. They replaced
 kernel.org/doc/Documentation with a raw git checkout, and I expect them to
 replace kernel.org/doc/menuconfig with a raw git checkout any day now.)

 That said, a 00-INDEX file would let you know where to start reading to find
 the file with the intro paragraph at the start of the old file, the bit
 explaining what GPIO is. Here the first file alphabetically is board.txt,
 and I have no idea why it's named that, given how it starts. (I was sort of
 hoping that somebody who already knows the subsystem would comment before I
 do. I have no way of knowing if this documentation is _right_.)

I actually submitted a patch that introduces a 00-INDEX file
yesterday. It's probably a few other gazillions mails under in your
inbox. ;)

 Aforementioned first paragraph:
 +This document explains how GPIOs can be assigned to given devices and
 functions.
 +Note that it only applies to the new descriptor-based interface. For a
 +description of the deprecated integer-based GPIO interface please refer
 to
 +gpio-legacy.txt (actually, there is no real mapping possible with the old
 +interface; you just fetch an integer from somewhere and request the
 +corresponding GPIO.


 Here's how I'd rewrite that:

 This document explains how to assign GPIOs to devices and functions using
 the descriptor-based GPIO interface. (For a description of the deprecated
 integer-based interface see gpio-legacy.txt.)

 Some reasons:

 1) The word given made me think assigned to and given were alternate
 ways of saying the same thing. I know what you mean, but had to read it
 twice to follow, and I don't think given adds anything here but potential
 confusion.

 2) Describing an interface as new is problematic; it will stop being new
 long before the documentation is updated to stop calling it that. Either say
 which kernel version it was introduced in or don't.

 3) Does the kernel still use the old one? Is it scheduled to be removed? Why
 was it deprecated? Should software that uses it be rewritten to use the new
 one? What kind of timetable are we talking about? If you're not going to
 answer obvious questions, don't open the can of worms of comparing them (at
 least not here).

 4) Warnings against the old interface belong in the document describing the
 old interface. (The sentence fragment and unbalanced parentheses was just
 gravy.)

All good points. Guess I need to do another pass on the doc with them in mind.

 But I really don't have time to go through every paragraph like that, and
 was hoping the gpio guys would (or just sign off on it so I don't have
 to)...

I will make another pass and send an update (or a new version of the
patch maybe, since we are still in -rc1 - whatever is more convenient
to Linus). Hopefully early users of the new (oops) interface will send
fixes to the documentation as well, if only to improve my approximate
English.

Thanks,
Alex.
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-19 Thread Linus Walleij
On Mon, Nov 18, 2013 at 11:33 AM, Alex Courbot  wrote:
> On 11/18/2013 06:34 PM, Linus Walleij wrote:

>> Don't we need an 00-INDEX file?
>> (Maybe Rob can tell whether this is desirable.)
>
> Good idea. gpio.txt somehow fulfills that role, but it might be better if we
> split it. Would you like me to submit a new revision?

No please just send some incremental patch on top of
my "fixes" branch in the GPIO tree.

I've read through the docs and couldn't find anything
really wrong with it BTW.

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-19 Thread Linus Walleij
On Mon, Nov 18, 2013 at 11:33 AM, Alex Courbot acour...@nvidia.com wrote:
 On 11/18/2013 06:34 PM, Linus Walleij wrote:

 Don't we need an 00-INDEX file?
 (Maybe Rob can tell whether this is desirable.)

 Good idea. gpio.txt somehow fulfills that role, but it might be better if we
 split it. Would you like me to submit a new revision?

No please just send some incremental patch on top of
my fixes branch in the GPIO tree.

I've read through the docs and couldn't find anything
really wrong with it BTW.

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-18 Thread Alex Courbot

On 11/18/2013 06:34 PM, Linus Walleij wrote:

On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot  wrote:


The first version received zero feedback, hopefully this one will get more
attention. :) Not much changes, just some more proofreading and the fixes
and improvements that came from it. It looks ok as far as I am concerned.


Sorry I was swamped with other stuff...


Linus, I hope this can be merged during the -rc cycle of 3.13, since the
gpiod_ interface is going to be introduced there. It would not make much
sense for it to come without its documentation.


You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)


Great, thanks!


Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)


Good idea. gpio.txt somehow fulfills that role, but it might be better 
if we split it. Would you like me to submit a new revision?



I don't like double spaces after periods. I will just go and remove
all of them from the new documentation unless you convince me
otherwise. Reference:
https://en.wikipedia.org/wiki/Sentence_spacing


Please do - actually I started doing it (they come from the old 
documentation, not the bits I have written myself) but have obviously 
missed at least a few of them. :)


Thanks,
Alex.

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-18 Thread Linus Walleij
On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot  wrote:

> The first version received zero feedback, hopefully this one will get more
> attention. :) Not much changes, just some more proofreading and the fixes
> and improvements that came from it. It looks ok as far as I am concerned.

Sorry I was swamped with other stuff...

> Linus, I hope this can be merged during the -rc cycle of 3.13, since the
> gpiod_ interface is going to be introduced there. It would not make much
> sense for it to come without its documentation.

You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)

Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)

I don't like double spaces after periods. I will just go and remove
all of them from the new documentation unless you convince me
otherwise. Reference:
https://en.wikipedia.org/wiki/Sentence_spacing

Linus
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-18 Thread Linus Walleij
On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot acour...@nvidia.com wrote:

 The first version received zero feedback, hopefully this one will get more
 attention. :) Not much changes, just some more proofreading and the fixes
 and improvements that came from it. It looks ok as far as I am concerned.

Sorry I was swamped with other stuff...

 Linus, I hope this can be merged during the -rc cycle of 3.13, since the
 gpiod_ interface is going to be introduced there. It would not make much
 sense for it to come without its documentation.

You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)

Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)

I don't like double spaces after periods. I will just go and remove
all of them from the new documentation unless you convince me
otherwise. Reference:
https://en.wikipedia.org/wiki/Sentence_spacing

Linus
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/


Re: [PATCH v2] Documentation: gpiolib: document new interface

2013-11-18 Thread Alex Courbot

On 11/18/2013 06:34 PM, Linus Walleij wrote:

On Sat, Nov 16, 2013 at 1:34 PM, Alexandre Courbot acour...@nvidia.com wrote:


The first version received zero feedback, hopefully this one will get more
attention. :) Not much changes, just some more proofreading and the fixes
and improvements that came from it. It looks ok as far as I am concerned.


Sorry I was swamped with other stuff...


Linus, I hope this can be merged during the -rc cycle of 3.13, since the
gpiod_ interface is going to be introduced there. It would not make much
sense for it to come without its documentation.


You're right of course. I'll read through it and apply fixes on top
(or squash into your patch.)


Great, thanks!


Formal stuff:
Don't we need an 00-INDEX file?
(Maybe Rob can tell whether this is desirable.)


Good idea. gpio.txt somehow fulfills that role, but it might be better 
if we split it. Would you like me to submit a new revision?



I don't like double spaces after periods. I will just go and remove
all of them from the new documentation unless you convince me
otherwise. Reference:
https://en.wikipedia.org/wiki/Sentence_spacing


Please do - actually I started doing it (they come from the old 
documentation, not the bits I have written myself) but have obviously 
missed at least a few of them. :)


Thanks,
Alex.

--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/