Date: Tue, 25 May 1999 07:42:32 +0100 (BST) From: "M.C. Vernon" <[EMAIL PROTECTED]>
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