I was reading an article today on Slashdot about how poorly documented the
Windows API was and had this fear that Linux could get the same way. So, cut to
the point:
Is there a project underway that documents how things like the VM, the Memory
Manger, what a a specific driver needs to do, what it needs to return, how it is
called, what do all those files in arch/whatever do? Are there bits and pieces
spewed around all over the net? It would seem to me that someone ( and I will
volunteer ) sould sit down and put together some sort of documentation system
for the Kernel. Somthing to the effect of a super help for users with all the
technical details for developers.
Obviously it should be kept on the Internet but in such a way that it can be
contributed to by many people ( preferrably the people who have influence with
the code ). It should also have a team of "editors" and be maintained such that
it is browsable, printable, and publishable.
I personally feel that now would be the time to do this while the current
development tree is being wrapped up for production and there is no major work
on a 2.5 development tree - at least publicly. Like I said, I voulenteer to
coordinate this effort and find a place to host it. What are the thoughts of
others? Good idea, bad idea? Input is more than welcome.
--
-Carl Perry
[email protected]
"Real programmers don't draw flowcharts. Flowcharts are, after
all, the illiterate's form of documentation. Cavemen drew
flowcharts; look how much good it did them."
-Fortune (The App, not the Magazine)
Carl Perry wrote:
>
> I was reading an article today on Slashdot about how poorly documented the
> Windows API was and had this fear that Linux could get the same way. So, cut to
> the point:
Whoever posted this on Slashdot is smoking some killer dope or
something. The Windows API is very well documented via online docs from
MSDN -- better than most software anywhere in the world. Whoever said
this was high or something or ignorant or never had an MSDN
subscription. I used to get 20-40 CD's a month from MS on a Universal
Subscription, with enormous documentation..
Jeff
> Is there a project underway that documents how things like the VM, the Memory
> Manger, what a a specific driver needs to do, what it needs to return, how it is
> called, what do all those files in arch/whatever do? Are there bits and pieces
For the kernel stuff there is a project to put documentation about functions
and what they do inline into the kernel. Its slow progress. Trying to do
anything formal and structured isnt going to be productive until the
documentation is much much more complete
For syscalls Andries Brouwer maintains a man page collection (and writes many
of them). He takes submissions.
On Fri, 08 Dec 2000, Alan Cox wrote:
> > Is there a project underway that documents how things like the VM, the Memory
> > Manger, what a a specific driver needs to do, what it needs to return, how it is
> > called, what do all those files in arch/whatever do? Are there bits and pieces
Of course we are not really talking Linux api here - these are internal
interfaces. The Linux syscalls themselves are reasonably
well-documented. The internal interfaces... weeelllll...
http://lxr.linux.no
I know exactly how it feels when first getting into the internal kernel
interfaces - for me that was barely a year ago. I wanted at that time
to try and fix all the documentation problems as I went, but it quickly
turned into a choice between doing useful development and doing useful
documentation. Guess which one I chose. I sincerely hope that others
will make the opposite choice, and the linux hacking world will be a
better place.
> For the kernel stuff there is a project to put documentation about functions
> and what they do inline into the kernel. Its slow progress. Trying to do
> anything formal and structured isnt going to be productive until the
> documentation is much much more complete
>
> For syscalls Andries Brouwer maintains a man page collection (and writes many
> of them). He takes submissions.
http://www.win.tue.nl/math/dw/personalpages/aeb/linux/
Wow, that's useful. Also check out:
http://kernelnewbies.org/links/
with many high quality links to kernel documentation around the web.
Tigran Aivazian has been preparing 'Linux Kernel Internals' which is
*highly recommended* and 100% free. Why don't you get together with
him, and Gary Lawrence Murphy (see his monthy kernel wiki nag)?
Personally, I try to do the right thing and submit at least one piece
of documentation per month to somebody's documenation project but...
it's not always so easy to free up the required hour or two. This
month my feeble attempt consisted of nagging Ben LaHaise to submit a
particularly lucid email he sent me as a code comment.
Maybe next month will be better.
--
Daniel
Daniel Phillips wrote:
> On Fri, 08 Dec 2000, Alan Cox wrote:
> > For the kernel stuff there is a project to put documentation about functions
> > and what they do inline into the kernel. Its slow progress. Trying to do
> > anything formal and structured isnt going to be productive until the
> > documentation is much much more complete
> Tigran Aivazian has been preparing 'Linux Kernel Internals' which is
> *highly recommended* and 100% free. Why don't you get together with
> him, and Gary Lawrence Murphy (see his monthy kernel wiki nag)?
>
> Personally, I try to do the right thing and submit at least one piece
> of documentation per month to somebody's documenation project but...
> it's not always so easy to free up the required hour or two. This
> month my feeble attempt consisted of nagging Ben LaHaise to submit a
> particularly lucid email he sent me as a code comment.
Lucid e-mails often get stuck into Documentation/*, that's fine.
The preferred is 'make {pdf,ps,html}docs' as yanked from
Documentation/DocBook.
Jeff
--
Jeff Garzik |
Building 1024 | These are not the J's you're lookin' for.
MandrakeSoft | It's an old Jedi mind trick.
On Fri, 8 Dec 2000, Daniel Phillips wrote:
> Tigran Aivazian has been preparing 'Linux Kernel Internals' which is
> *highly recommended* and 100% free.
in case he is curious where to find it:
http://www.moses.uklinux.net/patches/lki.html
(or .sgml for master source).
Interestingly, the main problem with LKI turned out to be _not_ the issue
of keeping it uptodate but filling in the missing bits, most notably
buffer cache and page cache. By now I more or less actually understand the
Linux buffer cache (only after diligent comparison with UW7, AIX, OSR5 and
many other commercial UNIX implementations whose source code is available)
but still not the page cache (even after reading everything about it that
I could find, including recent Understanding Linux Kernel book by Bovet
which I just finished reading). E.g. it is not even obvious to me that
things will get any worse if one throws away the entire readahead logic
from the page cache.
So, if someone wants to write a chapter on Linux page cache and contribute
it to the LKI book (and thus become a co-author :) please feel free -- it
will be a proof that someone in the world actually understands it -- at
the moment I doubt that very much... Take it as a challenge :)
Regards,
Tigran