Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!rutgers!att!ulysses!andante!alice!andrew
From: andrew@alice.UUCP (Andrew Hume)
Newsgroups: comp.unix.wizards
Subject: Re: 'nmake' manual pages
Summary: make documentation is hard
Keywords: nmake manual
Message-ID: <9378@alice.UUCP>
Date: 22 May 89 03:20:38 GMT
References: <1989@internal.Apple.COM>
Organization: AT&T Bell Laboratories, Murray Hill NJ
Lines: 29



	i haven't read the nmake manual (just the TM and papers)
but would offer a criticism of its man page which is nearly
twice as long as the Ninth Edition's manual entry for sh(1).
This is just too long, even if none of it is superfluous.

	as for gnu make; it certainly has a splendidly typeset
manual although i do miss a manual page (is there one now?).
The one thing that most sticks in my mind is that the manual
spends several pages covering recursive calls to gnu make
and the little conveniences offered fro this while it never
actually details the exact mechanism used to determine
who is out of date with respect to who. This is not obvious
and should be documented as least as well as recursive calls.
(I note stu dodged this too but webb miller(?) covered similar
ground in SP&E a while back.)

	make documentation is hard to write, particularly for the more modern
makes which have subtle features that interact in nonobvious ways.

	as for the person who bitched about the toolchest offering
several incompatible makes, it is not as if AT&T can't make up its mind (about make).
it is simply allowing us (developers buried inside at&t) a
chance to let outsiders use our code. this stuff is research,
its not supposed to be compatible. if you want a clear consistent
view, the best we got is system V. if that is not satisfactory,
try toolchest (nmake may be $?,000 but mk is ~$125) or gnu or
type in the make from Dr dobbs's journal!