Re: writing man pages or texinfo documentation
Date: Tue, 25 May 1999 07:42:32 +0100 (BST)
From: "M.C. Vernon" <mcv21@cus.cam.ac.uk>
On Tue, 25 May 1999, Mark Kettenis wrote:
> I know that the GNU project doesn't like man pages. Improving the info file
> would of course also be a good way to help. We can than write a dummy man
> page that only goves a synopsis and then points to the info file.
>
> IMHO, we really should not waste time on man pages. It is better to
> work on proper documentation instead, extending the current Hurd
> texinfo manual. Having some information in man pages and other
> information in the manual is confusing. What will happen is that at a
> certain point the manual pages will even contradict what's in the
> manual.
What is the GNU objection to man pages? I've found them easier to use
personally, especially if I just want to check the prototype of a library
function.
The GNU coding standards (in standards.info) contain an explanation.
Here are some of the arguments:
* As you say, man pages are good to check things (a prototype, a command
line option). But they are not very well suited for learning about
a program. So they are not a substitute for a real manual.
* The structure of man pages is OK for a short description, but not
very well suited for detailed information, with a lot of examples.
A good manual, divided in chapters and sections, with an index and
cross references is a much better way to structure the information
in a, for the user, logical way.
* Maintaining man pages takes time away from improving the program
and the manual.
However, I think it would be a good idea, have man pages automatically
generated from --help and --version output, as the current fileutils
do. That way, people who are used to UNIX will feel a little more at
home on the Hurd. But at this stage it really isn't a priority.
Improving the manual is!
Mark
Reply to: