summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormjf <mjf@NetBSD.org>2007-11-29 12:35:04 +0000
committermjf <mjf@NetBSD.org>2007-11-29 12:35:04 +0000
commit036409b85969342e92632932fa5fe96f1c329a05 (patch)
tree36901cc7a43fb092e69f647e4510d3060bef2737
parentd0f12a6ad912c78206ad0eaa199e3a5b63cb3ea0 (diff)
Commit Caldera licensed documentation from 4.4BSD. This was taken from the
OpenBSD tree. No objections on netbsd-docs.
-rw-r--r--distrib/sets/lists/misc/mi15
-rw-r--r--share/doc/smm/17.password/Makefile7
-rw-r--r--share/doc/smm/17.password/password.ms601
-rw-r--r--share/doc/smm/Makefile6
-rw-r--r--share/doc/usd/01.begin/Makefile7
-rw-r--r--share/doc/usd/01.begin/u.mac82
-rw-r--r--share/doc/usd/01.begin/u085
-rw-r--r--share/doc/usd/01.begin/u1638
-rw-r--r--share/doc/usd/01.begin/u21222
-rw-r--r--share/doc/usd/01.begin/u3357
-rw-r--r--share/doc/usd/01.begin/u4323
-rw-r--r--share/doc/usd/01.begin/u5219
-rw-r--r--share/doc/usd/17.msmacros/Makefile11
-rw-r--r--share/doc/usd/17.msmacros/fig1.pic45
-rw-r--r--share/doc/usd/17.msmacros/fig1.xfig46
-rw-r--r--share/doc/usd/17.msmacros/ms932
-rw-r--r--share/doc/usd/17.msmacros/refcard1289
-rw-r--r--share/doc/usd/17.msmacros/refcard.bad1253
-rw-r--r--share/doc/usd/Makefile8
19 files changed, 7138 insertions, 8 deletions
diff --git a/distrib/sets/lists/misc/mi b/distrib/sets/lists/misc/mi
index 5a8bdc0e5e3..6173286ecdb 100644
--- a/distrib/sets/lists/misc/mi
+++ b/distrib/sets/lists/misc/mi
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.148 2007/11/12 15:04:02 jmmv Exp $
+# $NetBSD: mi,v 1.149 2007/11/29 12:35:04 mjf Exp $
./etc/mtree/set.misc misc-sys-root
./usr/share/dict/README misc-reference-share share
./usr/share/dict/american misc-reference-share share
@@ -538,6 +538,8 @@
./usr/share/doc/smm/11.timedop/timed.ms misc-smm-doc doc
./usr/share/doc/smm/12.timed/Makefile misc-smm-doc doc
./usr/share/doc/smm/12.timed/timed.ms misc-smm-doc doc
+./usr/share/doc/smm/17.password/Makefile misc-smm-doc doc
+./usr/share/doc/smm/17.password/password.ms misc-smm-doc doc
./usr/share/doc/smm/18.net/0.t misc-smm-doc doc
./usr/share/doc/smm/18.net/1.t misc-smm-doc doc
./usr/share/doc/smm/18.net/2.t misc-smm-doc doc
@@ -558,6 +560,14 @@
./usr/share/doc/smm/Makefile misc-smm-doc doc
./usr/share/doc/smm/Title misc-smm-doc doc
./usr/share/doc/usd/00.contents misc-usd-doc doc
+./usr/share/doc/usd/01.begin/Makefile misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u.mac misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u0 misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u1 misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u2 misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u3 misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u4 misc-usd-doc doc
+./usr/share/doc/usd/01.begin/u5 misc-usd-doc doc
./usr/share/doc/usd/04.csh/Makefile misc-usd-doc doc
./usr/share/doc/usd/04.csh/csh.1 misc-usd-doc doc
./usr/share/doc/usd/04.csh/csh.2 misc-usd-doc doc
@@ -598,6 +608,9 @@
./usr/share/doc/usd/13.viref/spell.ok misc-obsolete obsolete
./usr/share/doc/usd/13.viref/vi.cmd.roff misc-usd-doc doc
./usr/share/doc/usd/13.viref/vi.ref misc-usd-doc doc
+./usr/share/doc/usd/17.msmacros/Makefile misc-usd-doc doc
+./usr/share/doc/usd/17.msmacros/fig1.pic misc-usd-doc doc
+./usr/share/doc/usd/17.msmacros/ms
./usr/share/doc/usd/18.msdiffs/Makefile misc-usd-doc doc
./usr/share/doc/usd/18.msdiffs/ms.diffs misc-usd-doc doc
./usr/share/doc/usd/19.memacros/Makefile misc-usd-doc doc
diff --git a/share/doc/smm/17.password/Makefile b/share/doc/smm/17.password/Makefile
new file mode 100644
index 00000000000..6e280d40d47
--- /dev/null
+++ b/share/doc/smm/17.password/Makefile
@@ -0,0 +1,7 @@
+# $NetBSD: Makefile,v 1.1 2007/11/29 12:35:05 mjf Exp $
+
+DIR= smm/17.password
+SRCS= password.ms
+MACROS= -ms
+
+.include <bsd.doc.mk>
diff --git a/share/doc/smm/17.password/password.ms b/share/doc/smm/17.password/password.ms
new file mode 100644
index 00000000000..a454b331d1c
--- /dev/null
+++ b/share/doc/smm/17.password/password.ms
@@ -0,0 +1,601 @@
+.\" $NetBSD: password.ms,v 1.1 2007/11/29 12:35:05 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)password.ms 8.1 (Berkeley) 6/8/93
+.\"
+.\" tbl mm ^ eqn ^ troff -ms
+.if n \{\
+.po 5n
+.ll 70n
+.\}
+.EH 'SMM:17-%''Password Security: A Case History'
+.OH 'Password Security: A Case History''SMM:17-%'
+.EQ
+delim $$
+.EN
+.\".RP
+.\" TM 78-1271-5 39199 39199-11
+.ND April 3, 1978
+.TL
+Password Security:
+A Case History
+.\" .OK
+.\"Encryption
+.\"Computing
+.AU "MH 2C-524" 3878
+Robert Morris
+.AU "MH 2C-523" 2394
+Ken Thompson
+.AI
+AT&T Bell Laboratories
+Murray Hill, NJ
+.AB
+This paper describes the history of the design of the
+password security scheme on a remotely accessed time-sharing
+system.
+The present design was the result of countering
+observed attempts to penetrate the system.
+The result is a compromise between extreme security and
+ease of use.
+.AE
+.\" .CS 6 0 6 0 0 4
+.SH
+INTRODUCTION
+.PP
+Password security on the
+.UX
+time-sharing system [1] is provided by a
+collection of programs
+whose elaborate and strange design is the outgrowth of
+many years of experience with earlier versions.
+To help develop a secure system, we have had a continuing
+competition to devise new ways to
+attack the security of the system (the bad guy) and, at the same time, to
+devise new techniques to resist the new attacks (the good guy).
+This competition has been in the same vein as the
+competition of long standing between manufacturers of armor
+plate and those of armor-piercing shells.
+For this reason, the description that follows will
+trace the history of the password system rather than simply
+presenting the program in its current state.
+In this way, the reasons for the design will be made clearer,
+as the design cannot be understood without also
+understanding the potential attacks.
+.PP
+An underlying goal has been to provide password security
+at minimal inconvenience to the users of the system.
+For example, those who want to run a completely open
+system without passwords, or to have passwords only at the
+option of the individual users, are able to do so, while
+those who require all of their users to have passwords
+gain a high degree of security
+against penetration of the system by unauthorized
+users.
+.PP
+The password system must be able not only to prevent
+any access to the system by unauthorized users
+(i.e. prevent them from logging in at all),
+but it must also
+prevent users who are already logged in from doing
+things that they are not authorized to do.
+The so called ``super-user'' password, for example, is especially
+critical because the super-user has all sorts of
+permissions and has essentially unlimited access to
+all system resources.
+.PP
+Password security is of course only one component of
+overall system security, but it is an essential component.
+Experience has shown that attempts to penetrate
+remote-access systems have been astonishingly
+sophisticated.
+.PP
+Remote-access systems are peculiarly vulnerable to
+penetration by outsiders as there are threats at the
+remote terminal, along the communications link, as well
+as at the computer itself.
+Although the security of a password encryption algorithm
+is an interesting intellectual and mathematical problem,
+it is only one tiny facet of a very large problem.
+In practice, physical security of the computer, communications
+security of the communications link, and physical control
+of the computer itself loom as far more important issues.
+Perhaps most important of all is control over the actions
+of ex-employees, since they are not under any direct control
+and they may have intimate
+knowledge about the system, its resources, and
+methods of access.
+Good system security involves realistic
+evaluation of the risks not only of deliberate
+attacks but also of casual unauthorized access
+and accidental disclosure.
+.SH
+PROLOGUE
+.PP
+The UNIX system was first implemented with a password file that contained
+the actual passwords of all the users, and for that reason
+the password file had to
+be heavily protected against being either read or written.
+Although historically, this had been the technique used
+for remote-access systems,
+it was completely unsatisfactory for several reasons.
+.PP
+The technique is excessively vulnerable to lapses in
+security.
+Temporary loss of protection can occur when
+the password file is being edited or otherwise modified.
+There is no way to prevent the making of copies by
+privileged users.
+Experience with several earlier remote-access systems
+showed that such lapses occur with frightening frequency.
+Perhaps the most memorable such occasion occurred
+in the early 60's when
+a system administrator on the CTSS system at MIT
+was editing the
+password file and another system administrator was editing
+the daily message that is printed on everyone's terminal
+on login.
+Due to a software design error, the temporary editor files
+of the two users were interchanged and thus, for a time, the password
+file was printed on every terminal when it was logged in.
+.PP
+Once such a lapse in security has been discovered, everyone's
+password must be changed, usually simultaneously, at a considerable
+administrative cost.
+This is not a great matter, but
+far more serious is the high probability of such lapses
+going unnoticed by the system administrators.
+.PP
+Security against unauthorized disclosure of the passwords was,
+in the last analysis, impossible with this system because,
+for example, if the
+contents of the file system are put on to magnetic tape for
+backup, as they must be, then anyone who has physical
+access to the tape
+can read anything on it with no restriction.
+.PP
+Many programs must get information of various kinds
+about the users of the system, and these programs in general
+should have no special permission to read the password file.
+The information which should have been in the password file actually was
+distributed (or replicated) into a number of files, all of
+which had to be updated whenever a user was added to or
+dropped from the system.
+.SH
+THE FIRST SCHEME
+.PP
+The obvious solution is to arrange that the passwords not
+appear in the system at all, and it is not difficult to decide
+that this can be done by encrypting each user's password,
+putting only the encrypted form in the password file, and
+throwing away his original password (the one that
+he typed in).
+When the user later tries to log in to the system, the password
+that he types is encrypted and compared with the encrypted
+version in the password file.
+If the two match, his login attempt is accepted.
+Such a scheme was first described
+in [3, p.91ff.].
+It also seemed advisable to devise
+a system in which neither the password file nor the
+password program itself needed to be
+protected against being read by anyone.
+.PP
+All that was needed to implement these ideas
+was to find a means of encryption that was very difficult
+to invert, even when the encryption program
+is available.
+Most of the standard encryption methods used (in the past)
+for encryption of messages are rather easy to invert.
+A convenient and rather good encryption program happened
+to exist on the system at the time; it simulated the
+M-209 cipher machine [4]
+used by the U.S. Army during World War II.
+It turned out that the M-209 program was usable, but with
+a given key, the ciphers produced by this program are
+trivial to invert.
+It is a much more difficult matter to find out the key
+given the cleartext input and the enciphered output of the program.
+Therefore,
+the password was used not as the text to be encrypted but as the
+key, and a constant was encrypted using this key.
+The encrypted result was entered into the password file.
+.SH
+ATTACKS ON THE FIRST APPROACH
+.PP
+Suppose that the bad guy has available
+the text of the password encryption program and
+the complete password file.
+Suppose also that he has substantial computing
+capacity at his disposal.
+.PP
+One obvious approach to penetrating the password
+mechanism is to attempt to find a general method of inverting
+the encryption algorithm.
+Very possibly this can be done, but few
+successful results
+have come to light, despite substantial efforts extending
+over a period of more than five years.
+The results have not proved to be very useful
+in penetrating systems.
+.PP
+Another approach to penetration is simply to keep trying
+potential
+passwords until one succeeds; this is a general cryptanalytic
+approach called
+.I
+key search.
+.R
+Human beings being what they are, there is a strong tendency
+for people to choose relatively short and simple passwords that
+they can remember.
+Given free choice, most people will choose their passwords
+from a restricted character set (e.g. all lower-case letters),
+and will often choose words or names.
+This human habit makes the key search job a great deal easier.
+.PP
+The critical factor involved in key search is the amount of
+time needed to encrypt a potential password and to check the result
+against an entry in the password file.
+The running time to encrypt one trial password and check
+the result turned out to be approximately 1.25 milliseconds on
+a PDP-11/70 when the encryption algorithm was recoded for
+maximum speed.
+It is takes essentially no more time to test the encrypted
+trial password against all the passwords in
+an entire password file, or for that matter, against
+any collection of encrypted passwords, perhaps collected
+from many installations.
+.PP
+If we want to check all passwords of length
+.I
+n
+.R
+that consist entirely of lower-case letters, the number
+of such passwords is $26 sup n$.
+If we suppose that the password consists of
+printable characters only, then the number of possible passwords
+is somewhat less than $95 sup n$.
+(The standard system ``character erase'' and ``line kill''
+characters are, for example, not prime
+candidates.)
+We can immediately estimate the running time of a program that
+will test every password of a given length with all of its
+characters chosen from some set of characters.
+The following table gives estimates of the running time
+required on a PDP-11/70
+to test all possible character strings of length $n$
+chosen from various sets of characters: namely, all lower-case
+letters, all lower-case letters plus digits,
+all alphanumeric characters, all 95 printable
+ASCII characters, and finally all 128 ASCII characters.
+.TS
+cccccc
+cccccc
+nnnnnn.
+ 26 lower-case 36 lower-case letters 62 alphanumeric 95 printable all 128 ASCII
+n letters and digits characters characters characters
+.sp .5
+1 30 msec. 40 msec. 80 msec. 120 msec. 160 msec.
+2 800 msec. 2 sec. 5 sec. 11 sec. 20 sec.
+3 22 sec. 58 sec. 5 min. 17 min. 43 min.
+4 10 min. 35 min. 5 hrs. 28 hrs. 93 hrs.
+5 4 hrs. 21 hrs. 318 hrs.
+6 107 hrs.
+.TE
+.LP
+One has to conclude that it is no great matter for someone with
+access to a PDP-11 to test all lower-case alphabetic strings up
+to length five
+and, given access to the machine for, say, several weekends, to test
+all such strings up to six characters in length.
+By using such a program against a collection of actual encrypted
+passwords, a substantial fraction of all the passwords will be
+found.
+.PP
+Another profitable approach for the bad guy is to use the word
+list from a dictionary or to use a list of names.
+For example, a large commercial dictionary contains typicallly about
+250,000 words; these words can be checked in about five minutes.
+Again, a noticeable fraction of any collection of passwords
+will be found.
+Improvements and extensions will be (and have been) found by
+a determined bad guy.
+Some ``good'' things to try are:
+.IP -
+The dictionary with the words spelled backwards.
+.IP -
+A list of first names (best obtained from some mailing list).
+Last names, street names, and city names also work well.
+.IP -
+The above with initial upper-case letters.
+.IP -
+All valid license plate numbers in your state.
+(This takes about five hours in New Jersey.)
+.IP -
+Room numbers, social security numbers, telephone numbers, and
+the like.
+.PP
+The authors have conducted experiments to try to determine
+typical users' habits in the choice of passwords when no
+constraint is put on their choice.
+The results were disappointing, except to the bad guy.
+In a collection of 3,289 passwords
+gathered from many users over a long period of time;
+.IP
+15 were a single ASCII character;
+.IP
+72 were strings of two ASCII characters;
+.IP
+464 were strings of three ASCII characters;
+.IP
+477 were string of four alphamerics;
+.IP
+706 were five letters, all upper-case or all lower-case;
+.IP
+605 were six letters, all lower-case.
+.LP
+An additional 492 passwords appeared in various available
+dictionaries, name lists, and the like.
+A total of 2,831, or 86% of this sample of passwords fell into one of
+these classes.
+.PP
+There was, of course, considerable overlap between the
+dictionary results and the character string searches.
+The dictionary search alone, which required only five
+minutes to run, produced about one third of the passwords.
+.PP
+Users could be urged (or forced) to use either longer passwords
+or passwords chosen from a larger character set, or the system
+could itself choose passwords for the users.
+.SH
+AN ANECDOTE
+.PP
+An entertaining and instructive example is
+the attempt made at one installation to force users to use less predictable
+passwords.
+The users did not choose their own passwords; the system supplied
+them.
+The supplied passwords were eight characters long and
+were taken from the character set consisting of
+lower-case letters and digits.
+They were generated by a pseudo-random number generator
+with only $2 sup 15$ starting values.
+The time required to search (again on a PDP-11/70) through
+all character strings of length 8 from a 36-character
+alphabet is 112 years.
+.PP
+Unfortunately, only $2 sup 15$ of them need be looked at,
+because that is the number of possible outputs of the random
+number generator.
+The bad guy did, in fact, generate and test each of these strings
+and found every one of the system-generated passwords using
+a total of only about one minute of machine time.
+.SH
+IMPROVEMENTS TO THE FIRST APPROACH
+.NH
+Slower Encryption
+.PP
+Obviously, the first algorithm used was far too fast.
+The announcement of the DES encryption algorithm [2]
+by the National Bureau of Standards
+was timely and fortunate.
+The DES is, by design, hard to invert, but equally valuable
+is the fact that it is extremely slow when implemented in
+software.
+The DES was implemented and used in the following way:
+The first eight characters of the user's password are
+used as a key for the DES; then the algorithm
+is used to encrypt a constant.
+Although this constant is zero at the moment, it is easily
+accessible and can be made installation-dependent.
+Then the DES algorithm is iterated 25 times and the
+resulting 64 bits are repacked to become a string of
+11 printable characters.
+.NH
+Less Predictable Passwords
+.PP
+The password entry program was modified so as to urge
+the user to use more obscure passwords.
+If the user enters an alphabetic password (all upper-case or
+all lower-case) shorter than six characters, or a
+password from a larger character set shorter than five
+characters, then the program asks him to enter a
+longer password.
+This further reduces the efficacy of key search.
+.PP
+These improvements make it exceedingly difficult to find
+any individual password.
+The user is warned of the risks and if he cooperates,
+he is very safe indeed.
+On the other hand, he is not prevented from using
+his spouse's name if he wants to.
+.NH
+Salted Passwords
+.PP
+The key search technique is still
+likely to turn up a few passwords when it is used
+on a large collection of passwords, and it seemed wise to make this
+task as difficult as possible.
+To this end, when a password is first entered, the password program
+obtains a 12-bit random number (by reading the real-time clock)
+and appends this to the password typed in by the user.
+The concatenated string is encrypted and both the
+12-bit random quantity (called the $salt$) and the 64-bit
+result of the encryption are entered into the password
+file.
+.PP
+When the user later logs in to the system, the 12-bit
+quantity is extracted from the password file and appended
+to the typed password.
+The encrypted result is required, as before, to be the same as the
+remaining 64 bits in the password file.
+This modification does not increase the task of finding
+any individual
+password,
+starting from scratch,
+but now the work of testing a given character string
+against a large collection of encrypted passwords has
+been multiplied by 4096 ($2 sup 12$).
+The reason for this is that there are 4096 encrypted
+versions of each password and one of them has been picked more
+or less at random by the system.
+.PP
+With this modification,
+it is likely that the bad guy can spend days of computer
+time trying to find a password on a system with hundreds
+of passwords, and find none at all.
+More important is the fact that it becomes impractical
+to prepare an encrypted dictionary in advance.
+Such an encrypted dictionary could be used to crack
+new passwords in milliseconds when they appear.
+.PP
+There is a (not inadvertent) side effect of this
+modification.
+It becomes nearly impossible to find out whether a
+person with passwords on two or more systems has used
+the same password on all of them,
+unless you already know that.
+.NH
+The Threat of the DES Chip
+.PP
+Chips to perform the DES encryption are already commercially
+available and they are very fast.
+The use of such a chip speeds up the process of password
+hunting by three orders of magnitude.
+To avert this possibility, one of the internal tables
+of the DES algorithm
+(in particular, the so-called E-table)
+is changed in a way that depends on the 12-bit random
+number.
+The E-table is inseparably wired into the DES chip,
+so that the commercial chip cannot be used.
+Obviously, the bad guy could have his own chip designed and
+built, but the cost would be unthinkable.
+.NH
+A Subtle Point
+.PP
+To login successfully on the UNIX system, it is necessary
+after dialing in to type a valid user name, and then the
+correct password for that user name.
+It is poor design to write the login command in such a way that it
+tells an interloper when he has typed in a invalid user name.
+The response to an invalid name should be identical to
+that for a valid name.
+.PP
+When the slow encryption algorithm was first implemented,
+the encryption was done only if the user name was valid,
+because otherwise there was no encrypted password to
+compare with the supplied password.
+The result was that the response was delayed
+by about one-half second if the name was valid, but was
+immediate if invalid.
+The bad guy could find out
+whether a particular user name was valid.
+The routine was modified to do the encryption in either
+case.
+.SH
+CONCLUSIONS
+.PP
+On the issue of password security, UNIX is probably
+better than most systems.
+The use of encrypted passwords appears reasonably
+secure in the absence of serious attention of experts
+in the field.
+.PP
+It is also worth some effort to conceal even the encrypted
+passwords.
+Some UNIX systems have instituted what is called an
+``external security code'' that must be typed when
+dialing into the system, but before logging in.
+If this code is changed periodically, then someone
+with an old password will likely be prevented from
+using it.
+.PP
+Whenever any security procedure is instituted that attempts
+to deny access to unauthorized persons, it is wise to
+keep a record of both successful and unsuccessful attempts
+to get at the secured resource.
+Just as an out-of-hours visitor to a computer center normally
+must not only identify himself, but a record is usually also kept of
+his entry.
+Just so, it is a wise precaution to make and keep a record
+of all attempts to log into a remote-access time-sharing
+system, and certainly all unsuccessful attempts.
+.PP
+Bad guys fall on a spectrum whose one end is someone with
+ordinary access to a system and whose goal is to find
+out a particular password (usually that of the super-user)
+and, at the other end, someone who wishes to collect as
+much password information as possible from as many systems
+as possible.
+Most of the work reported here serves to frustrate the latter type;
+our experience indicates that the former type of bad guy never
+was very successful.
+.PP
+We recognize that a time-sharing system must operate in a
+hostile environment.
+We did not attempt to hide the security aspects of the operating
+system, thereby playing the customary make-believe game in
+which weaknesses of the system are not discussed no matter
+how apparent.
+Rather we advertised the password algorithm and invited attack
+in the belief that this approach would minimize future trouble.
+The approach has been successful.
+.\" .SG MH-1271-RM/KT
+.SH
+References
+.IP [1]
+Ritchie, D.M. and Thompson, K.
+The UNIX Time-Sharing System.
+.I
+Comm. ACM
+.B
+17
+.R
+(July 1974),
+pp. 365-375.
+.IP [2]
+.I
+Proposed Federal Information Processing Data Encryption Standard.
+.R
+Federal Register (40FR12134), March 17, 1975
+.IP [3]
+Wilkes, M. V.
+.I
+Time-Sharing Computer Systems.
+.R
+American Elsevier,
+New York, (1968).
+.IP [4]
+U. S. Patent Number 2,089,603.
diff --git a/share/doc/smm/Makefile b/share/doc/smm/Makefile
index 3b166f63420..89b72f5dc75 100644
--- a/share/doc/smm/Makefile
+++ b/share/doc/smm/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.19 2004/01/11 16:11:52 lukem Exp $
+# $NetBSD: Makefile,v 1.20 2007/11/29 12:35:05 mjf Exp $
# from: @(#)Makefile 8.2 (Berkeley) 5/10/94
.include <bsd.own.mk>
@@ -10,13 +10,13 @@
# 02.config
# Missing from 4.4BSD-Lite:
-# 14.uucpimpl 15.uucpnet 16.security 17.password
+# 14.uucpimpl 15.uucpnet 16.security
BINDIR= /usr/share/doc/smm
.if ${MKDOC} != "no"
FILES= 00.contents Makefile Title
.endif
-SUBDIR= 01.setup 04.quotas 05.fastfs 06.nfs 18.net
+SUBDIR= 01.setup 04.quotas 05.fastfs 06.nfs 17.password 18.net
.if exists(03.fsck_ffs)
SUBDIR+= 03.fsck_ffs
.endif
diff --git a/share/doc/usd/01.begin/Makefile b/share/doc/usd/01.begin/Makefile
new file mode 100644
index 00000000000..5ce06a5f827
--- /dev/null
+++ b/share/doc/usd/01.begin/Makefile
@@ -0,0 +1,7 @@
+# $NetBSD: Makefile,v 1.1 2007/11/29 12:35:05 mjf Exp $
+
+DIR= usd/01.begin
+SRCS= u.mac u0 u1 u2 u3 u4 u5
+MACROS= -ms
+
+.include <bsd.doc.mk>
diff --git a/share/doc/usd/01.begin/u.mac b/share/doc/usd/01.begin/u.mac
new file mode 100644
index 00000000000..4ae318273ac
--- /dev/null
+++ b/share/doc/usd/01.begin/u.mac
@@ -0,0 +1,82 @@
+.\" $NetBSD: u.mac,v 1.1 2007/11/29 12:35:06 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u.mac 8.1 (Berkeley) 6/8/93
+.\"
+.tr |\(bv
+.de IT
+.if n .ul
+\%\&\\$3\f2\\$1\fR\&\\$2
+..
+.de UL
+.lg 0
+.if n .ul
+\%\&\\$3\f3\\$1\fR\&\\$2
+.lg
+..
+.de UC
+\\$3\s-1\\$1\s0\\$2
+..
+.de P1
+.DS I .4i
+.nf
+.lg 0
+.if n .ls 1
+.if n .ta 5 10 15 20 25 30 35 40 45 50 55 60
+.if t .ta .3i .6i .9i 1.2i 1.5i 1.8i
+.nr P \\n(.s
+.nr S \\n(.s+1
+.nr s \\n(.s-1
+.nr t 5*33u \" width in 9 point CW
+.if t .ta 1u*\\ntu 2u*\\ntu 3u*\\ntu 4u*\\ntu 5u*\\ntu 6u*\\ntu 7u*\\ntu 8u*\\ntu 9u*\\ntu 10u*\\ntu 11u*\\ntu 12u*\\ntu 13u*\\ntu 14u*\\ntu
+.ft 3
+.tr _\(ul
+.tr -\-
+.lg 0
+..
+.de P2
+.ps \\n(PS
+.vs \\n(VSp
+.nr P \\n(PS
+.nr S \\n(PS+1
+.nr s \\n(PS-1
+.ft R
+.if n .ls 2
+.fi
+.DE
+.tr --
+.tr ''
+.lg
+..
+.nr PI .2i
diff --git a/share/doc/usd/01.begin/u0 b/share/doc/usd/01.begin/u0
new file mode 100644
index 00000000000..218a3cc6eb5
--- /dev/null
+++ b/share/doc/usd/01.begin/u0
@@ -0,0 +1,85 @@
+.\" $NetBSD: u0,v 1.1 2007/11/29 12:35:06 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u0 8.1 (Berkeley) 6/8/93
+.\"
+.\" ...TM 78-1273-8
+.if n \{\
+.po 5n
+.ll 70n
+.\}
+.EH 'USD:1-%''UNIX For Beginners'
+.OH 'UNIX For Beginners''USD:1-%'
+.ND October 2, 1978
+.\" ...old TM -74-1273-18, October 29, 1974
+.\".RP
+.TL
+UNIX For Beginners \(em
+Second Edition
+.AU
+Brian W. Kernighan
+.AI
+.\" .MH
+.AU
+(Updated for 4.3BSD by Mark Seiden)
+.AB
+.PP
+This paper is meant to help
+new users get started on
+the
+.UX
+operating system.
+It includes:
+.IP "\ \(bu"
+basics needed for day-to-day use of the system \(em
+typing commands, correcting typing mistakes, logging in and out,
+mail, inter-terminal communication,
+the file system, printing files,
+redirecting I/O, pipes, and the shell.
+.IP "\ \(bu"
+document preparation \(em
+a brief discussion of the major formatting programs
+and macro packages,
+hints on preparing documents,
+and capsule descriptions of some supporting software.
+.IP "\ \(bu"
+.UC UNIX
+programming \(em
+using the editor, programming the shell, programming in C,
+other languages and tools.
+.IP "\ \(bu"
+An annotated
+.UC UNIX
+bibliography.
+.AE
diff --git a/share/doc/usd/01.begin/u1 b/share/doc/usd/01.begin/u1
new file mode 100644
index 00000000000..0e8d576ce8a
--- /dev/null
+++ b/share/doc/usd/01.begin/u1
@@ -0,0 +1,638 @@
+.\" $NetBSD: u1,v 1.1 2007/11/29 12:35:06 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u1 8.1 (Berkeley) 6/8/93
+.\"
+.nr PS 9
+.if t .nr VS 11
+.if n .ls 2
+.nr PI .25i
+.SH
+INTRODUCTION
+.PP
+From the user's point of view,
+the
+.UC UNIX
+operating system
+is easy
+to learn and use,
+and presents few of the usual impediments
+to getting the job done.
+It is hard, however, for the beginner
+to know where to start,
+and how to make the best use
+of the facilities available.
+The purpose of this introduction
+is to help new users
+get used to the main ideas of
+the
+.UC UNIX
+system
+and start making effective use of it quickly.
+.PP
+You should have a couple of other documents with you
+for easy reference as you read this one.
+The most important is
+.ul
+The
+.ul
+.UC UNIX
+.IT Programmer's
+.IT Manual \|;
+it's often easier to tell you to read about something
+in the manual
+than to repeat its contents here.
+The other useful document is
+.ul
+A Tutorial Introduction to the
+.ul
+.UC UNIX
+.ul
+Text Editor,
+which will tell you how to use the editor
+to get text \(em
+programs, data, documents \(em
+into the computer.
+.PP
+A word of warning:
+the
+.UC UNIX
+system
+has become quite popular,
+and there are several major variants
+in widespread use.
+Of course details also change with time.
+So although the basic structure of
+.UC UNIX
+and how to use it is common to all versions,
+there will certainly be a few things
+which are different on your system from
+what is described here.
+We have tried to minimize the problem,
+but be aware of it.
+In cases of doubt,
+this paper describes Version 7
+.UC UNIX .
+.PP
+This paper has five sections:
+.IP "\ \ 1."
+Getting Started:
+How to log in,
+how to type,
+what to do about mistakes in typing,
+how to log out.
+Some of this is dependent on which
+system
+you log into
+(phone numbers, for example)
+and what terminal you use,
+so this section must necessarily be supplemented
+by local information.
+.IP "\ \ 2."
+Day-to-day Use:
+Things you need every day to use
+the system
+effectively:
+generally useful commands;
+the file system.
+.IP "\ \ 3."
+Document Preparation:
+Preparing manu\%scripts is one of the most common uses
+for
+.UC UNIX
+systems.
+This section contains advice,
+but not
+extensive instructions on any
+of the formatting tools.
+.IP "\ \ 4."
+Writing Programs:
+.UC UNIX
+is an excellent system for developing programs.
+This section talks about some of the tools,
+but again is not a tutorial in any of the programming languages
+provided by the system.
+.IP "\ \ 5."
+A
+.UC UNIX
+Reading List.
+An annotated bibliography of
+documents that new users should be aware of.
+.SH
+I. GETTING STARTED
+.SH
+Logging In
+.PP
+You must have a
+.UC UNIX
+login name, which you can get from
+whoever administers your system.
+You also need to know the phone number,
+unless your system uses permanently connected terminals.
+The
+.UC UNIX
+system
+is capable of dealing with a wide variety of terminals:
+Terminet 300's; Execuport, TI and similar
+portables;
+video (CRT) terminals like the HP2640, etc.;
+high-priced graphics terminals like the Tektronix 4014;
+plotting terminals like those from GSI and DASI;
+and even the venerable
+Teletype in its various forms.
+But note:
+.UC UNIX
+is strongly oriented towards devices with
+.ul
+lower case.
+If your terminal produces only upper case (e.g., model 33 Teletype, some video and portable terminals),
+life will be so difficult that you should look for another
+terminal.
+.PP
+Be sure to set the switches appropriately on your device.
+Switches that might need to be adjusted include the speed,
+upper/lower case mode,
+full duplex, even parity, and any others
+that local wisdom advises.
+Establish a connection using whatever
+magic is needed for your terminal;
+this may involve dialing a telephone call or merely flipping a switch.
+In either case,
+.UC UNIX
+should type
+.UL login: '' ``
+at you.
+If it types garbage, you may be at the wrong speed;
+check the switches.
+If that fails,
+push the ``break'' or ``interrupt'' key a few times, slowly.
+If that fails to produce a login message, consult a guru.
+.PP
+When you get a
+.UL login:
+message,
+type your
+login name
+.ul
+in lower case.
+Follow it by a
+.UC RETURN ;
+the system will not do anything until you type a
+.UC RETURN .
+If a password is required,
+you will be asked for it,
+and (if possible)
+printing will be turned off while you type it.
+Don't forget
+.UC RETURN .
+.PP
+The culmination of your login efforts is a
+``prompt character,''
+a single character that indicates that
+the system
+is ready to accept commands from you.
+The prompt character is usually a
+dollar sign
+.UL $
+or a
+percent sign
+.UL % .
+(You may also get a message of the day just before the
+prompt character, or a notification that you have mail.)
+.SH
+Typing Commands
+.PP
+Once you've seen the prompt character, you can type commands,
+which are
+requests that
+the system
+do something.
+Try typing
+.P1
+date
+.P2
+followed by
+.UC RETURN.
+You should get back something like
+.P1
+Mon Jan 16 14:17:10 EST 1978
+.P2
+Don't forget the
+.UC RETURN
+after the command,
+or nothing will happen.
+If you think you're being ignored,
+type a
+.UC RETURN ;
+something should happen.
+.UC RETURN
+won't be mentioned
+again,
+but don't forget it \(em
+it has to be there
+at the end of each line.
+.PP
+Another command you might try is
+.UL who ,
+which tells you everyone who is currently logged in:
+.P1
+who
+.P2
+gives something like
+.P1
+.ta .5i 1i
+mb tty01 Jan 16 09:11
+ski tty05 Jan 16 09:33
+gam tty11 Jan 16 13:07
+.P2
+The time is when the user logged in;
+``ttyxx'' is the system's idea of what terminal
+the user is on.
+.PP
+If you make a mistake typing the command name,
+and refer to a non-existent command,
+you will be told.
+For example, if you type
+.P1
+whom
+.P2
+you will be told
+.P1
+whom: not found
+.P2
+Of course, if you inadvertently type the name of some other command,
+it will run,
+with more or less mysterious results.
+.SH
+Strange Terminal Behavior
+.PP
+Sometimes you can get into a state
+where your terminal acts strangely.
+For example,
+each letter may be typed twice,
+or the
+.UC RETURN
+may not cause a line feed
+or a return to the left margin.
+You can often fix this by logging out and logging back in.\(dg
+.FS
+\(dg In Berkeley Unix, the command "reset<control-j>"
+will often reset a terminal apparently in a strange state because a fullscreen
+editor crashed.
+.FE
+Or you can read the description of the command
+.UL stty
+in section 1 of the manual.
+To get intelligent treatment of
+tab characters
+(which are much used in
+.UC UNIX )
+if your terminal doesn't have tabs,
+type the command
+.P1
+stty \-tabs
+.P2
+and the system will convert each tab into the right number
+of blanks for you.
+.SH
+Mistakes in Typing
+.PP
+If you make a typing mistake, and see it before
+.UC RETURN
+has been typed,
+there are two ways to recover.
+The sharp-character
+.UL #
+erases the last character typed;
+in fact successive uses of
+.UL #
+erase characters back to
+the beginning of the line (but not beyond).
+So if you type badly, you can correct as you go:
+.P1
+dd#atte##e
+.P2
+is the same as
+.UL date .\(dd
+.FS
+\(dd Many installations set the erase character for display terminals to
+the delete or backspace key. "stty all" tells you what it actually is.
+.FE
+.PP
+The at-sign
+.UL @
+erases all of the characters
+typed so far
+on the current input line,
+so if the line is irretrievably fouled up, type an
+.UL @
+and start the line over.
+.PP
+What if you must enter a sharp or at-sign
+as part of the text?
+If you precede either
+.UL #
+or
+.UL @
+by a backslash
+.UL \e ,
+it loses its erase meaning.
+So to enter a sharp or at-sign in something, type
+.UL \e#
+or
+.UL \e@ .
+The system will always echo a newline at you after your at-sign,
+even if preceded by a backslash.
+Don't worry \(em
+the at-sign has been recorded.
+.PP
+To erase a backslash,
+you have to type two sharps or two at-signs, as in
+.UL \e## .
+The backslash is used extensively in
+.UC UNIX
+to indicate that the following character is in some way special.
+.SH
+Read-ahead
+.PP
+.UC UNIX
+has full read-ahead,
+which means that you can type as fast as you want,
+whenever you want,
+even when some command is typing at you.
+If you type during output,
+your input characters will appear intermixed with the output characters,
+but they will be stored away
+and interpreted in the correct order.
+So you can type several commands one after another without
+waiting for the first to finish or even begin.
+.SH
+Stopping a Program
+.PP
+You can stop most programs by
+typing the character
+.UC DEL '' ``
+(perhaps called ``delete'' or ``rubout'' on your terminal).
+The ``interrupt'' or ``break'' key found on most terminals
+can also be used.\(dg
+.FS
+\(dg In Berkeley Unix, "control-c" is the usual way to stop programs. "stty all"
+tells you the value of your "intr" key.
+.FE
+In a few programs, like the text editor,
+.UC DEL
+stops whatever the program is doing but leaves you in that program.
+Hanging up the phone will stop most programs.\(dd
+.FS
+\(dd In most modern shells, programs running in the background continue
+running even if you hang up.
+.FE
+.SH
+Logging Out
+.PP
+The easiest way to log out is to hang up the phone.
+You can also type
+.P1
+login
+.P2
+and let someone else use the terminal you were on.*
+.FS
+* "control-d" and "logout" are other alternatives.
+.FE
+It is usually not sufficient just to turn off the terminal.
+Most
+.UC UNIX
+systems
+do not use a time-out mechanism, so you'll be
+there forever unless you hang up.
+.SH
+Mail
+.PP
+When you log in, you may sometimes get the message
+.P1
+You have mail.
+.P2
+.UC UNIX
+provides a postal system so you can
+communicate with
+other users of the system.
+To read your mail,
+type the command
+.P1
+mail
+.P2
+The headers of your mail will be printed, in the order of their receipt.
+A message can be read with the
+.UL print
+command,
+or specified directly by number.
+Other commands are described in the manual.
+(Earlier versions of
+.UL mail
+do not process one message at a time,
+but are otherwise similar.)
+.PP
+How do you send mail to someone else?
+Suppose it is to go to ``joe'' (assuming ``joe'' is someone's login name).
+The easiest way is this:
+.P1
+mail joe
+.ft I
+now type in the text of the letter
+on as many lines as you like ...
+After the last line of the letter
+type the character ``.'',
+alone on the last line,
+like so:
+\&.
+.P2
+And that's it.
+.PP
+For practice, send mail to yourself.
+(This isn't as strange as it might sound \(em
+mail to oneself is a handy reminder mechanism.)
+.PP
+There are other ways to send mail \(em
+you can send a previously prepared letter,
+and you can mail to a number of people all at once.
+For more details, see
+.UL mail (1).
+(The notation
+.UL mail (1)
+means the command
+.UL mail
+in section 1
+of the
+.ul
+.UC UNIX
+.ul
+.IT Programmer's
+.IT Manual .)
+.SH
+Writing to other users\(dg
+.FS
+\(dg Although "write" works on Berkeley
+.UC UNIX,
+there is a much nicer way of communicating using display-terminals \(em
+"talk" splits the screen into two sections, and both of you can type
+simultaneously (see talk(1)).
+.FE
+.PP
+At some point,
+out of the blue will come a message
+like
+.P1
+Message from joe tty07...
+.P2
+accompanied by a startling beep.
+It means that Joe wants to talk to you,
+but unless you take explicit action you won't be able to talk back.
+To respond,
+type the command
+.P1
+write joe
+.P2
+This establishes a two-way communication path.
+Now whatever Joe types on his terminal will appear on yours
+and vice versa.
+The path is slow, rather like talking to the moon.
+(If you are in the middle of something, you have to
+get to a state where you can type a command.
+Normally, whatever program you are running has to terminate or be terminated.
+If you're editing, you can escape temporarily from the editor \(em
+read the editor tutorial.)
+.PP
+A protocol is needed to keep what you type from getting
+garbled up with what Joe types.
+Typically it's like this:
+.P1
+.tr --
+.fi
+.ft R
+Joe types
+.UL write
+.UL smith
+and waits.
+.br
+Smith types
+.UL write
+.UL joe
+and waits.
+.br
+Joe now types his message
+(as many lines as he likes).
+When he's ready for a reply, he
+signals it by typing
+.UL (o) ,
+which
+stands for ``over''.
+.br
+Now Smith types a reply, also
+terminated by
+.UL (o) .
+.br
+This cycle repeats until
+someone gets tired; he then
+signals his intent to quit with
+.UL (oo) ,
+for ``over
+and out''.
+.br
+To terminate
+the conversation, each side must
+type a ``control-d'' character alone
+on a line.
+When the other person types his ``control-d'',
+you will get the message
+.UL EOF
+on your terminal.
+.P2
+.PP
+If you write to someone who isn't logged in,
+or who doesn't want to be disturbed,
+you'll be told.
+If the target is logged in but doesn't answer
+after a decent interval,
+simply type ``control-d''.
+.SH
+On-line Manual
+.PP
+The
+.ul
+.UC UNIX
+.ul
+Programmer's Manual
+is typically kept on-line.
+If you get stuck on something,
+and can't find an expert to assist you,
+you can print on your terminal some manual section that might help.
+This is also useful for getting the most up-to-date
+information on a command.
+To print a manual section, type
+``man command-name''.
+Thus to read up on the
+.UL who
+command,
+type
+.P1
+man who
+.P2
+and, of course,
+.P1
+man man
+.P2
+tells all about the
+.UL man
+command.
+.SH
+Computer Aided Instruction
+.PP
+Your
+.UC UNIX
+system may have available
+a program called
+.UL learn ,
+which provides computer aided instruction on
+the file system and basic commands,
+the editor,
+document preparation,
+and even C programming.
+Try typing the command
+.P1
+learn
+.P2
+If
+.UL learn
+exists on your system,
+it will tell you what to do from there.
diff --git a/share/doc/usd/01.begin/u2 b/share/doc/usd/01.begin/u2
new file mode 100644
index 00000000000..15b9658d29c
--- /dev/null
+++ b/share/doc/usd/01.begin/u2
@@ -0,0 +1,1222 @@
+.\" $NetBSD: u2,v 1.1 2007/11/29 12:35:06 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u2 8.1 (Berkeley) 6/8/93
+.\"
+.SH
+II. DAY-TO-DAY USE
+.SH
+Creating Files \(em The Editor
+.PP
+If you have to type a paper or a letter or a program,
+how do you get the information stored in the machine?
+Most of these tasks are done with
+the
+.UC UNIX
+``text editor''
+.UL ed .
+Since
+.UL ed
+is thoroughly documented in
+.UL ed (1)
+and explained in
+.ul
+A Tutorial Introduction to the UNIX Text Editor,
+we won't spend any time here describing how to use it.
+All we want it for right now is to make some
+.ul
+files.
+(A file is just a collection of information stored in the machine,
+a simplistic but adequate definition.)
+.PP
+To create a file
+called
+.UL junk
+with some text in it, do the following:
+.P1
+.ta .65i
+ed junk \fR(invokes the text editor)\f3
+a \fR(command to ``ed'', to add text)\f3
+.ft I
+now type in
+whatever text you want ...
+.ft 3
+\&. \fR(signals the end of adding text)\f3
+.P2
+The ``\f3.\fR'' that signals the end of adding text must be
+at the beginning of a line by itself.
+Don't forget it,
+for until it is typed,
+no other
+.UL ed
+commands will be recognized \(em
+everything you type will be treated as text to be added.
+.PP
+At this point you can do various editing operations
+on the text you typed in, such as correcting spelling mistakes,
+rearranging paragraphs and the like.
+Finally, you must write the information you have typed
+into a file with the editor command
+.UL w :
+.P1
+w
+.P2
+.UL ed
+will respond with the number of characters it wrote
+into the file
+.UL junk .
+.PP
+Until the
+.UL w
+command,
+nothing is stored permanently,
+so if you hang up and go home
+the information is lost.\(dg
+.FS
+\(dg This is not strictly true \(em
+if you hang up while editing, the data you were
+working on is saved in a file called
+.UL ed.hup ,
+which you can continue with at your next session.
+.FE
+But after
+.UL w
+the information is there permanently;
+you can re-access it any time by typing
+.P1
+ed junk
+.P2
+Type a
+.UL q
+command
+to quit the editor.
+(If you try to quit without writing,
+.UL ed
+will print a
+.UL ?
+to remind you.
+A second
+.UL q
+gets you out regardless.)
+.PP
+Now create a second file called
+.UL temp
+in the same manner.
+You should now have two files,
+.UL junk
+and
+.UL temp .
+.SH
+What files are out there?
+.PP
+The
+.UL ls
+(for ``list'') command lists the names
+(not contents)
+of any of the files that
+.UC UNIX
+knows about.
+If you type
+.P1
+ls
+.P2
+the response will be
+.P1
+junk
+temp
+.P2
+which are indeed the two files just created.
+The names are sorted into alphabetical order automatically,
+but other variations are possible.
+For example,
+the command
+.P1
+ls -t
+.P2
+causes the files to be listed in the order in which they were last changed,
+most recent first.
+The
+.UL \-l
+option gives a ``long'' listing:
+.P1
+ls -l
+.P2
+will produce something like
+.P1
+-rw-rw-rw- 1 bwk users 41 Jul 22 2:56 junk
+-rw-rw-rw- 1 bwk users 78 Jul 22 2:57 temp
+.P2
+The date and time are of the last change to the file.
+The 41 and 78 are the number of characters
+(which should agree with the numbers you got from
+.UL ed ).
+.UL bwk
+is the owner of the file, that is, the person
+who created it.
+.UL users
+is the name of the file's group.
+The
+.UL \-rw\-rw\-rw\-
+tells who has permission to read and write the file,
+in this case everyone.
+.PP
+Options can be combined:
+.UL ls\ \-lt
+gives the same thing as
+.UL ls\ \-l ,
+but sorted into time order.
+You can also name the files you're interested in,
+and
+.UL ls
+will list the information about them only.
+More details can be found in
+.UL ls (1).
+.PP
+The use of optional arguments that begin with a minus sign,
+like
+.UL \-t
+and
+.UL \-lt ,
+is a common convention for
+.UC UNIX
+programs.
+In general, if a program accepts such optional arguments,
+they precede any filename arguments.
+It is also vital that you separate the various arguments with spaces:
+.UL ls\-l
+is not the same as
+.UL ls\ \ \-l .
+.SH
+Printing Files
+.PP
+Now that you've got a file of text,
+how do you print it so people can look at it?
+There are a host of programs that do that,
+probably more than are needed.
+.PP
+One simple thing is to use the editor,
+since printing is often done just before making changes anyway.
+You can say
+.P1
+ed junk
+1,$p
+.P2
+.UL ed
+will reply with the count of the characters in
+.UL junk
+and then print all the lines in the file.
+After you learn how to use the editor,
+you can be selective about the parts you print.
+.PP
+There are times when it's not feasible to use the editor for printing.
+For example, there is a limit on how big a file
+.UL ed
+can handle
+(several thousand lines).
+Secondly,
+it
+will only print one file at a time,
+and sometimes you want to print several, one after another.
+So here are a couple of alternatives.
+.PP
+First is
+.UL cat ,
+the simplest of all the printing programs.
+.UL cat
+simply prints on the terminal the contents of all the files
+named in a list.
+Thus
+.P1
+cat junk
+.P2
+prints one file, and
+.P1
+cat junk temp
+.P2
+prints two.
+The files are simply concatenated (hence the name
+.UL cat '') ``
+onto the terminal.
+.PP
+.UL pr
+produces formatted printouts of files.
+As with
+.UL cat ,
+.UL pr
+prints all the files named in a list.
+The difference is that it produces
+headings with date, time, page number and file name
+at the top of each page,
+and
+extra lines to skip over the fold in the paper.
+Thus,
+.P1
+pr junk temp
+.P2
+will print
+.UL junk
+neatly,
+then skip to the top of a new page and print
+.UL temp
+neatly.
+.PP
+.UL pr
+can also produce multi-column output:
+.P1
+pr -3 junk
+.P2
+prints
+.UL junk
+in 3-column format.
+You can use any reasonable number in place of ``3''
+and
+.UL pr
+will do its best.
+.UL pr
+has other capabilities as well;
+see
+.UL pr (1).
+.PP
+It should be noted that
+.UL pr
+is
+.ul
+not
+a formatting program in the sense of shuffling lines around
+and justifying margins.
+The true formatters are
+.UL nroff
+and
+.UL troff ,
+which we will get to in the section on document preparation.
+.PP
+There are also programs that print files
+on a high-speed printer.
+Look in your manual under
+.UL lpr .
+.SH
+Shuffling Files About
+.PP
+Now that you have some files in the file system
+and some experience in printing them,
+you can try bigger things.
+For example,
+you can move a file from one place to another
+(which amounts to giving it a new name),
+like this:
+.P1
+mv junk precious
+.P2
+This means that what used to be ``junk'' is now ``precious''.
+If you do an
+.UL ls
+command now,
+you will get
+.P1
+precious
+temp
+.P2
+Beware that if you move a file to another one
+that already exists,
+the already existing contents are lost forever.
+.PP
+If you want
+to make a
+.ul
+copy
+of a file (that is, to have two versions of something),
+you can use the
+.UL cp
+command:
+.P1
+cp precious temp1
+.P2
+makes a duplicate copy of
+.UL precious
+in
+.UL temp1 .
+.PP
+Finally, when you get tired of creating and moving
+files,
+there is a command to remove files from the file system,
+called
+.UL rm .
+.P1
+rm temp temp1
+.P2
+will remove both of the files named.
+.PP
+You will get a warning message if one of the named files wasn't there,
+but otherwise
+.UL rm ,
+like most
+.UC UNIX
+commands,
+does its work silently.
+There is no prompting or chatter,
+and error messages are occasionally curt.
+This terseness is sometimes disconcerting
+to new\%comers,
+but experienced users find it desirable.
+.SH
+What's in a Filename
+.PP
+So far we have used filenames without ever saying what's
+a legal name,
+so it's time for a couple of rules.
+First, filenames are limited to 14 characters,
+which is enough to be descriptive.\(dg
+.FS
+\(dg In 4.2 BSD the limit was extended to 255 characters.
+.FE
+Second, although you can use almost any character
+in a filename,
+common sense says you should stick to ones that are visible,
+and that you should probably avoid characters that might be used
+with other meanings.
+We have already seen, for example,
+that in the
+.UL ls
+command,
+.UL ls\ \-t
+means to list in time order.
+So if you had a file whose name
+was
+.UL \-t ,
+you would have a tough time listing it by name.
+Besides the minus sign, there are other characters which
+have special meaning.
+To avoid pitfalls,
+you would do well to
+use only letters, numbers and the period
+until you're familiar with the situation.
+.PP
+On to some more positive suggestions.
+Suppose you're typing a large document
+like a book.
+Logically this divides into many small pieces,
+like chapters and perhaps sections.
+Physically it must be divided too,
+for
+.UL ed
+will not handle really big files.
+Thus you should type the document as a number of files.
+You might have a separate file for each chapter,
+called
+.P1
+chap1
+chap2
+.ft R
+etc...
+.P2
+Or, if each chapter were broken into several files, you might have
+.P1
+chap1.1
+chap1.2
+chap1.3
+\&...
+chap2.1
+chap2.2
+\&...
+.P2
+You can now tell at a glance where a particular file fits into the whole.
+.PP
+There are advantages to a systematic naming convention which are not obvious
+to the novice
+.UC UNIX
+user.
+What if you wanted to print the whole book?
+You could say
+.P1
+pr chap1.1 chap1.2 chap1.3 ......
+.P2
+but you would get tired pretty fast, and would probably even make mistakes.
+Fortunately, there is a shortcut.
+You can say
+.P1
+pr chap*
+.P2
+The
+.UL *
+means ``anything at all,''
+so this translates into ``print all files
+whose names begin with
+.UL chap '',
+listed in alphabetical order.
+.PP
+This shorthand notation
+is not a property of the
+.UL pr
+command, by the way.
+It is system-wide, a service of the program
+that interprets commands
+(the ``shell,''
+.UL sh (1)).
+Using that fact, you can see how to list the names of the files in the book:
+.P1
+ls chap*
+.P2
+produces
+.P1
+chap1.1
+chap1.2
+chap1.3
+\&...
+.P2
+The
+.UL *
+is not limited to the last position in a filename \(em
+it can be anywhere
+and can occur several times.
+Thus
+.P1
+rm *junk* *temp*
+.P2
+removes all files that contain
+.UL junk
+or
+.UL temp
+as any part of their name.
+As a special case,
+.UL *
+by itself matches every filename,
+so
+.P1
+pr *
+.P2
+prints all your files
+(alphabetical order),
+and
+.P1
+rm *
+.P2
+removes
+.ul
+all files.
+(You had better be
+.IT very
+sure that's what you wanted to say!)
+.PP
+The
+.UL *
+is not
+the only pattern-matching feature available.
+Suppose you want to print only chapters 1 through 4 and 9.
+Then you can say
+.P1
+pr chap[12349]*
+.P2
+The
+.UL [...]
+means to match any of the characters inside the brackets.
+A range of consecutive letters or digits can be abbreviated,
+so you can also do this
+with
+.P1
+pr chap[1-49]*
+.P2
+Letters can also be used within brackets:
+.UL [a\-z]
+matches any character in the range
+.UL a
+through
+.UL z .
+.PP
+The
+.UL ?
+pattern matches any single character,
+so
+.P1
+ls ?
+.P2
+lists all files which have single-character names,
+and
+.P1
+ls -l chap?.1
+.P2
+lists information about the first file of each chapter
+.UL chap1.1 \&, (
+.UL chap2.1 ,
+etc.).
+.PP
+Of these niceties,
+.UL *
+is certainly the most useful,
+and you should get used to it.
+The others are frills, but worth knowing.
+.PP
+If you should ever have to turn off the special meaning
+of
+.UL * ,
+.UL ? ,
+etc.,
+enclose the entire argument in single quotes,
+as in
+.P1
+ls \(fm?\(fm
+.P2
+We'll see some more examples of this shortly.
+.SH
+What's in a Filename, Continued
+.PP
+When you first made that file called
+.UL junk ,
+how did
+the system
+know that there wasn't another
+.UL junk
+somewhere else,
+especially since the person in the next office is also
+reading this tutorial?
+The answer is that generally each user
+has a private
+.IT directory ,
+which contains only the files that belong to him.
+When you log in, you are ``in'' your directory.
+Unless you take special action,
+when you create a new file,
+it is made in the directory that you are currently in;
+this is most often your own directory,
+and thus the file is unrelated to any other file of the same name
+that might exist in someone else's directory.
+.PP
+The set of all files
+is organized into a (usually big) tree,
+with your files located several branches into the tree.
+It is possible for you to ``walk'' around this tree,
+and to find any file in the system, by starting at the root
+of the tree and walking along the proper set of branches.
+Conversely, you can start where you are and walk toward the root.
+.PP
+Let's try the latter first.
+The basic tools is the command
+.UL pwd
+(``print working directory''),
+which prints the name of the directory you are currently in.
+.PP
+Although the details will vary according to the system you are on,
+if you give the
+command
+.UL pwd ,
+it will print something like
+.P1
+/usr/your\(hyname
+.P2
+This says that you are currently in the directory
+.UL your-name ,
+which is in turn in the directory
+.UL /usr ,
+which is in turn in the root directory
+called by convention just
+.UL / .
+(Even if it's not called
+.UL /usr
+on your system,
+you will get something analogous.
+Make the corresponding mental adjustment and read on.)
+.PP
+If you now type
+.P1
+ls /usr/your\(hyname
+.P2
+you should get exactly the same list of file names
+as you get from a plain
+.UL ls :
+with no arguments,
+.UL ls
+lists the contents of the current directory;
+given the name of a directory,
+it lists the contents of that directory.
+.PP
+Next, try
+.P1
+ls /usr
+.P2
+This should print a long series of names,
+among which is your own login name
+.UL your-name .
+On many systems,
+.UL usr
+is a directory that contains the directories
+of all the normal users of the system,
+like you.
+.PP
+The next step is to try
+.P1
+ls /
+.P2
+You should get a response something like this
+(although again the details may be different):
+.P1
+bin
+dev
+etc
+lib
+tmp
+usr
+.P2
+This is a collection of the basic directories of files
+that
+the system
+knows about;
+we are at the root of the tree.
+.PP
+Now try
+.P1
+cat /usr/your\(hyname/junk
+.P2
+(if
+.UL junk
+is still around in your directory).
+The name
+.P1
+/usr/your\(hyname/junk
+.P2
+is called the
+.UL pathname
+of the file that
+you normally think of as ``junk''.
+``Pathname'' has an obvious meaning:
+it represents the full name of the path you have to follow from the root
+through the tree of directories to get to a particular file.
+It is a universal rule in
+the
+.UC UNIX
+system
+that anywhere you can use an ordinary filename,
+you can use a pathname.
+.PP
+Here is a picture which may make this clearer:
+.P1 1
+.ft R
+.if t .vs 9p
+.if t .tr /\(sl
+.if t .tr ||
+.ce 100
+(root)
+/ | \e
+/ | \e
+/ | \e
+ bin etc usr dev tmp
+/ | \e / | \e / | \e / | \e / | \e
+/ | \e
+/ | \e
+adam eve mary
+/ / \e \e
+ / \e junk
+junk temp
+.ce 0
+.br
+.tr //
+.P2
+.LP
+Notice that Mary's
+.UL junk
+is unrelated to Eve's.
+.PP
+This isn't too exciting if all the files of interest are in your own
+directory, but if you work with someone else
+or on several projects concurrently,
+it becomes handy indeed.
+For example, your friends can print your book by saying
+.P1
+pr /usr/your\(hyname/chap*
+.P2
+Similarly, you can find out what files your neighbor has
+by saying
+.P1
+ls /usr/neighbor\(hyname
+.P2
+or make your own copy of one of his files by
+.P1
+cp /usr/your\(hyneighbor/his\(hyfile yourfile
+.P2
+.PP
+If your neighbor doesn't want you poking around in his files,
+or vice versa,
+privacy can be arranged.
+Each file and directory has read-write-execute permissions for the owner,
+a group, and everyone else,
+which can be set
+to control access.
+See
+.UL ls (1)
+and
+.UL chmod (1)
+for details.
+As a matter of observed fact,
+most users most of the time find openness of more
+benefit than privacy.
+.PP
+As a final experiment with pathnames, try
+.P1
+ls /bin /usr/bin
+.P2
+Do some of the names look familiar?
+When you run a program, by typing its name after the prompt character,
+the system simply looks for a file of that name.
+It normally looks first in your directory
+(where it typically doesn't find it),
+then in
+.UL /bin
+and finally in
+.UL /usr/bin .
+There is nothing magic about commands like
+.UL cat
+or
+.UL ls ,
+except that they have been collected into a couple of places to be easy to find and administer.
+.PP
+What if you work regularly with someone else on common information
+in his directory?
+You could just log in as your friend each time you want to,
+but you can also say
+``I want to work on his files instead of my own''.
+This is done by changing the directory that you are
+currently in:
+.P1
+cd /usr/your\(hyfriend
+.P2
+(On some systems,
+.UL cd
+is spelled
+.UL chdir .)
+Now when you use a filename in something like
+.UL cat
+or
+.UL pr ,
+it refers to the file in your friend's directory.
+Changing directories doesn't affect any permissions associated
+with a file \(em
+if you couldn't access a file from your own directory,
+changing to another directory won't alter that fact.
+Of course,
+if you forget what directory you're in, type
+.P1
+pwd
+.P2
+to find out.
+.PP
+It is usually convenient to arrange your own files
+so that all the files related to one thing are in a directory separate
+from other projects.
+For example, when you write your book, you might want to keep all the text
+in a directory called
+.UL book .
+So make one with
+.P1
+mkdir book
+.P2
+then go to it with
+.P1
+cd book
+.P2
+then start typing chapters.
+The book is now found in (presumably)
+.P1
+/usr/your\(hyname/book
+.P2
+To remove the directory
+.UL book ,
+type
+.P1
+rm book/*
+rmdir book
+.P2
+The first command removes all files from the directory;
+the second
+removes the empty directory.
+.PP
+You can go up one level in the tree of files
+by saying
+.P1
+cd ..
+.P2
+.UL .. '' ``
+is the name of the parent of whatever directory you are currently in.
+For completeness,
+.UL . '' ``
+is an alternate name
+for the directory you are in.
+.SH
+Using Files instead of the Terminal
+.PP
+Most of the commands we have seen so far produce output
+on the terminal;
+some, like the editor, also take their input from the terminal.
+It is universal in
+.UC UNIX
+systems
+that the terminal can be replaced by a file
+for either or both of input and output.
+As one example,
+.P1
+ls
+.P2
+makes a list of files on your terminal.
+But if you say
+.P1
+ls >filelist
+.P2
+a list of your files will be placed in the file
+.UL filelist
+(which
+will be created if it doesn't already exist,
+or overwritten if it does).
+The symbol
+.UL >
+means ``put the output on the following file,
+rather than on the terminal.''
+Nothing is produced on the terminal.
+As another example, you could combine
+several files into one by capturing the output of
+.UL cat
+in a file:
+.P1
+cat f1 f2 f3 >temp
+.P2
+.PP
+The symbol
+.UL >>
+operates very much like
+.UL >
+does,
+except that it means
+``add to the end of.''
+That is,
+.P1
+cat f1 f2 f3 >>temp
+.P2
+means to concatenate
+.UL f1 ,
+.UL f2
+and
+.UL f3
+to the end of whatever is already in
+.UL temp ,
+instead of overwriting the existing contents.
+As with
+.UL > ,
+if
+.UL temp
+doesn't exist, it will be created for you.
+.PP
+In a similar way, the symbol
+.UL <
+means to take the input
+for a program from the following file,
+instead of from the terminal.
+Thus, you could make up a script of commonly used editing commands
+and put them into a file called
+.UL script .
+Then you can run the script on a file by saying
+.P1
+ed file <script
+.P2
+As another example, you can use
+.UL ed
+to prepare a letter in file
+.UL let ,
+then send it to several people with
+.P1
+mail adam eve mary joe <let
+.P2
+.SH
+Pipes
+.PP
+One of the novel contributions of
+the
+.UC UNIX
+system
+is the idea of a
+.ul
+pipe.
+A pipe is simply a way to connect the output of one program
+to the input of another program,
+so the two run as a sequence of processes \(em
+a pipeline.
+.PP
+For example,
+.P1
+pr f g h
+.P2
+will print the files
+.UL f ,
+.UL g ,
+and
+.UL h ,
+beginning each on a new page.
+Suppose you want
+them run together instead.
+You could say
+.P1
+cat f g h >temp
+pr <temp
+rm temp
+.P2
+but this is more work than necessary.
+Clearly what we want is to take the output of
+.UL cat
+and
+connect it to the input of
+.UL pr .
+So let us use a pipe:
+.P1
+cat f g h | pr
+.P2
+The vertical bar
+.UL |
+means to
+take the output from
+.UL cat ,
+which would normally have gone to the terminal,
+and put it into
+.UL pr
+to be neatly formatted.
+.PP
+There are many other examples of pipes.
+For example,
+.P1
+ls | pr -3
+.P2
+prints a list of your files in three columns.
+The program
+.UL wc
+counts the number of lines, words and characters in
+its input, and as we saw earlier,
+.UL who
+prints a list of currently-logged on people,
+one per line.
+Thus
+.P1
+who | wc
+.P2
+tells how many people are logged on.
+And of course
+.P1
+ls | wc
+.P2
+counts your files.
+.PP
+Any program
+that reads from the terminal
+can read from a pipe instead;
+any program that writes on the terminal can drive
+a pipe.
+You can have as many elements in a pipeline as you wish.
+.PP
+Many
+.UC UNIX
+programs are written so that they will take their input from one or more files
+if file arguments are given;
+if no arguments are given they will read from the terminal,
+and thus can be used in pipelines.
+.UL pr
+is one example:
+.P1
+pr -3 a b c
+.P2
+prints files
+.UL a ,
+.UL b
+and
+.UL c
+in order in three columns.
+But in
+.P1
+cat a b c | pr -3
+.P2
+.UL pr
+prints the information coming down the pipeline,
+still in
+three columns.
+.SH
+The Shell
+.PP
+We have already mentioned once or twice the mysterious
+``shell,''
+which is in fact
+.UL sh (1).
+The shell is the program that interprets what you type as
+commands and arguments.
+It also looks after translating
+.UL * ,
+etc.,
+into lists of filenames,
+and
+.UL < ,
+.UL > ,
+and
+.UL |
+into changes of input and output streams.
+.PP
+The shell has other capabilities too.
+For example, you can run two programs with one command line
+by separating the commands with a semicolon;
+the shell recognizes the semicolon and
+breaks the line into two commands.
+Thus
+.P1
+date; who
+.P2
+does both commands before returning with a prompt character.
+.PP
+You can also have more than one program running
+.ul
+simultaneously
+if you wish.
+For example, if you are doing something time-consuming,
+like the editor script
+of an earlier section,
+and you don't want to wait around for the results before starting something else,
+you can say
+.P1
+ed file <script &
+.P2
+The ampersand at the end of a command line
+says ``start this command running,
+then take further commands from the terminal immediately,''
+that is,
+don't wait for it to complete.
+Thus the script will begin,
+but you can do something else at the same time.
+Of course, to keep the output from interfering
+with what you're doing on the terminal,
+it would be better to say
+.P1
+ed file <script >script.out &
+.P2
+which saves the output lines in a file
+called
+.UL script.out .
+.PP
+When you initiate a command with
+.UL & ,
+the system
+replies with a number
+called the process number,
+which identifies the command in case you later want
+to stop it.
+If you do, you can say
+.P1
+kill process\(hynumber
+.P2
+If you forget the process number,
+the command
+.UL ps
+will tell you about everything you have running.
+(If you are desperate,
+.UL kill\ 0
+will kill all your processes.)
+And if you're curious about other people,
+.UL ps\ a
+will tell you about
+.ul
+all
+programs that are currently running.
+.PP
+You can say
+.P1 1
+(command\(hy1; command\(hy2; command\(hy3) &
+.P2
+to start three commands in the background,
+or you can start a background pipeline with
+.P1
+command\(hy1 | command\(hy2 &
+.P2
+.PP
+Just as you can tell the editor
+or some similar program to take its input
+from a file instead of from the terminal,
+you can tell the shell to read a file
+to get commands.
+(Why not? The shell, after all, is just a program,
+albeit a clever one.)
+For instance, suppose you want to set tabs on
+your terminal, and find out the date
+and who's on the system every time you log in.
+Then you can put the three necessary commands
+.UL tabs , (
+.UL date ,
+.UL who )
+into a file, let's call it
+.UL startup ,
+and then run it with
+.P1
+sh startup
+.P2
+This says to run the shell with the file
+.UL startup
+as input.
+The effect is as if you had typed
+the contents of
+.UL startup
+on the terminal.
+.PP
+If this is to be a regular thing,
+you can eliminate the
+need to type
+.UL sh :
+simply type, once only, the command
+.P1
+chmod +x startup
+.P2
+and thereafter you need only say
+.P1
+startup
+.P2
+to run the sequence of commands.
+The
+.UL chmod (1)
+command marks the file executable;
+the shell recognizes this and runs it as a sequence of commands.
+.PP
+If you want
+.UL startup
+to run automatically every time you log in,
+create a file in your login directory called
+.UL .profile ,
+and place in it the line
+.UL startup .
+When the shell first gains control when you log in,
+it looks for the
+.UL .profile
+file and does whatever commands it finds in it.\(dg
+.FS
+\(dg The c shell instead reads a file called
+.UL .login
+.
+.FE
+We'll get back to the shell in the section
+on programming.
diff --git a/share/doc/usd/01.begin/u3 b/share/doc/usd/01.begin/u3
new file mode 100644
index 00000000000..096405ce904
--- /dev/null
+++ b/share/doc/usd/01.begin/u3
@@ -0,0 +1,357 @@
+.\" $NetBSD: u3,v 1.1 2007/11/29 12:35:06 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u3 8.1 (Berkeley) 6/8/93
+.\"
+.sp
+.SH
+III. DOCUMENT PREPARATION
+.PP
+.UC UNIX
+systems are used extensively for document preparation.
+There are two major
+formatting
+programs,
+that is,
+programs that produce a text with
+justified right margins, automatic page numbering and titling,
+automatic hyphenation,
+and the like.
+.UL nroff
+is designed to produce output on terminals and
+line-printers.
+.UL troff
+(pronounced ``tee-roff'')
+instead drives a phototypesetter,
+which produces very high quality output
+on photographic paper.
+This paper was formatted with
+.UL troff .
+.SH
+Formatting Packages
+.PP
+The basic idea of
+.UL nroff
+and
+.UL troff
+is that the text to be formatted contains within it
+``formatting commands'' that indicate in detail
+how the formatted text is to look.
+For example, there might be commands that specify how long
+lines are, whether to use single or double spacing,
+and what running titles to use on each page.
+.PP
+Because
+.UL nroff
+and
+.UL troff
+are relatively hard to learn to use effectively,
+several
+``packages'' of canned formatting requests are available
+to let you specify
+paragraphs, running titles, footnotes, multi-column output,
+and so on, with little effort
+and without having to learn
+.UL nroff
+and
+.UL troff .
+These packages take a modest effort to learn,
+but the rewards for using them are so great
+that it is time well spent.
+.PP
+In this section,
+we will provide a hasty look at the ``manuscript''
+package known as
+.UL \-ms .
+Formatting requests typically consist of a period and two upper-case letters,
+such as
+.UL .TL ,
+which is used to introduce a title,
+or
+.UL .PP
+to begin a new paragraph.
+.PP
+A document is typed so it looks something like this:
+.P1
+\&.TL
+title of document
+\&.AU
+author name
+\&.SH
+section heading
+\&.PP
+paragraph ...
+\&.PP
+another paragraph ...
+\&.SH
+another section heading
+\&.PP
+etc.
+.P2
+The lines that begin with a period are the formatting requests.
+For example,
+.UL .PP
+calls for starting a new paragraph.
+The precise meaning of
+.UL .PP
+depends on what output device is being used
+(typesetter or terminal, for instance),
+and on what publication the document will appear in.
+For example,
+.UL \-ms
+normally assumes that a paragraph is preceded by a space
+(one line in
+.UL nroff ,
+\(12 line in
+.UL troff ),
+and the first word is indented.
+These rules can be changed if you like,
+but they are changed by changing the interpretation
+of
+.UL .PP ,
+not by re-typing the document.
+.PP
+To actually produce a document in standard format
+using
+.UL \-ms ,
+use the command
+.P1
+troff -ms files ...
+.P2
+for the typesetter, and
+.P1
+nroff -ms files ...
+.P2
+for a terminal.
+The
+.UL \-ms
+argument tells
+.UL troff
+and
+.UL nroff
+to use the manuscript package of formatting requests.
+.PP
+There are several similar packages;
+check with a local expert to determine which ones
+are in common use on your machine.
+.SH
+Supporting Tools
+.PP
+In addition to the basic formatters,
+there is
+a host of supporting programs
+that help with document preparation.
+The list in the next few paragraphs
+is far from complete,
+so browse through the manual
+and check with people around you for other possibilities.
+.PP
+.UL eqn
+and
+.UL neqn
+let you integrate mathematics
+into the text of a document,
+in an easy-to-learn language that closely resembles the way
+you would speak it aloud.
+For example, the
+.UL eqn
+input
+.P1
+sum from i=0 to n x sub i ~=~ pi over 2
+.P2
+produces the output
+.EQ
+sum from i=0 to n x sub i ~=~ pi over 2
+.EN
+.PP
+The program
+.UL tbl
+provides an analogous service for preparing tabular material;
+it does all the computations necessary to align complicated columns
+with elements of varying widths.
+.PP
+.UL refer
+prepares bibliographic citations from a data base,
+in whatever style is defined by the formatting package.
+It looks after all the details of numbering references in sequence,
+filling in page and volume numbers,
+getting the author's initials and the journal name right,
+and so on.
+.PP
+.UL spell
+and
+.UL typo
+detect possible spelling mistakes in a document.\(dg
+.FS
+\(dg "typo" is not provided with Berkeley Unix.
+.FE
+.UL spell
+works by comparing the words in your document
+to a dictionary,
+printing those that are not in the dictionary.
+It knows enough about English spelling to detect plurals and the like,
+so it does a very good job.
+.UL typo
+looks for words which are ``unusual'',
+and prints those.
+Spelling mistakes tend to be more unusual,
+and thus show up early when the most unusual words
+are printed first.
+.PP
+.UL grep
+looks through a set of files for lines
+that contain a particular text pattern
+(rather like the editor's context search does,
+but on a bunch of files).
+For example,
+.P1
+grep \(fming$\(fm chap*
+.P2
+will find all lines that end with
+the letters
+.UL ing
+in the files
+.UL chap* .
+(It is almost always a good practice to put single quotes around
+the pattern you're searching for,
+in case it contains characters like
+.UL *
+or
+.UL $
+that have a special meaning to the shell.)
+.UL grep
+is often useful for finding out in which of a set of files
+the misspelled words detected by
+.UL spell
+are actually located.
+.PP
+.UL diff
+prints a list of the differences between
+two files,
+so you can compare
+two versions of something automatically
+(which certainly beats proofreading by hand).
+.PP
+.UL wc
+counts the words, lines and characters in a set of files.
+.UL tr
+translates characters into other characters;
+for example it will convert upper to lower case and vice versa.
+This translates upper into lower:
+.P1
+tr A-Z a-z <input >output
+.P2
+.PP
+.UL sort
+sorts files in a variety of ways;
+.UL sed
+provides many of the editing facilities
+of
+.UL ed ,
+but can apply them to arbitrarily long inputs.
+.UL awk
+provides the ability to do both pattern matching and numeric computations,
+and to conveniently process fields within lines.
+These programs are for more advanced users,
+and they are not limited to document preparation.
+Put them on your list of things to learn about.
+.PP
+Most of these programs are either independently documented
+(like
+.UL eqn
+and
+.UL tbl ),
+or are sufficiently simple that the description in
+the
+.ul 2
+.UC UNIX
+Programmer's Manual
+is adequate explanation.
+.SH
+Hints for Preparing Documents
+.PP
+Most documents go through several versions (always more than you expected) before they
+are finally finished.
+Accordingly, you should do whatever possible to make
+the job of changing them easy.
+.PP
+First, when you do the purely mechanical operations of typing,
+type so that subsequent editing will be easy.
+Start each sentence on a new line.
+Make lines short,
+and break lines at natural places,
+such as after commas and semicolons,
+rather than randomly.
+Since most people change documents by rewriting phrases
+and adding, deleting and rearranging sentences,
+these precautions simplify any editing
+you have to do later.
+.PP
+Keep the individual files of a document down
+to modest size,
+perhaps ten to fifteen thousand characters.
+Larger files edit more slowly,
+and of course if you make a dumb mistake
+it's better to have clobbered a small file than a big one.
+Split into files at natural boundaries in the document,
+for the same reasons that you start each sentence
+on a new line.
+.PP
+The second aspect of making change easy
+is to not commit yourself to formatting details too early.
+One of the advantages of formatting packages like
+.UL \-ms
+is that they permit you to delay decisions
+to the last possible moment.
+Indeed,
+until a document is printed,
+it is not even decided whether it will be typeset
+or put on a line printer.
+.PP
+As a rule of thumb, for all but the most trivial jobs,
+you should type a document in terms of a set of requests
+like
+.UL .PP ,
+and then define them appropriately,
+either by using one of the canned packages
+(the better way)
+or by defining your own
+.UL nroff
+and
+.UL troff
+commands.
+As long as you have entered the text in some systematic way,
+it can always be cleaned up and re-formatted
+by a judicious combination of
+editing commands and request definitions.
diff --git a/share/doc/usd/01.begin/u4 b/share/doc/usd/01.begin/u4
new file mode 100644
index 00000000000..abf43af17ae
--- /dev/null
+++ b/share/doc/usd/01.begin/u4
@@ -0,0 +1,323 @@
+.\" $NetBSD: u4,v 1.1 2007/11/29 12:35:06 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u4 8.1 (Berkeley) 6/8/93
+.\"
+.SH
+IV. PROGRAMMING
+.PP
+There will be no attempt made to teach any of
+the programming languages available
+but a few words of advice are in order.
+One of the reasons why the
+.UC UNIX
+system is a productive programming environment
+is that there is already a rich set of tools available,
+and facilities like pipes, I/O redirection,
+and the capabilities of the shell
+often make it possible to do a job
+by pasting together programs that already exist
+instead of writing from scratch.
+.SH
+The Shell
+.PP
+The pipe mechanism lets you fabricate quite complicated operations
+out of spare parts that already exist.
+For example,
+the first draft of the
+.UL spell
+program was (roughly)
+.P1
+.ta .6i 1.2i
+cat ... \f2collect the files\f3
+| tr ... \f2put each word on a new line\f3
+| tr ... \f2delete punctuation, etc.\f3
+| sort \f2into dictionary order\f3
+| uniq \f2discard duplicates\f3
+| comm \f2print words in text\f3
+ \f2 but not in dictionary\f3
+.P2
+More pieces have been added subsequently,
+but this goes a long way
+for such a small effort.
+.PP
+The editor can be made to do things that would normally
+require special programs on other systems.
+For example, to list the first and last lines of each of a
+set of files, such as a book,
+you could laboriously type
+.P1
+ed
+e chap1.1
+1p
+$p
+e chap1.2
+1p
+$p
+.ft R
+etc.
+.P2
+But you can do the job much more easily.
+One way is to type
+.P1
+ls chap* >temp
+.P2
+to get the list of filenames into a file.
+Then edit this file to make the necessary
+series of editing commands
+(using the global commands of
+.UL ed ),
+and write it into
+.UL script .
+Now the command
+.P1
+ed <script
+.P2
+will produce
+the same output as the laborious hand typing.
+Alternately
+(and more easily),
+you can use the fact that the shell will perform loops,
+repeating a set of commands over and over again
+for a set of arguments:
+.P1
+for i in chap*
+do
+ ed $i <script
+done
+.P2
+This sets the shell variable
+.UL i
+to each file name in turn,
+then does the command.
+You can type this command at the terminal,
+or put it in a file for later execution.
+.SH
+Programming the Shell
+.PP
+An option often overlooked by newcomers
+is that the shell is itself a programming language,
+with variables,
+control flow
+.UL if-else , (
+.UL while ,
+.UL for ,
+.UL case ),
+subroutines,
+and interrupt handling.
+Since
+there are
+many building-block programs,
+you can sometimes avoid writing a new program
+merely by piecing together some of the building blocks
+with shell command files.
+.PP
+We will not go into any details here;
+examples and rules can be found in
+.ul
+An Introduction to the
+.ul
+.UC UNIX
+.IT Shell ,
+by S. R. Bourne.
+.SH
+Programming in C
+.PP
+If you are undertaking anything substantial,
+C is the only reasonable choice of programming language:
+everything in
+the
+.UC UNIX
+system
+is tuned to it.
+The
+system
+itself
+is written in C,
+as are most of the programs that run on it.
+It is also an easy language to use
+once you get started.
+C is introduced and fully described in
+.ul
+The C Programming Language
+by
+B. W. Kernighan and D. M. Ritchie
+(Prentice-Hall, 1978).
+Several sections of the manual
+describe the system interfaces, that is,
+how you do I/O
+and similar functions.
+Read
+.ul
+UNIX Programming
+for more complicated things.
+.PP
+Most input and output in C is best handled with the
+standard I/O library,
+which provides a set of I/O functions
+that exist in compatible form on most machines
+that have C compilers.
+In general, it's wisest to confine the system interactions
+in a program to the facilities provided by this library.
+.PP
+C programs that don't depend too much on special features of
+.UC UNIX
+(such as pipes)
+can be moved to other computers that have C compilers.
+The list of such machines grows daily;
+in addition to the original
+.UC PDP -11,
+it currently includes
+at least
+Honeywell 6000,
+IBM 370 and PC families,
+Interdata 8/32,
+Data General Nova and Eclipse,
+HP 2100,
+Harris /7,
+Motorola 68000 family (including machines like Sun Microsystems and
+Apple Macintosh),
+VAX 11 family,
+SEL 86,
+and
+Zilog Z80.
+Calls to the standard I/O library will work on all of these machines.
+.PP
+There are a number of supporting programs that go with C.
+.UL lint
+checks C programs for potential portability problems,
+and detects errors such as mismatched argument types
+and uninitialized variables.
+.PP
+For larger programs
+(anything whose source is on more than one file)
+.UL make
+allows you to specify the dependencies among the source files
+and the processing steps needed to make a new version;
+it then checks the times that the pieces were last changed
+and does the minimal amount of recompiling
+to create a consistent updated version.
+.PP
+The debugger
+.UL gdb
+is useful for digging through the dead bodies
+of C programs,
+but is rather hard to learn to use effectively.
+The most effective debugging tool is still
+careful thought, coupled with judiciously placed
+print statements.
+.PP
+The C compiler provides a limited instrumentation service,
+so you can find out
+where programs spend their time and what parts are worth optimizing.
+Compile the routines with the
+.UL \-pg
+option;
+after the test run, use
+.UL gprof
+to print an execution profile.
+The command
+.UL time
+will give you the gross run-time statistics
+of a program, but they are not super accurate or reproducible.
+.SH
+Other Languages
+.PP
+If you
+.ul
+have
+to use Fortran,
+there are two possibilities.
+You might consider
+Ratfor,
+which gives you the decent control structures
+and free-form input that characterize C,
+yet lets you write code that
+is still portable to other environments.
+Bear in mind that
+.UC UNIX
+Fortran
+tends to produce large and relatively slow-running
+programs.
+Furthermore, supporting software like
+.UL gdb ,
+.UL prof ,
+etc., are all virtually useless with Fortran programs.
+There may also be a Fortran 77 compiler on your system.
+If so,
+this is a viable alternative to
+Ratfor,
+and has the non-trivial advantage that it is compatible with C
+and related programs.
+(The Ratfor processor
+and C tools
+can be used with Fortran 77 too.)
+.PP
+If your application requires you to translate
+a language into a set of actions or another language,
+you are in effect building a compiler,
+though probably a small one.
+In that case,
+you should be using
+the
+.UL yacc
+compiler-compiler,
+which helps you develop a compiler quickly.
+The
+.UL lex
+lexical analyzer generator does the same job
+for the simpler languages that can be expressed as regular expressions.
+It can be used by itself,
+or as a front end to recognize inputs for a
+.UL yacc -based
+program.
+Both
+.UL yacc
+and
+.UL lex
+require some sophistication to use,
+but the initial effort of learning them
+can be repaid many times over in programs
+that are easy to change later on.
+.PP
+Most
+.UC UNIX
+systems also make available other languages,
+such as
+Algol 68, APL, Basic, Lisp, Pascal, and Snobol.
+Whether these are useful depends largely on the local environment:
+if someone cares about the language and has worked on it,
+it may be in good shape.
+If not, the odds are strong that it
+will be more trouble than it's worth.
diff --git a/share/doc/usd/01.begin/u5 b/share/doc/usd/01.begin/u5
new file mode 100644
index 00000000000..d26fed3d993
--- /dev/null
+++ b/share/doc/usd/01.begin/u5
@@ -0,0 +1,219 @@
+.\" $NetBSD: u5,v 1.1 2007/11/29 12:35:07 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)u5 8.1 (Berkeley) 6/8/93
+.\"
+.SH
+V. UNIX READING LIST
+.SH
+General:
+.LP
+K. L. Thompson and D. M. Ritchie,
+.IT The
+.ul
+.UC UNIX
+.ul
+Programmer's Manual,
+Bell Laboratories, 1978 (PS2:3)\(dd
+Lists commands,
+system routines and interfaces, file formats,
+and some of the maintenance procedures.
+You can't live without this,
+although you will probably only need to read section 1.
+.LP
+D. M. Ritchie and K. L. Thompson,
+``The
+.UC UNIX
+Time-sharing System,''
+CACM, July 1974. (PS2:1)\(dd
+.FS
+\(dg These documents (previously in Volume 2 of the Bell Labs
+Unix distribution) are provided among the "User Supplementary"
+Documents for 4.3BSD, available from the Usenix Association.
+.FE
+.FS
+\(dd These are among the "Programmer Supplementary" Documents for 4.3BSD.
+PS1 is Volume 1, PS2 is Volume 2.
+.FE
+An overview of the system,
+for people interested in operating systems.
+Worth reading by anyone who programs.
+Contains a remarkable number of one-sentence observations
+on how to do things right.
+.LP
+The Bell System Technical Journal
+(BSTJ)
+Special Issue on
+.UC UNIX ,
+July/August, 1978,
+contains many papers describing recent developments,
+and some retrospective material.
+.LP
+The 2nd International Conference on Software Engineering
+(October, 1976)
+contains several
+papers describing the use of the
+Programmer's Workbench
+.UC PWB ) (
+version of
+.UC UNIX .
+.SH
+Document Preparation:
+.LP
+B. W. Kernighan,
+``A Tutorial Introduction to the
+.UC UNIX
+Text Editor'' (USD:12)
+and
+``Advanced Editing on
+.UC UNIX ,''
+(USD:13) Bell Laboratories, 1978.\(dg
+Beginners need the introduction;
+the advanced material will help you get the most
+out of the editor.
+.LP
+M. E. Lesk,
+``Typing Documents on
+.UC UNIX ,''
+Bell Laboratories, 1978. (USD:20)\(dg
+Describes the
+.UL \-ms
+macro package, which isolates the novice
+from the vagaries of
+.UL nroff
+and
+.UL troff ,
+and takes care of most formatting situations.
+If this specific package isn't available on your system,
+something similar probably is.
+The most likely alternative is the
+.UC PWB/UNIX
+macro package
+.UL \-mm ;
+see your local guru if you use
+.UC PWB/UNIX .*
+.FS
+*The macro package -me is additionally available on Berkeley Unix Systems.
+-mm is typically not available.
+.FE
+.LP
+B. W. Kernighan and L. L. Cherry,
+``A System for Typesetting Mathematics,''
+Bell Laboratories Computing Science Tech. Rep. 17. (USD:26)\(dg
+.LP
+M. E. Lesk,
+``Tbl \(em A Program to Format Tables,''
+Bell Laboratories CSTR 49, 1976. (USD:28)\(dg
+.LP
+J. F. Ossanna, Jr.,
+``NROFF/TROFF User's Manual,''
+Bell Laboratories CSTR 54, 1976. (USD:24)\(dg
+.UL troff
+is the basic formatter used by
+.UL \-ms ,
+.UL eqn
+and
+.UL tbl .
+The reference manual is indispensable
+if you are going to write or maintain these
+or similar programs.
+But start with:
+.LP
+B. W. Kernighan,
+``A TROFF Tutorial,''
+Bell Laboratories, 1976. (USD:25)\(dg
+An attempt to unravel the intricacies of
+.UL troff .
+.SH
+Programming:
+.LP
+B. W. Kernighan and D. M. Ritchie,
+.ul
+The C Programming Language,
+Prentice-Hall, 1978.
+Contains a tutorial introduction,
+complete discussions of all language features,
+and the reference manual.
+.LP
+B. W. Kernighan and R. Pike,
+.ul
+The Unix Programming Environment,
+Prentice-Hall, 1984.
+Contains many examples of C programs which use the system
+interfaces, and explanations of ``why''.
+.LP
+B. W. Kernighan and D. M. Ritchie,
+.UC UNIX \& ``
+Programming,''
+Bell Laboratories, 1978. (PS2:3)\(dd
+Describes how to interface with the system from C programs:
+I/O calls, signals, processes.
+.LP
+S. R. Bourne,
+``An Introduction to the
+.UC UNIX
+Shell,''
+Bell Laboratories, 1978. (USD:3)\(dg
+An introduction and reference manual for the Version 7 shell.
+Mandatory reading if you intend to make effective use
+of the programming power
+of this shell.
+.LP
+S. C. Johnson,
+``Yacc \(em Yet Another Compiler-Compiler,''
+Bell Laboratories CSTR 32, 1978. (PS1:15)\(dd
+.LP
+M. E. Lesk,
+``Lex \(em A Lexical Analyzer Generator,''
+Bell Laboratories CSTR 39, 1975. (PS1:16)\(dd
+.LP
+S. C. Johnson,
+``Lint, a C Program Checker,''
+Bell Laboratories CSTR 65, 1977. (PS1:9)\(dd
+.LP
+S. I. Feldman,
+``MAKE \(em A Program for Maintaining Computer Programs,''
+Bell Laboratories CSTR 57, 1977. (PS1:12)\(dd
+.LP
+J. F. Maranzano and S. R. Bourne,
+``A Tutorial Introduction to ADB,''
+Bell Laboratories CSTR 62, 1977. (PS1:10)\(dd
+An introduction to a powerful but complex debugging tool.
+.LP
+S. I. Feldman and P. J. Weinberger,
+``A Portable Fortran 77 Compiler,''
+Bell Laboratories, 1978. (PS1:2)\(dd
+A full Fortran 77 for
+.UC UNIX
+systems.
diff --git a/share/doc/usd/17.msmacros/Makefile b/share/doc/usd/17.msmacros/Makefile
new file mode 100644
index 00000000000..5d9ae1304e6
--- /dev/null
+++ b/share/doc/usd/17.msmacros/Makefile
@@ -0,0 +1,11 @@
+# $NetBSD: Makefile,v 1.1 2007/11/29 12:35:07 mjf Exp $
+
+DIR= usd/17.msmacros
+SRCS= ms fig1.pic
+MACROS= -ms
+
+paper.ps: ${SRCS}
+ ${TOOL_SOELIM} ${SRCS} | ${TOOL_PIC} | ${TOOL_TBL} | ${TOOL_EQN} | \
+ ${TOOL_ROFF_PS} ${MACROS} > ${.TARGET}
+
+.include <bsd.doc.mk>
diff --git a/share/doc/usd/17.msmacros/fig1.pic b/share/doc/usd/17.msmacros/fig1.pic
new file mode 100644
index 00000000000..9d90d549ea4
--- /dev/null
+++ b/share/doc/usd/17.msmacros/fig1.pic
@@ -0,0 +1,45 @@
+.\" Copyright (c) 1993
+.\" The Regents of the University of California. All rights reserved.
+.\"
+.\" @(#)fig1.pic 8.1 (Berkeley) 8/14/93
+.PS
+.ps
+.ps 10
+line from 5.612,3.388 to 5.612,2.888
+line from 4.237,4.888 to 4.237,4.763 to 5.612,4.763
+line from 3.175,5.700 to 3.175,5.513 to 5.612,5.513
+line from 3.237,9.700 to 3.237,9.512 to 2.425,9.512
+line from 4.237,6.825 to 4.237,5.138
+line from 4.212,5.237 to 4.237,5.138 to 4.263,5.237
+line from 2.425,6.950 to 2.425,6.825 to 5.612,6.825 to 5.612,4.638
+line from 5.587,4.737 to 5.612,4.638 to 5.638,4.737
+line from 2.425,9.387 to 3.175,9.387 to 3.175,6.700
+line from 3.150,6.800 to 3.175,6.700 to 3.200,6.800
+line from 2.425,10.200 to 3.237,10.200 to 3.237,9.950
+line from 3.212,10.050 to 3.237,9.950 to 3.262,10.050
+line from 5.612,4.388 to 5.612,3.575
+line from 5.587,3.675 to 5.612,3.575 to 5.638,3.675
+line from 3.175,6.388 to 3.175,5.825
+line from 3.150,5.925 to 3.175,5.825 to 3.200,5.925
+line from 2.425,7.950 to 2.425,7.200
+line from 2.400,7.300 to 2.425,7.200 to 2.450,7.300
+line from 2.425,8.950 to 2.425,8.137
+line from 2.400,8.237 to 2.425,8.137 to 2.450,8.237
+line from 2.425,10.387 to 2.425,9.200
+line from 2.400,9.300 to 2.425,9.200 to 2.450,9.300
+.ps
+.ps 12
+.ft
+.ft R
+"RP" at 3.175,9.796 ljust
+"text..." at 5.487,3.483 ljust
+"PP, LP" at 5.425,4.483 ljust
+"NH, SH" at 3.987,4.983 ljust
+"AE" at 3.112,5.733 ljust
+"AB" at 3.112,6.546 ljust
+"AI" at 2.362,7.046 ljust
+"AU" at 2.362,7.983 ljust
+"TL" at 2.362,9.046 ljust
+.ps
+.ft
+.PE
diff --git a/share/doc/usd/17.msmacros/fig1.xfig b/share/doc/usd/17.msmacros/fig1.xfig
new file mode 100644
index 00000000000..d77c89f3d6c
--- /dev/null
+++ b/share/doc/usd/17.msmacros/fig1.xfig
@@ -0,0 +1,46 @@
+#FIG 2.0
+80 2
+2 1 0 1 0 0 0 0 0.000 0 0
+ 449 569 449 609 9999 9999
+2 1 0 1 0 0 0 0 0.000 0 0
+ 339 449 339 459 449 459 9999 9999
+2 1 0 1 0 0 0 0 0.000 0 0
+ 254 384 254 399 449 399 9999 9999
+2 1 0 1 0 0 0 0 0.000 0 0
+ 259 64 259 79 194 79 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 339 294 339 429 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 194 284 194 294 449 294 449 469 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 194 89 254 89 254 304 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 194 24 259 24 259 44 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 449 489 449 554 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 254 329 254 374 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 194 204 194 264 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 194 124 194 189 9999 9999
+2 1 0 1 0 0 0 0 0.000 1 0
+ 0 0 1.000 4.000 8.000
+ 194 9 194 104 9999 9999
+4 0 0 12 0 0 0 0.000 1 9 15 254 59 RP
+4 0 0 12 0 0 0 0.000 1 7 29 439 564 text...
+4 0 0 12 0 0 0 0.000 1 11 34 434 484 PP, LP
+4 0 0 12 0 0 0 0.000 1 11 40 319 444 NH, SH
+4 0 0 12 0 0 0 0.000 1 9 17 249 384 AE
+4 0 0 12 0 0 0 0.000 1 9 17 249 319 AB
+4 0 0 12 0 0 0 0.000 1 9 13 189 279 AI
+4 0 0 12 0 0 0 0.000 1 9 17 189 204 AU
+4 0 0 12 0 0 0 0.000 1 9 14 189 119 TL
diff --git a/share/doc/usd/17.msmacros/ms b/share/doc/usd/17.msmacros/ms
new file mode 100644
index 00000000000..fd6edc549a6
--- /dev/null
+++ b/share/doc/usd/17.msmacros/ms
@@ -0,0 +1,932 @@
+.\" $NetBSD: ms,v 1.1 2007/11/29 12:35:07 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)ms 8.2 (Berkeley) 6/1/94
+.\"
+.if n \{\
+.po 5n
+.ll 70n
+.\}
+.EH 'USD:17-%''Using the \-ms Macros with Troff and Nroff'
+.OH 'Using the \-ms Macros with Troff and Nroff''USD:17-%'
+.\".RP
+.\" ....TM 76-1274-16 39199 39199-11
+.\" ....ND October 8, 1976
+.nr CW 2.85i
+.nr GW .3i
+.TL
+Typing Documents on the UNIX System:
+.br
+\!.br
+Using the \-ms Macros with Troff and Nroff
+.AU "MH 2C-572" 6377
+M. E. Lesk
+.AI
+.\" .MH
+.\" .OK
+\"Text Formatting
+\"Phototypesetting
+.AB
+This document describes a set of easy-to-use macros
+for preparing documents on the UNIX system.
+Documents may be produced on either the
+phototypesetter or on a computer terminal,
+without changing the input.
+.PP
+The macros provide facilities for paragraphs, sections (optionally
+with automatic numbering), page titles, footnotes,
+equations,
+tables, two-column format, and
+cover pages for papers.
+.PP
+This memo includes, as an appendix,
+the text of the ``Guide to Preparing
+Documents with \-ms''
+which contains additional examples
+of features of \-ms.
+.PP
+This manual is a revision of, and replaces,
+``Typing Documents on UNIX,''
+dated November 22, 1974.
+.AE
+.\" .CS 6 6 12 1 0 8
+.bd I 3
+.PP
+.I
+Introduction.
+.R
+This memorandum describes a package of commands to produce
+papers
+using the
+.bd I
+.I
+troff
+.R
+and
+.I nroff
+formatting programs on the
+.SM
+UNIX
+.NL
+system.
+As with other
+.I roff -derived
+programs,
+text is prepared interspersed with formatting commands.
+However, this package,
+which itself is written in
+.I troff
+commands,
+provides higher-level commands
+than those provided with the basic
+.I troff
+program.
+The commands available in this package are listed in
+Appendix A.
+.bd I 3
+.PP
+.I
+Text.
+.R
+Type normally, except that instead of indenting for paragraphs,
+place a line reading ``.PP'' before each paragraph.
+This will produce indenting and extra space.
+.LP
+Alternatively, the command .LP that was used here will produce
+a left-aligned (block) paragraph.
+The paragraph spacing can be changed: see below under ``Registers.''
+.PP
+.I
+Beginning.
+.R
+For a document with a paper-type cover sheet, the input should start as follows:
+.DS L
+ [optional overall format .RP \- see below]
+ .TL
+ Title of document (one or more lines)
+ .AU
+ Author(s) (may also be several lines)
+ .AI
+ Author's institution(s)
+ .AB
+ Abstract; to be placed on the cover sheet of a paper.
+ Line length is 5/6 of normal; use .ll here to change.
+ .AE (abstract end)
+ text ... (begins with .PP, which see)
+.DE
+To omit some of the standard headings
+(e.g. no abstract, or no author's institution) just
+omit the corresponding fields and command lines.
+The word
+.SM
+ABSTRACT
+.NL
+can be suppressed by writing ``.AB no'' for ``.AB''.
+Several interspersed .AU and .AI lines can be used for multiple authors.
+The headings are not compulsory: beginning
+with a .PP command is perfectly OK and will just
+start printing an ordinary paragraph.
+.I Warning:
+You can't just begin a document with a line of text.
+Some \-ms command must
+precede any text input. When in doubt, use .LP
+to get proper initialization, although any of
+the commands .PP, .LP, .TL, .SH, .NH is good enough.
+Figure 1 shows the legal arrangement of commands at the
+start of a document.
+.PP
+.I
+Cover Sheets and First Pages.
+.R
+The first line
+of a document signals the general format of the first page.
+In particular, if it is ".RP" a cover sheet with title and
+abstract is prepared.
+The default format
+is useful for scanning drafts.
+.PP
+In general \-ms is arranged so that only one form
+of a document need be stored, containing all
+information; the first command gives the format,
+and unnecessary items for that format are ignored.
+.PP
+Warning: don't put extraneous material
+between the .TL and .AE commands. Processing
+of the titling items is
+special, and other data placed in them may not behave
+as you expect.
+Don't forget that some \-ms command must precede any input text.
+.PP
+.I
+Page headings.
+.R
+The \-ms macros, by default, will print a page heading containing
+a page number (if greater than 1).
+A default page footer is provided only in
+.I nroff ,
+where the date is used.
+The user can make minor adjustments to the page headings/footings
+by redefining the
+strings
+LH, CH, and RH
+which are the left, center and right portions of the page headings,
+respectively; and the
+strings
+LF, CF, and RF,
+which are the left, center and right portions of the page footer.
+For more complex formats, the user can redefine
+the macros PT and BT, which are invoked respectively at the top
+and bottom of each page.
+The margins (taken from registers HM and FM for the top and bottom
+margin respectively) are normally 1 inch; the page header/footer are
+in the middle of that space.
+The user who redefines these macros should be careful
+not to change parameters such as point size or font
+without resetting them to default values.
+.PP
+.I
+Multi-column formats.
+.R
+If you place the command ``.2C'' in your document, the document will
+be printed in double column format beginning
+at that point. This feature is not too useful in computer
+terminal output, but is often desirable on the typesetter.
+The command ``.1C'' will go
+back to one-column format and also skip to a new page.
+The ``.2C'' command is actually a special case of the command
+.DS L
+ .MC [column width [gutter width]]
+.DE
+which makes multiple columns with the specified column
+and gutter width; as many columns as will fit across the page
+are used.
+Thus triple, quadruple, ... column pages can be printed.
+Whenever the number of columns is changed (except going from
+full width to some larger number of columns)
+a new page is started.
+.PP
+.I
+Headings.
+.R
+To produce a special heading, there are two commands.
+If you type
+.DS L
+ .NH
+ type section heading here
+ may be several lines
+.DE
+you will get automatically numbered section headings (1, 2, 3, ...),
+in boldface.
+For example,
+.DS L
+ .NH
+ Care and Feeding of Department Heads
+.DE
+produces
+.NH
+Care and Feeding of Department Heads
+.PP
+Alternatively,
+.DS L
+ .SH
+ Care and Feeding of Directors
+.DE
+will print the heading with no number added:
+.SH
+Care and Feeding of Directors
+.PP
+Every section heading, of either type, should be followed
+by a paragraph beginning with .PP or .LP, indicating
+the end of the heading.
+Headings may contain more than one line
+of text.
+.PP
+The .NH command also supports more complex numbering schemes.
+If a numerical argument is given, it is taken to be a
+``level'' number and an appropriate sub-section
+number is generated.
+Larger level numbers indicate deeper
+sub-sections, as in this example:
+.DS L
+ .NH
+ Erie-Lackawanna
+ .NH 2
+ Morris and Essex Division
+ .NH 3
+ Gladstone Branch
+ .NH 3
+ Montclair Branch
+ .NH 2
+ Boonton Line
+.DE
+.ne 1i
+generates:
+.NH
+Erie-Lackawanna
+.NH 2
+Morris and Essex Division
+.NH 3
+Gladstone Branch
+.NH 3
+Montclair Branch
+.NH 2
+Boonton Line
+.PP
+An explicit ``.NH 0'' will reset the numbering of level 1
+to one, as here:
+.DS L
+ .NH 0
+ Penn Central
+.DE
+.ft 3
+.if n .ul 1
+.sp 1
+1. Penn Central
+.PP
+.I
+Indented paragraphs.
+.R
+(Paragraphs with hanging numbers, e.g. references.)
+The sequence
+.DS L
+ .IP [1]
+ Text for first paragraph, typed
+ normally for as long as you would
+ like on as many lines as needed.
+ .IP [2]
+ Text for second paragraph, ...
+.DE
+produces
+.IP [1]
+Text for first paragraph, typed normally for as long
+as you would like on as many lines as
+needed.
+.IP [2]
+Text for second paragraph, ...
+.LP
+A series of indented paragraphs may be followed by an ordinary paragraph
+beginning with .PP or .LP,
+depending on whether you wish indenting or not.
+The command .LP was used here.
+.PP
+More sophisticated uses of .IP are also possible.
+If the label is omitted, for example, a plain block indent
+is produced.
+.DS L
+ .IP
+ This material will
+ just be turned into a
+ block indent suitable for quotations or
+ such matter.
+ .LP
+.DE
+will produce
+.IP
+This material
+will just be turned
+into a block indent
+suitable for
+quotations or such matter.
+.LP
+If a non-standard amount of indenting is required,
+it may be specified after the label (in character positions)
+and will remain in effect until the next .PP or .LP.
+Thus, the general form of the .IP command
+contains two additional fields: the label and the indenting
+length. For example,
+.DS L
+ .IP first: 9
+ Notice the longer label, requiring larger
+ indenting for these paragraphs.
+ .IP second:
+ And so forth.
+ .LP
+.DE
+produces this:
+.IP first: 9
+Notice the longer label, requiring larger
+indenting for these paragraphs.
+.IP second:
+And so forth.
+.LP
+It is also possible to produce multiple nested indents;
+the command .RS indicates that the next .IP starts from the
+current indentation level.
+Each .RE will eat up one level of indenting
+so you should balance .RS and .RE commands.
+The .RS command should be thought of as ``move right'' and
+the .RE command as ``move left''.
+As an example
+.DS L
+ .IP 1.
+ Bell Laboratories
+ .RS
+ .IP 1.1
+ Murray Hill
+ .IP 1.2
+ Holmdel
+ .IP 1.3
+ Whippany
+ .RS
+ .IP 1.3.1
+ Madison
+ .RE
+ .IP 1.4
+ Chester
+ .RE
+ .LP
+.DE
+will result in
+.IP 1.
+Bell Laboratories
+.RS
+.IP 1.1
+Murray Hill
+.IP 1.2
+Holmdel
+.IP 1.3
+Whippany
+.RS
+.IP 1.3.1
+Madison
+.RE
+.IP 1.4
+Chester
+.RE
+.LP
+All of these variations on .LP leave the right
+margin untouched. Sometimes, for purposes
+such as setting off a quotation, a paragraph indented
+on both right and left is required.
+.QP
+A single paragraph
+like this is obtained
+by preceding it with .QP.
+More complicated material (several paragraphs) should be
+bracketed with .QS and .QE.
+.LP
+.I
+Emphasis.
+.R
+To get
+italics
+(on the typesetter) or underlining (on the terminal)
+say
+.DS L
+ .I
+ as much text as you want
+ can be typed here
+ .R
+.DE
+.bd I
+.br
+as was done for
+.I
+these three words.
+.R
+The .R command restores the normal (usually Roman) font.
+If only one word is to be italicized, it
+may be just given on the line with the .I command,
+.br
+.bd I 3
+.DS
+ .I word
+.DE
+and in this case no .R is needed to restore
+the previous font.
+.B
+Boldface
+.R
+can be produced by
+.DS L
+ .B
+ Text to be set in boldface
+ goes here
+ .R
+.DE
+and also will be underlined on the terminal or line printer.
+As with .I, a single word can be placed in boldface
+by placing it on the same line as the .B command.
+.PP
+A few size changes
+can be specified similarly with
+the commands .LG (make larger), .SM (make smaller), and .NL
+(return to normal size).
+The size change
+is two points; the commands may be repeated for
+.SM
+increased
+.SM
+effect
+.NL
+(here one .NL canceled two .SM commands).
+.PP
+If actual
+.UL underlining
+as opposed to italicizing is required on the typesetter,
+the command
+.DS
+ .UL word
+.DE
+will underline a word. There is no way to underline
+multiple words on the typesetter.
+.PP
+.I
+Footnotes.
+.R
+Material placed between lines with the commands .FS
+(footnote) and .FE (footnote end) will
+be collected, remembered, and finally placed
+at the bottom of the current page*.
+By default, footnotes are 11/12th the
+length of normal text,
+but this can be changed using the FL register (see below).
+.FS
+* Like this.
+.FE
+.PP
+.I
+Displays and Tables.
+.R
+To prepare displays of lines, such as tables, in which
+the lines should not be re-arranged,
+enclose them in the commands .DS and .DE
+.DS L
+ .DS
+ table lines, like the
+ examples here, are placed
+ between .DS and .DE
+ .DE
+.DE
+By default, lines between .DS and .DE are indented and left-adjusted.
+You can also center lines, or retain the left margin.
+Lines bracketed by .DS C and .DE commands are
+centered (and not re-arranged); lines bracketed
+by .DS L and .DE are left-adjusted, not indented, and
+not re-arranged.
+A plain .DS is equivalent
+to .DS I, which indents and left-adjusts. Thus,
+.DS C
+these lines were preceded
+by .DS C and followed by
+a .DE command;
+.DE
+whereas
+.DS L
+these lines were preceded
+by .DS L and followed by
+a .DE command.
+.DE
+Note that .DS C centers each line; there is a variant .DS B
+that makes the display into a left-adjusted block of text, and
+then centers that entire block.
+Normally a display is kept together, on one page.
+If you wish to have a long display which
+may be split across page
+boundaries,
+use .CD, .LD, or .ID in place of
+the commands .DS C, .DS L, or .DS I respectively.
+An extra argument to the .DS I or .DS command is taken
+as an amount to indent.
+Note: it is tempting to assume that .DS R will right adjust
+lines, but it doesn't work.
+.PP
+.I
+Boxing words or lines.
+.R
+To draw rectangular boxes around words the command
+.DS L
+ .BX word
+.DE
+will print
+.BX word
+as shown.
+The boxes will not be neat on a terminal, and this
+should not be used as a substitute for italics.
+.B1
+Longer pieces of text may be boxed
+by enclosing them with .B1 and .B2:
+.DS L
+ .B1
+ text...
+ .B2
+.DE
+as has been done here.
+.B2
+.ne 1i
+.PP
+.I
+Keeping blocks together.
+.R
+If you wish to keep a table or other block of lines
+together on a page, there are ``keep - release'' commands.
+If a block of lines preceded by .KS and followed by .KE does
+not fit on the remainder of the current page, it will begin
+on a new page.
+Lines bracketed by .DS and .DE commands are automatically
+kept together this way.
+There is also a ``keep floating'' command: if the
+block to be kept together is preceded by .KF instead of .KS
+and does not fit
+on the current page, it will be moved down through the text
+until the top of the next page. Thus, no large blank space
+will be introduced in the document.
+.PP
+.I
+Nroff/Troff commands.
+.R
+Among the useful commands from the basic formatting programs
+are the following. They all work with both typesetter and
+computer terminal output:
+.DS L
+ .bp - begin new page.
+ .br - ``break'', stop running text
+ from line to line.
+ .sp n - insert n blank lines.
+ .na - don't adjust right margins.
+.DE
+.PP
+.I
+Date.
+.R
+By default, documents produced on computer terminals have the
+date at the bottom of each page; documents produced on
+the typesetter don't.
+To force the date, say ``.DA''. To force no date, say ``.ND''.
+To lie about the date, say ``.DA July 4, 1776''
+which puts the specified date at the bottom of each page.
+The command
+.DS L
+ .ND May 8, 1945
+.DE
+in ".RP" format
+places the specified date on the cover sheet and nowhere else.
+Place this line before the title.
+.PP
+.I
+Registers.
+.R
+Certain of the registers used by \-ms can
+be altered to change default
+settings.
+They should be changed with .nr commands,
+as with
+.DS
+ .nr PS 9
+.DE
+.bd I
+to make the default point size 9 point.
+If the effect is needed immediately, the
+normal
+.I
+troff
+.R
+command should be used
+in addition to changing the number register.
+.br
+.ps 9
+.vs 10p
+.TS
+c0 c c c
+c c c c
+a l l l.
+Register Defines Takes Default
+ effect
+PO page offset next page 1\(fm\(fm
+LL line length next para. 6\(fm\(fm
+LT title length next para. 6\(fm\(fm
+HM top margin next page 1\(fm\(fm
+FM bottom margin next page 1\(fm\(fm
+PS point size next para. 10 pts
+VS line spacing next para. 12 pts
+PI para. indent next para. 5 ens
+PD para. spacing next para. 0.3 VS
+QI quote para ind next para. 5 ens
+FL footnote length next FS *5/6 LL
+FI footnote indent next FS *5/6 LL
+FF footnote format next FS *5/6 LL
+MINGW min. column wid next page 2 ens
+.TE
+.ps \n(PS
+.vs \n(VS
+You may also alter
+the strings
+LH, CH, and RH which are the left, center, and right headings
+respectively; and similarly LF, CF, and RF which are strings in the
+page footer.
+The page number on
+.I
+output
+.R
+is taken from register PN, to permit
+changing its output style.
+For more complicated headers and footers
+the macros PT and BT can be redefined, as
+explained earlier.
+.bd I 3
+.PP
+.I
+Accents.
+.R
+To simplify typing certain foreign words,
+strings representing common accent marks are defined.
+They precede the letter over which the mark
+is to appear.
+Here are the strings:
+.TS
+center;
+c c6 c c.
+Input Output Input Output
+\e*\(fme \*'e \e*~a \*~a
+\e*\(gae \*`e \e*Ce \h'0.15m'\v'-0.6m'\s6\zv\s0\v'0.6m'\h'-0.15m'e
+\e*:u \*:u \e*,c \*,c
+\e*^e \o'^e'
+.TE
+.PP
+.I
+Use.
+.R
+After your document is prepared and stored on a file,
+you can print it on a terminal with the command*
+.bd I
+.FS
+* If .2C was used, pipe the
+.I nroff
+output
+through
+.I col;
+make the first line of the input
+``.pi /usr/bin/col.''
+.br
+.FE
+.DS L
+.I
+ nroff \-ms file
+.R
+.DE
+and you can print it on the typesetter with the
+command
+.DS L
+.I
+ troff \-ms file
+.R
+.DE
+(many options are possible).
+In each case, if your document is stored in several files,
+just list all the filenames
+where we have used ``file''.
+If equations or tables are used,
+.I
+eqn
+.R
+and/or
+.I
+tbl
+.R
+must be invoked as preprocessors.
+.br
+.bd I 3
+.PP
+.I
+References and further study.
+.R
+If you have to do Greek or mathematics, see
+.I eqn
+[1]
+for equation setting.
+To aid
+.I eqn
+users,
+.I \-ms
+provides definitions of .EQ and .EN
+which normally center the equation and set it off slightly.
+An argument on .EQ is taken to be an equation
+number and placed in the right margin near the equation.
+In addition, there are three special arguments to EQ:
+the letters C, I, and L indicate centered (default),
+indented, and left adjusted equations, respectively.
+If there is both a format argument
+and an equation number,
+give the format argument first, as in
+.bd I
+.DS
+ .EQ L (1.3a)
+.DE
+for a left-adjusted equation numbered (1.3a).
+.PP
+Similarly,
+the macros .TS and .TE
+are defined
+to separate tables (see [2]) from text with a little space.
+A very long table with a heading may be broken
+across pages by beginning it with .TS H
+instead of .TS,
+and placing the line .TH in the table data
+after the heading. If the table
+has no heading repeated from page to page,
+just use the ordinary .TS and .TE macros.
+.PP
+To learn more about
+.I troff
+see
+[3] for a general introduction, and [4]
+for the full details (experts only).
+Information on related UNIX commands
+is in [5].
+For jobs that do not seem well-adapted
+to \-ms, consider other macro packages.
+It is often far easier to write a specific macro packages
+for such tasks as imitating particular journals than
+to try to adapt \-ms.
+.PP
+.bd I 3
+.I
+Acknowledgment.
+.R
+Many thanks are due to Brian Kernighan for
+his help in the design and implementation of this package,
+and for his assistance in preparing this manual.
+.bd I
+.SH
+.ce
+References
+.PP
+.IP [1]
+B. W. Kernighan and L. L. Cherry,
+.I
+Typesetting Mathematics \(em Users Guide (2nd edition),
+.R
+Bell Laboratories Computing Science Report no. 17.
+.IP [2]
+M. E. Lesk,
+.I
+Tbl \(em A Program to Format Tables,
+.R
+Bell Laboratories Computing Science Report no. 45.
+.IP [3]
+B. W. Kernighan,
+.I
+A Troff Tutorial,
+.R
+Bell Laboratories, 1976.
+.IP [4]
+J. F. Ossanna,
+.I
+Nroff\|/Troff Reference Manual,
+.R
+Bell Laboratories Computing Science Report no. 51.
+.IP [5]
+K. Thompson and D. M. Ritchie,
+.I
+UNIX Programmer's Manual,
+.R
+Bell Laboratories, 1978.
+.1C
+.SH
+.ce
+Appendix A
+.ce
+List of Commands
+.ft R
+.TS
+expand;
+l2 l5 l2 l.
+1C Return to single column format. LG Increase type size.
+2C Start double column format. LP Left aligned block paragraph.
+AB Begin abstract.
+AE End abstract.
+AI Specify author's institution.
+AU Specify author. ND Change or cancel date.
+B Begin boldface. NH Specify numbered heading.
+DA Provide the date on each page. NL Return to normal type size.
+DE End display. PP Begin paragraph.
+DS Start display (also CD, LD, ID).
+EN End equation. R Return to regular font (usually Roman).
+EQ Begin equation. RE End one level of relative indenting.
+FE End footnote. RP Use released paper format.
+FS Begin footnote. RS Relative indent increased one level.
+I Begin italics. SH Specify section heading.
+ SM Change to smaller type size.
+IP Begin indented paragraph. TL Specify title.
+KE Release keep.
+KF Begin floating keep. UL Underline one word.
+KS Start keep.
+.TE
+.sp
+.ce
+.ft B
+Register Names
+.ft R
+.PP
+The following register names are used by \-ms internally.
+Independent use of these names in one's own macros may
+produce incorrect output.
+Note that no lower case letters are used in any \-ms internal name.
+.TS
+ expand;
+c s s s s s s s s s s
+l l l l l l l l l l l.
+Number registers used in \-ms
+: DW GW HM IQ LL NA OJ PO T. TV
+#T EF H1 HT IR LT NC PD PQ TB VS
+\&.T FC H2 IF IT MF ND PE PS TC WF
+1T FL H3 IK KI MM NF PF PX TD YE
+AV FM H4 IM L1 MN NS PI RO TN YY
+CW FP H5 IP LE MO OI PN ST TQ ZN
+.TE
+.sp
+.TS
+expand;
+c s s s s s s s s s s
+l l l l l l l l l l l.
+String registers used in \-ms
+\(fm A5 CB DW EZ I KF MR R1 RT TL
+\(ga AB CC DY FA I1 KQ ND R2 S0 TM
+^ AE CD E1 FE I2 KS NH R3 S1 TQ
+~ AI CF E2 FJ I3 LB NL R4 S2 TS
+: AU CH E3 FK I4 LD NP R5 SG TT
+, B CM E4 FN I5 LG OD RC SH UL
+1C BG CS E5 FO ID LP OK RE SM WB
+2C BT CT EE FQ IE ME PP RF SN WH
+A1 C D EL FS IM MF PT RH SY WT
+A2 C1 DA EM FV IP MH PY RP TA XD
+A3 C2 DE EN FY IZ MN QF RQ TE XF
+A4 CA DS EQ HO KE MO R RS TH XK
+.TE
+.\" .(z
+.\".so fig1.pic
+.ce 2
+Figure 1:\ \ Order of Commands in Input
+.ce 0
+.\" .)z
diff --git a/share/doc/usd/17.msmacros/refcard b/share/doc/usd/17.msmacros/refcard
new file mode 100644
index 00000000000..a5f20e3551d
--- /dev/null
+++ b/share/doc/usd/17.msmacros/refcard
@@ -0,0 +1,1289 @@
+.\" $NetBSD: refcard,v 1.1 2007/11/29 12:35:07 mjf Exp $
+.\"
+.\" Copyright (C) Caldera International Inc. 2001-2002.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code and documentation must retain the above
+.\" copyright notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed or owned by Caldera
+.\" International, Inc.
+.\" 4. Neither the name of Caldera International, Inc. nor the names of other
+.\" contributors may be used to endorse or promote products derived from
+.\" this software without specific prior written permission.
+.\"
+.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
+.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" @(#)refcard 8.1 (Berkeley) 6/8/93
+.\"
+.fp 3 gB
+.po .5i
+.de I
+.ft 2
+..
+.de R
+.ft 1
+..
+.de B
+.bd R 2
+\\$1
+.bd R
+..
+.de hh
+.br
+.vs 10p
+.ps 12
+.bd 1 3
+.ce
+\\$1
+.ps 9
+.br
+.bd 1
+.sp
+..
+.de NP
+'po 0
+.ps 9
+.ta .25i 3.75i 7.25i 7.7i
+\(rn\t|\t|\t|\t\(rn
+'po
+'sp .2i
+.mk z
+..
+.de FT
+.po 0
+.ps 9
+.ta .25i 3.75i 7.25i
+ | | |
+.po .5i
+..
+.wh -8p FT
+.de b1
+.br
+.tm left col bottom at \\n(nl
+.po +3.5i
+.sp |\\nzu
+.ph
+..
+.de b2
+.br
+.tm right col bottom at \\n(nl
+.po -3.5i
+.bp
+.ph
+..
+.de ph
+.nr x +1
+.tl ''\\nx''
+.sp .2i
+..
+.nr x 1
+.wh 0 NP
+.ll 3i
+.lt 3i
+.nr LL 3i
+.nr IQ 4
+.nr IR 4
+.de IP
+.RT
+.if \\n(IP=0 .nr IP +1
+.if \\n(.$ .LB "\\$1"
+.if !\\n(.$ .LB
+..
+.de RT
+.if \\n(IP .in -\\n(IQn
+.if \\n(IP .nr IP -1
+..
+.de LP
+.RT
+.ti 0
+.ne 3
+.if \\n(.$ .LB \\$1
+..
+.de LB
+.in +\\n(IQn
+.ta \\n(IQn
+.if \\n(.$ .ti -\\n(IQn
+.if \\n(.$ \\$1\t\c
+..
+.de RS
+.in +\\n(IRn
+..
+. \"RE - retreat to the left
+.de RE
+.br
+.in -\\n(IRn
+..
+.br
+.rs
+.sp 1i
+.ps 14
+.vs 16p
+.ce 3
+A Guide to Preparing
+Documents with \-ms
+.sp 2
+.ps 10
+.vs 12p
+.ft I
+.ce
+M. E. Lesk
+.ft R
+.lt \n(.lu
+.sp .5
+.tl 'Bell Laboratories''August 1978'
+.sp .5
+.tl xx\l'\n(.lu'xx
+.sp 1
+.bd I 2
+.vs 11p
+.fi
+This guide gives some simple examples of
+document preparation on Bell Labs computers,
+emphasizing the use of the \fI\-ms\fR macro
+package.
+It enormously abbreviates
+information in
+.IP 1.
+.I
+Typing Documents on UNIX and GCOS,
+.R
+by M. E. Lesk;
+.IP 2.
+.I
+Typesetting Mathematics \- User's Guide,
+.R
+by B. W. Kernighan and L. L. Cherry; and
+.IP 3.
+.I
+Tbl \- A Program to Format Tables,
+.R
+by M. E. Lesk.
+.LP
+These memos are all included in the
+.I
+UNIX Programmer's Manual, Volume 2.
+.R
+The new user should also have
+.I
+A Tutorial Introduction to the UNIX Text Editor,
+.R
+by B. W. Kernighan.
+.sp .5
+For more detailed information, read
+.I
+Advanced Editing on UNIX
+.R
+and
+.I
+A Troff Tutorial,
+.R
+by B. W. Kernighan,
+and (for experts)
+.I
+Nroff\^/Troff Reference Manual
+.R
+by J. F. Ossanna.
+Information on related commands is
+found (for UNIX users) in
+.I
+UNIX for Beginners
+.R
+by B. W. Kernighan
+and the
+.I
+UNIX Programmer's Manual
+.R
+by K. Thompson and D. M. Ritchie.
+.br
+.vs 12p
+.sp 1.5
+.ce
+.ps +2
+Contents
+.nf
+.ps
+.sp .5
+.in .2i
+.bd I
+.ta 2.4i
+.cs I 25
+A TM \fI\fR 2
+A released paper \fI\fR 3
+An internal memo, and headings \fI\fR 4
+Lists, displays, and footnotes \fI\fR 5
+Indents, keeps, and double column \fI\fR 6
+Equations and registers \fI\fR 7
+Tables and usage \fI\fR 8
+.in 0
+.cs I
+.sp 1
+.fi
+.EQ
+delim $$
+.EN
+Throughout the examples, input is shown in
+.ft 3
+.br
+.ti +2n
+this Helvetica sans serif font
+.ft R
+.br
+while the resulting output is shown in
+.ti +2n
+this Times Roman font.
+.nf
+.sp 2
+.ce
+UNIX Document no. 1111
+.ps 9
+.vs 10p
+.EQ
+gsize 9
+.EN
+.b1
+.hh "Commands for a TM"
+.nf
+.ft 3
+\&.TM 1978-5b3 99999 99999-11
+\&.ND April 1, 1976
+\&.TL
+\&The Role of the Allen Wrench in Modern
+\&Electronics
+\&.AU "MH 2G-111" 2345
+\&J. Q. Pencilpusher
+\&.AU "MH 1K-222" 5432
+\&X. Y. Hardwired
+\&.AI
+\&.MH
+\&.OK
+\&Tools
+\&Design
+\&.AB
+\&This abstract should be short enough to
+\&fit on a single page cover sheet.
+\&It must attract the reader into sending for
+\&the complete memorandum.
+\&.AE
+\&.CS 10 2 12 5 6 7
+\&.NH
+\&Introduction.
+\&.PP
+\&Now the first paragraph of actual text ...
+\&...
+\&Last line of text.
+\&.SG MH-1234-JQP/XYH-unix
+\&.NH
+\&References ...
+.ft
+.sp
+.fi
+Commands not needed in a particular
+format are ignored.
+.sp
+.ps 8
+.vs 9p
+.mk a
+.sp .20i
+.ll 3i
+.nf
+\h'2n'\s16\(bs\s7 $fat roman size 7 "Bell Laboratories"$ \s8Cover Sheet for TM
+.sp
+\s6\l'3i'
+.fi
+.ps 7
+.ft 2
+.sp 1p
+This information is for employees of Bell Laboratories. (GEI 13.9-3)\p
+.ft 1
+.nf
+.vs 4p
+\s6\l'3i'
+.vs 9p
+.sp
+.ll 3.0i
+.ps 7
+.ta .25i 2.25i 2.45i
+.mk
+Title- \s8
+.rt
+.in .25i
+.hy 0
+.bd 1 2
+The Role of the Allen Wrench
+in Modern Electronics
+.hy 14
+.br
+.bd 1
+.rt
+.ll \\n(LLu
+.in 2.1i
+\s7Date- \s8
+.rt
+.in 2.35i
+.bd 1 2
+.ps 8
+April 1, 1976
+.sp
+.bd 1
+.ti 2.1i
+.mk
+\s7TM- \s8
+.br
+.rt
+.bd 1 2
+1978-5b3
+.rt
+.in 0
+.bd 1
+.sp
+.mk
+\s7Other Keywords- \kQ
+.rt
+.in \nQu
+.bd 1 2
+.ps 8
+Tools
+Design
+.rm OK
+.rm OD
+.in 0
+.bd 1
+.if t .sp .35i
+.ps 7
+.ta 1.05i 1.7i 2.0i
+Author Location Ext. Charging Case- \s8$fat roman size 8 99999$
+.nf
+.mk
+.bd 1 2
+.ps 8
+J. Q. Pencilpusher MH 2G-111 2345
+.rt
+.br
+.bd 1
+ \s7Filing Case- \s8$fat roman size 8 "99999a"$
+.br
+.bd 1 2
+X. Y. Hardwired MH 1K-222 5432
+.sp .2i
+.bd 1
+.br
+.ll 3i
+.ce
+.ft I
+ABSTRACT
+.ft 1
+.sp
+.fi
+.ps 8
+.ll 2.5i
+.in +.25i
+.ti +2
+This abstract should be short enough to fit
+on a single page cover sheet.
+It must attract the reader into sending for the
+complete memorandum.
+.in
+.ll
+.sp .4i
+.nf
+\l'3i'
+.ta .9i 1.8i 2.7i
+.sp 5p
+Pages Text 10 Other 2 Total 12
+.if t .sp 8p
+.if n .sp
+.if t No. Figures 5 No. Tables 6 No. Refs. 7 \b'|||||\ \ '
+\l'3i'
+.ps 6
+.if n .sp
+.lt 3i
+.tl 'E-1932-U (6-73)''SEE REVERSE SIDE FOR DISTRIBUTION LIST'
+.sp .20i
+.de eb
+.sp -1
+.nf
+\h'-1m'\L'|\\nau-1'\l'\\n(.lu+2m\(ul'\L'-|\\nau+1'\l'|0u-1m\(ul'
+.fi
+..
+.eb
+.b2
+.hh "A Released Paper with Mathematics"
+.ft 3
+.nf
+.EQ
+delim off
+.EN
+\&.EQ
+\&delim $$
+\&.EN
+\&.RP
+.sp
+.ft 1
+\&... (as for a TM)
+.sp
+.ft 3
+\&.CS 10 2 12 5 6 7
+\&.NH
+\&Introduction
+\&.PP
+\&The solution to the torque handle equation
+\&.EQ (1)
+\&sum from 0 to inf F ( x sub i ) = G ( x )
+\&.EN
+\&is found with the transformation $ x = rho over
+\&theta $ where $ rho = G prime (x) $ and $theta$
+\&is derived ...
+.ft 1
+.sp 2
+.mk a
+.ll 3i
+.ps 9
+.bd 1 2
+.sp .4i
+.ce 2
+.vs 11p
+The Role of the Allen Wrench
+in Modern Electronics
+.sp .7
+.ce 3
+.ft 2
+.bd 1
+.ps 8
+.vs 9p
+J. Q. Pencilpusher
+.sp .7
+X. Y. Hardwired
+.sp .7
+.ce 2
+.ft 1
+Bell Laboratories
+Murray Hill, New Jersey 07974
+.sp 2
+.ce
+.ft 2
+ABSTRACT
+.ft 1
+.sp .7
+.in +.25i
+.ll 2.75i
+.fi
+.ad
+.ti +2n
+This abstract should be short enough to fit
+on a single page cover sheet.
+It must attract the reader into sending for the
+complete memorandum.
+.sp 5v
+.in
+.ll
+April 1, 1976
+.sp .2i
+.eb
+.ll 3i
+.sp .5v
+.sp 3.5p
+.mk a
+.lt 3i
+.ps 9
+.sp .25i
+.bd 1 2
+.ce 2
+.vs 11p
+The Role of the Allen Wrench
+in Modern Electronics
+.sp
+.ce 3
+.bd 1
+.ft 2
+.ps 8
+.vs 9p
+J. Q. Pencilpusher
+.sp
+X. Y. Hardwired
+.sp
+.ce 2
+.ft 1
+Bell Laboratories
+Murray Hill, New Jersey 07974
+.sp 3
+.ce
+.de SH
+.bd 1 2
+.sp
+.ce 0
+.in 0
+..
+.de PP
+.sp .3
+.ft 1
+.bd 1
+.ti +2n
+..
+.SH
+1. Introduction
+.PP
+The solution to the torque handle equation
+.br
+.di xx
+.EQ
+delim $$
+gsize 8
+sum from 0 to inf F ( x sub i ) = G ( x )
+.EN
+.br
+.di
+.tl ''\*(10'(1)'
+is found with the transformation
+$ x = rho over theta $ where $ rho = G prime ( x )$
+and $theta$ is derived from well-known principles.
+......PP
+......ft 2
+.....The Ascent of the Riffelberg,
+......ft 1
+.....by Mark Twain.
+.....I sat silent some time, then turned to Harris and said:
+.....``My mind is made up.''
+.....Something in my tone struck him; and when he glanced
+.....at my eye and read what was written there, his face paled
+.....perceptibly. He hesitated a moment, then said:
+.....``Speak.''
+.....I answered, with perfect calmness:
+......ft 2
+.....``I will ascend the Riffelberg.''
+......ft 1
+.....If I had shot my poor friend he could not have fallen from
+.....his chair more suddenly. If I had been his father he
+.....could not have pleaded harder to get me to give up my
+.....purpose. But I turned a deaf ear to all he said. When he
+.....perceived at last that nothing could alter my determination,
+.....he ceased to urge, and for a while the deep\p
+.sp .5v
+.sp 3.5p
+.eb
+.b1
+.hh "An Internal Memorandum"
+.ft 3
+.nf
+\&.IM
+\&.ND January 24, 1956
+\&.TL
+\&The 1956 Consent Decree
+\&.AU
+\&Able, Baker &
+\&Charley, Attys.
+\&.PP
+Plaintiff, United States of America, having filed
+its complaint herein on January 14, 1949; the
+defendants having appeared and filed their
+answer to such complaint denying the
+substantive allegations thereof; and the parties,
+by their attorneys, ...
+.ft
+.sp
+.ft 1
+.mk a
+.br
+.sp .20i
+.ta 2.1i
+.ll 3i
+.ps 18
+.br
+ \(bs
+.vs .20i
+.ps 7
+.br
+.bd 1 2
+.nf
+ Bell Laboratories
+.fi
+.na
+.bd 1
+.ps 7
+.vs 8p
+.sp .12i
+.mk
+.fi
+.ll
+.ll 2.0i
+Subject:
+.ps 8
+.hy 0
+.br
+.bd 1 2
+.sp -1
+\h'\w'\s7Subject: \s0'u'The 1956 Consent Decree
+.hy 14
+.br
+.bd 1
+.rt
+.ll 3.25i
+.in 2.10i
+.ps 7
+.mk
+.ti -6n
+date:
+.br
+.bd 1 2
+.rt
+.ps 8
+January 24, 1956
+.sp
+.bd 1
+.ps 7
+.mk
+.ti -6n
+from:
+.ps 8
+.nf
+.br
+.bd 1 2
+.rt
+Able, Baker &
+Charley, Attys.
+.br
+.bd 1
+.sp
+.sp
+.ll 3i
+.ad
+.fi
+.in 0
+.de SH
+.sp .5
+.bd 1 2
+..
+.de PP
+.sp .3
+.bd 1
+.ti +2n
+..
+.PP
+Plaintiff, United States of America, having filed its complaint
+herein on January 14, 1949; the defendants having appeared and
+filed their answer to such complaint denying the substantive
+allegations thereof; and the parties, by their attorneys, having
+severally consented to the entry of this Final Judgment without
+trial or adjudication of any issues of fact or law herein and without
+this Final Judgment constituting any evidence or admission by any
+party in respect of any such issues;
+.PP
+Now, therefore before any testimony has been taken herein, and
+without trial or adjudication of any issue of fact or law herein,
+and upon the consent of all parties hereto, it is hereby
+.PP
+Ordered, adjudged and decreed as follows:
+.SH
+I.
+[Sherman Act]
+.PP
+This Court has jurisdiction of the subject matter herein and of all
+the parties hereto.
+The complaint states a claim upon which relief may be granted
+against each of the defendants under Sections 1, 2 and 3 of the
+Act of Congress of July 2, 1890, entitled ``An act to protect
+trade and commerce against unlawful restraints and monopolies,''
+commonly known as the Sherman Act, as amended.
+.SH
+II.
+[Definitions]
+.PP
+For the purposes of this Final Judgment:
+.PP
+(a) ``Western'' shall mean the defendant Western Electric
+Company, Incorporated.
+.sp .25i
+.eb
+.sp
+.ft 1
+.bd 1
+
+.ps 9
+.vs 10p
+Other formats possible (specify before \f3.TL\f1) are:
+\&\f3.MR\f1 (``memo for record''), \f3.MF\f1
+(``memo for file''),
+\&\f3.EG\f1 (``engineer's notes'') and \f3.TR\f1
+(Computing Science Tech. Report).
+.sp 2
+.hh "Headings"
+.sp .5
+.nf
+.ft 3
+.ta 2i
+\&.NH .SH
+Introduction. Appendix I
+\&.PP .PP
+text text text text text text
+.ft 1
+.bd 1 2
+.sp
+.br
+1. Introduction Appendix I
+.br
+.sp .3v
+.bd 1
+\0\0text text text \0\0text text text
+.br
+.b2
+.hh "A Simple List"
+.ft 3
+.nf
+\&.IP 1.
+\&J. Pencilpusher and X. Hardwired,
+\&.I
+\&A New Kind of Set Screw,
+\&.R
+\&Proc. IEEE
+\&.B 75
+\&(1976), 23-255.
+\&.IP 2.
+\&H. Nails and R. Irons,
+\&.I
+\&Fasteners for Printed Circuit Boards,
+\&.R
+\&Proc. ASME
+\&.B 23
+\&(1974), 23-24.
+\&.LP \fP(terminates list)
+.sp 1.5
+.EQ
+delim $$
+gsize 9
+.EN
+.fi
+.IP 1.
+J. Pencilpusher and X. Hardwired,
+.I
+A New Kind of Set Screw,
+.R
+Proc. IEEE
+$fat 75$
+(1976), 23-255.
+.IP 2.
+H. Nails and R. Irons,
+.I
+Fasteners for Printed Circuit Boards,
+.R
+Proc. ASME
+$fat 23$
+(1974), 23-24.
+.LP
+.sp 2
+.EQ
+delim off
+.EN
+.hh "Displays"
+.nf
+.ft 3
+\&text text text text text text
+\&.DS
+\&and now
+\&for something
+\&completely different
+\&.DE
+\&text text text text text text
+.ft
+.sp 1
+.fi
+hoboken harrison newark roseville avenue grove street
+east orange brick church orange highland avenue
+mountain station south orange maplewood millburn short hills
+summit new providence
+.in .4i
+.sp .5
+.nf
+and now
+for something
+completely different
+.sp .5
+.in
+.fi
+murray hill berkeley heights
+gillette stirling millington lyons basking ridge
+bernardsville far hills peapack gladstone
+.sp .5
+Options: \f3.DS L\f1: left-adjust;
+\&\f3.DS C\f1: line-by-line center; \f3.DS B\f1: make block, then center.
+.sp 2
+.hh "Footnotes"
+.nf
+.ft 3
+\&Among the most important occupants
+\&of the workbench are the long-nosed pliers.
+\&Without these basic tools*
+\&.FS
+\&* As first shown by Tiger & Leopard
+\&(1975).
+\&.FE
+\&few assemblies could be completed. They may
+\&lack the popular appeal of the sledgehammer
+.ft
+.sp 1.5
+.fi
+Among the most important occupants
+of the workbench are the long-nosed
+pliers.
+Without these basic tools*
+few assemblies could be completed.
+They may lack the
+popular appeal of the sledgehammer
+.br
+\l'1i'
+.ps -1
+.br
+* As first shown by Tiger & Leopard (1975).
+.ps
+.br
+.nf
+.b1
+.hh "Multiple Indents"
+.ft 3
+\&This is ordinary text to point out
+\&the margins of the page.
+\&.IP 1.
+\&First level item
+\&.RS
+\&.IP a)
+\&Second level.
+\&.IP b)
+\&Continued here with another second
+\&level item, but somewhat longer.
+\&.RE
+\&.IP 2.
+\&Return to previous value of the
+\&indenting at this point.
+\&.IP 3.
+\&Another
+\&line.
+.ft
+.sp 1.5v
+.fi
+This is ordinary text to point out
+the margins of the page.
+.IP 1.
+First level item
+.RS
+.IP a)
+Second level.
+.IP b)
+Continued here with another second level
+item, but somewhat longer.
+.RE
+.IP 2.
+Return to previous value of the
+indenting at this point.
+.IP 3.
+Another
+line.
+.LP
+.sp 2
+.hh "Keeps"
+.fi
+Lines bracketed by the following commands are kept together,
+and will appear entirely on one page:
+.TS
+center;
+Lf3 5 L8 Lf3 5 L.
+\&.KS not moved .KF may float
+\&.KE through text .KE in text
+.TE
+.nf
+.sp 2
+.hh "Double Column"
+.nf
+.hy 0
+.ft 3
+\&.TL
+The Declaration of Independence
+\&.2C
+.na
+.fi
+\&.PP
+.br
+When in the course of human events, it becomes
+necessary for one people to dissolve the political bonds
+which have connected them with another, and to assume
+among the powers of the earth the separate and equal station
+to which the laws of Nature and of Nature's God entitle them,
+a decent respect to the opinions of
+.ft
+.de xy
+.if \\n(xy=0 'rt
+.if \\n(xy=0 'po +1.58i
+.nr xy +1
+..
+.wh 10.45i xy
+.br
+.ad
+.hy 1
+.sp 1.5
+.ce
+The Declaration of Independence
+.sp .5
+.ll 1.42i
+.mk
+.fi
+.ti +2n
+When in the course of human events, it becomes
+necessary for one people to dissolve the political bonds which have
+connected them with another, and to assume among the
+powers of the earth the separate and equal station to which
+the laws of Nature and of Nature's God entitle them, a decent
+respect to the opinions of mankind requires that they should
+declare the causes which impel them to the separation.
+.ti +2n
+We hold these truths to be self-evident, that all men
+are created equal, that they are endowed by their creator
+with certain unalienable rights, that among these are life, liberty,
+and the pursuit of happiness. That to secure these rights,
+governments are instituted among men,\p
+.br
+.po -1.58i
+.ll 3i
+.lt 3i
+.rm xy
+.b2
+.hh "Equations"
+.nf
+.de EQ \"equation, breakout and display
+.nr EF \\n(.u
+.rm EE
+.nr LE 1 \" 1 is center
+.ds EL \\$1
+.if "\\$1"L" .ds EL \\$2
+.if "\\$1"L" .nr LE 0
+.if "\\$1"C" .ds EL \\$2
+.if "\\$1"I" .nr LE 0
+.if "\\$1"I" .ds EE \\h'5n'
+.if "\\$1"I" .if !"\\$3"" .ds EE \\h'\\$3n'
+.if "\\$1"I" .ds EL \\$2
+.nf
+.di EZ
+..
+.de EN \" end of a displayed equation
+.di
+.rm EZ
+.lt \\n(.lu
+.pc
+.if \\n(dn>0 .if \\n(LE>0 .tl \(ts\(ts\\*(10\(ts\\*(EL\(ts
+.if \\n(dn>0 .if \\n(LE=0 .tl '\\*(EE\\*(10''\\*(EL'
+.pc %
+.lt \\n(LLu
+.if \\n(EF>0 .fi
+.rm EL
+.rm 10
+.nr PE \\n(.d
+..
+.ft 3
+A displayed equation is marked
+with an equation number at the right margin
+by adding an argument to the EQ line:
+\&.EQ (1.3)
+x sup 2 over a sup 2 ~=~ sqrt {p z sup 2 +qz+r}
+\&.EN
+.ft
+.sp
+.fi
+A displayed equation is marked with an equation number
+at the right margin by adding an argument to the EQ line:
+.sp .4
+.EQ (1.3)
+x sup 2 over a sup 2
+~=~ sqrt { p z sup 2 + q z + r }
+.EN
+.sp
+.nf
+.ft 3
+\&.EQ I (2.2a)
+bold V bar sub nu~=~left [ pile {a above b above
+c } right ] + left [ matrix { col { A(11) above .
+above . } col { . above . above .} col {. above .
+above A(33) }} right ] cdot left [ pile { alpha
+above beta above gamma } right ]
+.nf
+\&.EN
+.ft
+.sp
+.EQ I (2.2a)
+fat {roman V} bar sub nu~=~left [ pile {a above b above c}
+right ] + left [ matrix { col { A(11) above .
+above . } col { . above . above .} col {. above .
+above A(33) }} right ] cdot left [ pile { alpha
+above beta above gamma } right ]
+.EN
+.sp
+.ft 3
+\&.EQ L
+F hat ( chi ) ~ mark = ~ | del V | sup 2
+\&.EN
+\&.EQ L
+.fi
+.na
+lineup =~ {left ( {partial V} over {partial x} right ) } sup 2
++ { left ( {partial V} over {partial y} right ) } sup 2
+~~~~~~ lambda -> inf
+.nf
+\&.EN
+.ft
+.ta .25i
+.sp
+.EQ L
+F hat ( chi ) ~ mark = ~ | del V | sup 2
+.EN
+.sp 1
+.EQ L
+delim off
+lineup =~ {left ( {partial V} over {partial x} right ) } sup 2
++ { left ( {partial V} over {partial y} right ) } sup 2
+~~~~~~ lambda -> inf
+.EN
+.rm EQ
+.rm EN
+.fi
+.sp
+.ft 3
+$ a dot $, $ b dotdot$, $ xi tilde times
+y vec$:
+.EQ
+delim $$
+.EN
+.ft R
+.br
+.sp
+$ a dot $, $ b dotdot$, $ xi tilde times
+y vec$.
+.EQ
+delim off
+.EN
+\h'.3i'(with delim $$ on, see panel 3).
+.sp .5
+See also the equations in the second table, panel 8.
+.nf
+.br
+.bd I
+.sp 2
+.ft R
+.hh "Some Registers You Can Change"
+.nf
+.mk
+Line length
+ .nr LL 7i
+.sp .4
+Title length
+ .nr LT 7i
+.sp .4
+Point size
+ .nr PS 9
+.sp .4
+Vertical spacing
+ .nr VS 11
+.sp .4
+Column width
+ .nr CW 3i
+.sp .4
+Intercolumn spacing
+ .nr GW .5i
+.sp .4
+Margins \- head and foot
+ .nr HM .75i
+ .nr FM .75i
+.sp .4
+Paragraph indent
+ .nr PI 2n
+.rt
+.po +1.6i
+Paragraph spacing
+ .nr PD 0
+.sp .4
+Page offset
+ .nr PO 0.5i
+.sp .4
+Page heading
+ .ds CH Appendix
+ (center)
+ .ds RH 7-25-76
+ (right)
+ .ds LH Private
+ (left)
+.sp .4
+Page footer
+ .ds CF Draft
+ .ds LF
+ .ds RF \u similar \d
+.sp .4
+Page numbers
+ .nr % 3
+.po -1.6i
+.b1
+.hh Tables
+.nf
+.ds T \|\h'.35n'\v'-.1n'\s6\zT\s0\v'.1n'\h'-.35n'\(ci\|
+.ft 3
+.EQ
+delim off
+.EN
+\&.TS\h'.5i'\fR(\f3\*T\f1 indicates a tab)\f3
+\&allbox;
+.nr x \n(nl
+\&c s s
+\&c c c
+\&n n n.
+\&AT&T Common Stock
+\&Year\*TPrice\*TDividend
+\&1971\*T41-54\*T$2.60
+\&2\*T41-54\*T2.70
+\&3\*T46-55\*T2.87
+\&4\*T40-53\*T3.24
+\&5\*T45-52\*T3.40
+\&6\*T51-59\*T.95*
+\&.TE
+\&* (first quarter only)
+.ft 1
+.nr y \n(nl
+.sp |\nxu
+.di qq
+.TS
+allbox;
+c s s
+c c c
+n1 n1 n1.
+AT&T Common Stock
+Year Price Dividend
+1971 41-54 $2.60
+2 41-54 2.70
+3 46-55 2.87
+4 40-53 3.24
+5 45-52 3.40
+6 51-59 .95*
+.TE
+* (first quarter only)
+.br
+.di
+.in 3i-\n(TWu
+.nf
+.qq
+.in 0
+.if \ny>\n(nl .sp |\nyu
+.sp .5
+.ft 1
+.fi
+.ad
+The meanings of the key-letters describing
+the alignment of each entry are:
+.br
+.nf
+.TS
+center;
+cf3 l6 cf3 l.
+c center n numerical
+r right-adjust a subcolumn
+l left-adjust s spanned
+.TE
+.fi
+The global table options are
+.ft 3
+.bd I 2
+.hy 0
+center, expand, box, doublebox, allbox,
+tab (\f2x\fP\|)
+.ft 1
+and
+.ft 3
+linesize (\f2n\fP\|).
+.br
+.hy 1
+.ft 1
+.bd I
+.sp 1
+.nf
+.ta .1i
+.ft 3
+\&.TS\h'.5i'\fR(with delim $$ on, see panel 3)\fP
+\&doublebox, center;
+\&c c
+\&l l.
+\&Name\*TDefinition
+\&.sp
+\&Gamma\*T$GAMMA (z) = int sub 0 sup inf \e
+ t sup {z-1} e sup -t dt$
+\&Sine\*T$sin (x) = 1 over 2i ( e sup ix - e sup -ix )$
+\&Error\*T$ roman erf (z) = 2 over sqrt pi \e
+ int sub 0 sup z e sup {-t sup 2} dt$
+\&Bessel\*T$ J sub 0 (z) = 1 over pi \e
+ int sub 0 sup pi cos ( z sin theta ) d theta $
+\&Zeta\*T$ zeta (s) = \e
+ sum from k=1 to inf k sup -s ~~( Re~s > 1)$
+\&.TE
+.ft
+.sp
+.EQ
+delim $$
+.EN
+.vs +2p
+.TS
+doublebox, center;
+c c
+l l.
+Name Definition
+.sp
+Gamma $GAMMA (z) = int sub 0 sup inf t sup {z-1} e sup -t dt$
+Sine $sin (x) = 1 over 2i ( e sup ix - e sup -ix )$
+Error $ roman erf (z) = 2 over sqrt pi int sub 0 sup z e sup {-t sup 2} dt$
+Bessel $ J sub 0 (z) = 1 over pi int sub 0 sup pi cos ( z sin theta ) d theta $
+Zeta $ zeta (s) = sum from k=1 to inf k sup -s ~~( Re~s > 1)$
+.TE
+.vs -2p
+.br
+.bd I 2
+.sp 1
+.hh "Usage"
+.ps 9
+.vs 10p
+.ds & \\s-1&\\s0
+.TS
+l.
+\h'.25i'Documents with just text:
+troff -ms files
+\h'.25i'With equations only:
+eqn files | troff -ms
+\h'.25i'With tables only:
+tbl files | troff -ms
+\h'.25i'With both tables and equations:
+tbl files\||\|eqn\||\|troff -ms
+_
+.TE
+.ft R
+.fi
+.sp .5
+The above generates \s-2STARE\s0 output on
+\s-2GCOS\s0: replace
+.ft 3
+\-st
+.ft R
+with
+.ft 3
+\-ph
+.ft R
+for typesetter output.
+.ft 1
+.bd I
+.b2
diff --git a/share/doc/usd/17.msmacros/refcard.bad b/share/doc/usd/17.msmacros/refcard.bad
new file mode 100644
index 00000000000..fc5b646ce52
--- /dev/null
+++ b/share/doc/usd/17.msmacros/refcard.bad
@@ -0,0 +1,1253 @@
+\".fp 3 H
+\" no Helvetica on dandelion printer
+.fp 3 El
+.po .5i
+.de I
+.ft 2
+..
+.de R
+.ft 1
+..
+.de B
+.bd R 2
+\\$1
+.bd R
+..
+.de hh
+.br
+.vs 10p
+.ps 12
+.bd 1 3
+.ce
+\\$1
+.ps 9
+.br
+.bd 1
+.sp
+..
+.de NP
+'po 0
+.ps 9
+.ta .25i 3.75i 7.25i 7.7i
+\(rn\t|\t|\t|\t\(rn
+'po
+'sp .2i
+.mk z
+..
+.de FT
+.po 0
+.ps 9
+.ta .25i 3.75i 7.25i
+ | | |
+.po .5i
+..
+.wh -8p FT
+.de b1
+.br
+.tm left col bottom at \\n(nl
+.po +3.5i
+.sp |\\nzu
+.ph
+..
+.de b2
+.br
+.tm right col bottom at \\n(nl
+.po -3.5i
+.bp
+.ph
+..
+.de ph
+.nr x +1
+.tl ''\\nx''
+.sp .2i
+..
+.nr x 1
+.wh 0 NP
+.ll 3i
+.lt 3i
+.nr LL 3i
+.nr IQ 4
+.nr IR 4
+.de IP
+.RT
+.if \\n(IP=0 .nr IP +1
+.if \\n(.$ .LB "\\$1"
+.if !\\n(.$ .LB
+..
+.de RT
+.if \\n(IP .in -\\n(IQn
+.if \\n(IP .nr IP -1
+..
+.de LP
+.RT
+.ti 0
+.ne 3
+.if \\n(.$ .LB \\$1
+..
+.de LB
+.in +\\n(IQn
+.ta \\n(IQn
+.if \\n(.$ .ti -\\n(IQn
+.if \\n(.$ \\$1\t\c
+..
+.de RS
+.in +\\n(IRn
+..
+. \"RE - retreat to the left
+.de RE
+.br
+.in -\\n(IRn
+..
+.br
+.rs
+.sp .5i
+.ps 14
+.vs 16p
+.ce 3
+A Guide to Preparing
+Documents with \-ms
+.sp
+.ps 10
+.vs 12p
+.ft I
+.ce
+M. E. Lesk
+.ft R
+.lt \n(.lu
+.sp .5
+.tl 'Bell Laboratories''August 1978'
+.sp .5
+.tl xx\l'\n(.lu'xx
+.sp 1
+.bd I 2
+.vs 11p
+.fi
+This guide gives some simple examples of
+document preparation on Bell Labs computers,
+emphasizing the use of the \fI\-ms\fR macro
+package.
+It enormously abbreviates
+information in
+.IP 1.
+.I
+Typing Documents on the UNIX System
+.R
+by M. E. Lesk;
+.IP 2.
+.I
+Typesetting Mathematics \- User's Guide,
+.R
+by B. W. Kernighan and L. L. Cherry; and
+.IP 3.
+.I
+Tbl \- A Program to Format Tables,
+.R
+by M. E. Lesk.
+.LP
+These memos are all included in the
+.I
+UNIX User Supplementary Documents.
+.R
+The new user should also have
+.I
+A Tutorial Introduction to the UNIX Text Editor,
+.R
+by B. W. Kernighan.
+.sp .5
+For more detailed information, read
+.I
+Advanced Editing on UNIX
+.R
+and
+.I
+A Troff Tutorial,
+.R
+by B. W. Kernighan,
+and (for experts)
+.I
+Nroff\^/Troff Reference Manual
+.R
+by J. F. Ossanna.
+Information on related commands is
+found in
+.I
+UNIX for Beginners
+.R
+by B. W. Kernighan
+and the
+.I
+UNIX User's Manual.
+.R
+.br
+.vs 12p
+.sp 1.5
+.ce
+.ps +2
+Contents
+.nf
+.ps
+.sp .5
+.in .2i
+.bd I
+.ta 2.4i
+.cs I 25
+A TM \fI\fR 2
+A released paper \fI\fR 3
+An internal memo, and headings \fI\fR 4
+Lists, displays, and footnotes \fI\fR 5
+Indents, keeps, and double column \fI\fR 6
+Equations and registers \fI\fR 7
+Tables and usage \fI\fR 8
+.in 0
+.cs I
+.sp 1
+.fi
+.EQ
+delim $$
+.EN
+Throughout the examples, input is shown in
+.ft 3
+.br
+.ti +2n
+this sans serif font
+.ft R
+.br
+while the resulting output is shown in
+.ti +2n
+this Roman font.
+.nf
+.sp 2
+.ce
+UNIX Document no. 1111
+.ps 9
+.vs 10p
+.EQ
+gsize 9
+.EN
+.b1
+.hh "Commands for a TM"
+.nf
+.ft 3
+\&.TM 1978-5b3 99999 99999-11
+\&.ND April 1, 1976
+\&.TL
+\&The Role of the Allen Wrench in Modern
+\&Electronics
+\&.AU "MH 2G-111" 2345
+\&J. Q. Pencilpusher
+\&.AU "MH 1K-222" 5432
+\&X. Y. Hardwired
+\&.AI
+\&.MH
+\&.OK
+\&Tools
+\&Design
+\&.AB
+\&This abstract should be short enough to fit
+\&on a single page cover sheet. It must attract
+\&the reader into sending for the complete report.
+\&.AE
+\&.CS 10 2 12 5 6 7
+\&.NH
+\&Introduction.
+\&.PP
+\&Now the first paragraph of actual text ...
+\&...
+\&Last line of text.
+\&.SG MH-1234-JQP/XYH-unix
+\&.NH
+\&References ...
+.ft
+.sp
+.fi
+Commands not needed in a particular
+format are ignored.
+.sp
+.ps 8
+.vs 9p
+.mk a
+.sp .20i
+.ll 3i
+.nf
+\h'2n'\s16\(bs\s7 $fat roman size 7 "Bell Laboratories"$ \s8Cover Sheet for TM
+.sp
+\s6\l'3i'
+.fi
+.ps 7
+.ft 2
+.sp 1p
+This information is for employees of Bell Laboratories. (GEI 13.9-3)\p
+.ft 1
+.nf
+.vs 4p
+\s6\l'3i'
+.vs 9p
+.sp
+.ll 3.0i
+.ps 7
+.ta .25i 2.25i 2.45i
+.mk
+Title- \s8
+.rt
+.in .25i
+.hy 0
+.bd 1 2
+The Role of the Allen Wrench
+in Modern Electronics
+.hy 14
+.br
+.bd 1
+.rt
+.ll \\n(LLu
+.in 2.1i
+\s7Date- \s8
+.rt
+.in 2.35i
+.bd 1 2
+.ps 8
+April 1, 1976
+.sp
+.bd 1
+.ti 2.1i
+.mk
+\s7TM- \s8
+.br
+.rt
+.bd 1 2
+1978-5b3
+.rt
+.in 0
+.bd 1
+.sp
+.mk
+\s7Other Keywords- \kQ
+.rt
+.in \nQu
+.bd 1 2
+.ps 8
+Tools
+Design
+.rm OK
+.rm OD
+.in 0
+.bd 1
+.if t .sp .30i
+.ps 7
+.ta 1.05i 1.7i 2.0i
+Author Location Ext. Charging Case- \s8$fat roman size 8 99999$
+.nf
+.mk
+.bd 1 2
+.ps 8
+J. Q. Pencilpusher MH 2G-111 2345
+.rt
+.br
+.bd 1
+ \s7Filing Case- \s8$fat roman size 8 "99999a"$
+.br
+.bd 1 2
+X. Y. Hardwired MH 1K-222 5432
+.sp .2i
+.bd 1
+.br
+.ll 3i
+.ce
+.ft I
+ABSTRACT
+.ft 1
+.sp
+.fi
+.ps 8
+.ll 2.5i
+.in +.25i
+.ti +2
+This abstract should be short enough to fit
+on a single page cover sheet.
+It must attract the reader into sending for the
+complete report.
+.in
+.ll
+.sp .3i
+.nf
+\l'3i'
+.ta .9i 1.8i 2.7i
+.sp 5p
+Pages Text 10 Other 2 Total 12
+.if t .sp 8p
+.if n .sp
+.if t No. Figures 5 No. Tables 6 No. Refs. 7 \b'|||||\ \ '
+\l'3i'
+.ps 6
+.if n .sp
+.lt 3i
+.tl 'E-1932-U (6-73)''SEE REVERSE SIDE FOR DISTRIBUTION LIST'
+.sp .20i
+.de eb
+.sp -1
+.nf
+\h'-1m'\L'|\\nau-1'\l'\\n(.lu+2m\(ul'\L'-|\\nau+1'\l'|0u-1m\(ul'
+.fi
+..
+.eb
+.b2
+.hh "A Released Paper with Mathematics"
+.ft 3
+.nf
+.EQ
+delim off
+.EN
+\&.EQ
+\&delim $$
+\&.EN
+\&.RP
+.sp
+.ft 1
+\&... (as for a TM)
+.sp
+.ft 3
+\&.CS 10 2 12 5 6 7
+\&.NH
+\&Introduction
+\&.PP
+\&The solution to the torque handle equation
+\&.EQ (1)
+\&sum from 0 to inf F ( x sub i ) = G ( x )
+\&.EN
+\&is found with the transformation $ x = rho over
+\&theta $ where $ rho = G prime (x) $ and $theta$
+\&is derived ...
+.ft 1
+.sp 2
+.mk a
+.ll 3i
+.ps 9
+.bd 1 2
+.sp .4i
+.ce 2
+.vs 11p
+The Role of the Allen Wrench
+in Modern Electronics
+.sp .7
+.ce 3
+.ft 2
+.bd 1
+.ps 8
+.vs 9p
+J. Q. Pencilpusher
+.sp .7
+X. Y. Hardwired
+.sp .7
+.ce 2
+.ft 1
+Bell Laboratories
+Murray Hill, New Jersey 07974
+.sp 2
+.ce
+.ft 2
+ABSTRACT
+.ft 1
+.sp .7
+.in +.25i
+.ll 2.75i
+.fi
+.ad
+.ti +2n
+This abstract should be short enough to fit
+on a single page cover sheet.
+It must attract the reader into sending for the
+complete memorandum.
+.sp 5v
+.in
+.ll
+April 1, 1976
+.sp .2i
+.eb
+.ll 3i
+.sp .5v
+.sp 3.5p
+.mk a
+.lt 3i
+.ps 9
+.sp .25i
+.bd 1 2
+.ce 2
+.vs 11p
+The Role of the Allen Wrench
+in Modern Electronics
+.sp
+.ce 3
+.bd 1
+.ft 2
+.ps 8
+.vs 9p
+J. Q. Pencilpusher
+.sp
+X. Y. Hardwired
+.sp
+.ce 2
+.ft 1
+Bell Laboratories
+Murray Hill, New Jersey 07974
+.sp 3
+.ce
+.de SH
+.bd 1 2
+.sp
+.ce 0
+.in 0
+..
+.de PP
+.sp .3
+.ft 1
+.bd 1
+.ti +2n
+..
+.SH
+1. Introduction
+.PP
+The solution to the torque handle equation
+.br
+.di xx
+.EQ
+delim $$
+gsize 8
+sum from 0 to inf F ( x sub i ) = G ( x )
+.EN
+.br
+.di
+.tl ''\*(10'(1)'
+is found with the transformation
+$ x = rho over theta $ where $ rho = G prime ( x )$
+and $theta$ is derived from well-known principles.
+......PP
+......ft 2
+.....The Ascent of the Riffelberg,
+......ft 1
+.....by Mark Twain.
+.....I sat silent some time, then turned to Harris and said:
+.....``My mind is made up.''
+.....Something in my tone struck him; and when he glanced
+.....at my eye and read what was written there, his face paled
+.....perceptibly. He hesitated a moment, then said:
+.....``Speak.''
+.....I answered, with perfect calmness:
+......ft 2
+.....``I will ascend the Riffelberg.''
+......ft 1
+.....If I had shot my poor friend he could not have fallen from
+.....his chair more suddenly. If I had been his father he
+.....could not have pleaded harder to get me to give up my
+.....purpose. But I turned a deaf ear to all he said. When he
+.....perceived at last that nothing could alter my determination,
+.....he ceased to urge, and for a while the deep\p
+.sp .5v
+.sp 3.5p
+.eb
+.b1
+.hh "An Internal Memorandum"
+.ft 3
+.nf
+\&.IM
+\&.ND January 24, 1956
+\&.TL
+\&The 1956 Consent Decree
+\&.AU
+\&Able, Baker &
+\&Charley, Attys.
+\&.PP
+Plaintiff, United States of America, having filed
+its complaint herein on January 14, 1949; the
+defendants having appeared and filed their
+answer to such complaint denying the
+substantive allegations thereof; and the parties,
+by their attorneys, ...
+.ft
+.sp
+.ft 1
+.mk a
+.br
+.sp .20i
+.ta 2.1i
+.ll 3i
+.ps 18
+.br
+ \(bs
+.vs .20i
+.ps 7
+.br
+.bd 1 2
+.nf
+ Bell Laboratories
+.fi
+.na
+.bd 1
+.ps 7
+.vs 8p
+.sp .12i
+.mk
+.fi
+.ll
+.ll 2.0i
+Subject:
+.ps 8
+.hy 0
+.br
+.bd 1 2
+.sp -1
+\h'\w'\s7Subject: \s0'u'The 1956 Consent Decree
+.hy 14
+.br
+.bd 1
+.rt
+.ll 3.25i
+.in 2.10i
+.ps 7
+.mk
+.ti -6n
+date:
+.br
+.bd 1 2
+.rt
+.ps 8
+January 24, 1956
+.sp
+.bd 1
+.ps 7
+.mk
+.ti -6n
+from:
+.ps 8
+.nf
+.br
+.bd 1 2
+.rt
+Able, Baker &
+Charley, Attys.
+.br
+.bd 1
+.sp
+.sp
+.ll 3i
+.ad
+.fi
+.in 0
+.de SH
+.sp .5
+.bd 1 2
+..
+.de PP
+.sp .3
+.bd 1
+.ti +2n
+..
+.PP
+Plaintiff, United States of America, having filed its complaint
+herein on January 14, 1949; the defendants having appeared and
+filed their answer to such complaint denying the substantive
+allegations thereof; and the parties, by their attorneys, having
+severally consented to the entry of this Final Judgment without
+trial or adjudication of any issues of fact or law herein and without
+this Final Judgment constituting any evidence or admission by any
+party in respect of any such issues;
+.PP
+Now, therefore before any testimony has been taken herein, and
+without trial or adjudication of any issue of fact or law herein,
+and upon the consent of all parties hereto, it is hereby
+.PP
+Ordered, adjudged and decreed as follows:
+.SH
+I.
+[Sherman Act]
+.PP
+This Court has jurisdiction of the subject matter herein and of all
+the parties hereto.
+The complaint states a claim upon which relief may be granted
+against each of the defendants under Sections 1, 2 and 3 of the
+Act of Congress of July 2, 1890, entitled ``An act to protect
+trade and commerce against unlawful restraints and monopolies,''
+commonly known as the Sherman Act, as amended.
+.SH
+II.
+[Definitions]
+.PP
+For the purposes of this Final Judgment:
+.PP
+(a) ``Western'' shall mean the defendant Western Electric
+Company, Incorporated.
+.sp .25i
+.eb
+.sp
+.ft 1
+.bd 1
+
+.ps 9
+.vs 10p
+Other formats possible (specify before \f3.TL\f1) are:
+\&\f3.MR\f1 (``memo for record''), \f3.MF\f1
+(``memo for file''),
+\&\f3.EG\f1 (``engineer's notes'') and \f3.TR\f1
+(Computing Science Tech. Report).
+.sp 2
+.hh "Headings"
+.sp .5
+.nf
+.ft 3
+.ta 2i
+\&.NH .SH
+Introduction. Appendix I
+\&.PP .PP
+text text text text text text
+.ft 1
+.bd 1 2
+.sp
+.br
+1. Introduction Appendix I
+.br
+.sp .3v
+.bd 1
+\0\0text text text \0\0text text text
+.br
+.b2
+.hh "A Simple List"
+.ft 3
+.nf
+\&.IP 1.
+\&J. Pencilpusher and X. Hardwired,
+\&.I
+\&A New Kind of Set Screw,
+\&.R
+\&Proc. IEEE
+\&.B 75
+\&(1976), 23-255.
+\&.IP 2.
+\&H. Nails and R. Irons,
+\&.I
+\&Fasteners for Printed Circuit Boards,
+\&.R
+\&Proc. ASME
+\&.B 23
+\&(1974), 23-24.
+\&.LP \fP(terminates list)
+.sp 1.5
+.EQ
+delim $$
+gsize 9
+.EN
+.fi
+.IP 1.
+J. Pencilpusher and X. Hardwired,
+.I
+A New Kind of Set Screw,
+.R
+Proc. IEEE
+$fat 75$
+(1976), 23-255.
+.IP 2.
+H. Nails and R. Irons,
+.I
+Fasteners for Printed Circuit Boards,
+.R
+Proc. ASME
+$fat 23$
+(1974), 23-24.
+.LP
+.sp 2
+.EQ
+delim off
+.EN
+.hh "Displays"
+.nf
+.ft 3
+\&text text text text text text
+\&.DS
+\&and now
+\&for something
+\&completely different
+\&.DE
+\&text text text text text text
+.ft
+.sp 1
+.fi
+hoboken harrison newark roseville avenue grove street
+east orange brick church orange highland avenue
+mountain station south orange maplewood millburn short hills
+summit new providence
+.in .4i
+.sp .5
+.nf
+and now
+for something
+completely different
+.sp .5
+.in
+.fi
+murray hill berkeley heights
+gillette stirling millington lyons basking ridge
+bernardsville far hills peapack gladstone
+.sp .5
+Options: \f3.DS L\f1: left-adjust;
+\&\f3.DS C\f1: line-by-line center; \f3.DS B\f1: make block, then center.
+.sp 2
+.hh "Footnotes"
+.nf
+.ft 3
+\&Among the most important occupants
+\&of the workbench are the long-nosed pliers.
+\&Without these basic tools*
+\&.FS
+\&* As first shown by Tiger & Leopard
+\&(1975).
+\&.FE
+\&few assemblies could be completed. They may
+\&lack the popular appeal of the sledgehammer
+.ft
+.sp 1.5
+.fi
+Among the most important occupants
+of the workbench are the long-nosed
+pliers.
+Without these basic tools*
+few assemblies could be completed.
+They may lack the
+popular appeal of the sledgehammer
+.br
+\l'1i'
+.ps -1
+.br
+* As first shown by Tiger & Leopard (1975).
+.ps
+.br
+.nf
+.b1
+.hh "Multiple Indents"
+.ft 3
+\&This is ordinary text to point out
+\&the margins of the page.
+\&.IP 1.
+\&First level item
+\&.RS
+\&.IP a)
+\&Second level.
+\&.IP b)
+\&Continued here with another second
+\&level item, but somewhat longer.
+\&.RE
+\&.IP 2.
+\&Return to previous value of the
+\&indenting at this point.
+\&.IP 3.
+\&Another
+\&line.
+.ft
+.sp 1.5v
+.fi
+This is ordinary text to point out
+the margins of the page.
+.IP 1.
+First level item
+.RS
+.IP a)
+Second level.
+.IP b)
+Continued here with another second level
+item, but somewhat longer.
+.RE
+.IP 2.
+Return to previous value of the
+indenting at this point.
+.IP 3.
+Another
+line.
+.LP
+.sp 2
+.hh "Keeps"
+.fi
+Lines bracketed by the following commands are kept together,
+and will appear entirely on one page:
+.TS
+center;
+Lf3 5 L8 Lf3 5 L.
+\&.KS not moved .KF may float
+\&.KE through text .KE in text
+.TE
+.nf
+.sp 2
+.hh "Double Column"
+.nf
+.hy 0
+.ft 3
+\&.TL
+The Declaration of Independence
+\&.2C
+.na
+.fi
+\&.PP
+.br
+When in the course of human events, it becomes
+necessary for one people to dissolve the political bonds
+which have connected them with another, and to assume
+among the powers of the earth the separate and equal station
+to which the laws of Nature and of Nature's God entitle them,
+a decent respect to the opinions of
+.ft
+.de xy
+.if \\n(xy=0 'rt
+.if \\n(xy=0 'po +1.58i
+.nr xy +1
+..
+.wh 10.45i xy
+.br
+.ad
+.hy 1
+.sp 1.5
+.ce
+The Declaration of Independence
+.sp .5
+.ll 1.42i
+.mk
+.fi
+.ti +2n
+When in the course of human events, it becomes
+necessary for one people to dissolve the political bonds which have
+connected them with another, and to assume among the
+powers of the earth the separate and equal station to which
+the laws of Nature and of Nature's God entitle them, a decent
+respect to the opinions of mankind requires that they should
+declare the causes which impel them to the separation.
+.ti +2n
+We hold these truths to be self-evident, that all men
+are created equal, that they are endowed by their creator
+with certain unalienable rights, that among these are life, liberty,
+and the pursuit of happiness. That to secure these rights,
+governments are instituted among men,\p
+.br
+.po -1.58i
+.ll 3i
+.lt 3i
+.rm xy
+.b2
+.hh "Equations"
+.nf
+.de EQ \"equation, breakout and display
+.nr EF \\n(.u
+.rm EE
+.nr LE 1 \" 1 is center
+.ds EL \\$1
+.if "\\$1"L" .ds EL \\$2
+.if "\\$1"L" .nr LE 0
+.if "\\$1"C" .ds EL \\$2
+.if "\\$1"I" .nr LE 0
+.if "\\$1"I" .ds EE \\h'5n'
+.if "\\$1"I" .if !"\\$3"" .ds EE \\h'\\$3n'
+.if "\\$1"I" .ds EL \\$2
+.nf
+.di EZ
+..
+.de EN \" end of a displayed equation
+.di
+.rm EZ
+.lt \\n(.lu
+.pc
+.if \\n(dn>0 .if \\n(LE>0 .tl \(ts\(ts\\*(10\(ts\\*(EL\(ts
+.if \\n(dn>0 .if \\n(LE=0 .tl '\\*(EE\\*(10''\\*(EL'
+.pc %
+.lt \\n(LLu
+.if \\n(EF>0 .fi
+.rm EL
+.rm 10
+.nr PE \\n(.d
+..
+.ft 3
+A displayed equation is marked
+with an equation number at the right margin
+by adding an argument to the EQ line:
+\&.EQ (1.3)
+x sup 2 over a sup 2 ~=~ sqrt {p z sup 2 +qz+r}
+\&.EN
+.ft
+.sp
+.fi
+A displayed equation is marked with an equation number
+at the right margin by adding an argument to the EQ line:
+.sp .4
+.EQ (1.3)
+x sup 2 over a sup 2
+~=~ sqrt { p z sup 2 + q z + r }
+.EN
+.sp
+.nf
+.ft 3
+\&.EQ I (2.2a)
+bold V bar sub nu~=~left [ pile {a above b above
+c } right ] + left [ matrix { col { A(11) above .
+above . } col { . above . above .} col {. above .
+above A(33) }} right ] cdot left [ pile { alpha
+above beta above gamma } right ]
+.nf
+\&.EN
+.ft
+.sp
+.EQ I (2.2a)
+fat {roman V} bar sub nu~=~left [ pile {a above b above c}
+right ] + left [ matrix { col { A(11) above .
+above . } col { . above . above .} col {. above .
+above A(33) }} right ] cdot left [ pile { alpha
+above beta above gamma } right ]
+.EN
+.sp
+.ft 3
+\&.EQ L
+F hat ( chi ) ~ mark = ~ | del V | sup 2
+\&.EN
+\&.EQ L
+.fi
+.na
+lineup =~ {left ( {partial V} over {partial x} right ) } sup 2
++ { left ( {partial V} over {partial y} right ) } sup 2
+~~~~~~ lambda -> inf
+.nf
+\&.EN
+.ft
+.ta .25i
+.sp
+.EQ L
+F hat ( chi ) ~ mark = ~ | del V | sup 2
+.EN
+.sp 1
+.EQ L
+delim off
+lineup =~ {left ( {partial V} over {partial x} right ) } sup 2
++ { left ( {partial V} over {partial y} right ) } sup 2
+~~~~~~ lambda -> inf
+.EN
+.rm EQ
+.rm EN
+.fi
+.sp
+.ft 3
+$ a dot $, $ b dotdot$, $ xi tilde times
+y vec$:
+.EQ
+delim $$
+.EN
+.ft R
+.br
+.sp
+$ a dot $, $ b dotdot$, $ xi tilde times
+y vec$.
+.EQ
+delim off
+.EN
+\h'.3i'(with delim $$ on, see panel 3).
+.sp .5
+See also the equations in the second table, panel 8.
+.nf
+.br
+.bd I
+.sp 2
+.ft R
+.hh "Some Registers You Can Change"
+.nf
+.mk
+Line length
+ .nr LL 7i
+.sp .4
+Title length
+ .nr LT 7i
+.sp .4
+Point size
+ .nr PS 9
+.sp .4
+Vertical spacing
+ .nr VS 11
+.sp .4
+Column width
+ .nr CW 3i
+.sp .4
+Intercolumn spacing
+ .nr GW .5i
+.sp .4
+Margins \- head and foot
+ .nr HM .75i
+ .nr FM .75i
+.sp .4
+Paragraph indent
+ .nr PI 2n
+.rt
+.po +1.6i
+Paragraph spacing
+ .nr PD 0
+.sp .4
+Page offset
+ .nr PO 0.5i
+.sp .4
+Page heading
+ .ds CH Appendix
+ (center)
+ .ds RH 7-25-76
+ (right)
+ .ds LH Private
+ (left)
+.sp .4
+Page footer
+ .ds CF Draft
+ .ds LF
+ .ds RF \u similar \d
+.sp .4
+Page numbers
+ .nr % 3
+.po -1.6i
+.b1
+.hh Tables
+.nf
+.ds T \|\h'.35n'\v'-.1n'\s6\zT\s0\v'.1n'\h'-.35n'\(ci\|
+.ft 3
+.EQ
+delim off
+.EN
+\&.TS\h'.5i'\fR(\f3\*T\f1 indicates a tab)\f3
+\&allbox;
+.nr x \n(nl
+\&c s s
+\&c c c
+\&n n n.
+\&AT&T Common Stock
+\&Year\*TPrice\*TDividend
+\&1971\*T41-54\*T$2.60
+\&2\*T41-54\*T2.70
+\&3\*T46-55\*T2.87
+\&4\*T40-53\*T3.24
+\&5\*T45-52\*T3.40
+\&6\*T51-59\*T.95*
+\&.TE
+\&* (first quarter only)
+.ft 1
+.nr y \n(nl
+.sp |\nxu
+.di qq
+.TS
+allbox;
+c s s
+c c c
+n1 n1 n1.
+AT&T Common Stock
+Year Price Dividend
+1971 41-54 $2.60
+2 41-54 2.70
+3 46-55 2.87
+4 40-53 3.24
+5 45-52 3.40
+6 51-59 .95*
+.TE
+* (first quarter only)
+.br
+.di
+.in 3i-\n(TWu
+.nf
+.qq
+.in 0
+.if \ny>\n(nl .sp |\nyu
+.sp .5
+.ft 1
+.fi
+.ad
+The meanings of the key-letters describing
+the alignment of each entry are:
+.br
+.nf
+.TS
+center;
+cf3 l6 cf3 l.
+c center n numerical
+r right-adjust a subcolumn
+l left-adjust s spanned
+.TE
+.fi
+The global table options are
+.ft 3
+.bd I 2
+.hy 0
+center, expand, box, doublebox, allbox,
+tab (\f2x\fP\|)
+.ft 1
+and
+.ft 3
+linesize (\f2n\fP\|).
+.br
+.hy 1
+.ft 1
+.bd I
+.sp 1
+.nf
+.ta .1i
+.ft 3
+\&.TS\h'.5i'\fR(with delim $$ on, see panel 3)\fP
+\&doublebox, center;
+\&c c
+\&l l.
+\&Name\*TDefinition
+\&.sp
+\&Gamma\*T$GAMMA (z) = int sub 0 sup inf \e
+ t sup {z-1} e sup -t dt$
+\&Sine\*T$sin (x) = 1 over 2i ( e sup ix - e sup -ix )$
+\&Error\*T$ roman erf (z) = 2 over sqrt pi \e
+ int sub 0 sup z e sup {-t sup 2} dt$
+\&Bessel\*T$ J sub 0 (z) = 1 over pi \e
+ int sub 0 sup pi cos ( z sin theta ) d theta $
+\&Zeta\*T$ zeta (s) = \e
+ sum from k=1 to inf k sup -s ~~( Re~s > 1)$
+\&.TE
+.ft
+.sp
+.EQ
+delim $$
+.EN
+.vs +2p
+.TS
+doublebox, center;
+c c
+l l.
+Name Definition
+.sp
+Gamma $GAMMA (z) = int sub 0 sup inf t sup {z-1} e sup -t dt$
+Sine $sin (x) = 1 over 2i ( e sup ix - e sup -ix )$
+Error $ roman erf (z) = 2 over sqrt pi int sub 0 sup z e sup {-t sup 2} dt$
+Bessel $ J sub 0 (z) = 1 over pi int sub 0 sup pi cos ( z sin theta ) d theta $
+Zeta $ zeta (s) = sum from k=1 to inf k sup -s ~~( Re~s > 1)$
+.TE
+.vs -2p
+.br
+.bd I 2
+.sp 1
+.hh "Usage"
+.ps 9
+.vs 10p
+.ds & \\s-1&\\s0
+.TS
+l.
+\h'.25i'Documents with just text:
+troff -ms files
+\h'.25i'With equations only:
+eqn files | troff -ms
+\h'.25i'With tables only:
+tbl files | troff -ms
+\h'.25i'With both tables and equations:
+tbl files\||\|eqn\||\|troff -ms
+_
+.TE
+.ft R
+.fi
+.sp .5
+The above generates \s-2STARE\s0 output on
+\s-2GCOS\s0: replace
+.ft 3
+\-st
+.ft R
+with
+.ft 3
+\-ph
+.ft R
+for typesetter output.
+.ft 1
+.bd I
+.b2
diff --git a/share/doc/usd/Makefile b/share/doc/usd/Makefile
index c5e2071c1b3..af0229c79e5 100644
--- a/share/doc/usd/Makefile
+++ b/share/doc/usd/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.23 2004/08/06 16:35:41 mycroft Exp $
+# $NetBSD: Makefile,v 1.24 2007/11/29 12:35:05 mjf Exp $
#
# @(#)Makefile 8.3 (Berkeley) 5/16/94
@@ -11,15 +11,15 @@
# 14.jove 15.sed 28.bib
# Missing from 4.4BSD-Lite:
-# 01.begin 02.learn 03.shell 05.dc 06.bc 08.mh 09.edtut 10.edadv
-# 16.awk 17.msmacros 21.troff 22.trofftut 23.eqn 24.eqnguide
+# 02.learn 03.shell 05.dc 06.bc 08.mh 09.edtut 10.edadv
+# 16.awk 21.troff 22.trofftut 23.eqn 24.eqnguide
# 25.tbl 26.refer 27.invert 29.diction
BINDIR= /usr/share/doc/usd
.if ${MKDOC} != "no"
FILES= 00.contents Makefile Title
.endif
-SUBDIR+=18.msdiffs 19.memacros 20.meref
+SUBDIR+=01.begin 17.msmacros 18.msdiffs 19.memacros 20.meref
.if !make(install)
SUBDIR+=04.csh 07.mail 11.edit 12.ex 13.viref
SUBDIR+=30.rogue 31.trek