Re: Kernel Documentation

Re: Kernel Documentation

[Charles Samuels]

On 2001-07-17 20:46:24, Ignacio Vazquez-Abrams <ignacio@openservices.net> 
wrote:

> This is probably a silly question, but why doesn't your site just use
> DocBook?

DocBook is more "bookish" complete with chapters and all.  I've used it 
before, it's nice, but not for this, in my opinion.  Also, the backend just 
moves the XML data into a temporary MySQL database for easy searching, and 
sorting, and something like that, I think, would be much more difficult with 
docbook.

Re: Kernel Documentation

[Crutcher Dunnavant]

++ 17/07/01 14:02 -0700 - Charles Samuels:
> On 2001-07-17 20:46:24, Ignacio Vazquez-Abrams <ignacio@openservices.net> 
> wrote:
> 
> > This is probably a silly question, but why doesn't your site just use
> > DocBook?
> 
> DocBook is more "bookish" complete with chapters and all.  I've used it 
> before, it's nice, but not for this, in my opinion.  Also, the backend just 
> moves the XML data into a temporary MySQL database for easy searching, and 
> sorting, and something like that, I think, would be much more difficult with 
> docbook.

2 things:

1: there is a project in the kernel to establish API references.
you should not duplicate this work, but should add to it.
Reason: There is no way you can get or stay ahead.

2: the secondary issue of documenting best practices in the
kernel is a different matter altogether. I, myself, have started
a project to do this. I'm sorta scared of letting people know
about it at this point, but I feel it is necessary.

the entry point is:
http://bama.ua.edu/~dunn001/journeyman/

I /am/ looking for help, but it is very early. I am NOT looking
for exposure, so dont even bother looking if you dont want to write
docs; there isnt anything there for you.

-- 
Crutcher        <crutcher@datastacks.com>
GCS d--- s+:>+:- a-- C++++$ UL++++$ L+++$>++++ !E PS+++ PE Y+ PGP+>++++
    R-(+++) !tv(+++) b+(++++) G+ e>++++ h+>++ r* y+>*$

Re: Kernel Documentation

[Charles Samuels]

BTW: 

On Tuesday 17 July 2001 02:18 pm, you wrote:
> ++ 17/07/01 14:02 -0700 - Charles Samuels:
> 2 things:
>
> 1: there is a project in the kernel to establish API references.
> you should not duplicate this work, but should add to it.
> Reason: There is no way you can get or stay ahead.

make htmldoc ? I don't have docbook, and don't want to have to install it, 
well, unless I know that it'l get me what I want.  Does it create an actual 
API reference?

>
> 2: the secondary issue of documenting best practices in the
> kernel is a different matter altogether. I, myself, have started
> a project to do this. I'm sorta scared of letting people know
> about it at this point, but I feel it is necessary.
>
> the entry point is:
> http://bama.ua.edu/~dunn001/journeyman/

404.  Not sure what this is anyway :)

>
> I /am/ looking for help, but it is very early. I am NOT looking
> for exposure, so dont even bother looking if you dont want to write
> docs; there isnt anything there for you.

Re: Kernel Documentation

[Charles Samuels]

On Tuesday 17 July 2001 02:25 pm, Charles Samuels wrote:
> BTW:
Sorry, multitasking: I meant to say I'm on the linux-kernel mailing list now, 
so you don't need to be CCing me


-Charles

Re: Kernel Documentation

[John Levon]

On Tue, Jul 17, 2001 at 02:25:03PM -0700, Charles Samuels wrote:

> On Tuesday 17 July 2001 02:18 pm, you wrote:
> > ++ 17/07/01 14:02 -0700 - Charles Samuels:
> > 2 things:
> >
> > 1: there is a project in the kernel to establish API references.
> > you should not duplicate this work, but should add to it.
> > Reason: There is no way you can get or stay ahead.
> 
> make htmldoc ? I don't have docbook, and don't want to have to install it, 
> well, unless I know that it'l get me what I want.  Does it create an actual 
> API reference?

yes. you can read a recent version at http://kernelnewbies.org/documents/kdoc/

Everyone would much prefer it if you pitched in with this instead I think...

one simple advantage is the docs are inline so have a slightly higher chance
of staying up to date.

regards
john

-- 
"Voodoo Programming:  Things programmers do that they know shouldn't work but
 they try anyway, and which sometimes actually work, such as recompiling
 everything."
	- Karl Lehenbauer

Re: Kernel Documentation

[Tim Jansen]

On Wednesday 18 July 2001 04:19, John Levon wrote:
> one simple advantage is the docs are inline so have a slightly higher
> chance of staying up to date.

BTW Is there any place where the exact format of the inline docs is explained?

bye...

Re: Kernel Documentation

[Tim Waugh]

[-- Attachment #1: Type: text/plain, Size: 281 bytes --]

On Wed, Jul 18, 2001 at 11:06:21AM +0200, Tim Jansen wrote:

> BTW Is there any place where the exact format of the inline docs is
> explained?

scripts/kernel-doc, which interprets them. ;-)

Seriously though, there is a comment at the top of the file explaining
it all.

Tim.
*/

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]

Re: Kernel Documentation

[Ignacio Vazquez-Abrams]

On Tue, 17 Jul 2001, Crutcher Dunnavant wrote:

> the entry point is:
> http://bama.ua.edu/~dunn001/journeyman/
>
> I /am/ looking for help, but it is very early. I am NOT looking
> for exposure, so dont even bother looking if you dont want to write
> docs; there isnt anything there for you.

In reality, there isn't anything there for anyone. There isn't anything at all
right now at that address.

-- 
Ignacio Vazquez-Abrams  <ignacio@openservices.net>

Re: Kernel Documentation

[Crutcher Dunnavant]

++ 17/07/01 17:18 -0400 - Crutcher Dunnavant:
> ++ 17/07/01 14:02 -0700 - Charles Samuels:
> the entry point is:
> http://bama.ua.edu/~dunn001/journeyman/
oops:
http://bama.ua.edu/~dunna001/journeyman/

-- 
Crutcher        <crutcher@datastacks.com>
GCS d--- s+:>+:- a-- C++++$ UL++++$ L+++$>++++ !E PS+++ PE Y+ PGP+>++++
    R-(+++) !tv(+++) b+(++++) G+ e>++++ h+>++ r* y+>*$

Re: Kernel Documentation

[Wichert Akkerman]

In article <200107172102.OAA19756@altair.dhs.org>,
Charles Samuels  <charles@kde.org> wrote:
>DocBook is more "bookish" complete with chapters and all.  I've used it 
>before, it's nice, but not for this, in my opinion.  Also, the backend just 
>moves the XML data into a temporary MySQL database for easy searching, and 
>sorting, and something like that, I think, would be much more difficult with 
>docbook.

DocBook can be XML though.

Wichert.
-- 
  _________________________________________________________________
 /       Nothing is fool-proof to a sufficiently talented fool     \
| wichert@wiggy.net                   http://www.liacs.nl/~wichert/ |
| 1024D/2FA3BC2D 576E 100B 518D 2F16 36B0  2805 3CB8 9250 2FA3 BC2D |

Kernel Documentation

[Charles Samuels]

I apologize for using the D-word, however, I've created some, so I think that 
makes it acceptable.

But first, I was having a little fun kernel-hacking the other day, and I had 
noticed that every time I want information on function-X, I have to start 
grepping like hell, and it's even worse when I don't know the name of the 
function. What we needed was an API (KPI?) reference.

So I made one.  

<blink><marquee> http://derkarl.org/kerneldoc/ </marquee></blink>
(It seems that 10% of europe can't get that domain: 207.44.242.45)

Obviously, it's not complete, in fact, if it were any less complete, I could 
call it the linux kernel :)

The _real_ reason I post this message is, of course, for help.  I'll be more 
than happy to accept new xml documentation files (the bottom of each page 
contains a link to the associated XML file, as an example).

PS. I'm not on this mailing list (I'm on plenty, don't worry), so I'll be 
following it on the archives.

-Charles

Re: Kernel Documentation

[Ignacio Vazquez-Abrams]

On Tue, 17 Jul 2001, Charles Samuels wrote:

>
> I apologize for using the D-word, however, I've created some, so I think that
> makes it acceptable.
>
> But first, I was having a little fun kernel-hacking the other day, and I had
> noticed that every time I want information on function-X, I have to start
> grepping like hell, and it's even worse when I don't know the name of the
> function. What we needed was an API (KPI?) reference.
>
> So I made one.
>
> <blink><marquee> http://derkarl.org/kerneldoc/ </marquee></blink>
> (It seems that 10% of europe can't get that domain: 207.44.242.45)
>
> Obviously, it's not complete, in fact, if it were any less complete, I could
> call it the linux kernel :)
>
> The _real_ reason I post this message is, of course, for help.  I'll be more
> than happy to accept new xml documentation files (the bottom of each page
> contains a link to the associated XML file, as an example).
>
> PS. I'm not on this mailing list (I'm on plenty, don't worry), so I'll be
> following it on the archives.
>
> -Charles

This is probably a silly question, but why doesn't your site just use DocBook?

-- 
Ignacio Vazquez-Abrams  <ignacio@openservices.net>