Forced Interaction, and YAUF (Yet Another Unix Flame)

[utzoo!decvax!ucbvax!ihnss!ihuxl!jej]

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)