On 11/24/2013 12:02:30 AM, Alexandre Courbot wrote:
Hi Rob,
On Sun, Nov 24, 2013 at 8:31 AM, Rob Landley <rob@xxxxxxxxxxx> 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-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
