Text File

Aihuxl.103 fa.unix-wizards utzoo!decvax!ucbvax!ihnss!ihuxl!jej Thu Aug 13 20:19:50 1981 Forced Interaction, and YAUF (Yet Another Unix Flame) Subject: program interface to mail-like commands, Unix documentation

I've run into a problem of how to automate commands that, to quote Ritchie, "force interaction on the user whether it is wanted or not:" the primordial example is mail.

It is not clear how one could write a program that would issue the correct commands to mail to do a particular filtering, such as "save all mail from John Doe, and delete the rest after printing it offline." mail expects standard input to direct it, based on what it itself has output.

Any notions of a technique for writing such programs?

----------------------------------------

The item about the Unix user interface was very good--one item that the author left out, though, was Unix documentation.

Most notorious, I think, are the multitude of manual pages which say about the error messages that they are "self-explanatory." I believe that this must mean that the author intends them to be meaningful to himself.

Examples:

1. run-time error messages from C programs--these are QUITE machine dependent; rather embarassingly so for an OS based on C as Unix is, one would think. 2. C compiler error messages, which describe every syntax error as "syntax error," which may be enough for Dennis Ritchie, but not for mere mortals. Another worthless error message is that which describes the error in terms of compiler internals. What does that have to do with the constructs the user knows?

Also quite helpful are the error codes one gets from make(1), such as "Error code 100".

Manual pages are frequently vague and casual: I recall the times when I had to try VERY hard to persuade someone that egrep(1) should treat '$' as just another character when it is not at the end of a regular expression, and in another case, that ed(1) permitted nested escaped parentheses in regular expressions. Formal specifications of options and accepted commands may not be useful to some readers, but they cer- tainly are more useful to those who CAN understand them than vague English prose.

"Casualness" at times degenerates into flippancy or display of the author's self-estimated cleverness: e.g.

"This brash one-liner intends to build a new library from existing .o files." (This sentence, with absolutely NO other explanation, accompanies an example of lorder(1).)

or

"This is an area where experience and informed courage count for much."

What good do these do to the reader who is trying to figure out what on EARTH a command does?

Options on commands, in a sense documentation, don't have much chance to indicate their meaning, since they're typically restricted to one letter. (Some day I intend to write a phony command page containing

SYNOPSIS cmd -[abcdefghijklmnopqrstuvwxyz] name ...

OPTIONS -a Use the 'a' option. etc.)

James Jones (ihuxl!jej)

----------------------------------------------------------------- gopher://quux.org/ conversion by John Goerzen <jgoerzen@complete.org> of http://communication.ucsd.edu/A-News/

This Usenet Oldnews Archive article may be copied and distributed freely, provided:

1. There is no money collected for the text(s) of the articles.

2. The following notice remains appended to each copy:

The Usenet Oldnews Archive: Compilation Copyright (C) 1981, 1996 Bruce Jones, Henry Spencer, David Wiseman.