bin@primate.wisc.edu (Brain in Neutral) (07/24/90)
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? Paul DuBois Internet: dubois@primate.wisc.edu UUCP: rhesus!dubois CompuServe: >INTERNET:dubois@primate.wisc.edu FAX: 608/263-4031
marcs@servio.UUCP (Marc San Soucie) (07/25/90)
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
bin@primate.wisc.edu (Brain in Neutral) (07/25/90)
From article <595@servio.UUCP>, by marcs@servio.UUCP (Marc San Soucie): >> 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? Marc, thanks for your suggestions. Re: #1 above, what other tools are you thinking of, with which imake should be compared? Also, I'm not sure that to fill the gaps in imake documentation that it's as important to *justify* imake as to *explain* it. There may be other tools that work better, but since imake is in fact what X is configured with, that's what we have to work with, that's what needs to be described. Of course (thinking out loud here...), on the other hand, such a justification might be useful insofar as it would demonstrate why someone might want to use imake for something *other* than X... hmm... Paul DuBois dubois@primate.wisc.edu
dinah@WILKINS.BCM.TMC.EDU (Dinah Anderson) (07/25/90)
To add to Marc's list of what he'd like to see in a document on imake:
1) Clear, concise documentation of all the cases imake can handle
(from include files to man pages) and how to build your own macro if
your specific case has not been addressed.
2) Maybe a list of some commonly asked questions (with answers of course.)
3) I think a case study with step by step instructions would be valuable.
We just changed over to using Imake on a big project here and once I
figured out how to restructure the source and whipped up some sample
Imakefiles, it only took me and 2 other people a few hours to get to the
point where a make World would work. The programmers were impressed at
how painless it was. (Of course I spared them the agony of figuring out
how Imake actually works.)
Dinah Anderson Manager of Systems Integration
Baylor College of Medicine Houston, Texas
internet: dinah@bcm.tmc.edu uucp: {rutgers,mailrus}!bcm!dinahegc@CS.CMU.EDU (eddie caplan) (07/25/90)
In article <2816@uakari.primate.wisc.edu> bin@primate.wisc.edu writes: > >From article <595@servio.UUCP>, by marcs@servio.UUCP (Marc San Soucie): > >What is the problem that Imake purports to solve > >I'm not sure that to fill the gaps in imake documentation that it's >as important to *justify* imake as to *explain* it. i agree with Marc. good documentation of any sort needs to clearly, in laymens' terms as much as possible, establish the context and justification of the accompanying technical material. thanks, and say what you mean. -- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% INTERNET: caplan@cs.cmu.edu BITNET: caplan%cs.cmu.edu@cmuccvma CSNET: caplan%cs.cmu.edu@relay.cs.net UUCP: ...!seismo!cs.cmu.edu!caplan USPS: eddie caplan, c/o school of comp sci, cmu, pittsburgh, pa 15213-3890 phone: (412) 268-6426 a good engineer is a good thief. bennet, thanks for the signature. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% INTERNET: caplan@cs.cmu.edu BITNET: caplan%cs.cmu.edu@cmuccvma
marcs@servio.UUCP (Marc San Soucie) (07/26/90)
Paul DuBois writes: > Marc San Soucie wrote: > >> What do *you* want to see imake documentation 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? > > Re: #1 above, what other tools are you > thinking of, with which imake should be compared? Make, specifically. Most people are vaguely familiar with using makefiles to generate different versions of software for different systems/OS's. Many people are probably not familiar with the kinds of problems that come up when trying to do this on the scale of X, and in particular with the problems that caused the X folks to come up with imake. A problem statement should make the reader sit up and say "Oh yeah, I hadn't thought of that. You'd need a new tool to solve that problem..." > Also, I'm not sure that to fill the gaps in imake documentation that it's > as important to *justify* imake as to *explain* it. The problem statement is all the justification you need. The rest explains how imake solves the problem, and how to use imake to solve similar problems. > Of course (thinking out loud here...), on the other hand, such a > justification might be useful insofar as it would demonstrate why > someone might want to use imake for something *other* than X... hmm... Ubetcha. Marc San Soucie Servio Corporation Beaverton, Oregon marcs@slc.com
bin@primate.wisc.edu (Brain in Neutral) (07/26/90)
From article <9007251354.AA04770@NICOLLE.IAIMS.BCM.TMC.EDU>, by dinah@WILKINS.BCM.TMC.EDU (Dinah Anderson): > 1) Clear, concise documentation of all the cases imake can handle > (from include files to man pages) and how to build your own macro if > your specific case has not been addressed. What do you mean by "cases"? The kinds of targets that can be built using the existing Imake.rules file? > 2) Maybe a list of some commonly asked questions (with answers of course.) This is a good idea, but people will have to post (or mail) the questions so that a list of them can be compiled. (Some of the articles in this thread do contain such questions, but we need more of them.) Paul DuBois dubois@primate.wisc.edu
moraes@cs.toronto.edu (Mark Moraes) (07/27/90)
People may want to consider contrib/doc/imake in R4 as a starting point. I'd welcome comments and criticism about it. Yep, I know it hasn't been updated for R4 yet -- I didn't think there was any interest... :-) Mark.