- add margin when formatting w/ -Tascii

- update doc w/ reality
- grammar/punctuation fixes

Thanks Todd Miller, who provided feedback, fixed some buggy examples,
fixed some of my blunders, and sanity checked the diff (and ok'd it);

1 files changed, 42 insertions, 38 deletions

diff --git a/bin/csh/USD.doc/csh.1 b/bin/csh/USD.doc/csh.1
index 974475543a3..12acb8644be 100644
--- a/bin/csh/USD.doc/csh.1
+++ b/bin/csh/USD.doc/csh.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: csh.1,v 1.8 2004/03/18 09:37:25 jmc Exp $
+.\"	$OpenBSD: csh.1,v 1.9 2004/04/21 08:11:15 jmc Exp $
 .\"	$NetBSD: csh.1,v 1.3 1995/03/21 09:03:33 cgd Exp $
 .\"
 .\" Copyright (c) 1980, 1993
@@ -30,6 +30,10 @@
 .\"
 .\"	@(#)csh.1	8.1 (Berkeley) 6/8/93
 .\"
+.if n \{\
+.po 5n
+.ll 70n
+.\}
 .EH 'USD:4-%''An Introduction to the C shell'
 .OH 'An Introduction to the C shell''USD:4-%'
 .\".RP
@@ -106,7 +110,7 @@ features of the shell and is the definitive reference for questions
 about the shell.
 .PP
 Many words in this document are shown in
-.I italics.
+.I italics .
 These are important words;
 names of commands, and words which have special meaning in discussing
 the shell and \s-2UNIX\s0.
@@ -160,7 +164,7 @@ in the \s-2UNIX\s0 system consist of a list of strings or
 interpreted as a
 .I "command name"
 followed by
-.I arguments.
+.I arguments .
 Thus the command
 .DS
 mail bill
@@ -210,7 +214,7 @@ then echoed the characters `EOT' and transmitted our message.
 The characters `% ' were printed before and after the mail command
 by the shell to indicate that input was needed.
 .PP
-After typing the `% ' prompt the shell was reading command input from
+After typing the `% ' prompt, the shell was reading command input from
 our terminal.
 We typed a complete command `mail bill'.
 The shell then executed the
@@ -386,7 +390,7 @@ Metacharacters normally have effect only when the shell is reading
 our input.
 We need not worry about placing shell metacharacters in a letter
 we are sending via
-.I mail,
+.I mail ,
 or when we are typing in text or data to some other program.
 Note that the shell is only reading input when it has prompted with
 `% ' (although we can type our input even before it prompts).
@@ -428,7 +432,7 @@ We should note that if we just typed
 sort
 .DE
 then the sort program would sort lines from its
-.I "standard input."
+.I "standard input" .
 Since we did not
 .I redirect
 the standard input, it would sort lines as we typed them on the terminal
@@ -437,7 +441,7 @@ until we typed a ^D to indicate an end-of-file.
 A most useful capability is the ability to combine the standard output
 of one command with the standard input of another, i.e. to run the
 commands in a sequence known as a
-.I pipeline.
+.I pipeline .
 For instance the command
 .DS
 ls \-s
@@ -449,11 +453,10 @@ may wish to have this sorted by size rather than by name, which is
 the default way in which
 .I ls
 sorts.
-We could look at the many options of
+We can look at the many options of
 .I ls
-to see if there was an option to do this but would eventually discover
-that there is not.
-Instead we can use a couple of simple options of the
+to see if there was an option to do this,
+or instead we can use a couple of simple options of the
 .I sort
 command, combining it with
 .I ls
@@ -502,7 +505,7 @@ The notation introduced above is called the
 .I pipe
 mechanism.
 Commands separated by `\||\|' characters are connected together by the
-shell and the standard output of each is run into the standard input of the
+shell, and the standard output of each is run into the standard input of the
 next.
 The leftmost command in a pipeline will normally take its standard
 input from the terminal and the rightmost will place its standard
@@ -691,32 +694,32 @@ the
 directory of other users.
 This notation consists of the character `~' (tilde) followed by another user's
 login name.
-For instance the word `~bill' would map to the pathname `/usr/bill'
-if the home directory for `bill' was `/usr/bill'.
+For instance the word `~bill' would map to the pathname `/home/bill'
+if the home directory for `bill' was `/home/bill'.
 Since, on large systems, users may have login directories scattered over
 many different disk volumes with different prefix directory names,
 this notation provides a convenient way of accessing the files
 of other users.
 .PP
 A special case of this notation consists of a `~' alone, e.g. `~/mbox'.
-This notation is expanded by the shell into the file `mbox' in your
-.I home
-directory, i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB
+This notation is expanded by the shell into the file `mbox' in
+.I your
+home directory, i.e. into `/home/bill/mbox' for me on Ernie Co-vax, the UCB
 Computer Science Department VAX machine, where this document was prepared.
 This can be very useful if you have used
 .I cd
 to change to another directory and have found a file you wish to
 copy using
-.I cp.
+.I cp .
 If I give the command
 .DS
 cp thatfile ~
 .DE
 the shell will expand this command to
 .DS
-cp thatfile /usr/bill
+cp thatfile /home/bill
 .DE
-since my home directory is /usr/bill.
+since my home directory is /home/bill.
 .PP
 There also exists a mechanism using the characters `{' and `}' for
 abbreviating a set of words which have common parts but cannot
@@ -739,7 +742,7 @@ echo *
 will not echo the character `*'.
 It will either echo a sorted list of filenames in the
 current
-.I "working directory,"
+.I "working directory" ,
 or print the message `No match' if there are
 no files in the working directory.
 .PP
@@ -779,7 +782,7 @@ between `\'' characters.
 Terminating commands
 .PP
 When you are executing a command and the shell is
-waiting for it to complete there are several ways
+waiting for it to complete, there are several ways
 to force it to stop.
 For instance if you type the command
 .DS
@@ -796,11 +799,11 @@ to the
 command by typing ^C on your terminal.*
 .FS
 *On some older Unix systems the \s-2DEL\s0 or \s-2RUBOUT\s0 key
-has the same effect. "stty all" will tell you the INTR key value.
+has the same effect. "stty all" will tell you the `intr' key value.
 .FE
 Since
 .I cat
-does not take any precautions to avoid or otherwise handle this signal
+does not take any precautions to avoid or otherwise handle this signal,
 the
 \s-2INTERRUPT\s0
 will cause it to terminate.
@@ -820,7 +823,7 @@ Thus the
 .I mail
 program in the first example above was terminated when we typed a ^D
 which generates an end-of-file from the standard input.
-The shell also terminates when it gets an end-of-file printing `logout';
+The shell also terminates when it gets an end-of-file, printing `logout';
 \s-2UNIX\s0 then logs you off the system.
 Since this means that typing too many ^D's can accidentally log us off,
 the shell has a mechanism for preventing this.
@@ -860,9 +863,9 @@ Another possibility for stopping a command is to suspend its execution
 temporarily, with the possibility of continuing execution later.  This is
 done by sending a \s-2STOP\s0 signal via typing a ^Z.
 This signal causes all commands running on the terminal
-(usually one but more if a pipeline is executing) to become suspended.
+(usually one, but more if a pipeline is executing) to become suspended.
 The shell notices that the command(s) have been suspended, types
-`Stopped' and then prompts for a new command.
+`Suspended', and then prompts for a new command.
 The previously executing command has been suspended, but otherwise
 unaffected by the \s-2STOP\s0 signal.  Any other commands can be executed
 while the original command remains suspended.  The suspended command can
@@ -879,16 +882,17 @@ example of command suspension follows.
 % mail harold
 Someone just copied a big file into my directory and its name is
 ^Z
-Stopped
+Suspended
 % ls
 funnyfile
 prog.c
 prog.o
 % jobs
 .ta 1.75i
-[1]  + Stopped	mail harold
+[1]  + Suspended	mail harold
 % fg
 mail harold
+(continue)
 funnyfile. Do you know who did it?
 EOT
 %
@@ -897,7 +901,7 @@ EOT
 In this example someone was sending a message to Harold and forgot the
 name of the file he wanted to mention.  The mail command was suspended
 by typing ^Z.  When the shell noticed that the mail program was
-suspended, it typed `Stopped' and prompted for a new command.  Then the
+suspended, it typed `Suspended' and prompted for a new command.  Then the
 .I ls
 command was typed to find out the name of the file.  The
 .I jobs
@@ -916,13 +920,13 @@ signals.  More information on
 suspending jobs and controlling them is given in
 section 2.6.
 .PP
-If you write or run programs which are not fully debugged then it may
+If you write or run programs which are not fully debugged, then it may
 be necessary to stop them somewhat ungracefully.
 This can be done by sending them a \s-2QUIT\s0
 signal, sent by typing a ^\e.
 This will usually provoke the shell to produce a message like:
 .DS
-Quit (Core dumped)
+Quit (core dumped)
 .DE
 indicating that a file
 `core' has been created containing information about the running program's
@@ -949,9 +953,9 @@ more /etc/passwd
 .DE
 The
 .I more
-program pauses after each complete screen-full and types `\-\-More\-\-'
+program pauses after each complete screen-full and types `[filename] %',
 at which point you can hit a space to get another screen full, a return
-to get another line, a `?' to get some help on other commands, or a `q' to end the
+to get another line, an `h' to get some help on other commands, or a `q' to end the
 .I more
 program.  You can also use more as a filter, i.e.
 .DS
@@ -960,7 +964,7 @@ cat /etc/passwd | more
 works just like the more simple more command above.
 .PP
 For stopping output of commands not involving
-.I more
+.I more ,
 you can use the
 ^S key to stop the typeout.  The typeout will resume when you
 hit ^Q or any other key, but ^Q is normally used because
@@ -989,16 +993,16 @@ shell before you go any further.
 To try it you can log in to \s-2UNIX\s0 and type the following
 command to the system:
 .DS
-chsh myname /bin/csh
+chsh -s /bin/csh myname
 .DE
 Here `myname' should be replaced by the name you typed to
 the system prompt of `login:' to get onto the system.
-Thus I would use `chsh bill /bin/csh'.
+Thus I would use `chsh -s /bin/csh bill'.
 .B
 You only have to do this once; it takes effect at next login.
 .R
 You are now ready to try using
-.I csh.
+.I csh .
 .PP
 Before you do the `chsh' command, the shell you are using when
 you log into the system is `/bin/sh'.