Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!uunet!servio!marcs
From: marcs@servio.UUCP (Marc San Soucie)
Newsgroups: comp.windows.x
Subject: Re: imake documentation woes
Summary: Suggestions
Message-ID: <595@servio.UUCP>
Date: 24 Jul 90 17:09:51 GMT
Lines: 50

Paul DuBois writes:

> OK, we've all griped that the imake documentation isn't more complete
> than it is (I put it that way because it is not, after all, non-existent).
> I'll stick my neck out and start writing some.
>
> What do *you* want to see it contain?

1) A problem statement.

    What is the problem that Imake purports to solve, that isn't solved by
    other tools? Show some examples of those problems, using the other tools.
    Why is Imake a good solution to those problems?

2) A description of the assumptive environment.

    What does Imake assume about its operating environment? What directories
    must exist? What files must be in those directories? How do those
    directories relate to '.'? Can those files be moved? Which files can be
    changed, and which can not?

3) A description of the other tools Imake assumes will be used or available.

    Such as 'makedepend', 'xmkmf', 'make', 'install', etc.

3) A description of the contents of the various files.

    Why are there 3 (or 4?) (or is it 6?) include files in an Imake run? What
    symbols does each file contain? Why are those symbols defined in those
    files instead of in some other file? How do the placements of those symbols
    relate to the solution of the basic problem?

4) A description of the various symbols.

    Which symbols are significant to Imake? Which are significant to the basic
    problem solution? Which are specific to the program or programs being
    built? How does one add symbols to the set? Where do they go?

5) A step-by-step procedure for creating a new Imake script suite.

    I'm afraid I don't buy the 'find an Imakefile that works and change it'
    means of getting work done. A clear, step-by-step procedure will do as much
    to explain the proper use of Imake as all of the above description.


Thanks for any work you do to clarify things.

    Marc San Soucie
    Portland, Oregon
    marcs@slc.com