Path: utzoo!utgpu!jarvis.csri.toronto.edu!rutgers!njin!princeton!phoenix!eho From: eho@cognito.Princeton.EDU (Eric Ho) Newsgroups: gnu.emacs Subject: Re: 2nd Generation GNU Emacs & texinfo ? Message-ID: Date: 1 Jun 89 03:10:54 GMT Sender: news@phoenix.Princeton.EDU Distribution: gnu Organization: Cognitive Science Lab. Princeton University. Lines: 60 >> In article kim@watsup.waterloo.edu >> (Kim Nguyen) writes: >> >> In article eho@bogey.Princeton.EDU >> (Eric Y.W. Ho) writes: >> >> Also, is anyone extending texinfo where it can integrate code as >> well -- >> [...] now you're >> documenting your ideas & writing code at the same time and when >> you've finished, you just run the whole thing through some >> converter/filter and it'll churn out pure code (be they in Lisp, C >> or whatever) on the one hand and typesetted documentation for you >> designs on the other hand. >> >> Eric Ho >> Princeton Cognitive Science Lab., Princeton University >> email = eho@phoenix.princeton.edu voice = 609-987-2819 >> >> Generating "documentation" from the comments in your code is a >> somewhat brain-damaged way of describing your programs usefully. Good >> documentation consists of high-level descriptions, followed by >> increasingly detailed nitty-gritty discussions. >> >> A company for which I worked used to document its code >> "automatically", but the manuals were essentially useless. >> -- >> Kim Nguyen kim@watsup.waterloo.edu >> Systems Design Engineering -- University of Waterloo, Ontario, Canada Actually, what I've in mind was more like Don Knuth's WEB system where one can write code in a more or less hypertext fashion and one can easily sprinkle ideas/comments with the code so as to make the code much more easy to read. As for the typesetted documentation part, documentation means different thing to different people, depending on who is reading it. Obviously the kind of documentations that are sprinkled along with the code is really for people who need to understand your code quick & not really for people using your system. (of course, if one has time (ha ha) one can always write higher-level documentations or a paper so that casual users can have a better understanding of your system). Actaully, if you've implemented a somewhat complicated system and you've left it for a year or so and then you want to extend it or whatever, it usually will take you a while for you to remember what you've done at the nitty-gritty level and I hope that such as system will simply make such a process shorter and easier. It'll be nice too if it can be extended into multiple languages -- e.g. suppose you're building a system whose parts are written in different languages (e.g. Lisp & C++). -- regards. -eric- -- regards. -eric-