diff options
| author | mjf <mjf@NetBSD.org> | 2007-11-29 12:35:04 +0000 |
|---|---|---|
| committer | mjf <mjf@NetBSD.org> | 2007-11-29 12:35:04 +0000 |
| commit | 036409b85969342e92632932fa5fe96f1c329a05 (patch) | |
| tree | 36901cc7a43fb092e69f647e4510d3060bef2737 /share/doc | |
| parent | d0f12a6ad912c78206ad0eaa199e3a5b63cb3ea0 (diff) | |
Commit Caldera licensed documentation from 4.4BSD. This was taken from the
OpenBSD tree.
No objections on netbsd-docs.
Diffstat (limited to 'share/doc')
| -rw-r--r-- | share/doc/smm/17.password/Makefile | 7 | ||||
| -rw-r--r-- | share/doc/smm/17.password/password.ms | 601 | ||||
| -rw-r--r-- | share/doc/smm/Makefile | 6 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/Makefile | 7 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u.mac | 82 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u0 | 85 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u1 | 638 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u2 | 1222 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u3 | 357 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u4 | 323 | ||||
| -rw-r--r-- | share/doc/usd/01.begin/u5 | 219 | ||||
| -rw-r--r-- | share/doc/usd/17.msmacros/Makefile | 11 | ||||
| -rw-r--r-- | share/doc/usd/17.msmacros/fig1.pic | 45 | ||||
| -rw-r--r-- | share/doc/usd/17.msmacros/fig1.xfig | 46 | ||||
| -rw-r--r-- | share/doc/usd/17.msmacros/ms | 932 | ||||
| -rw-r--r-- | share/doc/usd/17.msmacros/refcard | 1289 | ||||
| -rw-r--r-- | share/doc/usd/17.msmacros/refcard.bad | 1253 | ||||
| -rw-r--r-- | share/doc/usd/Makefile | 8 |
18 files changed, 7124 insertions, 7 deletions
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 |
