Date: Tue, 6 Jun 1995 17:29:13 -0400 (EDT) From: Ken Bowen Subject: (NO) CODE STANDARDS/ (YES) DOCUMENTATION To: djgpp AT sun DOT soe DOT clarkson DOT edu At the risk of throwing ethanol on burning gasoline, let me make some observations and comments, with the pious hope that some might be seen as constructive. Obs#1: There are distinct subcommunities within the DJGPP readership whose individual goals are sometimes at cross purposes. Given individuals sometimes inhabit more than one camp. In particular, there are those who are primarily interested in implementation of DJGPP (the extender, gcc, etc.,etc.), and those who are primarily interested in using DJGPP in personal or professional projects. [I myself fall into the latter (apply it) for DJGPP, but into the former (implement it) for the Prolog compilers I use DJGPP to build. ] Each group really needs the other: A. Not many compiler builders find it much fun it there aren't any people using their tools. B. Obviously, a compiler user needs some compiler builders, unless he/she is inhabiting both camps. And then it is still more fun to play in a sandbox with other kids. So: Mutual symbiotic co-existence is the order of the day. Note on good manners: Both implementation and application are "real" work. Obs#2: There is a wide variation in individual ability to maintain detail in one's head. That is, some of us have more need for documentation than others. (I need more.) I've observed this "fact" and the variation in sytle/need in every project I've been involved with, including all of the work at this company. Obs#3: Good documentation is always valuable, for all of the reasons that various people have brought out, but most importantly: communication between programmers. Almost all of the other good things that flow from documentation can be seen to flow from good communication between programmers. Obs#4: Communication builds community. The on-line DJGPP community is very pleasant _AND_ very productive. This has come about already without any great documentation effort, which says good things about the people involved. Developing more extensive documentation would enable that conjenial community to expand a little bit more easily. [Let me comment that the Prolog on-line communitiy is neither so conjenial nor nearly so productive. In part, it is not so focused, but that doesn't account for everything.] I'll end the high-level observation/pontification here. I have a few more specific concerns and questions related to documentation. DJGPP (on DOS; hopefully on 32-bin MS Wins and OS/2), and GNU on Unix, is the tool we've used to build ALS Prolog, and is the primary tool that our users will use to extend Prolog programs with C-stuff (interfaces, etc.). So I've been mulling on what I could do to produce more of a "traditional" manual for people who (like me) are not the world's hottest C programmers, though usually they are hotshots at other things ranging from chemistry to risk analysis. The FAQ and the Info pages are a good start, but in both My Humble Opinion, and my experience supporting my users, not quite enough. What I envision would still be small and crisp, but do a bit more (linear) handholding, with good hypertext support. Perhaps it would be possible to start from the current FAQ and Info pages, and stitch them togehter with some editing/expansion, and just plain new hand-holding material. At ALS, we are moving from using hard-copy manuals to using on-line manuals. We are using the Adobe Acrobat reader for distribution because it is both (economically) free and available on a fairly wide range of platforms, including DOS with a very high-quality GUI presentation. It provides very nice PostScript and HyperLink connections. Unfortunately, even though the readers are ($) free, the tools to develop things are not. Realistically, one has to either invest in Adobe's Acrobat Distiller, or in the forthcoming version of FrameMaker. [For our historical sins, we have done both.] It is possible to convert between various of these Publishing formats, including TeX, but not at all easy. We use FrameMaker to prepare our manuals. Until this month (6/95), we had to do fairly arcane things to get the source transformed to Acrobat, but one would never want to prepare source in Acrobat. When the new version of Frame comes out this month, it will produce Acrobat, so it will make such things fairly nice. It can also produce PostScript (no hypertext there), and HTML, a very nice alternative, but to my eye, not as nice as reading PostScript. One other note. As I understand it, Adobe has no plans for further development of the DOS version of Acrobat. On the one hand, this is unfortunate, in that it doesn't support cross-document hyperlinks, as the Windows and Mac versions already do, and which Adobe says the next Unix versions will. On the other hand, it might possibly be fortunate. I've thought about approaching Adobe and encouraging them to put the DOS version in the public domain, much as QuarterDeck has done with some of its stuff. This should be a win-win move: The DOS-based public domain/free software community would gain a powerful documentat presentation tool, and Adobe would gain (presumably) an on-going improvement of the Acrobat reader. Sooooo, I'll put this out, inviting comments, flames, suggestions, offers of help or cooperation, etc., etc. || Ken Bowen Applied Logic Systems, Inc. PO Box 180, ||==== Voice: +1 (617)965-9191 Newton Centre, || FAX: +1 (617)965-1636 MA 02159 USA Email: ken AT als DOT com WWW: http://www.als.com