Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP
Path: utzoo!linus!decvax!ittvax!dcdwest!sdcsvax!sdcrdcf!hplabs!hao!
denelcor!udenva!jkcohen
From: jkco...@udenva.UUCP
Newsgroups: net.general
Subject: Pointer to Critiques of 4.2 documentation
Message-ID: <254@udenva.UUCP>
Date: Tue, 21-Aug-84 20:03:28 EDT
Article-I.D.: udenva.254
Posted: Tue Aug 21 20:03:28 1984
Date-Received: Thu, 30-Aug-84 09:47:18 EDT
Organization: U of Denver
Lines: 7
I have placed "crit1" and "crit2" in net.sources. The first is
a critique of the 4.2BSD Programmer's Manual, Vol. I, the latter a
critique of the first 2 sections of Vol. IIc. The first file is
an update of a previous version.
--
Jack Cohen
{nbires|denelcor|hao}!udenva!jkcohen
Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP
Path: utzoo!linus!decvax!ittvax!dcdwest!sdcsvax!sdcrdcf!hplabs!hao!
denelcor!udenva!jkcohen
From: jkco...@udenva.UUCP
Newsgroups: net.sources
Subject: Critique of 4.2BSD Doc, Vol I
Message-ID: <253@udenva.UUCP>
Date: Tue, 21-Aug-84 19:28:10 EDT
Article-I.D.: udenva.253
Posted: Tue Aug 21 19:28:10 1984
Date-Received: Thu, 30-Aug-84 09:46:44 EDT
Organization: U of Denver
Lines: 1719
CRITIQUE
of the
BERKELEY 4.2 UNIX DOCUMENTATION - Volume I
by
Jack K. Cohen
August 21, 1984
Copyright 1984 by Jack K. Cohen
Permission to copy all or part of this material is granted
provided that the copies are not made or distributed for
direct commercial advantage, the author's copyright notice
and the title of the article and its date appear, and notice
is given that copying is by permission of the author. To
copy otherwise, or to republish, requires a fee and/or
specific permission.
4.2BSD -1-
Introduction
This Critique emphasizes documentation problems rather
than 4.2BSD software problems. However, suggestions about
possible improvements to the latter are jabbed in here and
there. Critiques of various parts of Volume IIc will appear
separately.
My purpose is not to denigrate the work of the people
at Berkeley or at Bell (though I am not above teasing at
times). In fact, I hope the text shows my great admiration
for the marvelous applications engine provided by them.
Suffice it to say that I have used other operating systems
and read other documention!
Since I can report on only what I experience, be aware
that the effects recorded herein are descriptions of the
local University of Denver implementation of BSD4.2. In
cases where I know our implementation to be specialized
(e.g. effects caused by the local choices for Mailrc), I
will make that clear. I can only hope that my local readers
have caught any remaining instances of erroneously
attributing 'mis-documentation' instead of 'local
variation.'
For maximum enjoyment, I recommend having a hard copy
manual near at hand while reading these notes. You will
notice that there is lots of good stuff there in addition to
the nits picked by this Critique.
Being of impulsive cast, no doubt I have amply
displayed my ignorance below. I have never been troubled by
being wrong; life is too short to stand on ceremony. I
await your blunt refutations and explanations.
For several years, my first source of technical UNIX/C
information has been Andrew Burt, a graduate student at the
University of Denver. He has been kind enough to continue
tracking down puzzling items which cropped up during the
writing of these notes. I have also gotten valuable ideas
from several other students: Craig Ruff, Brian Sumner and
Matt Taylor. Also among the contributors to and critics of
these notes are various present and past members of the
University of Denver Computing Services including the 'Three
Bobs' (Shafer, Stocker and Ware), Carol Ward, and
especially, my first UNIX teacher, Howard Lasus. However,
none of my consultants are to be blamed for the remaining
errors in these notes; they rest (light-heartedly) with me.
I am now also in debt to those readers of the 'net' who
have provided corrections to an earlier edition of this
Critique. In many cases, I have acknowledged their
contributions below. In some cases, their comments have
J. K. Cohen
4.2BSD -2-
caused me to delete entries altogether, thus also removing
the opportunity to thank them in the text!
J. K. Cohen
4.2BSD -3-
Programmer's Manual: Section 1
adb On page 1 the last word - ADDRESSES - in the
DESCRIPTION should be enlarged to: "For further details
of address mapping see ADDRESSES." (The reference is to
a later section on page 5 of "man adb").
On page 4, the parenthetical in the description of $c -
(broken on the VAX) - is either opaque or incomplete.
What has happened to the adb tutorial? The only
remaining hint of its existence is in /usr/doc/run.
basename
Calling the shell example, 'base' and evoking it with
the suggested argument, 'base /usr/src/bin/cat.c',
produced:
0: No source file /usr/src/bin/cat.c
mv: cannot access a.out
Since /usr/src is a 'Permission denied' directory, I
could not investigate further. Since source code is
unlikely to be available to the vast majority of UNIX
users, a different example argument should be given.
cal See Kernighan and Pike's "The UNIX Programming
Environment" for a shell providing a friendly interface
to this utility.
calendar
Calendar service is erratic locally. If you want to
get daily reminders, you might start an infinite loop
of your own. Prepare a file, 'earlyam':
#! /bin/sh
# From K & P
# To start this infinite loop: earlyam
# To stop this process: edit the /usr/spool/at file, to cause an abort
file=/usr/tmp/cal.$$
/usr/bin/calendar >$file
if /bin/test -s $file
then
/usr/ucb/mail jkcohen <$file
fi
/bin/rm $file
/bin/echo earlyam | at 5am
and issue the command:
J. K. Cohen
4.2BSD -4-
% earlyam
to launch your service. The first time it comes right
back, but thereafter, the service sends you mail once a
day at 5 am. Remember, you have to prepare a 'calendar
file' as described on the manual page.
cat The command line "cat a b >a" mentioned in the BUG now
evokes the error message: "cat: input is output." But,
of course, the shell gets there first and file a is
still wiped out. Similarly for "cat a b >b". Even the
dreaded "cat * >>x" now does no harm to the system.
Cat with no arguments does not echo back to the
terminal at each newline. The manual says that when
the standard output is a terminal, the output is line
buffered. I take that to mean that each line input,
should be echoed after the NEWLINE. Since 'cat -u'
does echo back to the terminal, the problem is likely
that some undocumented buffering is going on.
Perhaps usages such as 'cat -vt file ...' should be
acceptable as per Kernighan and Ritchie, page 112-113.
In fact, this flexible acceptance of flag arguments
should be uniformly extended to all appropriate
commands.
cb It seems inconsistent with the vast majority of UNIX
software that this command does not accept command line
arguments.
cc I don't understand why some of the options accepted on
the command line by 'cc' are not discussed on the 'cc'
manual page, but instead are deferred to the 'ld' page.
In particular the -s option should be mentioned. There
may well be some distinction apparent to the expert,
but I vote for all the items which may be on the 'cc'
command line being discussed on the 'cc' manual page.
chfn Should be made more universally applicable.
compact
Compact violates the UNIX rule about not being
"chatty." This seems like a case of the author being so
proud of the algorithm's effectiveness that he must
brag each and every time about the degree of
compaction. Seems harmless? Well, suppose the system
is overloaded, so just before logout you go:
nohup compact file1 file2 file2 &
and log out. Next login, you find the files:
J. K. Cohen
4.2BSD -5-
file1 file1.C file2 file3
In addition to the "strange" failure of file2 and file3
to get compacted, the file1.C which looks like it is
the compaction of file1, really will not be recognized
by 'uncompact' as a compacted file! Thus if the naive
user deletes file1 before checking, he's in real
trouble.
Even online the messages can be a nuisance. If you go:
compact file1 file2 &
when file1 finishes compacting, the action stops until
you bring it into foreground to deliver its message.
Then the second compaction launches off in foreground,
so you have to stop it and stick it in background so
you can continue with your real foreground job. If you
still remember what that was.
The "RESTRICTION" of keeping files less than 13
characters, so as to have room for the .C is quaint.
In BSD4.2, less than 254 characters would be more like
it. Thus, I think we could safely delete the
RESTRICTION section.
Uncompact and ccat should be forgiving when you fail to
type the final .C.
In the previous release, I said:
Also, "compact" is a lot to type, why not some-
thing like "pack"?
But Lew Mullen points out that changing the name of
established commands is a poor idea. Well, it is
impossible to argue with that, so I'll retrench to
suggesting a link to a shorter name (as 'f' serves for
'finger' in 4.2BSD). (Lew also suggests that I learn
to type faster. This shows an all too penetrating
insight into my plight, my backspace key is worn down
to half the height of the other keys.)
csh
The header line:
#! /bin/csh
unambiguously specifies that a shell program is to be
executed in C shell. It also serves as an important
comment to the same effect. See execve(2).
J. K. Cohen
4.2BSD -6-
On page 14, "then" is omitted from the list of built-
ins.
On page 17, "term" and "user" are omitted from the list
of pre-defined and environmental variables.
The discussion of the "prompt" variable seems wrong to
me. If you want just the event number as a prompt,
then as per the discussion:
set prompt=!
does the job. But
set prompt=\!
also gives the same prompt, whereas the manual implies
that you will not get the event number in this case.
Similarly, the command
set prompt='\!: '
gives a prompt consisting of event number, colon,
space. Moreover, in the immortal phrasing from Bell:
set prompt='!: '
'does not have the effect intended.' One subtle point
in all this is that if ! is followed by a blank, tab,
newline, equal sign or left parenthesis then it loses
its history connotation. So, for example,
set prompt='! '
works just fine.
In the BUGS subsection, the alias facility is
deprecated vs. the use of Shell files. The user is
left uncertain whether something like 'alias del rm -i'
is a good or bad way to proceed. It's time someone
wrote an essay on what aliases and such cost in
response time (and yours truly just might throw caution
to the winds and attempt it). For now, a small tip:
things you use only in your login shell, should go in
.login instead of .cshrc. Even if (like aliases) they
"logically" seem associated with C shell.
Request: provide some way of turning off history's
echoing of the interpreted command. My personal need
for this concerns sending my serial printer a local
escape sequence to toggle it on. I send that sequence
after the command line, but before hitting the carriage
return. If I forget and use a history abbreviation in
J. K. Cohen
4.2BSD -7-
the command, then the first line of my hard copy shows
the interpreted command. I am sure others will have
other reasons why they'd like to suppress the echoing.
Request: Provide some version of 'set' which shows the
value of the variable. Maybe 'set var?' would be a
good choice. Of course, 'echo $var' works, but this
seems unnatural in this context.
Request: Extend 'repeat' to compound commands. The
shell program shown in the critique of the
"Introduction to the C Shell" below gives such an
extension.
checknr
This command should be extended to cover -mm too. And
also to include the 'checkeq' command's duties.
chsh Neither /bin/oldcsh nor /usr/new/csh exist, so I doubt
that they can be useful as possible second arguments to
'chsh.'
crypt
No command line arguments.
deroff
The macro package -me throws deroff into a tizzy. It's
fun to watch deroff on a file headed by '.so
/usr/lib/tmac/tmac.e'. For example, on the file:
.so /usr/lib/tmac/tmac.e
deroff gives:
You are using the wrong version of NROFF/TROFF!!
This macro package works only on the version seven
release of NROFF and TROFF.
which is not likely to provide the user with a clear
idea of what's going on. More fun is the input file:
.so /usr/lib/tmac/tmac.e
speling erroers
It is fun to run 'deroff' and 'spell'
on this file.
The effects are discussed in my
documentation critique.
which yields:
J. K. Cohen
4.2BSD -8-
Produced for your edification and enjoyment by:
Eric Allman
Electronics Research Laboratory
Berkeley.
VERSION First Release: Sept
See file for revision history
Documentation available.
This version has had comments stripped; unstripped version available.
You are using the wrong version NROFF/TROFF!!
This macro package works only the version seven
release NROFF and TROFF.
which is not more illuminating, but gives, in addition
to the above text, a nifty cursor display (not
reproduced here).
The inability of deroff to cope with such files means
that utilities such as 'spell' and 'diction' which rely
on deroff, cannot be used on this type of file (unless
it is nroffed first or unless the .so line is
temporarily removed). At the least, this defect should
be noted as a deroff BUG.
diction
It is time that the BUG was removed. That is, diction
should 'grok' -me (or a phasing out of -me should
begin). It is not nice to suck users into a macro
package for which tools like 'spell' and 'diction'
can't be used.
ed There are an incredible number of documentation errors
(see the note below for an explanation). The manual
describes an 'ex' like editor, but all we seem to have
is a barebones Bell 'ed' from the year one. A sampling
of the discrepencies follow.
The manual says that '%' abbreviates '1,$', but
%p
J. K. Cohen
4.2BSD -9-
produces an error message. Likewise, despite the
manual page, trailing delimiters are needed on the 's'
command. Especially serious is the false claim that
there is an 'u' undo command. The described command
'wq' is absent.
The manual description of q is incomplete: 'ed' flags
as an error a 'q' if a 'w' has not been done on a
changed file. Alas, the error message is just the
usual '?', which is likely to be too subtle to prevent
the user from issuing an immediate repeat of 'q' which,
as per standard Bell, is accepted. Good old 'silent
ed.'
There's not much point in going on. In case, the
documentation is later changed, I should note that my
manual page is labeled '3rd Berkeley Distribution 14
September 1979.' Interestingly enough, the manual page
I had from the 4.1BSD distribution had the same date
(3rd Berkeley Distribution 9/14/79). However, the
pages are not identical! The earlier page had
documented a -p option which provided a * prompt for
'ed' at the command level. Of course, that didn't work
either and the current distribution has 'fixed' that
bug by removing the option from the documentation.
In general, the only safe course is to expect nothing
more than what is described in the Kernighan tutorials.
It would be nice if 'ed' were jazzed up a bit along the
lines described in the documentation. Even though
'vi/ex' largely supercede 'ed', there are times on a
busy system when one does not want to wait for 'vi' to
start up.
Note on ed manual page
Mark Horton has been kind enough to explain how the
wrong manual page got released. It seems that before
the 3rd distribution, he spent some time at Bell and
wrote the jazzed up 'ed' (including the prompt option).
Expecting Bell to permit this code to be distributed,
the manual page was written for the new 'ed.'
Unfortunately, just before distribution time, Bell
decided against allowing the upgrade. The documentors
have never caught up with this sad fact of life.
error
This is a marvelous command for the reasonably
sophisticated user. A word of advice about using the
-v option: be sure to redirect standard output to a
file, because if vi starts up fast, the errors which
are written to standard output will vanish too quickly
to read before the screen clears. Note that even the
J. K. Cohen
4.2BSD -10-
'floodgate' effect noted under BUGS is not all that
serious a drawback: the inserts made by 'error' are so
distinctive that they can be eradicated by a single
global editor command.
ex Appending to a line and inserting at the beginning of a
line are such common operations that vi's 'A', 'I'
should be added to the 'ex' command set (one does get
trapped on a teletype terminal once in awhile).
The BUG entry concerning the inability to scan ignoring
case should be deleted, since the ex option 'ic' solves
that problem.
explain
This page is a repeat of the 'diction' page. But I am
not complaining. It's really frustrating to look up
'checkeq' and not find it, etc.
expr The last example is a little tough on the eyes. But I
tried it and got the error messages 'Variable syntax'
(csh) and 'syntax error' (sh). Maybe I screwed
something up. My 'csh' attempt was:
set x=/a/b/c
expr $x: '.*/\(.*\)' '|' $x
while my 'sh' attempt was:
x=/a/b/c
expr $x: '.*/\(.*\)' '|' $x
Someday someone should write a supplement explaining
these convoluted examples concocted by the 'Boys from
Bell.'
eyacc
The word 'old' in the first sentence seems to
contradict the same word in the last sentence. If this
version is an improvement over yacc, it should be
called 'yacc'. Otherwise, clearer guidelines are
needed as to when to use which.
f77 The subheading -o is missing.
find The bug cited is an understatement. It took me a month
to figure out how to find and print the files in my
subdirectories which matched a regular expression. To
alleviate the pain, why not give half a dozen simple
examples?
finger
The initial letter, 'f', is a valid abbreviation.
J. K. Cohen
4.2BSD -11-
gprof
Doesn't work locally because this program needs to
access /dev/kmem which has been made private to protect
the password buffer! We now know that a better
solution is to change /dev/mem, /dev/kmem, /dev/kUmem
and dev/drum to mode 0640, owned by 'root', with a
special group such as 'bin'. Then change the group
owner of the programs (gprof, iostat, sysline, ...)
that access these special devices to the special group.
Finally, make those programs setgid (mode 2755), so
they will read from the kernel. (Thank you to Chris
Torek and Jon Biggar for describing this 'fix'. Also
thanks to Mike Kupfer for pointing out that 'gprof'
needs to access kmem.)
grep The command 'grep \\ filename' does not fail
gracefully. At least that's what the Bell Lab
documenters would say. In the interest of the system,
I'll be explicit about what it does:
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
RE botch
^C
However, egrep handles this error in fine style and, of
course, it is not an error for fgrep.
Is there a way to get fgrep to search for multiple
strings without using the -f file option?
indent
What is the relation of this program to 'cb'?
iostat
Fails locally because of the /dev/kmem problem here,
see above discussion of 'gprof'.
learn
Attention: 'learn vi' is available locally. If it's
any good this should be one of the most valuable things
on the system.
J. K. Cohen
4.2BSD -12-
ln Compacting or uncompacting breaks links (quasi-bug).
lock Not available locally.
look My first reaction was: "Do we need this, if we have
'grep'?" On second glance, I noticed that the default
file was the spelling dictionary! This command allows
one to get correct spellings by searching through the
dictionary's list of words which begin with the desired
initial string. Why not spend a moment on this short
manual page, to explain this use of 'look'? Note that
homespun shells like:
#! /bin/sh
# lookup - check spelling dictionary for pattern
# Usage: lookup 'pattern'
/usr/bin/egrep $1 /usr/dict/words
while more general, do not take advantage of the
sorted, one word to a line, structure of the dictionary
(after "lookup '^aa'", there is a long pause while the
entire dictionary is searched, "look aa" terminates
promptly when the "aa's" end).
ls The option -A is not explained. It means the same as
-a, but omits the always present . and .. directories.
(Thank you to Percy Irani for this one.)
The discussion of permissions for directories is
inadequate. Instead of the vague word 'search' in
connection with the x permission for directories, why
not say:
r gives permission to 'ls' the directory;
w gives permission to create files in the directory;
x gives permission to 'cd' to the directory and to use
(e.g., 'cat' or execute) files whose names we know in
the directory.
Comment: Despite the claims of an over-abundance of
options, this version is inflexible. For example, one
cannot view the protections without seeing all the info
in -l. This has annoyed me enough to write a shell:
#! /bin/sh
# lsp - list files with protections
# Usage: lsp
/bin/ls -l | /bin/sed 's/ *.* / /' | exec /u/nosupport/p
J. K. Cohen
4.2BSD -13-
mail The local /usr/lib/Mail.rc is (5/6/84):
set append dot save
these three options mean:
(1) new mail is appended (the default is first in last out)
(2) a line consisting of just a '.' signals that you wish
to launch your completed message (the default is ^D; if
you like dot, you might also like 'ignoreeof').
(3) letters killed by two breaks are saved in ~/dead.letter
The ~b escape is not documented (it gives a 'bcc' -
'blind carbon copy').
The option 'quiet' has the undocumented effect of also
suppressing the current message number (unfortunately).
On the last line of page 5, 'the' is misspelled.
A possible BUG entry: ex/vi cannot be aimed at the
headers of a message you are typing. Given the content
of the first BUG entry, the option, 'debug' with its
confusing reference could be deleted.
Mail's help file still talks about /usr/mail (instead
of /usr/spool/mail) and .sendrc (instead of .mailrc).
A helpful usage hint. You can make mail customized by
putting mail commands in a login directory file, called
.mailrc. For an subject prompt and a cc prompt, enter
the lines:
set ask
set askcc
To suppress all those machine-generated mail headers,
put the following line in your .mailrc:
ignore Received Date From Message-Id Status
Since if you have 'vi', you have 'ex' via the 'Q'
command, you might consider specifying 'ed' as your
line editor within mail. Recall that 'vi' starts up
very slowly on a busy system and even the primitive
'ed' supplied by 4.2BSD (see above under 'ed') is often
adequate for mail messages. To obtain 'ed' when you ~e
and 'vi' when you ~v, place the following lines in your
J. K. Cohen
4.2BSD -14-
.mailrc file:
set EDITOR=/bin/ed
set VISUAL=/usr/ucb/vi
man The related commands 'apropos' and 'whatis' should be
mentioned.
Possible BUG. Is there a way to get the new subsection
introductions, such as intro(3S)?
mkdir
In the online manual, the default protection level
cited as 777 is actually (at least locally) 755.
The command:
mkdir
evokes the error message:
mkdir: arg count
The user who does not program in C will not find this
useful. Either a "Usage:" error message or an
interactive prompt for the directory name would be
preferable.
more This command needs an option to suppress its prompt
message. Yes, even on a CRT. Much local effort has
been expended in writing shells and C programs to avoid
having this prompt mess up hardcopy being output on
slaved serial printers.
The underlining done by "more" is often erratic.
Sometimes it extends to the end of the line when it
should not.
When using "more" and advancing to a new page by
hitting the space bar, the visual attribute of the
terminal you are using will change. In mail if you
type ~v it will do the same thing.
msgs Is currently off-limits locally (Permission denied).
pr It would be helpful to have options to set left margin
and the top margin. Also it would be useful to get
paginated output without a heading.
prof Sometimes 'mon.out' is not produced. I have hard copy
examples of a 'cc -p file.c' command, followed by a
'prof' which yielded:
J. K. Cohen
4.2BSD -15-
mon.out: No such file or directory
whereas some time later the same command sequence
worked fine. In both cases, 'a.out' was produced and
functioned normally. This certainly smells like a
local or a personal problem, but I report it in case
others have had the same experience.
The 'SEE ALSO' should reference 'gprof.'
ps Needs an option to suppress the header line.
ratfor
Should reference 'RATFOR A Preprocessor for a Rational
Fortran' by Brian W. Kernighan (in /usr/doc).
refer
In the description of -a, the letter following -a
should be 'n' instead of 'r.'
In the description of -f I think the intent is to set
the initial footnote number, but this is not clear from
the text.
Hooray! This revision gives an example. It is a good
example. It's contents belong in 'SEE ALSO.'
I suspect -me will drive "refer" as insane as "deroff",
"style", etc.
rev Give some examples of when this command would serve a
useful purpose.
rmdir
Again this is a duplicate of another manual page (rm)
and again this is not a complaint.
script
If you try "script", you get the following error
message:
%script
out of pty's
terminated
sed Should reference the manual in /usr/doc. Possibly (in
the future), also Kernighan and Pike for a tutorial.
sh The 'new' comment symbol, '#', is not mentioned. I am
not familiar enough with the history of Bourne shell
development to be able to tell what else is missing.
If you are, be warned that the documentation is not up
J. K. Cohen
4.2BSD -16-
to the minute.
The header line:
#! /bin/sh
unambiguously specifies that a shell program is to be
executed in Bourne shell. It also serves as an
important comment to the same effect. See execve(2).
Should reference the tutorial in /usr/doc. And
definitely (in the future) Kernighan and Pike as the
place to learn Bourne Shell programming.
spell
Here we are, back at Murray Hill, trying to get laughs
from cute examples. The little terminal sequence near
the bottom of the page creates 56 blocks of hashed
dictionary in the user's directory. Most systems can't
tolerate every novice maintaining their own 56 block
dictionary. Besides, following the method shown, you
wipe out out 'myhist' each time you add a new word.
Thus your 56 block dictionary would perpetually differ
from the system's by only one word. Finally, while the
association of 'hookey' with the filename, 'huckfinn',
may be obvious when one is composedly reading through
the manual, it may be totally opaque when one is
harried. Below, I shall show a first cut at a shell
program (following an example in Bourne's 'The UNIX
System') which employs an auxiliary personal spelling
list whose entries are not to be flagged as
misspellings.
The discussion of -d, -s, -h, will have to be greatly
expanded before this reader will understand it. For a
moment, I thought that -d provided an easy way to
maintain an exception list. But
spellin <myhist >myhist.hash
seems to create an alternate hashed spelling list (56
blocks, of course), not an auxiliary list. What is
needed is an option to specify a small extra list of
exceptions (hashed or not) which are NOT to be flagged
as spelling errors. If we demand that the list be in a
sorted, one word per line file, then the following C
shell program accomplishes this:
#! /bin/sh
# Usage: sp [-eexceptionlist] [-spelloptions] filename ...
# spell command with exception list
# NOTE: The exception list is assumed to be sorted:
# sort -o exclist exclist
J. K. Cohen
4.2BSD -17-
# NOTE to other users: Change the defaultlist below (yours might
# contain the names of you and yours, etc.)
# Caveat: Revise to ccat a compacted exception list if it's large.
cmd=`/usr/bin/basename $0`
typos=/usr/tmp/$$.dict
case $# in
0) echo Usage: $cmd [-eexclist] [-spelloptions] files 1>&2; exit 1
esac
defaultlist=/u/mathf/jkcohen/Wds/words # CHANGE THIS!
for i
do
case $i in
-e*) # User supplied exception list.
exceptions=`/bin/echo $i | /bin/sed 's/^-e//'`
;;
-*) # Collect user-supplied spell options
option="$option $i"
;;
*) # Collect filenames
files="$files $i"
;;
esac
done
exceptions=${exceptions-$defaultlist}
trap '/bin/rm $typos' 0 1 2 15
/usr/bin/spell $option $files >$typos
# spell sorts with -f option; but comm demands ASCII collating sequence!
/usr/bin/sort -o $typos $typos
/usr/bin/comm -23 $typos $exceptions
exit 0
The inclusion of .so lines such as '.so
/usr/lib/tmac/tmac.s' in your text utterly defeats
'spell.' Here is the story for our two most commonly
used nroff macro systems. For 'tmac.e', you do not get
the spelling errors. For 'tmac.s', you get the
spelling errors, but also get 107 two letter nroff-type
commands:
J. K. Cohen
4.2BSD -18-
AB
AE
AI
AJ
AU
BD
BG
bp
br
BT
.
.
.
The 'SEE ALSO' for 'spell' should reference 'look.'
struct
When I go:
struct prog.f
or
struct <prog.f
I get:
trap: Command not found
I looked, and 'struct' is a shell file from Berkeley.
My favorite guru points out that UCB added a header
saying that UCB wrote it. The header line is a comment
line. You can tell because it begins with a #. Alas,
there is an archaic convention that if the first line
of a shell file begins with a # line, then the file is
handed over to the C shell interpreter. The problem is
that the shell is actually a Bourne script! The
solution is either to delete the header line or use the
modern convention of first line beginning with '#!
/bin/sh.' (The system is smart enough to look past the
initial '#' to see if '!' is the next character; thus
both the archaic and the modern convention live on
together.)
stty Section 39 in Volume IIc, 'Bug Fixes and changes',
gives different defaults for erase, kill and interrupt
characters.
style
The BUG should be removed to the extent of dealing with
-me. Alternatively, -me should be withdrawn.
J. K. Cohen
4.2BSD -19-
sysline
This command fails locally because it needs /dev/kmem,
see discussion of 'gprof' above.
su Section 39 in Volume IIc, 'Bug Fixes and changes',
gives a new option, -f, which is omitted here.
Similarly, the extra arguments extension is not
discussed here.
tabs The BUG should be explained in greater detail: Why?
How?
talk Talk doesn't work here. According to a local expert:
'undoubtedly something to do with /etc/hosts not having
udenva listed in it.' ('udenva' is our system name.)
tbl There is an nroff mistake in the 'tbl' page! It causes
a missing line in the description and is due to a . at
the beginning of the line which was not protected by
the \& escape. The cute thing is that 'checknr' would
have found this error, because the line begins with .TS
and had no .TE to match it. Now you and I forget to
run 'spell' and 'checknr', but not the pros. Not much.
Recently, I was looking at a 'brand X' derivative of
4.2BSD and the ms(7) manual page similarly left out a
raft of \&'s and most of the first manual page was
omitted after nroffing. Your online manual may be
fixed, but in case not, here is the correct description
(underlining omitted):
Tbl is a preprocessor for formatting tables for
nroff or troff(1). The input files are copied
to the standard output, except for lines
between .TS and .TE command lines, which are
assumed to describe tables and are reformatted.
Details are given in the tbl(1) reference manu-
al.
tee Here is this big empty space (on the manual page). I
have an idea: let's use some of it to give examples.
time You may think that /bin/time is anachronistic, but
think about how you would get the effect of the
following shell using the C shell's built-in 'time'
command.
J. K. Cohen
4.2BSD -20-
#! /bin/sh
# cpu - put timing data into the file "timedata" (and throw output away).
# Usage: cpu command
file=timedata
/bin/echo -n $*: >>$file
/bin/time $* 1>/dev/null 2>>$file
tip The next to the last word on the last page should be
'pared' not 'paired.'
This is generally an excellent manual page about a very
difficult subject, but a local user of 'tip' suggests
inclusion of additional information on how to get
auto-dialers to work with it.
tr On one occasion, I found the BUG to actually be a
useful feature. Once, after transferring a file, I
wound up with a file loaded with NULs. The command,
'tr <file >nicefile', was very useful (the version of
'vi' I had then simply did not like files with NULs;
probably the current version doesn't either).
tset The alias given on page 2 proved deadly when I inserted
it into my .cshrc (unless you are a UNIX adept, don't
play around with this - if you can't resist, remember
to make a backup copy of your '.cshrc', so you can get
this file restored without use of 'vi').
The option '-s' (still used in our local
/usr/skel/.login) is not documented.
Locally, you get reasonable terminal characteristics
without using 'tset.' (As an experiment, I moved my
.login to another name and logged in on a CRT. My
backspace key worked fine.)
ul The sentence describing the -i option contains the
mystifying phrase: 'underlining onto ...'
uucp Is there a relation between 'tip' and the 'uu'
commands?
users
The initial letter, 'u', is a valid abbreviation.
wall Should document effect of 'mesg' on this command.
write
The concept of 'write back' should be elucidated (i.e.
describe how you do that).
J. K. Cohen
4.2BSD -21-
yacc SEE ALSO should reference 'eyacc'.
yes The manual page should squeeze in an example or two.
J. K. Cohen
4.2BSD -22-
Programmer's Manual: Section 2
intro
Should tell us where to find the values of {PROC_MAX}
etc.
Again under 'File Access Permissions' we have only a
vague hint of what x permission for a directory implies
(see above ls(1) discussion). In the last paragraph on
page 6, the 'and' at the end of the first line should
be 'but' as in the next paragraph. However, both these
paragraphs could be simplified by removing their
opening clauses.
creat
Last word in NOTES is misspelled.
execve
Near the top of page 2, argv is described as an array,
but envp as a pointer to an array. Their descriptions
should be identical, since their declarations are
identical.
fcntl
Last item under F_DUPFD should refer to execve, not
exec (or section 3, not section 2).
There's an extra blank line before FAPPEND.
gethostid
RETURN VALUE and ERRORS sections are missing.
The hostid is not set on Eos.
gethostname
The hostname on Eos is 'udenva.'
getpriority
The file <sys/time.h> must also be included, without
it, the include file, <sys/resource.h>, evokes:
"/usr/include/sys/resource.h", line 21: unknown size
"/usr/include/sys/resource.h", line 22: unknown size
"/usr/include/sys/resource.h", line 39: unknown size
"/usr/include/sys/resource.h", line 39: unknown size
The defines shown are already in resource.h and should
not be given here.
J. K. Cohen
4.2BSD -23-
Programmer's Manual: Section 3
A request for a missing utility from a local C whiz: "Put
itoa() back in. Sprintf is a bit much for just converting
one integer."
bstring
The BUGS are respectively non-existent and inexcusable.
Bcmp cannot take its parameters 'backwards' from
strcmp, because bcmp is symmetric in its first two
arguments. Unlike strcmp, bcmp does not return <0 and
>0 when the strings differ. Bcmp only promises to
return 'non-zero' when the strings differ. On the
basis of a very small sample, bcmp seems to return the
length of the strings when they differ.
On the other hand, having bcopy take its parameters in
the opposite order from strcpy is the pits.
ctime
The function, time(2), referred to in the DESCRIPTION
is non-existent. There is a gettimeofday(2).
The function, time(3), referred to in the DESCRIPTION
is non-existent. There is an obsolescent time(3c).
Page 2 has lots of room for usage examples.
ctype
In the definition of isprint, I think the '(8)' is
superfluous.
directory
The include file, <sys/types.h>, should be in the
synopsis.
Give the returns from 'seekdir', 'rewinddir' and
'closedir' or, if none, state that the functions are
void.
The quantities, d_namlen, d_name mentioned in the
example, as well as others in 'struct direct' need to
be defined. Probably, the include file should be
cited.
execl
If the second sentence of the description is saying
that the details of execl, execv are given on the
manual page for execve(2), it lies.
I think the FILES entry would be clearer as: '/bin/sh,
or whatever shell is invoked when a command file is
found by execlp or execvp'
J. K. Cohen
4.2BSD -24-
getlogin
The description says the correct procedure to get a
login name involves a call to 'getpw.' However,
'getpw' is deemed 'obsolescent.' A call to such a
function doesn't sound 'correct' to me.
And 'getpw(3C)' is cited as having two arguments, not
one, as indicated here.
In the SEE ALSO, 'getpw(3)' is cited, but doesn't exist
(the correct reference is 'getpw(3C).'
malloc
In the last phrase on the page omit the apostrophe.
random
The SEE ALSO should refer to rand(3C) instead of
rand(3).
qsort(3F)
The NAME says 'quick sort' instead of 'quicker sort.'
Is this intentional, i.e., is this algorithm different
than qsort(3)?
syslog(3F)
The header line should have (3F) instead of (3).
getfsent(3X)
Why gratuitously make things harder by omitting the
comments in the copy of 'struct fstab'?
printf(3S)
In the second paragraph of the description, the phrase,
'the first argument', should be replaced by, 'the
format argument.'
In the bullet item about field width, discuss effect of
insufficient or missing field width (i.e. move the next
to the last sentence of the description here).
In fourth bullet item, omit the first comma.
The X conversion is not defined.
In the paragraph on 's' conversion, put a comma after
the word, 'missing.'
J. K. Cohen
4.2BSD -25-
Programmer's Manual: Sections 4-7
Not a chance your roving reporter can understand much of
this. I am even incompetent at the games!
intro(4)
The first entry in the SEE ALSO sets up an infinite
loop.
General comment on section 5: this would be the right place
to have a complete set of documented #include files.
disktab(5)
In the first sentence, 'date' should be 'data.'
termcap(5)
Last sentence of next to last paragraph doesn't parse
well.
aardvark(6)
Won't run on this release (see volume 2c, section 39).
boggle(6)
Attempts to invoke produce the message: 'can't open
/usr/games/bogdict.' This is truly a shame.
/usr/games/bogdict exists (mode 600) and is of very
healthy size, 256 blocks. Even /usr/dict/hlista is
only 56 blocks.
chase(6)
Won't run on this release (see volume 2c, section 39).
doctor(6)
When invoked, pauses for a long time and then says:
'Can't open file ./doctor' and dies.
me(7)
None of the writer aids that depend on deroff (like
'spell') work, if you include a '.so
/usr/lib/tmac/tmac.e' line in your file.
Nroffing with -me causes variable length pages. One
cure is to specify the -Tlpr option. Another is to
filter the output through 'col.' Both of these fixes
nullify the advanced capabilities of the printer.
J. K. Cohen
--
Jack Cohen
{nbires|denelcor|hao}!udenva!jkcohen
Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP
Path: utzoo!linus!decvax!ittvax!dcdwest!sdcsvax!sdcrdcf!hplabs!hao!
denelcor!udenva!jkcohen
From: jkco...@udenva.UUCP
Newsgroups: net.sources
Subject: Critique of 4.2BSD Doc, sec 39,40
Message-ID: <252@udenva.UUCP>
Date: Tue, 21-Aug-84 19:26:42 EDT
Article-I.D.: udenva.252
Posted: Tue Aug 21 19:26:42 1984
Date-Received: Thu, 30-Aug-84 09:43:53 EDT
Organization: U of Denver
Lines: 465
CRITIQUE
of the
BERKELEY 4.2 UNIX DOCUMENTATION - Volume IIc
Sections 39-40
by
Jack K. Cohen
August 21, 1984
Copyright 1984 by Jack K. Cohen
Permission to copy all or part of this material is granted
provided that the copies are not made or distributed for
direct commercial advantage, the author's copyright notice
and the title of the article and its date appear, and notice
is given that copying is by permission of the author. To
copy otherwise, or to republish, requires a fee and/or
specific permission.
4.2BSD -1-
Introduction
I am hoping to issue a set of mini-critiques of the
Programmer's Manual Volume IIc to supplement the Critique of
Volume I which was recently distributed. This first
installement covers the first two sections of Volume IIc.
There are many sections totally beyond my interests and
abilities, but in addition to sections 39 and 40 presented
here, I anticipate eventually covering at least sections 41,
43, 45, 53, 54, and 56.
J. K. Cohen
4.2BSD -2-
Bug Fixes and changes in 4.2BSD, section 39
csh In the third line, add the word, 'be', after the word,
'to.'
script
Last phrase should probably be 'at a terminal.'
sdb We are told that "it still lives on in/usr/src/old for
those with a personal attachment." However, if anyone
does have such an attachment, they are doomed to
unrequited love since /usr/src is a private directory.
stty The defaults mentioned here disagree with those given
on the manual page.
su Changes noted do not appear on manual page. I could
not get the extra argument business to work:
su myfriend 'ls /u/gsis/myfriend'
evoked:
ls /u/gsis/myfriend: File or directory not found
tail Need something after the word, 'similar.'
J. K. Cohen
4.2BSD -3-
An Introduction to the C Shell, section 40
p2. The mail example shows a visible EOT signal being sent
to the terminal, and the text claims the characters,
'EOT', are echoed by the mail program. However, these
characters do not really appear at the terminal.
It is stated that the uparrow character will be used to
represent the control key. This conflicts with other
documents in this volume and conflicts with internal
usage in this document. For on pages 14-16, we find
uparrow being used in the discussion of history to
represent the hat character.
Locally, you get reasonable terminal characteristics
without using 'tset'. In particular, the default is
that the backspace key works fine.
p3. The command 'ls -s' gives file sizes in terms of
kilobytes (1024 characters) instead of in terms of
blocks of 512 characters.
p4. Again, 'ls -s' is said to use 512 character blocks
instead of the actual 1024.
p7. The first complete sentence on this page ('There exists
...'), is confusing because the list at the end of this
lengthy beast uses ',' instead of 'or' as the delimiter
between cases. Making a list of cases would be yet a
better solution.
The local interrupt signal is 'break' (control-c) not
'del.'
p8. The example may mislead the novice into believing that
people can put files into his/her directories. Rest
easy, dear novice, your directories are default
protected against such intrusions both on this system
and on any professionally administered UNIX system.
Except for the system administrator (aka 'super user',
aka 'support'), no one can write in any of your
directories unless you take special action (see the
'chmod' command) to allow them to do so. Again a
visible EOT is shown.
p9. Again, a claim is made for the appearance of a visible
EOT.
Third sentence of second paragraph gives the shell
human attributes (it can be 'provoked', but apparently
only sometimes).
J. K. Cohen
4.2BSD -4-
After the example of using the command, 'more', as a
filter, we find the awkward phrase, 'more simple more'.
p11. The example of a typical .login could be made more
useful if here, or elsewhere, a more complete
explanation was given.
The method shown of setting the terminal
characteristics is archaic (e.g. the option -s is no
longer even documented in TSET(1)).
The 'msgs' command does not currently function here.
The if-then-endif structure shown at the end of the
.login fails if one (see CSH(1), page 16) puts:
set mail=(300 /usr/spool/mail/username)
or the like.
It is stated that the default 'mail check' interval is
5 minutes; it seems to be 10 minutes as stated in
CSH(1), page 16.
p14-15.
The commands 'num' and 'ssp' do not exist.
p14-16.
As noted above, uparrow (defined as control key) is
used when the hat character is meant.
p15. To make the alias examples intelligible, it should be
explained that !* is the history notation for all
arguments of the previous (i.e. unaliased) command and
similarly that !^ means the first argument (and while
we are at it that !$ means the last argument).
p17. In the first sentence of the last paragraph, the word
'background' is misspelled.
p19. Before first example, 'background' is misspelled again.
Why does the 'ls' command produce only one process
number (cf. same command and explanation thereof on
page 18)?
p23. This is scary, but despite the explicit note about the
\ inside the quotes, I found that I got exactly the
prompt whether or not I used the \. (cf. my comments
about the same issue under 'csh' in part I of this
Critique).
J. K. Cohen
4.2BSD -5-
The reference to the repeat command (which has limited
usefulness since it iterates only a simple command)
might well be supplemented with a scaled down (and
improved!) version of the following shell program:
#! /bin/csh
# Usage: loop ntimes cmd ...
# Repeat group of commands n times
# Note: The built-in, 'repeat' works only on simple cmds.
# Note: Quote cmds with args, eg., loop 2 "sleep 10" who
set c=$0
set c=$c:t
set N=$#argv
if ($N < 2) then
echo Usage $c ntimes cmd ...
exit(1)
endif
@ x = $1
shift
@ N--
while ($x)
@ i = 1
while ($i <= $N)
$argv[$i]
@ i++
end
@ x--
end
The discussion of setenv needs to be supplemented with
some discussion of what an 'environment' is.
p25ff.
There should be far more examples of shell programs to
illustrate the many items mentioned all too fleetingly
in this part of the tutorial.
p25. In 4.2BSD, it would be better to start csh files with
#! /bin/csh
instead of just an arbitrary comment line. In fact, if
the first line of the file is
#! /bin/sh
then despite the fact that the file begins with a #
line, it will be handled by the Bourne shell
interpreter.
J. K. Cohen
4.2BSD -6-
p26. Near the bottom of the page the wrong form of 'echo' is
cited, it should be:
echo -n 'yes or no? '
p27. At midpage the 'd' is omitted from 'replaced.'
p29. I had trouble using set n=$0:t in shell scripts. (so
the program would be able to 'know' its name for error
messages). I found that set n=$0, followed by set
n=$n:t worked, but I have no idea why!
p30. I advocate illustrating the structures shown; this is
supposed to be a tutorial.
p31. A comment should be added, explaining what the
'oldstring' is in the ed 's' command. Note that here
the uparrow is again used in the non- control key
sense.
Section 3.10 is too terse to be of any use. And then
one-third of it re-explains the archaic usage of # to
distinguish Bourne from C shells.
p37. In the last paragraph, 'messages' is misspelled.
J. K. Cohen
--
Jack Cohen
{nbires|denelcor|hao}!udenva!jkcohen