Re: LDP / KDP?

Re: LDP / KDP?

[Charles Samuels]

Well, upon reading the output produced from a make htmldoc in the kernel
source, I've been rather (read: very) discouraged.

I'm not sure there'd be much of a "market" for this, seeing as how much more
complete the inline-kerneldocs will be.

_still_, I like my format more, it seems like it'd be much easier to search,
and I think the format is much more ideal than docbook (which I have worked
with)

e.g., an example data file: http://derkarl.org/kerneldoc/data/init_timer.kd

And of course, I'm making no effort in preventing others from "syndicating"
these data files.  With which it should be simple enough to generate a
printed form, and other formats from.  In other words: it's a really easy
parse.

But the main problem is, it will be easier for the actual writers of the code
to maintain their docs inline, which will severely slow the acceptance of
this.  So, it's a choice between inline docs and this.  If there's any
approval of this ("officially"?), then I'de be open to discuss moving this to
something LDP-sanctioned, but of course, I wouldn't want to remove the
versatility that I have so far.

However, the main reason I didn't use docbook at first was _because_ I wanted
the versatility, and I didn't want something that behaved like a book.

e.g. 
 http://developer.kde.org/documentation/library/2.0-api/classref/kdecore/

This documentation _is_ inline to the code (in the headers), generated via a
perl script "kdoc".

On Wednesday 18 July 2001 08:50 am, you wrote:
> Charles Samuels (charles@kde.org) wrote:
> (I'm only quoting your whole message because I'm
> cc'ing it to discuss@linuxdoc.org.)
>
> Have you considered writing this as an LDP Guide?
>
> Advantages:
> * Harness the incredible power of a virtual army of
> LDP volunteers. (Well, a virtual platoon...)
> * The docs become print-ready as well.
> * DocBook is a standard! Yay standards!
> * Use the already-present distribution network the LDP
> has in place.
>
> Disadvantages:
> * Your formatting looks spiffier than the LDP
> stylesheets.
> * You'd have to rewrite what you have.
> * DocBook is not tailored to your purposes.
> * Multiple versions will exist throughout the world.
>
> I believe it's an alternative worth considering. I'd
> be willing to convert what you already have to
> DocBook.

-------------------------------------------------------

Re: LDP / KDP?

[John Levon]

On Wed, Jul 18, 2001 at 09:36:48AM -0700, Charles Samuels wrote:

> _still_, I like my format more, it seems like it'd be much easier to search,
> and I think the format is much more ideal than docbook (which I have worked
> with)
> 
> e.g., an example data file: http://derkarl.org/kerneldoc/data/init_timer.kd

but docbook is not the inline docs format. DocBook is an /output/ of the hacky perl
script. You can write another hacky perl script to output in your format if you
want.

> This documentation _is_ inline to the code (in the headers), generated via a
> perl script "kdoc".

scripts/kernel-doc

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: LDP / KDP?

[gdrago23]

--- Charles Samuels <charles@kde.org> wrote:
> 
> Well, upon reading the output produced from a make
> htmldoc in the kernel 
> source, I've been rather (read: very) discouraged.
> 
> I'm not sure there'd be much of a "market" for this,
> seeing as how much more 
> complete the inline-kerneldocs will be.

Oops. I'm an idiot. After reading

http://kernelnewbies.org/documents/kdoc/

I realize that it's all been done now. Oopsie.

-adam buchbinder

__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail
http://personal.mail.yahoo.com/

LDP / KDP?

[gdrago23]

Charles Samuels (charles@kde.org) 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 

(I'm only quoting your whole message because I'm
cc'ing it to discuss@linuxdoc.org.)

Have you considered writing this as an LDP Guide?

Advantages:
* Harness the incredible power of a virtual army of
LDP volunteers. (Well, a virtual platoon...)
* The docs become print-ready as well.
* DocBook is a standard! Yay standards!
* Use the already-present distribution network the LDP
has in place.

Disadvantages:
* Your formatting looks spiffier than the LDP
stylesheets.
* You'd have to rewrite what you have.
* DocBook is not tailored to your purposes.
* Multiple versions will exist throughout the world.

I believe it's an alternative worth considering. I'd
be willing to convert what you already have to
DocBook.

-adam buchbinder



__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail
http://personal.mail.yahoo.com/