From uucp Fri Aug 14 11:55:22 1981 remote from pur-ee
NAihuxl.103
Nfa.unix-wizards
Npur-ee!cincy!duke!decvax!ucbvax!ihnss!ihuxl!jej
NThu Aug 13 20:19:50 1981
NForced Interaction, and YAUF (Yet Another Unix Flame)
NSubject: program interface to mail-like commands, Unix documentation
N
NI've run into a problem of how to automate commands that, to quote
NRitchie, "force interaction on the user whether it is wanted or not:"
Nthe primordial example is mail.
N
NIt is not clear how one could write a program that would issue the
Ncorrect commands to mail to do a particular filtering, such as "save
Nall mail from John Doe, and delete the rest after printing it offline."
Nmail expects standard input to direct it, based on what it itself has
Noutput.
N
NAny notions of a technique for writing such programs?
N
N----------------------------------------
N
NThe item about the Unix user interface was very good--one item
Nthat the author left out, though, was Unix documentation.
N
NMost notorious, I think, are the multitude of manual pages which
Nsay about the error messages that they are "self-explanatory."
NI believe that this must mean that the author intends them to be
Nmeaningful to himself.
N
NExamples:
N
N1. run-time error messages from C programs--these are QUITE machine
N	dependent; rather embarassingly so for an OS based on C as
N	Unix is, one would think.
N2. C compiler error messages, which describe every syntax error as
N	"syntax error," which may be enough for Dennis Ritchie, but
N	not for mere mortals. Another worthless error message is
N	that which describes the error in terms of compiler internals.
N	What does that have to do with the constructs the user knows?
N
NAlso quite helpful are the error codes one gets from make(1), such as
N"Error code 100".
N
NManual pages are frequently vague and casual: I recall the times when
NI had to try VERY hard to persuade someone that egrep(1) should treat
N'$' as just another character when it is not at the end of a regular
Nexpression, and in another case, that ed(1) permitted nested escaped
Nparentheses in regular expressions. Formal specifications of options
Nand accepted commands may not be useful to some readers, but they cer-
Ntainly are more useful to those who CAN understand them than vague
NEnglish prose.
N
N"Casualness" at times degenerates into flippancy or display of the
Nauthor's self-estimated cleverness: e.g.
N
N	"This brash one-liner intends to build a new library from
N	existing .o files." (This sentence, with absolutely NO other
N	explanation, accompanies an example of lorder(1).)
N
Nor
N
N	"This is an area where experience and informed courage
N	count for much."
N
NWhat good do these do to the reader who is trying to figure out
Nwhat on EARTH a command does?
N
NOptions on commands, in a sense documentation, don't have much chance
Nto indicate their meaning, since they're typically restricted to one
Nletter. (Some day I intend to write a phony command page containing
N
N	SYNOPSIS
N		cmd -[abcdefghijklmnopqrstuvwxyz] name ...
N
N	OPTIONS
N		-a	Use the 'a' option.
Netc.)
N
N				James Jones (ihuxl!jej)