From: Karel Kulhavy <clock@twibright.com>
To: linux-kernel@vger.kernel.org
Subject: Documentation approach bugreport.
Date: Thu, 14 Oct 2004 10:27:12 +0000 [thread overview]
Message-ID: <20041014102712.GC8837@beton.cybernet.src> (raw)
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<
reply other threads:[~2004-10-14 10:27 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20041014102712.GC8837@beton.cybernet.src \
--to=clock@twibright.com \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.