mg@cidam.oz (Mike A. Gigante) (05/25/86)
>From: mwh_adev@jhunix.UUCP (JHU UNIX Development Group) [Paul Markowitz] >Subject: unix help routines >Organization: Johns Hopkins Univ. Computing Ctr. > >I am interested in help routines for the unix system. The manual is >ok but is very difficult if you don't know already what you are looking >for. I have also thought about this, the Unix documentation is *bad* for the novice Unix users and *terrible* (even off-putting) for the novice computer user. At our site, this has led to great reluctance to using our Unix boxes from our faculty staff (mainly traditional mechanical engineering). They even prefer to use the institute's cyber!! [:-)] At least on the cyber, they can get semi-reasonable on-line help (with prompting for arguments etc.) One reason for the dislike of Unix documentation is the difficulty of finding the correct thing to ask for. For example, you *must* know that strlen is in string(3) to find out about it. I realise that ptx addresses that problem, but I would argue that for the *novice* user, this isn't sufficient. The keyword entries are also *woefully* inadequate. Just try `man -k files`, and you'll see what I mean (no mention of many important commands that deal with files) > >What I am interested in is a menu driven help routine similar to VMS help. > Even better than VMS help is the Embos help system (for the Elxsi 6400), it's been quite a while since I used the system, but it had excellent facilities for on-line help. Some of the nicer facilities are: - *good* keyword indexing for manual entries - indexing on arbitrary strings (inc. stripping suffixes, partial- match) - ability to retrieve each section of a manual entry (e.g. USAGE section, OPTIONS, EXAMPLES etc. -- the example section was generally *very good*) - was written in a better style than typical of Unix documentation. Most of this is not difficult, just takes a little time. Some of it could be easily automated esp. the keyword indexing etc. I would really like to someone implement the manual section retrieval. If I wasn't so busy, I'd think about doing it myself. Mike G. ----------- Michael Gigante [Research Engineer] UUCP :...!seismo!munnari!cidam.oz!mg Dept Mechanical & Production Eng. ARPA :mg%cidam.oz@seismo.css.gov Royal Melbourne Institute of Technology CSNET:mg%cidam.oz GPO Box 2476V Phone: +61 3 660-2161 Melbourne Vic., Australia 3001 D
chris@umcp-cs.UUCP (Chris Torek) (05/26/86)
In article <195@cidam.oz> mg@cidam.oz (Mike A. Gigante) writes: >The keyword entries are also *woefully* inadequate. Just try `man -k files`, >and you'll see what I mean (no mention of many important commands that deal >with files) The existing key words may be (and I think are) inadequate, but you have chosen a bad example. Most---I would say more than half at the very least---of the Unix commands can deal directly with files in some way or another (other than by redirection); so if the `files' keyword accessed all of these, one would be drowned in the flood of information. What would, of course, be ideal is a truly intelligent help system; but it is hard enough even for people (whose intelligence we agree upon, at least for the most part) to provide `good' help in some cases. There is often a communication barrier: Troublemaker: `Unix doesn't work'. Helper: `What seems to be the problem?' T: `It says "error". It used to work.' H: `*What* says "error"?' T: `My program.' ... (I imagine you get the idea. This is all too familiar to some.) In the mean time, I myself find the Unix Programmer's Manuals mostly sufficient for my own use (and better than VMS HELP, though that is no doubt due to my own unfamiliarity with the latter: I have used it perhaps thrice). An `Examples' section would be perhaps the most useful addition to these manuals; a careful rewrite of many manual entries is probably also in order, to be done by one who both knows how `man -k' works *and* (and I am not sure which is more important) is a good writer! This still leaves the problem of integrating the current systems with the more general documentation in /usr/doc. Most of the on line help systems for Unix seem to center on material in /usr/man. A more general retrieval system is perhaps next in order. But I should leave this to those with more knowledge (and interest) than I. -- In-Real-Life: Chris Torek, Univ of MD Comp Sci Dept (+1 301 454 1516) UUCP: seismo!umcp-cs!chris CSNet: chris@umcp-cs ARPA: chris@mimsy.umd.edu
hutch@sdcsvax.UUCP (Jim Hutchison) (05/27/86)
<> In article <1700@umcp-cs.UUCP> chris@maryland.UUCP (Chris Torek) writes: >used it perhaps thrice). An `Examples' section would be perhaps >the most useful addition to these manuals; ... Our recent copy of the blit support manual (a blit-related version of man called dmdman and all the various manual pages 1-8,l&n), dating 12/6/85, has nice examples included. You get what looks like a normal unix manual page (polygon(3) for example), and low and behold there on the bottom of the page is a hello world size program/program-section showing how to use the arcane little beasty that you just read about. putting it at the bottom is definitely helpful for those times when checking parameter order and type is all that you actually wanted. -- /* Jim Hutchison UUCP: {dcdwest,ucbvax}!sdcsvax!hutch ARPA: Hutch@sdcsvax.ucsd.edu [ Disclaimer eaten by a passing kiwi ] */