lkml.org 
[lkml]   [2004]   [Oct]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectDocumentation approach bugreport.
Linux kernel documentation redirects the user sometimes to manpages which is
a bad practice according to my opinion, which I am going to explain why
later.

make menuconfig, Loadable module support, Enable loadable module support,
< Help >: "For more information, see the man pages for x
modprobe, lsmod, modinfo, insmod and rmmod."

There are various reasons why I think this is a bad practice:
* Linux is a kernel. The place where Linux ends and other things (like programs)
begin lies in a syscall modprobe makes. The user could use another
program that complies to the same interface specification and does the same
job as insmod, modprobe etc. If he used such a program, he wouldn't
need neither modprobe nor insmod on his system and logically wouldn't have
installed corresponding manpages. The redirect in the Linux documentation
in the <Help> would be invalid then.
* Sometimes Linux is used in a restricted environment for example embedded
system where the manpages would take up unnecessary space and are omitted
for this reason. The redicrect in the Linux documentation would be invalid
then too.
* Manpages are different project than Linux. It isn't then clear, if e. g. man
modprobe contains a bug, whether it should be reported to them or to Linux.
* Linux kernel is subject to changes as well as manpages are. They are being
on the system independently and it easily becomes that manpages get out of
sync with Linux kernel. Then the pointed-to information could be
too old or too new (for example when old Linux version is being employed
for some technical reason).

I suggest the following:
* the manpage pointers to be removed and the information that is being referred
to be copied into Linux source tree and further maintained there
* If the above should prove too much burden for the size of the source tarball
, separate information page to be made on http://www.kernel.org in the style
of Exim 4.40 Specification http://exim.org/exim-html-4.40/doc/html/spec.html

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

\
 
 \ /
  Last update: 2005-03-22 14:07    [W:0.028 / U:12.296 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site