diff options
Diffstat (limited to 'share/doc/usd')
88 files changed, 36090 insertions, 0 deletions
diff --git a/share/doc/usd/04.csh/Makefile b/share/doc/usd/04.csh/Makefile new file mode 100644 index 000000000000..95aafe8851fa --- /dev/null +++ b/share/doc/usd/04.csh/Makefile @@ -0,0 +1,6 @@ +VOLUME= usd/04.csh +SRCS= tabs csh.1 csh.2 csh.3 csh.4 csh.a csh.g +MACROS= -ms +USE_SOELIM= + +.include <bsd.doc.mk> diff --git a/share/doc/usd/04.csh/csh.1 b/share/doc/usd/04.csh/csh.1 new file mode 100644 index 000000000000..5ae17b76650b --- /dev/null +++ b/share/doc/usd/04.csh/csh.1 @@ -0,0 +1,1009 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.EH 'USD:4-%''An Introduction to the C shell' +.OH 'An Introduction to the C shell''USD:4-%' +.\".RP +.TL +An Introduction to the C shell +.AU +William Joy +(revised for 4.3BSD by Mark Seiden) +.AI +Computer Science Division +.br +Department of Electrical Engineering and Computer Science +.br +University of California, Berkeley +.br +Berkeley, California 94720 +.AB +.I Csh +is a new command language interpreter for +.UX +systems. +It incorporates good features of other shells and a +.I history +mechanism similar to the +.I redo +of \s-2INTERLISP\s0. +While incorporating many features of other shells which make +writing shell programs (shell scripts) easier, +most of the features unique to +.I csh +are designed more for the interactive \s-2UNIX\s0 user. +.PP +\s-2UNIX\s0 +users who have read a general introduction to the system +will find a valuable basic explanation of the shell here. +Simple terminal interaction with +.I csh +is possible after reading just the first section of this document. +The second section describes the shell's capabilities which you can +explore after you have begun to become acquainted with the shell. +Later sections introduce features which are useful, but not necessary +for all users of the shell. +.PP +Additional information includes an appendix listing special characters of the shell +and a glossary of terms and commands introduced in this manual. +.AE +.SH +.if n .ND +Introduction +.PP +A +.I shell +is a command language interpreter. +.I Csh +is the name of one particular command interpreter on +\s-2UNIX\s0. +The primary purpose of +.I csh +is to translate command lines typed at a terminal into +system actions, such as invocation of other programs. +.I Csh +is a user program just like any you might write. +Hopefully, +.I csh +will be a very useful program for you +in interacting with the \s-2UNIX\s0 system. +.PP +In addition to this document, you will want to refer to a copy +of the \s-2UNIX\s0 User Reference Manual. +The +.I csh +documentation in section 1 of the manual provides a full description of all +features of the shell and is the definitive reference for questions +about the shell. +.PP +Many words in this document are shown in +.I italics. +These are important words; +names of commands, and words which have special meaning in discussing +the shell and \s-2UNIX\s0. +Many of the words are defined in a glossary at the end of this document. +If you don't know what is meant by a word, you should look +for it in the glossary. +.SH +Acknowledgements +.PP +Numerous people have provided good input about previous versions +of +.I csh +and aided in its debugging and in the debugging of its documentation. +I would especially like to thank Michael Ubell +who made the crucial observation that history commands could be +done well over the word structure of input text, and implemented +a prototype history mechanism in an older version of the shell. +Eric Allman has also provided a large number of useful comments on the +shell, helping to unify those concepts which are present and to identify +and eliminate useless and marginally useful features. +Mike O'Brien suggested the pathname hashing +mechanism which speeds command execution. +Jim Kulp added the job control and directory stack primitives and +added their documentation to this introduction. +.br +.bp +.NH +Terminal usage of the shell +.NH 2 +The basic notion of commands +.PP +A +.I shell +in +\s-2UNIX\s0 +acts mostly as a medium through which other +.I programs +are invoked. +While it has a set of +.I builtin +functions which it performs directly, +most commands cause execution of programs that are, in fact, +external to the shell. +The shell is thus distinguished from the command interpreters of other +systems both by the fact that it is just a user program, and by the fact +that it is used almost exclusively as a mechanism for invoking other programs. +.PP +.I Commands +in the \s-2UNIX\s0 system consist of a list of strings or +.I words +interpreted as a +.I "command name" +followed by +.I arguments. +Thus the command +.DS +mail bill +.DE +consists of two words. +The first word +.I mail +names the command to be executed, in this case the +mail program which sends messages to other users. +The shell uses the name of the command in attempting to execute it for you. +It will look in a number of +.I directories +for a file with the name +.I mail +which is expected to contain the mail program. +.PP +The rest of the words of the command are given as +.I arguments +to the command itself when it is executed. +In this case we specified also the argument +.I bill +which is interpreted by the +.I mail +program to be the name of a user to whom mail is to be sent. +In normal terminal usage we might use the +.I mail +command as follows. +.DS +% mail bill +I have a question about the csh documentation. +My document seems to be missing page 5. +Does a page five exist? + Bill +EOT +% +.DE +.PP +Here we typed a message to send to +.I bill +and ended this message with a ^D which sent an end-of-file to +the mail program. +(Here and throughout this document, the notation ``^\fIx\fR'' +is to be read ``control-\fIx\fR'' and represents the striking of the \fIx\fR +key while the control key is held down.) +The mail program +then echoed the characters `EOT' and transmitted our message. +The characters `% ' were printed before and after the mail command +by the shell to indicate that input was needed. +.PP +After typing the `% ' prompt the shell was reading command input from +our terminal. +We typed a complete command `mail bill'. +The shell then executed the +.I mail +program with argument +.I bill +and went dormant waiting for it to complete. +The mail program then read input from our terminal until we signalled +an end-of-file via typing a ^D after which the shell noticed +that mail had completed +and signaled us that it was ready to read from the terminal again by +printing another `% ' prompt. +.PP +This is the essential pattern of all interaction with \s-2UNIX\s0 +through the shell. +A complete command is typed at the terminal, the shell executes +the command and when this execution completes, it prompts for a new command. +If you run the editor for an hour, the shell will patiently wait for +you to finish editing and obediently prompt you again whenever you finish +editing. +.PP +An example of a useful command you can execute now is the +.I tset +command, which sets the default +.I erase +and +.I kill +characters on your terminal \- the erase character erases the last +character you typed and the kill character erases the entire line you +have entered so far. +By default, the erase character is the delete key (equivalent to `^?') +and the kill character is `^U'. Some people prefer to make the erase character +the backspace key (equivalent to `^H'). +You can make this be true by typing +.DS +tset \-e +.DE +which tells the program +.I tset +to set the erase character to tset's default setting for this character +(a backspace). +.NH 2 +Flag arguments +.PP +A useful notion in \s-2UNIX\s0 is that of a +.I flag +argument. +While many arguments to commands specify file names or user names, +some arguments rather specify an optional capability of the command +which you wish to invoke. +By convention, such arguments begin with the character `\-' (hyphen). +Thus the command +.DS +ls +.DE +will produce a list of the files in the current +.I "working directory" . +The option +.I \-s +is the size option, and +.DS +ls \-s +.DE +causes +.I ls +to also give, for each file the size of the file in blocks of 512 +characters. +The manual section for each command in the \s-2UNIX\s0 reference manual +gives the available options for each command. +The +.I ls +command has a large number of useful and interesting options. +Most other commands have either no options or only one or two options. +It is hard to remember options of commands which are not used very +frequently, so most \s-2UNIX\s0 utilities perform only one or two functions +rather than having a large number of hard to remember options. +.NH 2 +Output to files +.PP +Commands that normally read input or write output on the terminal +can also be executed with this input and/or output done to +a file. +.PP +Thus suppose we wish to save the current date in a file called `now'. +The command +.DS +date +.DE +will print the current date on our terminal. +This is because our terminal is the default +.I "standard output" +for the date command and the date command prints the date on its +standard output. +The shell lets us +.I redirect +the +.I "standard output" +of a command through a +notation using the +.I metacharacter +`>' and the name of the file where output is to be placed. +Thus the command +.DS +date > now +.DE +runs the +.I date +command such that its standard output is +the file `now' rather than the terminal. +Thus this command places the current date and time into the file `now'. +It is important to know that the +.I date +command was unaware that its output was going to a file rather than +to the terminal. +The shell performed this +.I redirection +before the command began executing. +.PP +One other thing to note here is that the file `now' +need not have existed before the +.I date +command was executed; the shell would have created the file if it did +not exist. +And if the file did exist? +If it had existed previously these previous contents would have been discarded! +A shell option +.I noclobber +exists to prevent this from happening accidentally; +it is discussed in section 2.2. +.PP +The system normally keeps files which you create with `>' and all other files. +Thus the default is for files to be permanent. If you wish to create a file +which will be removed automatically, you can begin its name with a `#' +character, this `scratch' character denotes the fact that the file will +be a scratch file.* +.FS +*Note that if your erase character is a `#', you will have to precede the +`#' with a `\e'. The fact that the `#' character is the old (pre-\s-2CRT\s0) +standard erase character means that it seldom appears in a file name, and +allows this convention to be used for scratch files. If you are using a +\s-2CRT\s0, your erase character should be a ^H, as we demonstrated +in section 1.1 how this could be set up. +.FE +The system will remove such files after a couple of days, +or sooner if file space becomes very tight. +Thus, in running the +.I date +command above, we don't really want to save the output forever, so we +would more likely do +.DS +date > #now +.DE +.NH 2 +Metacharacters in the shell +.PP +The shell has a large number of +special characters (like `>') +which indicate special functions. +We say that these notations have +.I syntactic +and +.I semantic +meaning to the shell. +In general, most characters which are neither letters nor digits +have special meaning to the shell. +We shall shortly learn a means of +.I quotation +which allows us to use +.I metacharacters +without the shell treating them in any special way. +.PP +Metacharacters normally have effect only when the shell is reading +our input. +We need not worry about placing shell metacharacters in a letter +we are sending via +.I mail, +or when we are typing in text or data to some other program. +Note that the shell is only reading input when it has prompted with +`% ' (although we can type our input even before it prompts). +.NH 2 +Input from files; pipelines +.PP +We learned above how to +.I redirect +the +.I "standard output" +of a command +to a file. +It is also possible to redirect the +.I "standard input" +of a command from a file. +This is not often necessary since most commands will read from +a file whose name is given as an argument. +We can give the command +.DS +sort < data +.DE +to run the +.I sort +command with standard input, where the command normally +reads its input, from the file +`data'. +We would more likely say +.DS +sort data +.DE +letting the +.I sort +command open the file +`data' +for input itself since this is less to type. +.PP +We should note that if we just typed +.DS +sort +.DE +then the sort program would sort lines from its +.I "standard input." +Since we did not +.I redirect +the standard input, it would sort lines as we typed them on the terminal +until we typed a ^D to indicate an end-of-file. +.PP +A most useful capability is the ability to combine the standard output +of one command with the standard input of another, i.e. to run the +commands in a sequence known as a +.I pipeline. +For instance the command +.DS +ls \-s +.DE +normally produces a list of the files in our directory with the size +of each in blocks of 512 characters. +If we are interested in learning which of our files is largest we +may wish to have this sorted by size rather than by name, which is +the default way in which +.I ls +sorts. +We could look at the many options of +.I ls +to see if there was an option to do this but would eventually discover +that there is not. +Instead we can use a couple of simple options of the +.I sort +command, combining it with +.I ls +to get what we want. +.PP +The +.I \-n +option of sort specifies a numeric sort rather than an alphabetic sort. +Thus +.DS +ls \-s | sort \-n +.DE +specifies that the output of the +.I ls +command run with the option +.I \-s +is to be +.I piped +to the command +.I sort +run with the numeric sort option. +This would give us a sorted list of our files by size, but with the +smallest first. +We could then use the +.I \-r +reverse sort option and the +.I head +command in combination with the previous command doing +.DS +ls \-s | sort \-n \-r | head \-5 +.DE +Here we have taken a list of our files sorted alphabetically, +each with the size in blocks. +We have run this to the standard input of the +.I sort +command asking it to sort numerically in reverse order (largest first). +This output has then been run into the command +.I head +which gives us the first few lines. +In this case we have asked +.I head +for the first 5 lines. +Thus this command gives us the names and sizes of our 5 largest files. +.PP +The notation introduced above is called the +.I pipe +mechanism. +Commands separated by `\||\|' characters are connected together by the +shell and the standard output of each is run into the standard input of the +next. +The leftmost command in a pipeline will normally take its standard +input from the terminal and the rightmost will place its standard +output on the terminal. +Other examples of pipelines will be given later when we discuss the +history mechanism; +one important use of pipes which is illustrated there is in the +routing of information to the line printer. +.NH 2 +Filenames +.PP +Many commands to be executed will need the names of files as arguments. +\s-2UNIX\s0 +.I pathnames +consist of a number of +.I components +separated by `/'. +Each component except the last names a directory in which the next +component resides, in effect specifying the +.I path +of directories to follow to reach the file. +Thus the pathname +.DS +/etc/motd +.DE +specifies a file in the directory +`etc' +which is a subdirectory of the +.I root +directory `/'. +Within this directory the file named is `motd' which stands +for `message of the day'. +A +.I pathname +that begins with a slash is said to be an +.I absolute +pathname since it is specified from the absolute top of the entire +directory hierarchy of the system (the +.I root ). +.I Pathnames +which do not begin with `/' are interpreted as starting in the current +.I "working directory" , +which is, by default, your +.I home +directory and can be changed dynamically by the +.I cd +change directory command. +Such pathnames are said to be +.I relative +to the working directory since they are found by starting +in the working directory and descending to lower levels of directories +for each +.I component +of the pathname. If the pathname contains no slashes at all then the +file is contained in the working directory itself and the pathname is merely +the name of the file in this directory. +Absolute pathnames have no relation +to the working directory. +.PP +Most filenames consist of a number of alphanumeric characters and +`.'s (periods). +In fact, all printing characters except `/' (slash) may appear in filenames. +It is inconvenient to have most non-alphabetic characters in filenames +because many of these have special meaning to the shell. +The character `.' (period) is not a shell-metacharacter and is often used +to separate the +.I extension +of a file name from the base of the name. +Thus +.DS +prog.c prog.o prog.errs prog.output +.DE +are four related files. +They share a +.I base +portion of a name +(a base portion being that part of the name that is left when a trailing +`.' and following characters which are not `.' are stripped off). +The file +`prog.c' +might be the source for a C program, +the file `prog.o' the corresponding object file, +the file +`prog.errs' the errors resulting from a compilation of the program +and the file +`prog.output' the output of a run of the program. +.PP +If we wished to refer to all four of these files in a command, we could +use the notation +.DS +prog.* +.DE +This expression is expanded by the shell, before the command to which it is +an argument is executed, into a list of names which begin with `prog.'. +The character `*' here matches any sequence (including the empty sequence) +of characters in a file name. +The names which match are alphabetically sorted and placed in the +.I "argument list" +of the command. +Thus the command +.DS +echo prog.* +.DE +will echo the names +.DS +prog.c prog.errs prog.o prog.output +.DE +Note that the names are in sorted order here, and a different +order than we listed them above. +The +.I echo +command receives four words as arguments, even though we only typed +one word as an argument directly. +The four words were generated by +.I "filename expansion" +of the one input word. +.PP +Other notations for +.I "filename expansion" +are also available. +The character `?' matches any single character in a filename. +Thus +.DS +echo ? \|?? \|??? +.DE +will echo a line of filenames; first those with one character names, +then those with two character names, and finally those with three +character names. +The names of each length will be independently sorted. +.PP +Another mechanism consists of a sequence of characters between `[' and `]'. +This metasequence matches any single character from the enclosed set. +Thus +.DS +prog.[co] +.DE +will match +.DS +prog.c prog.o +.DE +in the example above. +We can also place two characters around a `\-' in this notation to denote +a range. +Thus +.DS +chap.[1\-5] +.DE +might match files +.DS +chap.1 chap.2 chap.3 chap.4 chap.5 +.DE +if they existed. +This is shorthand for +.DS +chap.[12345] +.DE +and otherwise equivalent. +.PP +An important point to note is that if a list of argument words to +a command (an +.I "argument list)" +contains filename expansion syntax, and if this filename expansion syntax +fails to match any existing file names, then the shell considers this +to be an error and prints a diagnostic +.DS +No match. +.DE +and does not execute the command. +.PP +Another very important point is that files with the character `.' at the +beginning are treated specially. +Neither `*' or `?' or the `[' `]' mechanism will match it. +This prevents accidental matching of the filenames `.' and `..' +in the working directory which have special meaning to the system, +as well as other files such as +.I \&.cshrc +which are not normally +visible. +We will discuss the special role of the file +.I \&.cshrc +later. +.PP +Another filename expansion mechanism gives access to the pathname of +the +.I home +directory of other users. +This notation consists of the character `~' (tilde) followed by another user's +login name. +For instance the word `~bill' would map to the pathname `/usr/bill' +if the home directory for `bill' was `/usr/bill'. +Since, on large systems, users may have login directories scattered over +many different disk volumes with different prefix directory names, +this notation provides a convenient way of accessing the files +of other users. +.PP +A special case of this notation consists of a `~' alone, e.g. `~/mbox'. +This notation is expanded by the shell into the file `mbox' in your +.I home +directory, i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB +Computer Science Department VAX machine, where this document was prepared. +This can be very useful if you have used +.I cd +to change to another directory and have found a file you wish to +copy using +.I cp. +If I give the command +.DS +cp thatfile ~ +.DE +the shell will expand this command to +.DS +cp thatfile /usr/bill +.DE +since my home directory is /usr/bill. +.PP +There also exists a mechanism using the characters `{' and `}' for +abbreviating a set of words which have common parts but cannot +be abbreviated by the above mechanisms because they are not files, +are the names of files which do not yet exist, +are not thus conveniently described. +This mechanism will be described much later, +in section 4.2, +as it is used less frequently. +.NH 2 +Quotation +.PP +We have already seen a number of metacharacters used by the shell. +These metacharacters pose a problem in that we cannot use them directly +as parts of words. +Thus the command +.DS +echo * +.DE +will not echo the character `*'. +It will either echo a sorted list of filenames in the +current +.I "working directory," +or print the message `No match' if there are +no files in the working directory. +.PP +The recommended mechanism for placing characters which are neither numbers, +digits, `/', `.' or `\-' in an argument word to a command is to enclose +it with single quotation characters `\'', i.e. +.DS +echo \'*\' +.DE +There is one special character `!' which is used by the +.I history +mechanism of the shell and which cannot be +.I escaped +by placing it within `\'' characters. +It and the character `\'' itself can be preceded by a single `\e' +to prevent their special meaning. +Thus +.DS +echo \e\'\e! +.DE +prints +.DS +\'! +.DE +These two mechanisms suffice to place any printing character into a word +which is an argument to a shell command. They can be combined, as in +.DS +echo \e\'\'*\' +.DE +which prints +.DS +\'* +.DE +since the first `\e' escaped the first `\'' and the `*' was enclosed +between `\'' characters. +.NH 2 +Terminating commands +.PP +When you are executing a command and the shell is +waiting for it to complete there are several ways +to force it to stop. +For instance if you type the command +.DS +cat /etc/passwd +.DE +the system will print a copy of a list of all users of the system +on your terminal. +This is likely to continue for several minutes unless you stop it. +You can send an +\s-2INTERRUPT\s0 +.I signal +to the +.I cat +command by typing ^C on your terminal.* +.FS +*On some older Unix systems the \s-2DEL\s0 or \s-2RUBOUT\s0 key +has the same effect. "stty all" will tell you the INTR key value. +.FE +Since +.I cat +does not take any precautions to avoid or otherwise handle this signal +the +\s-2INTERRUPT\s0 +will cause it to terminate. +The shell notices that +.I cat +has terminated and prompts you again with `% '. +If you hit \s-2INTERRUPT\s0 again, the shell will just +repeat its prompt since it handles \s-2INTERRUPT\s0 signals +and chooses to continue to execute commands rather than terminating +like +.I cat +did, which would have the effect of logging you out. +.PP +Another way in which many programs terminate is when they get an end-of-file +from their standard input. +Thus the +.I mail +program in the first example above was terminated when we typed a ^D +which generates an end-of-file from the standard input. +The shell also terminates when it gets an end-of-file printing `logout'; +\s-2UNIX\s0 then logs you off the system. +Since this means that typing too many ^D's can accidentally log us off, +the shell has a mechanism for preventing this. +This +.I ignoreeof +option will be discussed in section 2.2. +.PP +If a command has its standard input redirected from a file, then it will +normally terminate when it reaches the end of this file. +Thus if we execute +.DS +mail bill < prepared.text +.DE +the mail command will terminate without our typing a ^D. +This is because it read to the end-of-file of our file +`prepared.text' in which we placed a message for `bill' with an editor program. +We could also have done +.DS +cat prepared.text \||\| mail bill +.DE +since the +.I cat +command would then have written the text through the pipe to the +standard input of the mail command. +When the +.I cat +command completed it would have terminated, +closing down the pipeline +and the +.I mail +command would have received an end-of-file from it and terminated. +Using a pipe here is more complicated than redirecting input +so we would more likely use the first form. +These commands could also have been stopped by sending an \s-2INTERRUPT\s0. +.PP +Another possibility for stopping a command is to suspend its execution +temporarily, with the possibility of continuing execution later. This is +done by sending a \s-2STOP\s0 signal via typing a ^Z. +This signal causes all commands running on the terminal +(usually one but more if a pipeline is executing) to become suspended. +The shell notices that the command(s) have been suspended, types +`Stopped' and then prompts for a new command. +The previously executing command has been suspended, but otherwise +unaffected by the \s-2STOP\s0 signal. Any other commands can be executed +while the original command remains suspended. The suspended command can +be continued using the +.I fg +command with no arguments. The shell will then retype the command +to remind you which command is being continued, and cause the command +to resume execution. Unless any input files in use by the suspended +command have been changed in the meantime, the suspension has no effect +whatsoever on the execution of the command. This feature can be very useful +during editing, when you need to look at another file before continuing. +An +example of command suspension follows. +.DS +% mail harold +Someone just copied a big file into my directory and its name is +^Z +Stopped +% ls +funnyfile +prog.c +prog.o +% jobs +.ta 1.75i +[1] + Stopped mail harold +% fg +mail harold +funnyfile. Do you know who did it? +EOT +% +.so tabs +.DE +In this example someone was sending a message to Harold and forgot the +name of the file he wanted to mention. The mail command was suspended +by typing ^Z. When the shell noticed that the mail program was +suspended, it typed `Stopped' and prompted for a new command. Then the +.I ls +command was typed to find out the name of the file. The +.I jobs +command was run to find out which command was suspended. +At this time the +.I fg +command was typed to continue execution of the mail program. Input +to the mail program was then continued and ended with a ^D +which indicated the end of the message at which time the mail +program typed EOT. The +.I jobs +command will show which commands are suspended. +The ^Z should only be typed at the beginning of a line since +everything typed on the current line is discarded when a signal is sent +from the keyboard. This also happens on \s-2INTERRUPT\s0, and \s-2QUIT\s0 +signals. More information on +suspending jobs and controlling them is given in +section 2.6. +.PP +If you write or run programs which are not fully debugged then it may +be necessary to stop them somewhat ungracefully. +This can be done by sending them a \s-2QUIT\s0 +signal, sent by typing a ^\e. +This will usually provoke the shell to produce a message like: +.DS +Quit (Core dumped) +.DE +indicating that a file +`core' has been created containing information about the running program's +state when it terminated due to the \s-2QUIT\s0 signal. +You can examine this file yourself, or forward information to the +maintainer of the program telling him/her where the +.I "core file" +is. +.PP +If you run background commands (as explained in section 2.6) then these +commands will ignore \s-2INTERRUPT\s0 and \s-2QUIT\s0 signals at the +terminal. To stop them you must use the +.I kill +command. See section 2.6 for an example. +.PP +If you want to examine the output of a command without having it move +off the screen as the output of the +.DS +cat /etc/passwd +.DE +command will, you can use the command +.DS +more /etc/passwd +.DE +The +.I more +program pauses after each complete screenful and types `\-\-More\-\-' +at which point you can hit a space to get another screenful, a return +to get another line, a `?' to get some help on other commands, or a `q' to end the +.I more +program. You can also use more as a filter, i.e. +.DS +cat /etc/passwd | more +.DE +works just like the more simple more command above. +.PP +For stopping output of commands not involving +.I more +you can use the +^S key to stop the typeout. The typeout will resume when you +hit ^Q or any other key, but ^Q is normally used because +it only restarts the output and does not become input to the program +which is running. This works well on low-speed terminals, but at 9600 +baud it is hard to type ^S and ^Q fast enough to paginate +the output nicely, and a program like +.I more +is usually used. +.PP +An additional possibility is to use the ^O flush output +character; when this character is typed, all output from the current +command is thrown away (quickly) until the next input read occurs +or until the next shell prompt. This can be used to allow a command +to complete without having to suffer through the output on a slow +terminal; ^O is a toggle, so flushing can be turned off by +typing ^O again while output is being flushed. +.NH 2 +What now? +.PP +We have so far seen a number of mechanisms of the shell and learned a lot +about the way in which it operates. +The remaining sections will go yet further into the internals of the +shell, but you will surely want to try using the +shell before you go any further. +To try it you can log in to \s-2UNIX\s0 and type the following +command to the system: +.DS +chsh myname /bin/csh +.DE +Here `myname' should be replaced by the name you typed to +the system prompt of `login:' to get onto the system. +Thus I would use `chsh bill /bin/csh'. +.B +You only have to do this once; it takes effect at next login. +.R +You are now ready to try using +.I csh. +.PP +Before you do the `chsh' command, the shell you are using when +you log into the system is `/bin/sh'. +In fact, much of the above discussion is applicable to `/bin/sh'. +The next section will introduce many features particular to +.I csh +so you should change your shell to +.I csh +before you begin reading it. +.bp diff --git a/share/doc/usd/04.csh/csh.2 b/share/doc/usd/04.csh/csh.2 new file mode 100644 index 000000000000..47552af09347 --- /dev/null +++ b/share/doc/usd/04.csh/csh.2 @@ -0,0 +1,1301 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr H1 1 +.NH +Details on the shell for terminal users +.NH 2 +Shell startup and termination +.PP +When you login, the shell is started by the system in your +.I home +directory and begins by reading commands from a file +.I \&.cshrc +in this directory. +All shells which you may start during your terminal session will +read from this file. +We will later see what kinds of commands are usefully placed there. +For now we need not have this file and the shell does not complain about +its absence. +.PP +A +.I "login shell" , +executed after you login to the system, +will, after it reads commands from +.I \&.cshrc, +read commands from a file +.I \&.login +also in your home directory. +This file contains commands which you wish to do each time you login +to the \s-2UNIX\s0 system. +My +.I \&.login +file looks something like: +.DS +set ignoreeof +set mail=(/usr/spool/mail/bill) +echo "${prompt}users" ; users +alias ts \e + \'set noglob ; eval \`tset \-s \-m dialup:c100rv4pna \-m plugboard:?hp2621nl \!*\`\'; +ts; stty intr ^C kill ^U crt +set time=15 history=10 +msgs \-f +if (\-e $mail) then + echo "${prompt}mail" + mail +endif +.DE +.PP +This file contains several commands to be executed by \s-2UNIX\s0 +each time I login. +The first is a +.I set +command which is interpreted directly by the shell. It sets the shell +variable +.I ignoreeof +which causes the shell to not log me off if I hit ^D. Rather, +I use the +.I logout +command to log off of the system. +By setting the +.I mail +variable, I ask the shell to watch for incoming mail to me. Every 5 minutes +the shell looks for this file and tells me if more mail has arrived there. +An alternative to this is to put the command +.DS +biff y +.DE +in place of this +.I set; +this will cause me to be notified immediately when mail arrives, and to +be shown the first few lines of the new message. +.PP +Next I set the shell variable `time' to `15' causing the shell to automatically +print out statistics lines for commands which execute for at least 15 seconds +of \s-2CPU\s+2 time. The variable `history' is set to 10 indicating that +I want the shell to remember the last 10 commands I type in its +.I "history list" , +(described later). +.PP +I create an +.I alias +``ts'' which executes a +\fItset\fR\|(1) command setting up the modes of the terminal. +The parameters to +.I tset +indicate the kinds of terminal which I usually use when not on a hardwired +port. I then execute ``ts'' and also use the +.I stty +command to change the interrupt character to ^C and the line kill +character to ^U. +.PP +I then run the `msgs' program, which provides me with any +system messages which I have not seen before; the `\-f' option here prevents +it from telling me anything if there are no new messages. +Finally, if my mailbox file exists, then I run the `mail' program to +process my mail. +.PP +When the `mail' and `msgs' programs finish, the shell will finish +processing my +.I \&.login +file and begin reading commands from the terminal, prompting for each with +`% '. +When I log off (by giving the +.I logout +command) the shell +will print `logout' and execute commands from the file `.logout' +if it exists in my home directory. +After that the shell will terminate and \s-2UNIX\s0 will log +me off the system. +If the system is not going down, I will receive a new login message. +In any case, after the `logout' message the shell is committed to terminating +and will take no further input from my terminal. +.NH 2 +Shell variables +.PP +The shell maintains a set of +.I variables. +We saw above the variables +.I history +and +.I time +which had values `10' and `15'. +In fact, each shell variable has as value an array of +zero or more +.I strings. +Shell variables may be assigned values by the set command. It has +several forms, the most useful of which was given above and is +.DS +set name=value +.DE +.PP +Shell variables may be used to store values which are to +be used in commands later through a substitution mechanism. +The shell variables most commonly referenced are, however, those which the +shell itself refers to. +By changing the values of these variables one can directly affect the +behavior of the shell. +.PP +One of the most important variables is the variable +.I path. +This variable contains a sequence of directory names where the shell +searches for commands. +The +.I set +command with no arguments +shows the value of all variables currently defined (we usually say +.I set) +in the shell. +The default value for path will be shown by +.I set +to be +.DS +% set +.ta .75i +argv () +cwd /usr/bill +home /usr/bill +path (. /usr/ucb /bin /usr/bin) +prompt % +shell /bin/csh +status 0 +term c100rv4pna +user bill +% +.so tabs +.DE +This output indicates that the variable path points to the current +directory `.' and then `/usr/ucb', `/bin' and `/usr/bin'. +Commands which you may write might be in `.' (usually one of +your directories). +Commands developed at Berkeley, live in `/usr/ucb' +while commands developed at Bell Laboratories live in `/bin' and `/usr/bin'. +.PP +A number of locally developed programs on the system live in the directory +`/usr/local'. +If we wish that all shells which we invoke to have +access to these new programs we can place the command +.DS +set path=(. /usr/ucb /bin /usr/bin /usr/local) +.DE +in our file +.I \&.cshrc +in our home directory. +Try doing this and then logging out and back in and do +.DS +set +.DE +again to see that the value assigned to +.I path +has changed. +.FS \(dg +Another directory that might interest you is /usr/new, which contains +many useful user-contributed programs provided with Berkeley Unix. +.FE +.PP +One thing you should be aware of is that the shell examines each directory +which you insert into your path and determines which commands are contained +there. Except for the current directory `.', which the shell treats specially, +this means that if commands are added to a directory in your search path after +you have started the shell, they will not necessarily be found by the shell. +If you wish to use a command which has been added in this way, you should +give the command +.DS +rehash +.DE +to the shell, which will cause it to recompute its internal table of command +locations, so that it will find the newly added command. +Since the shell has to look in the current directory `.' on each command, +placing it at the end of the path specification usually works equivalently +and reduces overhead. +.PP +Other useful built in variables are the variable +.I home +which shows your home directory, +.I cwd +which contains your current working directory, +the variable +.I ignoreeof +which can be set in your +.I \&.login +file to tell the shell not to exit when it receives an end-of-file from +a terminal (as described above). +The variable `ignoreeof' +is one of several variables which the shell does not care about the +value of, only whether they are +.I set +or +.I unset. +Thus to set this variable you simply do +.DS +set ignoreeof +.DE +and to unset it do +.DS +unset ignoreeof +.DE +These give the variable `ignoreeof' no value, but none is desired or required. +.PP +Finally, some other built-in shell variables of use are the +variables +.I noclobber +and +.I mail. +The metasyntax +.DS +> filename +.DE +which redirects the standard output of a command +will overwrite and destroy the previous contents of the named file. +In this way you may accidentally overwrite a file which is valuable. +If you would prefer that the shell not overwrite files in this +way you can +.DS +set noclobber +.DE +in your +.I \&.login +file. +Then trying to do +.DS +date > now +.DE +would cause a diagnostic if `now' existed already. +You could type +.DS +date >! now +.DE +if you really wanted to overwrite the contents of `now'. +The `>!' is a special metasyntax indicating that clobbering the +file is ok.\(dg +.FS +\(dgThe space between the `!' and the word `now' is critical here, as `!now' +would be an invocation of the +.I history +mechanism, and have a totally different effect. +.FE +.NH 2 +The shell's history list +.PP +The shell can maintain a +.I "history list" +into which it places the words +of previous commands. +It is possible to use a notation to reuse commands or words +from commands in forming new commands. +This mechanism can be used to repeat previous commands or to +correct minor typing mistakes in commands. +.PP +The following figure gives a sample session involving typical usage of the +history mechanism of the shell. +.KF +.DS +% cat bug.c +main() + +{ + printf("hello); +} +% cc !$ +cc bug.c +"bug.c", line 4: newline in string or char constant +"bug.c", line 5: syntax error +% ed !$ +ed bug.c +29 +4s/);/"&/p + printf("hello"); +w +30 +q +% !c +cc bug.c +% a.out +hello% !e +ed bug.c +30 +4s/lo/lo\e\en/p + printf("hello\en"); +w +32 +q +% !c \-o bug +cc bug.c \-o bug +% size a.out bug +a.out: 2784+364+1028 = 4176b = 0x1050b +bug: 2784+364+1028 = 4176b = 0x1050b +% ls \-l !* +ls \-l a.out bug +\(mirwxr\(mixr\(mix 1 bill 3932 Dec 19 09:41 a.out +\(mirwxr\(mixr\(mix 1 bill 3932 Dec 19 09:42 bug +% bug +hello +% num bug.c | spp +spp: Command not found. +% ^spp^ssp +num bug.c | ssp + 1 main() + 3 { + 4 printf("hello\en"); + 5 } +% !! | lpr +num bug.c | ssp | lpr +% +.DE +.KE +In this example we have a very simple C program which has a bug (or two) +in it in the file `bug.c', which we `cat' out on our terminal. We then +try to run the C compiler on it, referring to the file again as `!$', +meaning the last argument to the previous command. Here the `!' is the +history mechanism invocation metacharacter, and the `$' stands for the last +argument, by analogy to `$' in the editor which stands for the end of the line. +The shell echoed the command, as it would have been typed without use of +the history mechanism, and then executed it. +The compilation yielded error diagnostics so we now run the editor on the +file we were trying to compile, fix the bug, and run the C compiler again, +this time referring to this command simply as `!c', which repeats the last +command which started with the letter `c'. If there were other +commands starting with `c' done recently we could have said `!cc' or even +`!cc:p' which would have printed the last command starting with `cc' +without executing it. +.PP +After this recompilation, we ran the resulting `a.out' file, and then +noting that there still was a bug, ran the editor again. After fixing +the program we ran the C compiler again, but tacked onto the command +an extra `\-o bug' telling the compiler to place the resultant binary in +the file `bug' rather than `a.out'. In general, the history mechanisms +may be used anywhere in the formation of new commands and other characters +may be placed before and after the substituted commands. +.PP +We then ran the `size' command to see how large the binary program images +we have created were, and then an `ls \-l' command with the same argument +list, denoting the argument list `\!*'. +Finally we ran the program `bug' to see that its output is indeed correct. +.PP +To make a numbered listing of the program we ran the `num' command on the file `bug.c'. +In order to compress out blank lines in the output of `num' we ran the +output through the filter `ssp', but misspelled it as spp. To correct this +we used a shell substitute, placing the old text and new text between `^' +characters. This is similar to the substitute command in the editor. +Finally, we repeated the same command with `!!', but sent its output to the +line printer. +.PP +There are other mechanisms available for repeating commands. The +.I history +command prints out a number of previous commands with numbers by which +they can be referenced. There is a way to refer to a previous command +by searching for a string which appeared in it, and there are other, +less useful, ways to select arguments to include in a new command. +A complete description of all these mechanisms +is given in the C shell manual pages in the \s-2UNIX\s0 Programmer's Manual. +.NH 2 +Aliases +.PP +The shell has an +.I alias +mechanism which can be used to make transformations on input commands. +This mechanism can be used to simplify the commands you type, +to supply default arguments to commands, +or to perform transformations on commands and their arguments. +The alias facility is similar to a macro facility. +Some of the features obtained by aliasing can be obtained also +using shell command files, but these take place in another instance +of the shell and cannot directly affect the current shells environment +or involve commands such as +.I cd +which must be done in the current shell. +.PP +As an example, suppose that there is a new version of the mail program +on the system called `newmail' +you wish to use, rather than the standard mail program which is called +`mail'. +If you place the shell command +.DS +alias mail newmail +.DE +in your +.I \&.cshrc +file, the shell will transform an input line of the form +.DS +mail bill +.DE +into a call on `newmail'. +More generally, suppose we wish the command `ls' to always show +sizes of files, that is to always do `\-s'. +We can do +.DS +alias ls ls \-s +.DE +or even +.DS +alias dir ls \-s +.DE +creating a new command syntax `dir' +which does an `ls \-s'. +If we say +.DS +dir ~bill +.DE +then the shell will translate this to +.DS +ls \-s /mnt/bill +.DE +.PP +Thus the +.I alias +mechanism can be used to provide short names for commands, +to provide default arguments, +and to define new short commands in terms of other commands. +It is also possible to define aliases which contain multiple +commands or pipelines, showing where the arguments to the original +command are to be substituted using the facilities of the +history mechanism. +Thus the definition +.DS +alias cd \'cd \e!* ; ls \' +.DE +would do an +.I ls +command after each change directory +.I cd +command. +We enclosed the entire alias definition in `\'' characters to prevent +most substitutions from occurring and the character `;' from being +recognized as a metacharacter. +The `!' here is escaped with a `\e' to prevent it from being interpreted +when the alias command is typed in. +The `\e!*' here substitutes the entire argument list to the pre-aliasing +.I cd +command, without giving an error if there were no arguments. +The `;' separating commands is used here +to indicate that one command is to be done and then the next. +Similarly the definition +.DS +alias whois \'grep \e!^ /etc/passwd\' +.DE +defines a command which looks up its first argument in the password file. +.PP +.B Warning: +The shell currently reads the +.I \&.cshrc +file each time it starts up. If you place a large number of commands +there, shells will tend to start slowly. A mechanism for saving the shell +environment after reading the \fI\&.cshrc\fR file and quickly restoring it is +under development, but for now you should try to limit the number of +aliases you have to a reasonable number... 10 or 15 is reasonable, +50 or 60 will cause a noticeable delay in starting up shells, and make +the system seem sluggish when you execute commands from within the editor +and other programs. +.NH 2 +More redirection; >> and >& +.PP +There are a few more notations useful to the terminal user +which have not been introduced yet. +.PP +In addition to the standard output, commands also have a +.I "diagnostic output" +which is normally directed to the terminal even when the standard output +is redirected to a file or a pipe. +It is occasionally desirable to direct the diagnostic output along with +the standard output. +For instance if you want to redirect the output of a long running command +into a file and wish to have a record of any error diagnostic it produces +you can do +.DS +command >& file +.DE +The `>&' here tells the shell to route both the diagnostic output and the +standard output into `file'. +Similarly you can give the command +.DS +command |\|& lpr +.DE +to route both standard and diagnostic output through the pipe +to the line printer daemon +.I lpr.\(dd +.FS +\(dd A command of the form +.br +.ti +5 +command >&! file +.br +exists, and is used when +.I noclobber +is set and +.I file +already exists. +.FE +.PP +Finally, it is possible to use the form +.DS +command >> file +.DE +to place output at the end of an existing file.\(dg +.FS +\(dg If +.I noclobber +is set, then an error will result if +.I file +does not exist, otherwise the shell will create +.I file +if it doesn't exist. +A form +.br +.ti +5 +command >>! file +.br +makes it not be an error for file to not exist when +.I noclobber +is set. +.FE +.NH 2 +Jobs; Background, Foreground, or Suspended +.PP +When one or more commands +are typed together as a pipeline or as a sequence of commands separated by +semicolons, a single +.I job +is created by the shell consisting of these commands together as a unit. +Single commands without pipes or semicolons create the simplest jobs. +Usually, every line typed to the shell creates a job. +Some lines that create jobs (one per line) are +.DS +sort < data +ls \-s | sort \-n | head \-5 +mail harold +.DE +.PP +If the metacharacter `&' is typed +at the end of the commands, then the job is started as a +.I background +job. This means that the shell does not wait for it to complete but +immediately prompts and is ready for another command. The job runs +.I "in the background" +at the same time that normal jobs, called +.I foreground +jobs, continue to be read and executed by the shell one at a time. +Thus +.DS +du > usage & +.DE +would run the +.I du +program, which reports on the disk usage of your working directory (as well as +any directories below it), put the output into the file `usage' and return +immediately with a prompt for the next command without out waiting for +.I du +to finish. The +.I du +program would continue executing in the background +until it finished, even though you can type and execute more commands in the +mean time. +When a background +job terminates, a message is typed by the shell just before the next prompt +telling you that the job has completed. +In the following example the +.I du +job finishes sometime during the +execution of the +.I mail +command and its completion is reported just before +the prompt after the +.I mail +job is finished. +.DS +% du > usage & +[1] 503 +% mail bill +How do you know when a background job is finished? +EOT +.ta 1.75i +[1] \- Done du > usage +% +.so tabs +.DE +If the job did not terminate normally the `Done' message might say +something else like `Killed'. +If you want the +terminations of background jobs to be reported at the time they occur +(possibly interrupting the output of other foreground jobs), you can set +the +.I notify +variable. In the previous example this would mean that the +`Done' message might have come right in the middle of the message to +Bill. +Background jobs are unaffected by any signals from the keyboard like +the \s-2STOP\s0, \s-2INTERRUPT\s0, or \s-2QUIT\s0 signals mentioned earlier. +.PP +Jobs are recorded in a table inside the shell until they terminate. +In this table, the shell remembers the command names, arguments and the +.I "process numbers" +of all commands in the job as well as the working directory where the job was +started. +Each job in the table is either running +.I "in the foreground" +with the shell waiting for it to terminate, running +.I "in the background," +or +.I suspended. +Only one job can be running in the foreground at one time, but several +jobs can be suspended or running in the background at once. As each job +is started, it is assigned a small identifying +number called the +.I "job number" +which can be used later to refer to the job in the commands described below. +Job numbers remain +the same until the job terminates and then are re-used. +.PP +When a job is started in the background using `&', its number, as well +as the process numbers of all its (top level) commands, is typed by the shell +before prompting you for another command. +For example, +.DS +% ls \-s | sort \-n > usage & +[2] 2034 2035 +% +.DE +runs the `ls' program with the `\-s' options, pipes this output into +the `sort' program with the `\-n' option which puts its output into the +file `usage'. +Since the `&' was at the end of the line, these two programs were started +together as a background job. After starting the job, the shell prints +the job number in brackets (2 in this case) followed by the process number +of each program started in the job. Then the shell immediates prompts for +a new command, leaving the job running simultaneously. +.PP +As mentioned in section 1.8, foreground jobs become +.I suspended +by typing ^Z +which sends a \s-2STOP\s0 signal to the currently running +foreground job. A background job can become suspended by using the +.I stop +command described below. When jobs are suspended they merely stop +any further progress until started again, either in the foreground +or the background. The shell notices when a job becomes stopped and +reports this fact, much like it reports the termination of background jobs. +For foreground jobs this looks like +.DS +% du > usage +^Z +Stopped +% +.DE +`Stopped' message is typed by the shell when it notices that the +.I du +program stopped. +For background jobs, using the +.I stop +command, it is +.DS +% sort usage & +[1] 2345 +% stop %1 +.ta 1.75i +[1] + Stopped (signal) sort usage +% +.so tabs +.DE +Suspending foreground jobs can be very useful when you need to temporarily +change what you are doing (execute other commands) and then return to +the suspended job. Also, foreground jobs can be suspended and then +continued as background jobs using the +.I bg +command, allowing you to continue other work and +stop waiting for the foreground job to finish. Thus +.DS +% du > usage +^Z +Stopped +% bg +[1] du > usage & +% +.DE +starts `du' in the foreground, stops it before it finishes, then continues +it in the background allowing more foreground commands to be executed. +This is especially helpful +when a foreground job ends up taking longer than you expected and you +wish you had started it in the background in the beginning. +.PP +All +.I "job control" +commands can take an argument that identifies a particular +job. +All job name arguments begin with the character `%', since some of the +job control commands also accept process numbers (printed by the +.I ps +command.) +The default job (when no argument is given) is called the +.I current +job and is identified by a `+' in the output of the +.I jobs +command, which shows you which jobs you have. +When only one job is stopped or running in the background (the usual case) +it is always the current job thus no argument is needed. +If a job is stopped while running in the foreground it becomes the +.I current +job and the existing current job becomes the +.I previous +job \- identified by a `\-' in the output of +.I jobs. +When the current job terminates, the previous job becomes the current job. +When given, the argument is either `%\-' (indicating +the previous job); `%#', where # is the job number; +`%pref' where pref is some unique prefix of the command name +and arguments of one of the jobs; or `%?' followed by some string found +in only one of the jobs. +.PP +The +.I jobs +command types the table of jobs, giving the job number, +commands and status (`Stopped' or `Running') of each background or +suspended job. With the `\-l' option the process numbers are also +typed. +.DS +% du > usage & +[1] 3398 +% ls \-s | sort \-n > myfile & +[2] 3405 +% mail bill +^Z +Stopped +% jobs +.ta 1.75i +[1] \(mi Running du > usage +[2] Running ls \-s | sort \-n > myfile +[3] \(pl Stopped mail bill +% fg %ls +ls \-s | sort \-n > myfile +% more myfile +.so tabs +.DE +.PP +The +.I fg +command runs a suspended or background job in the foreground. It is +used to restart a previously suspended job or change a background job +to run in the foreground (allowing signals or input from the terminal). +In the above example we used +.I fg +to change the `ls' job from the +background to the foreground since we wanted to wait for it to +finish before looking at its output file. +The +.I bg +command runs a suspended job in the background. It is usually used +after stopping the currently running foreground job with the +\s-2STOP\s0 signal. The combination of the \s-2STOP\s0 signal and the +.I bg +command changes a foreground job into a background job. +The +.I stop +command suspends a background job. +.PP +The +.I kill +command terminates a background or suspended job immediately. +In addition to jobs, it may be given process numbers as arguments, +as printed by +.I ps. +Thus, in the example above, the running +.I du +command could have been terminated by the command +.DS +% kill %1 +.ta 1.75i +[1] Terminated du > usage +% +.so tabs +.DE +.PP +The +.I notify +command (not the variable mentioned earlier) indicates that the termination +of a specific job should be +reported at the time it finishes instead of waiting for the next prompt. +.PP +If a job running in the background tries to read input from the terminal +it is automatically stopped. When such a job is then run in the +foreground, input can be given to the job. If desired, the job can +be run in the background again until it requests input again. +This is illustrated in the following sequence where the `s' command in the +text editor might take a long time. +.ID +.nf +% ed bigfile +120000 +1,$s/thisword/thatword/ +^Z +Stopped +% bg +[1] ed bigfile & +% + . . . some foreground commands +.ta 1.75i +[1] Stopped (tty input) ed bigfile +% fg +ed bigfile +w +120000 +q +% +.so tabs +.DE +So after the `s' command was issued, the `ed' job was stopped with ^Z +and then put in the background using +.I bg. +Some time later when the `s' command was finished, +.I ed +tried to read another command and was stopped because jobs +in the background cannot read from the terminal. The +.I fg +command returned the `ed' job to the foreground where it could once again +accept commands from the terminal. +.PP +The command +.DS +stty tostop +.DE +causes all background jobs run on your terminal to stop +when they are about to +write output to the terminal. This prevents messages from background +jobs from interrupting foreground job output and allows you to run +a job in the background without losing terminal output. It also +can be used for interactive programs that sometimes have long +periods without interaction. Thus each time it outputs a prompt for more +input it will stop before the prompt. It can then be run in the +foreground using +.I fg, +more input can be given and, if necessary stopped and returned to +the background. This +.I stty +command might be a good thing to put in your +.I \&.login +file if you do not like output from background jobs interrupting +your work. It also can reduce the need for redirecting the output +of background jobs if the output is not very big: +.DS +% stty tostop +% wc hugefile & +[1] 10387 +% ed text +\&. . . some time later +q +.ta 1.75i +[1] Stopped (tty output) wc hugefile +% fg wc +wc hugefile + 13371 30123 302577 +% stty \-tostop +.so tabs +.DE +Thus after some time the `wc' command, which counts the lines, words +and characters in a file, had one line of output. When it tried to +write this to the terminal it stopped. By restarting it in the +foreground we allowed it to write on the terminal exactly when we were +ready to look at its output. +Programs which attempt to change the mode of the terminal will also +block, whether or not +.I tostop +is set, when they are not in the foreground, as +it would be very unpleasant to have a background job change the state +of the terminal. +.PP +Since the +.I jobs +command only prints jobs started in the currently executing shell, +it knows nothing about background jobs started in other login sessions +or within shell files. The +.I ps +can be used in this case to find out about background jobs not started +in the current shell. +.NH 2 +Working Directories +.PP +As mentioned in section 1.6, the shell is always in a particular +.I "working directory." +The `change directory' command +.I chdir +(its +short form +.I cd +may also be used) +changes the working directory of the shell, +that is, changes the directory you +are located in. +.PP +It is useful to make a directory for each project you wish to work on +and to place all files related to that project in that directory. +The `make directory' command, +.I mkdir, +creates a new directory. +The +.I pwd +(`print working directory') command +reports the absolute pathname of the working directory of the shell, +that is, the directory you are +located in. +Thus in the example below: +.DS +% pwd +/usr/bill +% mkdir newpaper +% chdir newpaper +% pwd +/usr/bill/newpaper +% +.DE +the user has created and moved to the +directory +.I newpaper. +where, for example, he might +place a group of related files. +.PP +No matter where you have moved to in a directory hierarchy, +you can return to your `home' login directory by doing just +.DS +cd +.DE +with no arguments. +The name `..' always means the directory above the current one in +the hierarchy, thus +.DS +cd .. +.DE +changes the shell's working directory to the one directly above the +current one. +The name `..' can be used in any +pathname, thus, +.DS +cd ../programs +.DE +means +change to the directory `programs' contained in the directory +above the current one. +If you have several directories for different +projects under, say, your home directory, +this shorthand notation +permits you to switch easily between them. +.PP +The shell always remembers the pathname of its current working directory in +the variable +.I cwd. +The shell can also be requested to remember the previous directory when +you change to a new working directory. If the `push directory' command +.I pushd +is used in place of the +.I cd +command, the shell saves the name of the current working directory +on a +.I "directory stack" +before changing to the new one. +You can see this list at any time by typing the `directories' +command +.I dirs. +.ID +.nf +% pushd newpaper/references +~/newpaper/references ~ +% pushd /usr/lib/tmac +/usr/lib/tmac ~/newpaper/references ~ +% dirs +/usr/lib/tmac ~/newpaper/references ~ +% popd +~/newpaper/references ~ +% popd +~ +% +.DE +The list is printed in a horizontal line, reading left to right, +with a tilde (~) as +shorthand for your home directory\(emin this case `/usr/bill'. +The directory stack is printed whenever there is more than one +entry on it and it changes. +It is also printed by a +.I dirs +command. +.I Dirs +is usually faster and more informative than +.I pwd +since it shows the current working directory as well as any +other directories remembered in the stack. +.PP +The +.I pushd +command with no argument +alternates the current directory with the first directory in the +list. +The `pop directory' +.I popd +command without an argument returns you to the directory you were in prior to +the current one, discarding the previous current directory from the +stack (forgetting it). +Typing +.I popd +several times in a series takes you backward through the directories +you had been in (changed to) by +.I pushd +command. +There are other options to +.I pushd +and +.I popd +to manipulate the contents of the directory stack and to change +to directories not at the top of the stack; see the +.I csh +manual page for details. +.PP +Since the shell remembers the working directory in which each job +was started, it warns you when you might be confused by restarting +a job in the foreground which has a different working directory than the +current working directory of the shell. Thus if you start a background +job, then change the shell's working directory and then cause the +background job to run in the foreground, the shell warns you that the +working directory of the currently running foreground job is different +from that of the shell. +.DS +% dirs \-l +/mnt/bill +% cd myproject +% dirs +~/myproject +% ed prog.c +1143 +^Z +Stopped +% cd .. +% ls +myproject +textfile +% fg +ed prog.c (wd: ~/myproject) +.DE +This way the shell warns you when there +is an implied change of working directory, even though no cd command was +issued. In the above example the `ed' job was still in `/mnt/bill/project' +even though the shell had changed to `/mnt/bill'. +A similar warning is given when such a foreground job +terminates or is suspended (using the \s-2STOP\s0 signal) since +the return to the shell again implies a change of working directory. +.DS +% fg +ed prog.c (wd: ~/myproject) + . . . after some editing +q +(wd now: ~) +% +.DE +These messages are sometimes confusing if you use programs that change +their own working directories, since the shell only remembers which +directory a job is started in, and assumes it stays there. +The `\-l' option of +.I jobs +will type the working directory +of suspended or background jobs when it is different +from the current working directory of the shell. +.NH 2 +Useful built-in commands +.PP +We now give a few of the useful built-in commands of the shell describing +how they are used. +.PP +The +.I alias +command described above is used to assign new aliases and to show the +existing aliases. +With no arguments it prints the current aliases. +It may also be given only one argument such as +.DS +alias ls +.DE +to show the current alias for, e.g., `ls'. +.PP +The +.I echo +command prints its arguments. +It is often used in +.I "shell scripts" +or as an interactive command +to see what filename expansions will produce. +.PP +The +.I history +command will show the contents of the history list. +The numbers given with the history events can be used to reference +previous events which are difficult to reference using the +contextual mechanisms introduced above. +There is also a shell variable called +.I prompt. +By placing a `!' character in its value the shell will there substitute +the number of the current command in the history list. +You can use this number to refer to this command in a history substitution. +Thus you could +.DS +set prompt=\'\e! % \' +.DE +Note that the `!' character had to be +.I escaped +here even within `\'' characters. +.PP +The +.I limit +command is used to restrict use of resources. +With no arguments it prints the current limitations: +.DS +.ta 1i +cputime unlimited +filesize unlimited +datasize 5616 kbytes +stacksize 512 kbytes +coredumpsize unlimited +.so tabs +.DE +Limits can be set, e.g.: +.DS +limit coredumpsize 128k +.DE +Most reasonable units abbreviations will work; see the +.I csh +manual page for more details. +.PP +The +.I logout +command can be used to terminate a login shell which has +.I ignoreeof +set. +.PP +The +.I rehash +command causes the shell to recompute a table of where commands are +located. This is necessary if you add a command to a directory +in the current shell's search path and wish the shell to find it, +since otherwise the hashing algorithm may tell the shell that the +command wasn't in that directory when the hash table was computed. +.PP +The +.I repeat +command can be used to repeat a command several times. +Thus to make 5 copies of the file +.I one +in the file +.I five +you could do +.DS +repeat 5 cat one >> five +.DE +.PP +The +.I setenv +command can be used +to set variables in the environment. +Thus +.DS +setenv TERM adm3a +.DE +will set the value of the environment variable \s-2TERM\s0 +to +`adm3a'. +A user program +.I printenv +exists which will print out the environment. +It might then show: +.DS +% printenv +HOME=/usr/bill +SHELL=/bin/csh +PATH=:/usr/ucb:/bin:/usr/bin:/usr/local +TERM=adm3a +USER=bill +% +.DE +.PP +The +.I source +command can be used to force the current shell to read commands from +a file. +Thus +.DS +source .cshrc +.DE +can be used after editing in a change to the +.I \&.cshrc +file which you wish to take effect right away. +.PP +The +.I time +command can be used to cause a command to be timed no matter how much +\s-2CPU\s0 time it takes. +Thus +.DS +% time cp /etc/rc /usr/bill/rc +0.0u 0.1s 0:01 8% 2+1k 3+2io 1pf+0w +% time wc /etc/rc /usr/bill/rc + 52 178 1347 /etc/rc + 52 178 1347 /usr/bill/rc + 104 356 2694 total +0.1u 0.1s 0:00 13% 3+3k 5+3io 7pf+0w +% +.DE +indicates that the +.I cp +command used a negligible amount of user time (u) +and about 1/10th of a system time (s); the elapsed time was 1 second (0:01), +there was an average memory usage of 2k bytes of program space and 1k +bytes of data space over the cpu time involved (2+1k); the program +did three disk reads and two disk writes (3+2io), and took one page fault +and was not swapped (1pf+0w). +The word count command +.I wc +on the other hand used 0.1 seconds of user time and 0.1 seconds of system +time in less than a second of elapsed time. +The percentage `13%' indicates that over the period when it was active +the command `wc' used an average of 13 percent of the available \s-2CPU\s0 +cycles of the machine. +.PP +The +.I unalias +and +.I unset +commands can be used +to remove aliases and variable definitions from the shell, and +.I unsetenv +removes variables from the environment. +.NH 2 +What else? +.PP +This concludes the basic discussion of the shell for terminal users. +There are more features of the shell to be discussed here, and all +features of the shell are discussed in its manual pages. +One useful feature which is discussed later is the +.I foreach +built-in command which can be used to run the same command +sequence with a number of different arguments. +.PP +If you intend to use \s-2UNIX\s0 a lot you should look through +the rest of this document and the csh manual pages (section1) to become familiar +with the other facilities which are available to you. +.bp diff --git a/share/doc/usd/04.csh/csh.3 b/share/doc/usd/04.csh/csh.3 new file mode 100644 index 000000000000..d5fda6079b1d --- /dev/null +++ b/share/doc/usd/04.csh/csh.3 @@ -0,0 +1,646 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr H1 2 +.NH +Shell control structures and command scripts +.NH 2 +Introduction +.PP +It is possible to place commands in files and to cause shells to be +invoked to read and execute commands from these files, +which are called +.I "shell scripts." +We here detail those features of the shell useful to the writers of such +scripts. +.NH 2 +Make +.PP +It is important to first note what shell scripts are +.I not +useful for. +There is a program called +.I make +which is very useful for maintaining a group of related files +or performing sets of operations on related files. +For instance a large program consisting of one or more files +can have its dependencies described in a +.I makefile +which contains definitions of the commands used to create these +different files when changes occur. +Definitions of the means for printing listings, cleaning up the directory +in which the files reside, and installing the resultant programs +are easily, and most appropriately placed in this +.I makefile. +This format is superior and preferable to maintaining a group of shell +procedures to maintain these files. +.PP +Similarly when working on a document a +.I makefile +may be created which defines how different versions of the document +are to be created and which options of +.I nroff +or +.I troff +are appropriate. +.NH 2 +Invocation and the argv variable +.PP +A +.I csh +command script may be interpreted by saying +.DS +% csh script ... +.DE +where +.I script +is the name of the file containing a group of +.I csh +commands and +`\&...' is replaced by a sequence of arguments. +The shell places these arguments in the variable +.I argv +and then begins to read commands from the script. +These parameters are then available through the same mechanisms +which are used to reference any other shell variables. +.PP +If you make the file +`script' +executable by doing +.DS +chmod 755 script +.DE +and place a shell comment at the beginning of the shell script +(i.e. begin the file with a `#' character) +then a `/bin/csh' will automatically be invoked to execute `script' when +you type +.DS +script +.DE +If the file does not begin with a `#' then the standard shell +`/bin/sh' will be used to execute it. +This allows you to convert your older shell scripts to use +.I csh +at your convenience. +.NH 2 +Variable substitution +.PP +After each input line is broken into words and history substitutions +are done on it, the input line is parsed into distinct commands. +Before each command is executed a mechanism know as +.I "variable substitution" +is done on these words. +Keyed by the character `$' this substitution replaces the names +of variables by their values. +Thus +.DS +echo $argv +.DE +when placed in a command script would cause the current value of the +variable +.I argv +to be echoed to the output of the shell script. +It is an error for +.I argv +to be unset at this point. +.PP +A number of notations are provided for accessing components and attributes +of variables. +The notation +.DS +$?name +.DE +expands to `1' if name is +.I set +or to `0' +if name is not +.I set. +It is the fundamental mechanism used for checking whether particular +variables have been assigned values. +All other forms of reference to undefined variables cause errors. +.PP +The notation +.DS +$#name +.DE +expands to the number of elements in the variable +.I name. +Thus +.DS +% set argv=(a b c) +% echo $?argv +1 +% echo $#argv +3 +% unset argv +% echo $?argv +0 +% echo $argv +Undefined variable: argv. +% +.DE +.PP +It is also possible to access the components of a variable +which has several values. +Thus +.DS +$argv[1] +.DE +gives the first component of +.I argv +or in the example above `a'. +Similarly +.DS +$argv[$#argv] +.DE +would give `c', +and +.DS +$argv[1\-2] +.DE +would give `a b'. Other notations useful in shell scripts are +.DS +$\fIn\fR +.DE +where +.I n +is an integer as a shorthand for +.DS +$argv[\fIn\fR\|] +.DE +the +.I n\|th +parameter and +.DS +$* +.DE +which is a shorthand for +.DS +$argv +.DE +The form +.DS +$$ +.DE +expands to the process number of the current shell. +Since this process number is unique in the system it can +be used in generation of unique temporary file names. +The form +.DS +$< +.DE +is quite special and is replaced by the next line of input read from +the shell's standard input (not the script it is reading). This is +useful for writing shell scripts that are interactive, reading +commands from the terminal, or even writing a shell script that +acts as a filter, reading lines from its input file. +Thus the sequence +.DS +echo 'yes or no?\ec' +set a=($<) +.DE +would write out the prompt `yes or no?' without a newline and then +read the answer into the variable `a'. In this case `$#a' would be +`0' if either a blank line or end-of-file (^D) was typed. +.PP +One minor difference between `$\fIn\fR\|' and `$argv[\fIn\fR\|]' +should be noted here. +The form +`$argv[\fIn\fR\|]' +will yield an error if +.I n +is not in the range +`1\-$#argv' +while `$n' +will never yield an out of range subscript error. +This is for compatibility with the way older shells handled parameters. +.PP +Another important point is that it is never an error to give a subrange +of the form `n\-'; if there are less than +.I n +components of the given variable then no words are substituted. +A range of the form `m\-n' likewise returns an empty vector without giving +an error when \fIm\fR exceeds the number of elements of the given variable, +provided the subscript \fIn\fR is in range. +.NH 2 +Expressions +.PP +In order for interesting shell scripts to be constructed it +must be possible to evaluate expressions in the shell based on the +values of variables. +In fact, all the arithmetic operations of the language C are available +in the shell +with the same precedence that they have in C. +In particular, the operations `==' and `!=' compare strings +and the operators `&&' and `|\|\||' implement the boolean and/or operations. +The special operators `=~' and `!~' are similar to `==' and `!=' except +that the string on the right side can have pattern matching characters +(like *, ? or []) and the test is whether the string on the left matches +the pattern on the right. +.PP +The shell also allows file enquiries of the form +.DS +\-? filename +.DE +where `?' is replace by a number of single characters. +For instance the expression primitive +.DS +\-e filename +.DE +tell whether the file +`filename' +exists. +Other primitives test for read, write and execute access to the file, +whether it is a directory, or has non-zero length. +.PP +It is possible to test whether a command terminates normally, +by a primitive of the +form `{ command }' which returns true, i.e. `1' if the command +succeeds exiting normally with exit status 0, or `0' if the command +terminates abnormally or with exit status non-zero. +If more detailed information about the execution status of a command +is required, it can be executed and the variable `$status' examined +in the next command. +Since `$status' is set by every command, it is very transient. +It can be saved if it is inconvenient to use it only in the single +immediately following command. +.PP +For a full list of expression components available see the manual +section for the shell. +.NH 2 +Sample shell script +.PP +A sample shell script which makes use of the expression mechanism +of the shell and some of its control structure follows: +.DS +% cat copyc +# +# Copyc copies those C programs in the specified list +# to the directory ~/backup if they differ from the files +# already in ~/backup +# +set noglob +foreach i ($argv) + + if ($i !~ *.c) continue # not a .c file so do nothing + + if (! \-r ~/backup/$i:t) then + echo $i:t not in backup... not cp\e\'ed + continue + endif + + cmp \-s $i ~/backup/$i:t # to set $status + + if ($status != 0) then + echo new backup of $i + cp $i ~/backup/$i:t + endif +end +.DE +.PP +This script makes use of the +.I foreach +command, which causes the shell to execute the commands between the +.I foreach +and the matching +.I end +for each of the values given between `(' and `)' with the named +variable, in this case `i' set to successive values in the list. +Within this loop we may use the command +.I break +to stop executing the loop +and +.I continue +to prematurely terminate one iteration +and begin the next. +After the +.I foreach +loop the iteration variable +(\fIi\fR in this case) +has the value at the last iteration. +.PP +We set the variable +.I noglob +here to prevent filename expansion of the members of +.I argv. +This is a good idea, in general, if the arguments to a shell script +are filenames which have already been expanded or if the arguments +may contain filename expansion metacharacters. +It is also possible to quote each use of a `$' variable expansion, +but this is harder and less reliable. +.PP +The other control construct used here is a statement of the form +.DS +\fBif\fR ( expression ) \fBthen\fR + command + ... +\fBendif\fR +.DE +The placement of the keywords here is +.B not +flexible due to the current implementation of the shell.\(dg +.FS +\(dgThe following two formats are not currently acceptable to the shell: +.sp +.in +5 +.nf +\fBif\fR ( expression ) # \fBWon't work!\fR +\fBthen\fR + command + ... +\fBendif\fR +.fi +.in -5 +.sp +and +.sp +.in +5 +.nf +\fBif\fR ( expression ) \fBthen\fR command \fBendif\fR # \fBWon't work\fR +.in -5 +.fi +.FE +.PP +The shell does have another form of the if statement of the form +.DS +\fBif\fR ( expression ) \fBcommand\fR +.DE +which can be written +.DS +\fBif\fR ( expression ) \e + command +.DE +Here we have escaped the newline for the sake of appearance. +The command must not involve `\||\|', `&' or `;' +and must not be another control command. +The second form requires the final `\e' to +.B immediately +precede the end-of-line. +.PP +The more general +.I if +statements above also admit a sequence of +.I else\-if +pairs followed by a single +.I else +and an +.I endif, +e.g.: +.DS +\fBif\fR ( expression ) \fBthen\fR + commands +\fBelse\fR \fBif\fR (expression ) \fBthen\fR + commands +\&... + +\fBelse\fR + commands +\fBendif\fR +.DE +.PP +Another important mechanism used in shell scripts is the `:' modifier. +We can use the modifier `:r' here to extract a root of a filename or +`:e' to extract the +.I extension. +Thus if the variable +.I i +has the value +`/mnt/foo.bar' +then +.sp +.in +5 +.nf +% echo $i $i:r $i:e +/mnt/foo.bar /mnt/foo bar +% +.sp +.in -5 +.fi +shows how the `:r' modifier strips off the trailing `.bar' and the +the `:e' modifier leaves only the `bar'. +Other modifiers will take off the last component of a pathname leaving +the head `:h' or all but the last component of a pathname leaving the +tail `:t'. +These modifiers are fully described in the +.I csh +manual pages in the User's Reference Manual. +It is also possible to use the +.I "command substitution" +mechanism described in the next major section to perform modifications +on strings to then reenter the shell's environment. +Since each usage of this mechanism involves the creation of a new process, +it is much more expensive to use than the `:' modification mechanism.\(dd +.FS +\(dd It is also important to note that +the current implementation of the shell limits the number of `:' modifiers +on a `$' substitution to 1. +Thus +.sp +.nf +.in +5 +% echo $i $i:h:t +/a/b/c /a/b:t +% +.in -5 +.fi +.sp +does not do what one would expect. +.FE +Finally, we note that the character `#' lexically introduces a shell +comment in shell scripts (but not from the terminal). +All subsequent characters on the input line after a `#' are discarded +by the shell. +This character can be quoted using `\'' or `\e' to place it in +an argument word. +.NH 2 +Other control structures +.PP +The shell also has control structures +.I while +and +.I switch +similar to those of C. +These take the forms +.DS +\fBwhile\fR ( expression ) + commands +\fBend\fR +.DE +and +.DS +\fBswitch\fR ( word ) + +\fBcase\fR str1: + commands + \fBbreaksw\fR + +\& ... + +\fBcase\fR strn: + commands + \fBbreaksw\fR + +\fBdefault:\fR + commands + \fBbreaksw\fR + +\fBendsw\fR +.DE +For details see the manual section for +.I csh. +C programmers should note that we use +.I breaksw +to exit from a +.I switch +while +.I break +exits a +.I while +or +.I foreach +loop. +A common mistake to make in +.I csh +scripts is to use +.I break +rather than +.I breaksw +in switches. +.PP +Finally, +.I csh +allows a +.I goto +statement, with labels looking like they do in C, i.e.: +.DS +loop: + commands + \fBgoto\fR loop +.DE +.NH 2 +Supplying input to commands +.PP +Commands run from shell scripts receive by default the standard +input of the shell which is running the script. +This is different from previous shells running +under \s-2UNIX\s0. It allows shell scripts to fully participate +in pipelines, but mandates extra notation for commands which are to take +inline data. +.PP +Thus we need a metanotation for supplying inline data to commands in +shell scripts. +As an example, consider this script which runs the editor to +delete leading blanks from the lines in each argument file: +.DS +% cat deblank +# deblank \-\- remove leading blanks +foreach i ($argv) +ed \- $i << \'EOF\' +1,$s/^[ ]*// +w +q +\&\'EOF\' +end +% +.DE +The notation `<< \'EOF\'' +means that the standard input for the +.I ed +command is to come from the text in the shell script file +up to the next line consisting of exactly `\'EOF\''. +The fact that the `EOF' is enclosed in `\'' characters, i.e. quoted, +causes the shell to not perform variable substitution on the +intervening lines. +In general, if any part of the word following the `<<' which the +shell uses to terminate the text to be given to the command is quoted +then these substitutions will not be performed. +In this case since we used the form `1,$' in our editor script +we needed to insure that this `$' was not variable substituted. +We could also have insured this by preceding the `$' here with a `\e', +i.e.: +.DS +1,\e$s/^[ ]*// +.DE +but quoting the `EOF' terminator is a more reliable way of achieving the +same thing. +.NH 2 +Catching interrupts +.PP +If our shell script creates temporary files, we may wish to catch +interruptions of the shell script so that we can clean up +these files. +We can then do +.DS +onintr label +.DE +where +.I label +is a label in our program. +If an interrupt is received the shell will do a +`goto label' +and we can remove the temporary files and then do an +.I exit +command (which is built in to the shell) +to exit from the shell script. +If we wish to exit with a non-zero status we can do +.DS +exit(1) +.DE +e.g. to exit with status `1'. +.NH 2 +What else? +.PP +There are other features of the shell useful to writers of shell +procedures. +The +.I verbose +and +.I echo +options and the related +.I \-v +and +.I \-x +command line options can be used to help trace the actions of the shell. +The +.I \-n +option causes the shell only to read commands and not to execute +them and may sometimes be of use. +.PP +One other thing to note is that +.I csh +will not execute shell scripts which do not begin with the +character `#', that is shell scripts that do not begin with a comment. +Similarly, the `/bin/sh' on your system may well defer to `csh' +to interpret shell scripts which begin with `#'. +This allows shell scripts for both shells to live in harmony. +.PP +There is also another quotation mechanism using `"' which allows +only some of the expansion mechanisms we have so far discussed to occur +on the quoted string and serves to make this string into a single word +as `\'' does. +.bp diff --git a/share/doc/usd/04.csh/csh.4 b/share/doc/usd/04.csh/csh.4 new file mode 100644 index 000000000000..de3f31eb4bd5 --- /dev/null +++ b/share/doc/usd/04.csh/csh.4 @@ -0,0 +1,173 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr H1 3 +.NH +Other, less commonly used, shell features +.NH 2 +Loops at the terminal; variables as vectors +.PP +It is occasionally useful to use the +.I foreach +control structure at the terminal to aid in performing a number +of similar commands. +For instance, there were at one point three shells in use on the Cory \s-2UNIX\s0 +system at Cory Hall, +`/bin/sh', +`/bin/nsh', +and +`/bin/csh'. +To count the number of persons using each shell one could have issued +the commands +.DS +% grep \-c csh$ /etc/passwd +27 +% grep \-c nsh$ /etc/passwd +128 +% grep \-c \-v sh$ /etc/passwd +430 +% +.DE +Since these commands are very similar we can use +.I foreach +to do this more easily. +.DS +% foreach i (\'sh$\' \'csh$\' \'\-v sh$\') +? grep \-c $i /etc/passwd +? end +27 +128 +430 +% +.DE +Note here that the shell prompts for +input with `? ' when reading the body of the loop. +.PP +Very useful with loops are variables which contain lists of filenames +or other words. +You can, for example, do +.DS +% set a=(\`ls\`) +% echo $a +csh.n csh.rm +% ls +csh.n +csh.rm +% echo $#a +2 +% +.DE +The +.I set +command here gave the variable +.I a +a list of all the filenames in the current directory as value. +We can then iterate over these names to perform any chosen function. +.PP +The output of a command within `\`' characters is converted by +the shell to a list of words. +You can also place the `\`' quoted string within `"' characters +to take each (non-empty) line as a component of the variable; +preventing the lines from being split into words at blanks and tabs. +A modifier `:x' exists which can be used later to expand each component +of the variable into another variable splitting it into separate words +at embedded blanks and tabs. +.NH 2 +Braces { ... } in argument expansion +.PP +Another form of filename expansion, alluded +to before involves the characters `{' and `}'. +These characters specify that the contained strings, separated by `,' +are to be consecutively substituted into the containing characters +and the results expanded left to right. +Thus +.DS +A{str1,str2,...strn}B +.DE +expands to +.DS +Astr1B Astr2B ... AstrnB +.DE +This expansion occurs before the other filename expansions, and may +be applied recursively (i.e. nested). +The results of each expanded string are sorted separately, left +to right order being preserved. +The resulting filenames are not required to exist if no other expansion +mechanisms are used. +This means that this mechanism can be used to generate arguments which are +not filenames, but which have common parts. +.PP +A typical use of this would be +.DS +mkdir ~/{hdrs,retrofit,csh} +.DE +to make subdirectories `hdrs', `retrofit' and `csh' +in your home directory. +This mechanism is most useful when the common prefix is longer +than in this example, i.e. +.DS +chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} +.DE +.NH 2 +Command substitution +.PP +A command enclosed in `\`' characters is replaced, just before +filenames are expanded, by the output from that command. +Thus it is possible to do +.DS +set pwd=\`pwd\` +.DE +to save the current directory in the variable +.I pwd +or to do +.DS +ex \`grep \-l TRACE *.c\` +.DE +to run the editor +.I ex +supplying as arguments those files whose names end in `.c' +which have the string `TRACE' in them.* +.FS +*Command expansion also occurs in input redirected with `<<' +and within `"' quotations. +Refer to the shell manual section for full details. +.FE +.NH 2 +Other details not covered here +.PP +In particular circumstances it may be necessary to know the exact +nature and order of different substitutions performed by the shell. +The exact meaning of certain combinations of quotations is also +occasionally important. +These are detailed fully in its manual section. +.PP +The shell has a number of command line option flags mostly of use +in writing \s-2UNIX\s0 programs, +and debugging shell scripts. +See the csh(1) manual section for a list of these options. +.bp diff --git a/share/doc/usd/04.csh/csh.a b/share/doc/usd/04.csh/csh.a new file mode 100644 index 000000000000..e2a0d2e6243e --- /dev/null +++ b/share/doc/usd/04.csh/csh.a @@ -0,0 +1,90 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.SH +Appendix \- Special characters +.LP +The following table lists the special characters of +.I csh +and the \s-2UNIX\s0 system, giving for each the section(s) in which it +is discussed. +A number of these characters also have special meaning in expressions. +See the +.I csh +manual section +for a complete list. +.ta .75i 1.5i 2.25i +.LP +Syntactic metacharacters +.DS +; 2.4 separates commands to be executed sequentially +| 1.5 separates commands in a pipeline +( ) 2.2,3.6 brackets expressions and variable values +& 2.5 follows commands to be executed without waiting for completion +.DE +.LP +Filename metacharacters +.DS +/ 1.6 separates components of a file's pathname +\&. 1.6 separates root parts of a file name from extensions +? 1.6 expansion character matching any single character +* 1.6 expansion character matching any sequence of characters +[ ] 1.6 expansion sequence matching any single character from a set +~ 1.6 used at the beginning of a filename to indicate home directories +{ } 4.2 used to specify groups of arguments with common parts +.DE +.LP +Quotation metacharacters +.DS +\e 1.7 prevents meta-meaning of following single character +\' 1.7 prevents meta-meaning of a group of characters +" 4.3 like \', but allows variable and command expansion +.DE +.LP +Input/output metacharacters +.DS +< 1.5 indicates redirected input +> 1.3 indicates redirected output +.DE +.LP +Expansion/substitution metacharacters +.DS +$ 3.4 indicates variable substitution +! 2.3 indicates history substitution +: 3.6 precedes substitution modifiers +^ 2.3 used in special forms of history substitution +\` 4.3 indicates command substitution +.DE +.LP +Other metacharacters +.DS +# 1.3,3.6 begins scratch file names; indicates shell comments +\- 1.2 prefixes option (flag) arguments to commands +% 2.6 prefixes job name specifications +.DE +.bp diff --git a/share/doc/usd/04.csh/csh.g b/share/doc/usd/04.csh/csh.g new file mode 100644 index 000000000000..1d562530780d --- /dev/null +++ b/share/doc/usd/04.csh/csh.g @@ -0,0 +1,1716 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.SH +Glossary +.PP +This glossary lists the most important terms introduced in the +introduction to the +shell and gives references to sections of the shell +document for further information about them. +References of the form +`pr (1)' +indicate that the command +.I pr +is in the \s-2UNIX\s0 User Reference manual in section 1. +You can look at an online copy of its manual page by doing +.DS +man 1 pr +.DE +References of the form (2.5) +indicate that more information can be found in section 2.5 of this +manual. +.IP \&\fB.\fR 15n +Your current directory has the name `.' as well as the name printed +by the command +.I pwd; +see also +.I dirs. +The current directory `.' is usually the first +.I component +of the search path contained in the variable +.I path , +thus commands which are in `.' are found first (2.2). +The character `.' is also used in separating +.I components +of filenames +(1.6). +The character `.' at the beginning of a +.I component +of a +.I pathname +is treated specially and not matched by the +.I "filename expansion" +metacharacters `?', `*', and `[' `]' pairs (1.6). +.IP \&\fB..\fR +Each directory has a file `..' in it which is a reference to its +parent directory. +After changing into the directory with +.I chdir , +i.e. +.DS +chdir paper +.DE +you can return to the parent directory by doing +.DS +chdir .. +.DE +The current directory is printed by +.I pwd +(2.7). +.IP a.out +Compilers which create executable images create them, by default, in the +file +.I a.out. +for historical reasons (2.3). +.IP "absolute pathname" +.br +A +.I pathname +which begins with a `/' is +.I absolute +since it specifies the +.I path +of directories from the beginning +of the entire directory system \- called the +.I root +directory. +.I Pathname s +which are not +.I absolute +are called +.I relative +(see definition of +.I "relative pathname" ) +(1.6). +.IP alias +An +.I alias +specifies a shorter or different name for a \s-2UNIX\s0 +command, or a transformation on a command to be performed in +the shell. +The shell has a command +.I alias +which establishes +.I aliases +and can print their current values. +The command +.I unalias +is used to remove +.I aliases +(2.4). +.IP argument +Commands in \s-2UNIX\s0 receive a list of +.I argument +words. +Thus the command +.DS +echo a b c +.DE +consists of the +.I "command name" +`echo' and three +.I argument +words `a', `b' and `c'. +The set of +.I arguments +after the +.I "command name" +is said to be the +.I "argument list" +of the command (1.1). +.IP argv +The list of arguments to a command written in the shell language +(a shell script or shell procedure) is stored in a variable called +.I argv +within the shell. +This name is taken from the conventional name in the +C programming language (3.4). +.IP background +Commands started without waiting for them to complete are called +.I background +commands (2.6). +.IP base +A filename is sometimes thought of as consisting of a +.I base +part, before any `.' character, and an +.I extension +\- the part after +the `.'. See +.I filename +and +.I extension +(1.6) and basename (1). +.IP bg +The +.I bg +command causes a +.I suspended +job to continue execution in the +.I background +(2.6). +.IP bin +A directory containing binaries of programs and shell scripts to be +executed is typically called a +.I bin +directory. +The standard system +.I bin +directories are `/bin' containing the most +heavily used commands and `/usr/bin' which contains most other user +programs. +Programs developed at UC Berkeley live in `/usr/ucb', while locally +written programs live in `/usr/local'. Games are kept in the directory +`/usr/games'. +You can place binaries in any directory. +If you wish to execute them often, the name of the directories +should be a +.I component +of the variable +.I path . +.IP break +.I Break +is a builtin command used to exit from loops within the control +structure of the shell (3.7). +.IP breaksw +The +.I breaksw +builtin command is used to exit from a +.I switch +control structure, like a +.I break +exits from loops (3.7). +.IP builtin +A command executed directly by the shell is called a +.I builtin +command. +Most commands in \s-2UNIX\s0 are not built into the shell, +but rather exist as files in +.I bin +directories. +These commands are accessible because the directories in which +they reside are named in the +.I path +variable. +.IP case +A +.I case +command is used as a label in a +.I switch +statement in the shell's control structure, similar to that of the +language C. +Details are given in the shell documentation `csh (1)' (3.7). +.IP cat +The +.I cat +program catenates a list of specified files on the +.I "standard output" . +It is usually used to look at the contents of a single file on the terminal, +to `cat a file' (1.8, 2.3). +.IP cd +The +.I cd +command is used to change the +.I "working directory" . +With no arguments, +.I cd +changes your +.I "working directory" +to be your +.I home +directory (2.4, 2.7). +.IP chdir +The +.I chdir +command is a synonym for +.I cd . +.I Cd +is usually used because it is easier to type. +.IP chsh +The +.I chsh +command is used to change the shell which you use on \s-2UNIX\s0. +By default, you use a different version of the shell +which resides in `/bin/sh'. +You can change your shell to `/bin/csh' by doing +.DS +chsh your-login-name /bin/csh +.DE +Thus I would do +.DS +chsh bill /bin/csh +.DE +It is only necessary to do this once. +The next time you log in to \s-2UNIX\s0 after doing this command, +you will be using +.I csh +rather than the shell in `/bin/sh' (1.9). +.IP cmp +.I Cmp +is a program which compares files. +It is usually used on binary files, or to see if two files are identical (3.6). +For comparing text files the program +.I diff , +described in `diff (1)' is used. +.IP command +A function performed by the system, either by the shell +(a builtin +.I command ) +or by a program residing in a file in +a directory within the \s-2UNIX\s0 system, is called a +.I command +(1.1). +.IP "command name" +.br +When a command is issued, it consists of a +.I "command name" , +which is the first word of the command, +followed by arguments. +The convention on \s-2UNIX\s0 is that the first word of a +command names the function to be performed (1.1). +.IP "command substitution" +.br +The replacement of a command enclosed in `\`' characters +by the text output by that command +is called +.I "command substitution" +(4.3). +.IP component +A part of a +.I pathname +between `/' characters is called a +.I component +of that +.I pathname . +A variable +which has multiple strings as value is said to have +several +.I component s; +each string is a +.I component +of the variable. +.IP continue +A builtin command which causes execution of the enclosing +.I foreach +or +.I while +loop to cycle prematurely. +Similar to the +.I continue +command in the programming language C (3.6). +.IP control- +Certain special characters, called +.I control +characters, are produced by holding down the \s-2CONTROL\s0 key +on your terminal and simultaneously pressing another character, much like +the \s-2SHIFT\s0 key is used to produce upper case characters. Thus +.I control- c +is produced by holding down the \s-2CONTROL\s0 key while pressing the +`c' key. Usually \s-2UNIX\s0 prints a caret (^) followed by the +corresponding letter when you type a +.I control +character (e.g. `^C' for +.I control- c +(1.8). +.IP "core\ dump" +When a program terminates abnormally, the system places an image +of its current state in a file named `core'. +This +.I "core dump" +can be examined with the system debugger `adb (1)' +or `sdb (1)' in order to determine what went wrong with the program (1.8). +If the shell produces a message of the form +.DS +Illegal instruction (core dumped) +.DE +(where `Illegal instruction' is only one of several possible +messages), you should report this to the author of the program +or a system administrator, +saving the `core' file. +.IP cp +The +.I cp +(copy) program is used to copy the contents of one file into another +file. +It is one of the most commonly used \s-2UNIX\s0 commands (1.6). +.IP csh +The name of the shell +program that this document describes. +.IP \&.cshrc +The file +.I \&.cshrc +in your +.I home +directory is read by each shell as it begins execution. +It is usually used to change the setting of the variable +.I path +and to set +.I alias +parameters which are to take effect globally (2.1). +.IP cwd +The +.I cwd +variable in the shell holds the +.I "absolute pathname" +of the current +.I "working directory" \&. +It is changed by the shell whenever your current +.I "working directory" +changes and should not be changed otherwise (2.2). +.IP date +The +.I date +command prints the current date and time (1.3). +.IP debugging +.I Debugging +is the process of correcting mistakes in programs and shell scripts. +The shell has several options and variables which may be used +to aid in shell +.I debugging +(4.4). +.IP default: +The label +.I default: +is used within shell +.I switch +statements, as it is in the C language +to label the code to be executed if none of the +.I case +labels matches the value switched on (3.7). +.IP \s-2DELETE\s0 +The +\s-2DELETE\s0 +or +\s-2RUBOUT\s0 +key on the terminal normally causes an interrupt to be sent to the current job. +Many users change the interrupt character to be ^C. +.IP detached +A command that continues running in the +.I background +after you logout is said to be +.I detached . +.IP diagnostic +An error message produced by a program is often referred to as a +.I diagnostic . +Most error messages are not written to the +.I "standard output" , +since that is often directed away from the terminal (1.3, 1.5). +Error messsages are instead written to the +.I "diagnostic output" +which may be directed away from the terminal, but usually is not. +Thus +.I diagnostics +will usually appear on the terminal (2.5). +.IP directory +A structure which contains files. +At any time you are in one particular +.I directory +whose names can be printed by the command +.I pwd . +The +.I chdir +command will change you to another +.I directory , +and make the files +in that +.I directory +visible. The +.I directory +in which you are when you first login is your +.I home +directory (1.1, 2.7). +.IP "directory\ stack" +The shell saves the names of previous +.I "working directories" +in the +.I "directory stack" +when you change your current +.I "working directory" +via the +.I pushd +command. The +.I "directory stack" +can be printed by using the +.I dirs +command, which includes your current +.I "working directory" +as the first directory name on the left (2.7). +.IP dirs +The +.I dirs +command prints the shell's +.I "directory stack" +(2.7). +.IP du +The +.I du +command is a program (described in `du (1)') which +prints the number of disk blocks is all directories below +and including your current +.I "working directory" +(2.6). +.IP echo +The +.I echo +command prints its arguments (1.6, 3.6). +.IP else +The +.I else +command is part of the `if-then-else-endif' control +command construct (3.6). +.IP endif +If an +.I if +statement is ended with the word +.I then , +all lines following the +.I if +up to a line starting with the word +.I endif +or +.I else +are executed if the condition between parentheses after the +.I if +is true (3.6). +.IP \s-2EOF\s0 +An +.I "end\f1-\fPof\f1-\fPfile" +is generated by the terminal by a control-d, +and whenever a command reads to the end of a file which +it has been given as input. +Commands receiving input from a +.I pipe +receive an +.I "end\f1-\fPof\f1-\fPfile" +when the command sending them input completes. +Most commands terminate when they receive an +.I "end\f1-\fPof\f1-\fPfile" . +The shell has an option to ignore +.I "end\f1-\fPof\f1-\fPfile" +from a terminal +input which may help you keep from logging out accidentally +by typing too many control-d's (1.1, 1.8, 3.8). +.IP escape +A character `\e' used to prevent the special meaning of a metacharacter +is said to +.I escape +the character from its special meaning. +Thus +.DS +echo \e* +.DE +will echo the character `*' while just +.DS +echo * +.DE +will echo the names of the file in the current directory. +In this example, \e +.I escape s +`*' (1.7). +There is also a non-printing character called +.I escape , +usually labelled +\s-2ESC\s0 +or +\s-2ALTMODE\s0 +on terminal keyboards. +Some older \s-2UNIX\s0 systems use this character to indicate that +output is to be +.I suspended . +Most systems use control-s to stop the output and control-q to start it. +.IP /etc/passwd +This file contains information about the accounts currently on the +system. +It consists of a line for each account with fields separated by +`:' characters (1.8). +You can look at this file by saying +.DS +cat /etc/passwd +.DE +The commands +.I finger +and +.I grep +are often used to search for information in this file. +See `finger (1)', `passwd(5)', and `grep (1)' for more details. +.IP exit +The +.I exit +command is used to force termination of a shell script, +and is built into the shell (3.9). +.IP "exit\ status" +A command which discovers a problem may reflect this back to the command +(such as a shell) which invoked (executed) it. +It does this by returning a non-zero number as its +.I "exit status" , +a status of zero being considered +`normal termination'. +The +.I exit +command can be used to force a shell command script to give a non-zero +.I "exit status" +(3.6). +.IP expansion +The replacement of strings in the shell input which contain metacharacters +by other strings is referred to as the process of +.I expansion . +Thus the replacement of the word `*' by a sorted list of files +in the current directory is a `filename expansion'. +Similarly the replacement of the characters `!!' by the text of +the last command is a `history expansion'. +.I Expansions +are also referred to as +.I substitutions +(1.6, 3.4, 4.2). +.IP expressions +.I Expressions +are used in the shell +to control the conditional structures used in the writing of shell +scripts and in calculating values for these scripts. +The operators available in shell +.I expressions +are those of the language +C (3.5). +.IP extension +Filenames often consist of a +.I base +name and an +.I extension +separated by the character `.'. +By convention, groups of related files often share the same +.I root +name. +Thus if `prog.c' were a C program, then the object file for this +program would be stored in `prog.o'. +Similarly a paper written with the +`\-me' +nroff macro package might be stored in +`paper.me' +while a formatted version of this paper might be kept in +`paper.out' and a list of spelling errors in +`paper.errs' (1.6). +.IP fg +The +.I "job control" +command +.I fg +is used to run a +.I background +or +.I suspended +job in the +.I foreground +(1.8, 2.6). +.IP filename +Each file in \s-2UNIX\s0 has a name consisting of up to 14 characters +and not including the character `/' which is used in +.I pathname +building. Most +.I filenames +do not begin with the character `.', and contain +only letters and digits with perhaps a `.' separating the +.I base +portion of the +.I filename +from an +.I extension +(1.6). +.IP "filename expansion" +.br +.I "Filename expansion" +uses the metacharacters `*', `?' and `[' and `]' +to provide a convenient mechanism for naming files. +Using +.I "filename expansion" +it is easy to name all the files in +the current directory, or all files which have a common +.I root +name. Other +.I "filename expansion" +mechanisms use the metacharacter `~' and allow +files in other users' directories to be named easily (1.6, 4.2). +.IP flag +Many \s-2UNIX\s0 commands accept arguments which are not the names +of files or other users but are used to modify the action of the commands. +These are referred to as +.I flag +options, and by convention consist of one or more letters preceded by +the character `\-' (1.2). +Thus the +.I ls +(list files) command has an option +`\-s' to list the sizes of files. +This is specified +.DS +ls \-s +.DE +.IP foreach +The +.I foreach +command is used in shell scripts and at the terminal to specify +repetition of a sequence of commands while the value of a certain +shell variable ranges through a specified list (3.6, 4.1). +.IP foreground +When commands are executing in the normal way such that the +shell is waiting for them to finish before prompting for another +command they are said to be +.I "foreground jobs" +or +.I "running in the foreground" \&. +This is as opposed to +.I background . +.I Foreground +jobs can be stopped by signals +from the terminal caused by typing different +control characters at the keyboard (1.8, 2.6). +.IP goto +The shell has a command +.I goto +used in shell scripts to transfer control to a given label (3.7). +.IP grep +The +.I grep +command searches through a list of argument files for a specified string. +Thus +.DS +grep bill /etc/passwd +.DE +will print each line in the file +.I "/etc/passwd" +which contains the string `bill'. +Actually, +.I grep +scans for +.I "regular expressions" +in the sense of the editors +`ed (1)' and `ex (1)'. +.I Grep +stands for +`globally find +.I "regular expression" +and print' (2.4). +.IP head +The +.I head +command prints the first few lines of one or more files. +If you have a bunch of files containing text which you are wondering +about it is sometimes useful to run +.I head +with these files as arguments. +This will usually show enough of what is in these files to let you decide +which you are interested in (1.5). +.br +.I Head +is also used to describe the part of a +.I pathname +before and including the last `/' character. The +.I tail +of a +.I pathname +is the part after the last `/'. The `:h' and `:t' modifiers allow the +.I head +or +.I tail +of a +.I pathname +stored in a shell variable to be used (3.6). +.IP history +The +.I history +mechanism of the shell allows previous commands to be repeated, +possibly after modification to correct typing mistakes or to change +the meaning of the command. +The shell has a +.I "history list" +where these commands are kept, and a +.I history +variable which controls how large this list is (2.3). +.IP "home\ directory" +.br +Each user has a +.I "home directory" , +which is given in your entry +in the password file, +.I /etc/passwd . +This is the directory which you are placed in when you first login. +The +.I cd +or +.I chdir +command with no arguments takes you back to this directory, whose +name is recorded in the shell variable +.I home . +You can also access the +.I "home directories" +of other users in forming +filenames using a +.I "filename expansion" +notation and the character `~' (1.6). +.IP if +A conditional command within the shell, the +.I if +command is used in shell command scripts to make decisions +about what course of action to take next (3.6). +.IP ignoreeof +Normally, your shell will exit, printing +`logout' +if you type a control-d at a prompt of `% '. +This is the way you usually log off the system. +You can +.I set +the +.I ignoreeof +variable if you wish in your +.I \&.login +file and then use the command +.I logout +to logout. +This is useful if you sometimes accidentally type too many control-d +characters, logging yourself off +(2.2). +.IP input +Many commands on \s-2UNIX\s0 take information from the terminal or from +files which they then act on. +This information is called +.I input . +Commands normally read for +.I input +from their +.I "standard input" +which is, by default, the terminal. +This +.I "standard input" +can be redirected from a file using a shell metanotation +with the character `<'. +Many commands will also read from a file specified as argument. +Commands placed in +.I pipelines +will read from the output of the previous +command in the +.I pipeline . +The leftmost command in a +.I pipeline +reads from the terminal if +you neither redirect its +.I input +nor give it a filename to use as +.I "standard input" . +Special mechanisms exist for supplying input to commands in shell +scripts (1.5, 3.8). +.IP interrupt +An +.I interrupt +is a signal to a program that is generated by typing ^C. (On older versions +of UNIX the \s-2RUBOUT\s0 or \s-2DELETE\s0 key were used for this purpose.) +It causes most programs to stop execution. +Certain programs, such as the shell and the editors, +handle an +.I interrupt +in special ways, usually by stopping what they +are doing and prompting for another command. +While the shell is executing another command and waiting for it +to finish, the shell does not listen to +.I interrupts. +The shell often wakes up when you hit +.I interrupt +because many commands +die when they receive an +.I interrupt +(1.8, 3.9). +.IP job +One or more commands +typed on the same input line separated by `|' or `;' characters +are run together and are called a +.I job \&. +Simple commands run by themselves without any `|' or `;' characters +are the simplest +.I jobs. +.I Jobs +are classified as +.I foreground , +.I background , +or +.I suspended +(2.6). +.IP "job\ control" +The builtin functions that control the execution of +jobs are called +.I "job control" +commands. These are +.I "bg, fg, stop, kill" +(2.6). +.IP "job\ number" +When each job +is started it is assigned a small number called a +.I "job number" +which is printed next to the job in the output of the +.I jobs +command. This number, preceded by a `%' character, can be used as an argument +to +.I "job control" +commands to indicate +a specific job (2.6). +.IP jobs +The +.I jobs +command prints a table showing +jobs that are either running in the +.I background +or are +.I suspended +(2.6). +.IP kill +A command which sends a +signal +to a job causing it to terminate (2.6). +.IP \&.login +The file +.I \&.login +in your +.I home +directory is read by the shell each time you login to \s-2UNIX\s0 +and the commands there are executed. +There are a number of commands which are usefully placed here, +especially +.I set +commands to the shell itself (2.1). +.IP "login\ shell" +The shell that is started on your terminal when you login is called +your +.I "login shell" . +It is different from other shells which you may run (e.g. on +shell scripts) +in that it reads the +.I \&.login +file before reading commands from the terminal and it reads the +.I \&.logout +file after you logout +(2.1). +.IP logout +The +.I logout +command causes a login shell to exit. +Normally, a login shell will exit when you hit control-d +generating an +.I end\f1-\fPof\f1-\fPfile, +but if you have set +.I ignoreeof +in you +.I \&.login +file then this will not work and you must use +.I logout +to log off the \s-2UNIX\s0 system (2.8). +.IP \&.logout +When you log off of \s-2UNIX\s0 the shell will execute commands from +the file +.I \&.logout +in your +.I home +directory after it prints `logout'. +.IP lpr +The command +.I lpr +is the line printer daemon. +The standard input of +.I lpr +spooled and printed on the \s-2UNIX\s0 line printer. +You can also give +.I lpr +a list of filenames as arguments to be printed. +It is most common to use +.I lpr +as the last component of a +.I pipeline +(2.3). +.IP ls +The +.I ls +(list files) command is one of the most commonly used \s-2UNIX\s0 +commands. +With no argument filenames it prints the names of the files in the +current directory. +It has a number of useful +.I flag +arguments, and can also be given the names of directories +as arguments, in which case it lists the names of the files in these +directories (1.2). +.IP mail +The +.I mail +program is used to send and receive messages from other \s-2UNIX\s0 +users (1.1, 2.1), whether they are logged on or not. +.IP make +The +.I make +command is used to maintain one or more related files and to +organize functions to be performed on these files. +In many ways +.I make +is easier to use, and more helpful than +shell command scripts (3.2). +.IP makefile +The file containing commands for +.I make +is called +.I makefile +or +.I Makefile +(3.2). +.IP manual +The +.I manual +often referred to is the +`\s-2UNIX\s0 manual'. +It contains 8 numbered sections with a description of each \s-2UNIX\s0 +program (section 1), system call (section 2), subroutine (section 3), +device (section 4), special data structure (section 5), game (section 6), +miscellaneous item (section 7) and system administration program (section 8). +There are also supplementary documents (tutorials and reference guides) +for individual programs which require explanation in more detail. +An online version of the +.I manual +is accessible through the +.I man +command. +Its documentation can be obtained online via +.DS +man man +.DE +If you can't decide what manual page to look in, try the +.I apropos (1) +command. +The supplementary documents are in subdirectories of /usr/doc. +.IP metacharacter +.br +Many characters which are neither letters nor digits have special meaning +either to the shell or to \s-2UNIX\s0. +These characters are called +.I metacharacters . +If it is necessary to place these characters in arguments to commands +without them having their special meaning then they must be +.I quoted . +An example of a +.I metacharacter +is the character `>' which is used +to indicate placement of output into a file. +For the purposes of the +.I history +mechanism, +most unquoted +.I metacharacters +form separate words (1.4). +The appendix to this user's manual lists the +.I metacharacters +in groups by their function. +.IP mkdir +The +.I mkdir +command is used to create a new directory. +.IP modifier +Substitutions with the +.I history +mechanism, keyed by the character `!' +or of variables using the metacharacter `$', are often subjected +to modifications, indicated by placing the character `:' after the +substitution and following this with the +.I modifier +itself. +The +.I "command substitution" +mechanism can also be used to perform modification in a similar way, +but this notation is less clear (3.6). +.IP more +The program +.I more +writes a file on your terminal allowing you to control how much text +is displayed at a time. +.I More +can move through the file screenful by screenful, line by line, +search forward for a string, or start again at the beginning of the file. +It is generally the easiest way of viewing a file (1.8). +.IP noclobber +The shell has a variable +.I noclobber +which may be set in the file +.I \&.login +to prevent accidental destruction of files by the `>' output redirection +metasyntax of the shell (2.2, 2.5). +.IP noglob +The shell variable +.I noglob +is set to suppress the +.I "filename expansion" +of arguments containing the metacharacters `~', `*', `?', `[' and `]' (3.6). +.IP notify +The +.I notify +command tells the shell to report on the termination of a specific +.I "background job" +at the exact time it occurs as opposed to waiting +until just before the next prompt to report the termination. +The +.I notify +variable, if set, causes the shell to always report the termination +of +.I background +jobs exactly when they occur (2.6). +.IP onintr +The +.I onintr +command is built into the shell and is used to control the action +of a shell command script when an +.I interrupt +signal is received (3.9). +.IP output +Many commands in \s-2UNIX\s0 result in some lines of text which are +called their +.I output. +This +.I output +is usually placed on what is known as the +.I "standard output" +which is normally connected to the user's terminal. +The shell has a syntax using the metacharacter `>' for redirecting +the +.I "standard output" +of a command to a file (1.3). +Using the +.I pipe +mechanism and the metacharacter `|' it is also possible for +the +.I "standard output" +of one command to become the +.I "standard input" +of another command (1.5). +Certain commands such as the line printer daemon +.I p +do not place their results on the +.I "standard output" +but rather in more +useful places such as on the line printer (2.3). +Similarly the +.I write +command places its output on another user's terminal rather than its +.I "standard output" +(2.3). +Commands also have a +.I "diagnostic output" +where they write their error messages. +Normally these go to the terminal even if the +.I "standard output" +has been sent to a file or another command, but it is possible +to direct error diagnostics along with +.I "standard output" +using a special metanotation (2.5). +.IP path +The shell has a variable +.I path +which gives the names of the directories in which it searches for +the commands which it is given. +It always checks first to see if the command it is given is +built into the shell. +If it is, then it need not search for the command as it can do it internally. +If the command is not builtin, then the shell searches for a file +with the name given in each of the directories in the +.I path +variable, left to right. +Since the normal definition of the +.I path +variable is +.DS +path (. /usr/ucb /bin /usr/bin) +.DE +the shell normally looks in the current directory, and then in +the standard system directories `/usr/ucb', `/bin' and `/usr/bin' for the named +command (2.2). +If the command cannot be found the shell will print an error diagnostic. +Scripts of shell commands will be executed using another shell to interpret +them if they have `execute' permission set. +This is normally true because a command of the form +.DS +chmod 755 script +.DE +was executed to turn this execute permission on (3.3). +If you add new commands to a directory in the +.I path , +you should issue +the command +.I rehash +(2.2). +.IP pathname +A list of names, separated by `/' characters, forms a +.I pathname. +Each +.I component, +between successive `/' characters, names a directory +in which the next +.I component +file resides. +.I Pathnames +which begin with the character `/' are interpreted relative +to the +.I root +directory in the file system. +Other +.I pathnames +are interpreted relative to the current directory +as reported by +.I pwd. +The last component of a +.I pathname +may name a directory, but +usually names a file. +.IP pipeline +A group of commands which are connected together, the +.I "standard output" +of each connected to the +.I "standard input" +of the next, +is called a +.I pipeline. +The +.I pipe +mechanism used to connect these commands is indicated by +the shell metacharacter `|' (1.5, 2.3). +.IP popd +The +.I popd +command changes the shell's +.I "working directory" +to the directory you most recently left using the +.I pushd +command. It returns to the directory without having to type its name, +forgetting the name of the current +.I "working directory" +before doing so (2.7). +.IP port +The part of a computer system to which each terminal is +connected is called a +.I port . +Usually the system has a fixed number of +.I ports , +some of which are connected to telephone lines +for dial-up access, and some of which are permanently +wired directly to specific terminals. +.IP pr +The +.I pr +command is used to prepare listings of the contents of files +with headers giving the name of the file and the date and +time at which the file was last modified (2.3). +.IP printenv +The +.I printenv +command is used +to print the current setting of variables in the environment +(2.8). +.IP process +An instance of a running program is called a +.I process +(2.6). +\s-2UNIX\s0 assigns each +.I process +a unique number when it is +started \- called the +.I "process number" . +.I "Process numbers" +can be used to stop individual +.I processes +using the +.I kill +or +.I stop +commands when the +.I processes +are part of a detached +.I background +job. +.IP program +Usually synonymous with +.I command ; +a binary file or shell command script +which performs a useful function is often +called a +.I program . +.IP prompt +Many programs will print a +.I prompt +on the terminal when they expect input. +Thus the editor +`ex (1)' will print a `:' when it expects input. +The shell +.I prompts +for input with `% ' and occasionally with `? ' when +reading commands from the terminal (1.1). +The shell has a variable +.I prompt +which may be set to a different value to change the shell's main +.I prompt . +This is mostly used when debugging the shell (2.8). +.IP pushd +The +.I pushd +command, which means `push directory', changes the shell's +.I "working directory" +and also remembers the current +.I "working directory" +before the change is made, allowing you to return to the same +directory via the +.I popd +command later without retyping its name (2.7). +.IP ps +The +.I ps +command is used to show the processes you are currently running. +Each process is shown with its unique process number, +an indication of the terminal name it is attached to, +an indication of the state of the process (whether it is running, +stopped, awaiting some event (sleeping), and whether it is swapped out), +and the amount of \s-2CPU\s0 time it has used so far. +The command is identified by printing some of the words used +when it was invoked (2.6). +Shells, such as the +.I csh +you use to run the +.I ps +command, are not normally shown in the output. +.IP pwd +The +.I pwd +command prints the full +.I pathname +of the current +.I "working directory" \&. +The +.I dirs +builtin command is usually a better and faster choice. +.IP quit +The +.I quit +signal, generated by a control-\e, +is used to terminate programs which are behaving unreasonably. +It normally produces a core image file (1.8). +.IP quotation +The process by which metacharacters are prevented their special +meaning, usually by using the character `\' in pairs, or by +using the character `\e', is referred to as +.I quotation +(1.7). +.IP redirection +The routing of input or output from or to a file is known +as +.I redirection +of input or output (1.3). +.IP rehash +The +.I rehash +command tells the shell to rebuild its internal table of which commands +are found in which directories in your +.I path . +This is necessary when a new program is installed in one of these +directories (2.8). +.IP "relative pathname" +.br +A +.I pathname +which does not begin with a `/' is called a +.I "relative pathname" +since it is interpreted +.I relative +to the current +.I "working directory" . +The first +.I component +of such a +.I pathname +refers to some file or directory in the +.I "working directory" , +and subsequent +.I components +between `/' characters refer to directories below the +.I "working directory" . +.I Pathnames +that are not +.I relative +are called +.I "absolute pathnames" +(1.6). +.IP repeat +The +.I repeat +command iterates another command a specified number of times. +.IP root +The directory +that is at the top of the entire directory structure is called the +.I root +directory since it is the `root' of the entire tree structure of +directories. The name used in +.I pathnames +to indicate the +.I root +is `/'. +.I Pathnames +starting with `/' are said to be +.I absolute +since they start at the +.I root +directory. +.I Root +is also used as the part of a +.I pathname +that is left after removing +the +.I extension . +See +.I filename +for a further explanation (1.6). +.IP \s-2RUBOUT\s0 +The \s-2RUBOUT\s0 or \s-2DELETE\s0 +key is often used to erase the previously typed character; some users +prefer the \s-2BACKSPACE\s0 for this purpose. On older versions of \s-2UNIX\s0 +this key served as the \s-2INTR\s0 character. +.IP "scratch file" +Files whose names begin with a `#' are referred to as +.I "scratch files" , +since they are automatically removed by the system after a couple of +days of non-use, or more frequently if disk space becomes tight (1.3). +.IP script +Sequences of shell commands placed in a file are called shell command +.I scripts . +It is often possible to perform simple tasks using these +.I scripts +without writing a program in a language such as C, by +using the shell to selectively run other programs (3.3, 3.10). +.IP set +The builtin +.I set +command is used to assign new values to shell variables +and to show the values of the current variables. +Many shell variables have special meaning to the shell itself. +Thus by using the +.I set +command the behavior of the shell can be affected (2.1). +.IP setenv +Variables in the environment `environ (5)' +can be changed by using the +.I setenv +builtin command (2.8). +The +.I printenv +command can be used to print the value of the variables in the environment. +.IP shell +A +.I shell +is a command language interpreter. +It is possible to write and run your own +.I shell , +as +.I shells +are no different than any other programs as far as the +system is concerned. +This manual deals with the details of one particular +.I shell , +called +.I csh. +.IP "shell script" +See +.I script +(3.3, 3.10). +.IP signal +A +.I signal +in \s-2UNIX\s0 is a short message that is sent to a running program +which causes something to happen to that process. +.I Signals +are sent either by typing special +.I control +characters on the keyboard or by using the +.I kill +or +.I stop +commands (1.8, 2.6). +.IP sort +The +.I sort +program sorts a sequence of lines in ways that can be controlled +by argument +.I flags +(1.5). +.IP source +The +.I source +command causes the shell to read commands from a specified file. +It is most useful for reading files such as +.I \&.cshrc +after changing them (2.8). +.IP "special character" +.br +See +.I metacharacters +and the +appendix to this manual. +.IP standard +We refer often to the +.I "standard input" +and +.I "standard output" +of commands. +See +.I input +and +.I output +(1.3, 3.8). +.IP status +A command normally returns a +.I status +when it finishes. +By convention a +.I status +of zero indicates that the command succeeded. +Commands may return non-zero +.I status +to indicate that some abnormal event has occurred. +The shell variable +.I status +is set to the +.I status +returned by the last command. +It is most useful in shell command scripts (3.6). +.IP stop +The +.I stop +command causes a +.I background +job to become +.I suspended +(2.6). +.IP string +A sequential group of characters taken together is called a +.I string \&. +.I Strings +can contain any printable characters (2.2). +.IP stty +The +.I stty +program changes certain parameters inside \s-2UNIX\s0 which determine +how your terminal is handled. See `stty (1)' for a complete description (2.6). +.IP substitution +The shell implements a number of +.I substitutions +where sequences indicated by metacharacters are replaced by other sequences. +Notable examples of this are history +.I substitution +keyed by the +metacharacter `!' and variable +.I substitution +indicated by `$'. +We also refer to +.I substitutions +as +.I expansions +(3.4). +.IP suspended +A job becomes +.I suspended +after a \s-2STOP\s0 signal is sent to it, either by typing a +.I control -z +at the terminal (for +.I foreground +jobs) or by using the +.I stop +command (for +.I background +jobs). When +.I suspended , +a job temporarily stops running until it is restarted by either the +.I fg +or +.I bg +command (2.6). +.IP switch +The +.I switch +command of the shell allows the shell +to select one of a number of sequences of commands based on an +argument string. +It is similar to the +.I switch +statement in the language C (3.7). +.IP termination +When a command which is being executed finishes we say it undergoes +.I termination +or +.I terminates. +Commands normally terminate when they read an +.I end\f1-\fPof\f1-\fPfile +from their +.I "standard input" . +It is also possible to terminate commands by sending them +an +.I interrupt +or +.I quit +signal (1.8). +The +.I kill +program terminates specified jobs (2.6). +.IP then +The +.I then +command is part of the shell's +`if-then-else-endif' control construct used in command scripts (3.6). +.IP time +The +.I time +command can be used to measure the amount of \s-2CPU\s0 +and real time consumed by a specified command as well +as the amount of disk i/o, memory utilized, and number +of page faults and swaps taken by the command (2.1, 2.8). +.IP tset +The +.I tset +program is used to set standard erase and kill characters +and to tell the system what kind of terminal you are using. +It is often invoked in a +.I \&.login +file (2.1). +.IP tty +The word +.I tty +is a historical abbreviation for `teletype' which is frequently used +in \s-2UNIX\s0 to indicate the +.I port +to which a given terminal is connected. The +.I tty +command will print the name of the +.I tty +or +.I port +to which your terminal is presently connected. +.IP unalias +The +.I unalias +command removes aliases (2.8). +.IP \s-2UNIX\s0 +\s-2UNIX\s0 is an operating system on which +.I csh +runs. +\s-2UNIX\s0 provides facilities which allow +.I csh +to invoke other programs such as editors and text formatters which +you may wish to use. +.IP unset +The +.I unset +command removes the definitions of shell variables (2.2, 2.8). +.IP "variable expansion" +.br +See +.I variables +and +.I expansion +(2.2, 3.4). +.IP variables +.I Variables +in +.I csh +hold one or more strings as value. +The most common use of +.I variables +is in controlling the behavior +of the shell. +See +.I path , +.I noclobber , +and +.I ignoreeof +for examples. +.I Variables +such as +.I argv +are also used in writing shell programs (shell command scripts) +(2.2). +.IP verbose +The +.I verbose +shell variable can be set to cause commands to be echoed +after they are history expanded. +This is often useful in debugging shell scripts. +The +.I verbose +variable is set by the shell's +.I \-v +command line option (3.10). +.IP wc +The +.I wc +program calculates the number of characters, words, and lines in the +files whose names are given as arguments (2.6). +.IP while +The +.I while +builtin control construct is used in shell command scripts (3.7). +.IP word +A sequence of characters which forms an argument to a command is called +a +.I word . +Many characters which are neither letters, digits, `\-', `.' nor `/' +form +.I words +all by themselves even if they are not surrounded +by blanks. +Any sequence of characters may be made into a +.I word +by surrounding it +with `\'' characters +except for the characters `\'' and `!' which require special treatment +(1.1). +This process of placing special characters in +.I words +without their special meaning is called +.I quoting . +.IP "working directory" +.br +At any given time you are in one particular directory, called +your +.I "working directory" . +This directory's name is printed by the +.I pwd +command and the files listed by +.I ls +are the ones in this directory. +You can change +.I "working directories" +using +.I chdir . +.IP write +The +.I write +command is an obsolete way of communicating with other users who are logged in to +\s-2UNIX\s0 (you have to take turns typing). If you are both using display +terminals, use \fItalk\fP(1), which is much more pleasant. diff --git a/share/doc/usd/04.csh/tabs b/share/doc/usd/04.csh/tabs new file mode 100644 index 000000000000..ac89ef425d54 --- /dev/null +++ b/share/doc/usd/04.csh/tabs @@ -0,0 +1,29 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n diff --git a/share/doc/usd/05.dc/Makefile b/share/doc/usd/05.dc/Makefile new file mode 100644 index 000000000000..4a850d9f21aa --- /dev/null +++ b/share/doc/usd/05.dc/Makefile @@ -0,0 +1,5 @@ +VOLUME= usd/05.dc +SRCS= dc +MACROS= -ms + +.include <bsd.doc.mk> diff --git a/share/doc/usd/05.dc/dc b/share/doc/usd/05.dc/dc new file mode 100644 index 000000000000..0569b6ac7939 --- /dev/null +++ b/share/doc/usd/05.dc/dc @@ -0,0 +1,750 @@ +.\" $OpenBSD: dc,v 1.2 2003/09/22 19:08:27 otto 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. +.\" +.EH 'USD:5-%''DC \- An Interactive Desk Calculator' +.OH 'DC \- An Interactive Desk Calculator''USD:5-%' +.\".RP +.\" ....TM 75-1271-8 39199 39199-11 +.ND +.TL +DC \- An Interactive Desk Calculator +.AU "MH 2C-524" 3878 +Robert Morris +.AU +Lorinda Cherry +.AI +.\" .MH +.AB +DC is an interactive desk calculator program implemented +on the +.UX +time-sharing system to do arbitrary-precision +integer arithmetic. +It has provision for manipulating scaled fixed-point numbers and +for input and output in bases other than decimal. +.PP +The size of numbers that can be manipulated is limited +only by available core storage. +On typical implementations of +.UX , +the size of numbers that +can be handled varies from several hundred digits on the smallest +systems to several thousand on the largest. +.AE +.PP +.SH +.PP +.ft I +Editor's note: the description of the implementation details of DC in this +paper is only valid for the original version of DC. +The current version of DC uses a different approach. +.ft +.PP +DC is an arbitrary precision arithmetic package implemented +on the +.UX +time-sharing system +in the form of an interactive desk calculator. +It works like a stacking calculator using reverse Polish notation. +Ordinarily DC operates on decimal integers, but one may +specify an input base, output base, and a number of fractional +digits to be maintained. +.PP +A language called BC [1] has been developed which accepts +programs written in the familiar style of higher-level +programming languages and compiles output which is +interpreted by DC. +Some of the commands described below were designed +for the compiler interface and are not easy for a human user +to manipulate. +.PP +Numbers that are typed into DC are put on a push-down +stack. +DC commands work by taking the top number or two +off the stack, performing the desired operation, and pushing the result +on the stack. +If an argument is given, +input is taken from that file until its end, +then from the standard input. +.SH +SYNOPTIC DESCRIPTION +.PP +Here we describe the DC commands that are intended +for use by people. The additional commands that are +intended to be invoked by compiled output are +described in the detailed description. +.PP +Any number of commands are permitted on a line. +Blanks and new-line characters are ignored except within numbers +and in places where a register name is expected. +.PP +The following constructions are recognized: +.SH +number +.IP +The value of the number is pushed onto the main stack. +A number is an unbroken string of the digits 0-9 +and the capital letters A\-F which are treated as digits +with values 10\-15 respectively. +The number may be preceded by an underscore _ to input a +negative number. +Numbers may contain decimal points. +.SH ++ \- * % ^ +.IP +The +top two values on the stack are added +(\fB+\fP), +subtracted +(\fB\-\fP), +multiplied (\fB*\fP), +divided (\fB/\fP), +remaindered (\fB%\fP), +or exponentiated (^). +The two entries are popped off the stack; +the result is pushed on the stack in their place. +The result of a division is an integer truncated toward zero. +See the detailed description below for the treatment of +numbers with decimal points. +An exponent must not have any digits after the decimal point. +.SH +s\fIx\fP +.IP +The +top of the main stack is popped and stored into +a register named \fIx\fP, where \fIx\fP may be any character. +If +the +.ft B +s +.ft +is capitalized, +.ft I +x +.ft +is treated as a stack and the value is pushed onto it. +Any character, even blank or new-line, is a valid register name. +.SH +l\fIx\fP +.IP +The +value in register +.ft I +x +.ft +is pushed onto the stack. +The register +.ft I +x +.ft +is not altered. +If the +.ft B +l +.ft +is capitalized, +register +.ft I +x +.ft +is treated as a stack and its top value is popped onto the main stack. +.LP +All registers start with empty value which is treated as a zero +by the command \fBl\fP and is treated as an error by the command \fBL\fP. +.SH +d +.IP +The +top value on the stack is duplicated. +.SH +p +.IP +The top value on the stack is printed. +The top value remains unchanged. +.SH +f +.IP +All values on the stack and in registers are printed. +.SH +x +.IP +treats the top element of the stack as a character string, +removes it from the stack, and +executes it as a string of DC commands. +.SH +[ ... ] +.IP +puts the bracketed character string onto the top of the stack. +.SH +q +.IP +exits the program. +If executing a string, the recursion level is +popped by two. +If +.ft B +q +.ft +is capitalized, +the top value on the stack is popped and the string execution level is popped +by that value. +.SH +<\fIx\fP >\fIx\fP =\fIx\fP !<\fIx\fP !>\fIx\fP !=\fIx\fP +.IP +The +top two elements of the stack are popped and compared. +Register +.ft I +x +.ft +is executed if they obey the stated +relation. +Exclamation point is negation. +.SH +v +.IP +replaces the top element on the stack by its square root. +The square root of an integer is truncated to an integer. +For the treatment of numbers with decimal points, see +the detailed description below. +.SH +! +.IP +interprets the rest of the line as a +.UX +command. +Control returns to DC when the +.UX +command terminates. +.SH +c +.IP +All values on the stack are popped; the stack becomes empty. +.SH +i +.IP +The top value on the stack is popped and used as the +number radix for further input. +If \fBi\fP is capitalized, the value of +the input base is pushed onto the stack. +No mechanism has been provided for the input of arbitrary +numbers in bases less than 1 or greater than 16. +.SH +o +.IP +The top value on the stack is popped and used as the +number radix for further output. +If \fBo\fP is capitalized, the value of the output +base is pushed onto the stack. +.SH +k +.IP +The top of the stack is popped, and that value is used as +a scale factor +that influences the number of decimal places +that are maintained during multiplication, division, and exponentiation. +The scale factor must be greater than or equal to zero and +less than 100. +If \fBk\fP is capitalized, the value of the scale factor +is pushed onto the stack. +.SH +z +.IP +The value of the stack level is pushed onto the stack. +.SH +? +.IP +A line of input is taken from the input source (usually the console) +and executed. +.SH +DETAILED DESCRIPTION +.SH +Internal Representation of Numbers +.PP +Numbers are stored internally using a dynamic storage allocator. +Numbers are kept in the form of a string +of digits to the base 100 stored one digit per byte +(centennial digits). +The string is stored with the low-order digit at the +beginning of the string. +For example, the representation of 157 +is 57,1. +After any arithmetic operation on a number, care is taken +that all digits are in the range 0\-99 and that +the number has no leading zeros. +The number zero is represented by the empty string. +.PP +Negative numbers are represented in the 100's complement +notation, which is analogous to two's complement notation for binary +numbers. +The high order digit of a negative number is always \-1 +and all other digits are in the range 0\-99. +The digit preceding the high order \-1 digit is never a 99. +The representation of \-157 is 43,98,\-1. +We shall call this the canonical form of a number. +The advantage of this kind of representation of negative +numbers is ease of addition. When addition is performed digit +by digit, the result is formally correct. The result need only +be modified, if necessary, to put it into canonical form. +.PP +Because the largest valid digit is 99 and the byte can +hold numbers twice that large, addition can be carried out +and the handling of carries done later when +that is convenient, as it sometimes is. +.PP +An additional byte is stored with each number beyond +the high order digit to indicate the number of +assumed decimal digits after the decimal point. The representation +of .001 is 1,\fI3\fP +where the scale has been italicized to emphasize the fact that it +is not the high order digit. +The value of this extra byte is called the +.ft B +scale factor +.ft +of the number. +.SH +The Allocator +.PP +DC uses a dynamic string storage allocator +for all of its internal storage. +All reading and writing of numbers internally is done through +the allocator. +Associated with each string in the allocator is a four-word header containing pointers +to the beginning of the string, the end of the string, +the next place to write, and the next place to read. +Communication between the allocator and DC +is done via pointers to these headers. +.PP +The allocator initially has one large string on a list +of free strings. All headers except the one pointing +to this string are on a list of free headers. +Requests for strings are made by size. +The size of the string actually supplied is the next higher +power of 2. +When a request for a string is made, the allocator +first checks the free list to see if there is +a string of the desired size. +If none is found, the allocator finds the next larger free string and splits it repeatedly until +it has a string of the right size. +Left-over strings are put on the free list. +If there are no larger strings, +the allocator tries to coalesce smaller free strings into +larger ones. +Since all strings are the result +of splitting large strings, +each string has a neighbor that is next to it in core +and, if free, can be combined with it to make a string twice as long. +This is an implementation of the `buddy system' of allocation +described in [2]. +.PP +Failing to find a string of the proper length after coalescing, +the allocator asks the system for more space. +The amount of space on the system is the only limitation +on the size and number of strings in DC. +If at any time in the process of trying to allocate a string, the allocator runs out of +headers, it also asks the system for more space. +.PP +There are routines in the allocator for reading, writing, copying, rewinding, +forward-spacing, and backspacing strings. +All string manipulation is done using these routines. +.PP +The reading and writing routines +increment the read pointer or write pointer so that +the characters of a string are read or written in +succession by a series of read or write calls. +The write pointer is interpreted as the end of the +information-containing portion of a string and a call +to read beyond that point returns an end-of-string indication. +An attempt to write beyond the end of a string +causes the allocator to +allocate a larger space and then copy +the old string into the larger block. +.SH +Internal Arithmetic +.PP +All arithmetic operations are done on integers. +The operands (or operand) needed for the operation are popped +from the main stack and their scale factors stripped off. +Zeros are added or digits removed as necessary to get +a properly scaled result from the internal arithmetic routine. +For example, if the scale of the operands is different and decimal +alignment is required, as it is for +addition, zeros are appended to the operand with the smaller +scale. +After performing the required arithmetic operation, +the proper scale factor is appended to the end of the number before +it is pushed on the stack. +.PP +A register called \fBscale\fP plays a part +in the results of most arithmetic operations. +\fBscale\fP is the bound on the number of decimal places retained in +arithmetic computations. +\fBscale\fP may be set to the number on the top of the stack +truncated to an integer with the \fBk\fP command. +\fBK\fP may be used to push the value of \fBscale\fP on the stack. +\fBscale\fP must be greater than or equal to 0 and less than 100. +The descriptions of the individual arithmetic operations will +include the exact effect of \fBscale\fP on the computations. +.SH +Addition and Subtraction +.PP +The scales of the two numbers are compared and trailing +zeros are supplied to the number with the lower scale to give both +numbers the same scale. The number with the smaller scale is +multiplied by 10 if the difference of the scales is odd. +The scale of the result is then set to the larger of the scales +of the two operands. +.PP +Subtraction is performed by negating the number +to be subtracted and proceeding as in addition. +.PP +Finally, the addition is performed digit by digit from the +low order end of the number. The carries are propagated +in the usual way. +The resulting number is brought into canonical form, which may +require stripping of leading zeros, or for negative numbers +replacing the high-order configuration 99,\-1 by the digit \-1. +In any case, digits which are not in the range 0\-99 must +be brought into that range, propagating any carries or borrows +that result. +.SH +Multiplication +.PP +The scales are removed from the two operands and saved. +The operands are both made positive. +Then multiplication is performed in +a digit by digit manner that exactly mimics the hand method +of multiplying. +The first number is multiplied by each digit of the second +number, beginning with its low order digit. The intermediate +products are accumulated into a partial sum which becomes the +final product. +The product is put into the canonical form and its sign is +computed from the signs of the original operands. +.PP +The scale of the result is set equal to the sum +of the scales of the two operands. +If that scale is larger than the internal register +.ft B +scale +.ft +and also larger than both of the scales of the two operands, +then the scale of the result is set equal to the largest +of these three last quantities. +.SH +Division +.PP +The scales are removed from the two operands. +Zeros are appended or digits removed from the dividend to make +the scale of the result of the integer division equal to +the internal quantity +\fBscale\fP. +The signs are removed and saved. +.PP +Division is performed much as it would be done by hand. +The difference of the lengths of the two numbers +is computed. +If the divisor is longer than the dividend, +zero is returned. +Otherwise the top digit of the divisor is divided into the top +two digits of the dividend. +The result is used as the first (high-order) digit of the +quotient. +It may turn out be one unit too low, but if it is, the next +trial quotient will be larger than 99 and this will be +adjusted at the end of the process. +The trial digit is multiplied by the divisor and the result subtracted +from the dividend and the process is repeated to get +additional quotient digits until the remaining +dividend is smaller than the divisor. +At the end, the digits of the quotient are put into +the canonical form, with propagation of carry as needed. +The sign is set from the sign of the operands. +.SH +Remainder +.PP +The division routine is called and division is performed +exactly as described. The quantity returned is the remains of the +dividend at the end of the divide process. +Since division truncates toward zero, remainders have the same +sign as the dividend. +The scale of the remainder is set to +the maximum of the scale of the dividend and +the scale of the quotient plus the scale of the divisor. +.SH +Square Root +.PP +The scale is stripped from the operand. +Zeros are added if necessary to make the +integer result have a scale that is the larger of +the internal quantity +\fBscale\fP +and the scale of the operand. +.PP +The method used to compute sqrt(y) is Newton's method +with successive approximations by the rule +.EQ +x sub {n+1} ~=~ half ( x sub n + y over x sub n ) +.EN +The initial guess is found by taking the integer square root +of the top two digits. +.SH +Exponentiation +.PP +Only exponents with zero scale factor are handled. If the exponent is +zero, then the result is 1. If the exponent is negative, then +it is made positive and the base is divided into one. The scale +of the base is removed. +.PP +The integer exponent is viewed as a binary number. +The base is repeatedly squared and the result is +obtained as a product of those powers of the base that +correspond to the positions of the one-bits in the binary +representation of the exponent. +Enough digits of the result +are removed to make the scale of the result the same as if the +indicated multiplication had been performed. +.SH +Input Conversion and Base +.PP +Numbers are converted to the internal representation as they are read +in. +The scale stored with a number is simply the number of fractional digits input. +Negative numbers are indicated by preceding the number with a \fB\_\fP (an +underscore). +The hexadecimal digits A\-F correspond to the numbers 10\-15 regardless of input base. +The \fBi\fP command can be used to change the base of the input numbers. +This command pops the stack, truncates the resulting number to an integer, +and uses it as the input base for all further input. +The input base is initialized to 10 but may, for example be changed to +8 or 16 to do octal or hexadecimal to decimal conversions. +The command \fBI\fP will push the value of the input base on the stack. +.SH +Output Commands +.PP +The command \fBp\fP causes the top of the stack to be printed. +It does not remove the top of the stack. +All of the stack and internal registers can be output +by typing the command \fBf\fP. +The \fBo\fP command can be used to change the output base. +This command uses the top of the stack, truncated to an integer as +the base for all further output. +The output base in initialized to 10. +It will work correctly for any base. +The command \fBO\fP pushes the value of the output base on the stack. +.SH +Output Format and Base +.PP +The input and output bases only affect +the interpretation of numbers on input and output; they have no +effect on arithmetic computations. +Large numbers are output with 70 characters per line; +a \\ indicates a continued line. +All choices of input and output bases work correctly, although not all are +useful. +A particularly useful output base is 100000, which has the effect of +grouping digits in fives. +Bases of 8 and 16 can be used for decimal-octal or decimal-hexadecimal +conversions. +.SH +Internal Registers +.PP +Numbers or strings may be stored in internal registers or loaded on the stack +from registers with the commands \fBs\fP and \fBl\fP. +The command \fBs\fIx\fR pops the top of the stack and +stores the result in register \fBx\fP. +\fIx\fP can be any character. +\fBl\fIx\fR puts the contents of register \fBx\fP on the top of the stack. +The \fBl\fP command has no effect on the contents of register \fIx\fP. +The \fBs\fP command, however, is destructive. +.SH +Stack Commands +.PP +The command \fBc\fP clears the stack. +The command \fBd\fP pushes a duplicate of the number on the top of the stack +on the stack. +The command \fBz\fP pushes the stack size on the stack. +The command \fBX\fP replaces the number on the top of the stack +with its scale factor. +The command \fBZ\fP replaces the top of the stack +with its length. +.SH +Subroutine Definitions and Calls +.PP +Enclosing a string in \fB[ ]\fP pushes the ascii string on the stack. +The \fBq\fP command quits or in executing a string, pops the recursion levels by two. +.SH +Internal Registers \- Programming DC +.PP +The load and store +commands together with \fB[ ]\fP to store strings, \fBx\fP to execute +and the testing commands `<', `>', `=', `!<', `!>', `!=' can be used to program +DC. +The \fBx\fP command assumes the top of the stack is an string of DC commands +and executes it. +The testing commands compare the top two elements on the stack and if the relation holds, execute the register +that follows the relation. +For example, to print the numbers 0-9, +.DS +[lip1+ si li10>a]sa +0si lax +.DE +.SH +Push-Down Registers and Arrays +.PP +These commands were designed for used by a compiler, not by +people. +They involve push-down registers and arrays. +In addition to the stack that commands work on, DC can be thought +of as having individual stacks for each register. +These registers are operated on by the commands \fBS\fP and \fBL\fP. +\fBS\fIx\fR pushes the top value of the main stack onto the stack for +the register \fIx\fP. +\fBL\fIx\fR pops the stack for register \fIx\fP and puts the result on the main +stack. +The commands \fBs\fP and \fBl\fP also work on registers but not as push-down +stacks. +\fBl\fP doesn't effect the top of the +register stack, and \fBs\fP destroys what was there before. +.PP +The commands to work on arrays are \fB:\fP and \fB;\fP. +\fB:\fIx\fR pops the stack and uses this value as an index into +the array \fIx\fP. +The next element on the stack is stored at this index in \fIx\fP. +An index must be greater than or equal to 0 and +less than 2048. +\fB;\fIx\fR is the command to load the main stack from the array \fIx\fP. +The value on the top of the stack is the index +into the array \fIx\fP of the value to be loaded. +.SH +Miscellaneous Commands +.PP +The command \fB!\fP interprets the rest of the line as a +.UX +command and passes it to +.UX +to execute. +One other compiler command is \fBQ\fP. +This command uses the top of the stack as the number of levels of recursion to skip. +.SH +DESIGN CHOICES +.PP +The real reason for the use of a dynamic storage allocator was +that a general purpose program could be (and in fact has been) +used for a variety of other tasks. +The allocator has some value for input and for compiling (i.e. +the bracket [...] commands) where it cannot be known in advance +how long a string will be. +The result was that at a modest +cost in execution time, all considerations of string allocation +and sizes of strings were removed from the remainder of the program +and debugging was made easier. The allocation method +used wastes approximately 25% of available space. +.PP +The choice of 100 as a base for internal arithmetic +seemingly has no compelling advantage. Yet the base cannot +exceed 127 because of hardware limitations and at the cost +of 5% in space, debugging was made a great deal easier and +decimal output was made much faster. +.PP +The reason for a stack-type arithmetic design was +to permit all DC commands from addition to subroutine execution +to be implemented in essentially the same way. The result +was a considerable degree of logical separation of the final +program into modules with very little communication between +modules. +.PP +The rationale for the lack of interaction between the scale and the bases +was to provide an understandable means of proceeding after +a change of base or scale when numbers had already been entered. +An earlier implementation which had global notions of +scale and base did not work out well. +If the value of +.ft B +scale +.ft +were to be interpreted in the current +input or output base, +then a change of base or scale in the midst of a +computation would cause great confusion in the interpretation +of the results. +The current scheme has the advantage that the value of +the input and output bases +are only used for input and output, respectively, and they +are ignored in all other operations. +The value of +scale +is not used for any essential purpose by any part of the program +and it is used only to prevent the number of +decimal places resulting from the arithmetic operations from +growing beyond all bounds. +.PP +The design rationale for the choices for the scales of +the results of arithmetic were that in no case should +any significant digits be thrown away if, on appearances, the +user actually wanted them. Thus, if the user wants +to add the numbers 1.5 and 3.517, it seemed reasonable to give +him the result 5.017 without requiring him to unnecessarily +specify his rather obvious requirements for precision. +.PP +On the other hand, multiplication and exponentiation produce +results with many more digits than their operands and it +seemed reasonable to give as a minimum the number of decimal +places in the operands but not to give more than that +number of digits +unless the user asked for them by specifying a value for \fBscale\fP. +Square root can be handled in just the same way as multiplication. +The operation of division gives arbitrarily many decimal places +and there is simply no way to guess how many places the user +wants. +In this case only, the user must +specify a \fBscale\fP to get any decimal places at all. +.PP +The scale of remainder was chosen to make it possible +to recreate the dividend from the quotient and remainder. +This is easy to implement; no digits are thrown away. +.SH +References +.IP [1] +L. L. Cherry, R. Morris, +.ft I +BC \- An Arbitrary Precision Desk-Calculator Language. +.ft +.IP [2] +K. C. Knowlton, +.ft I +A Fast Storage Allocator, +.ft +Comm. ACM \fB8\fP, pp. 623-625 (Oct. 1965). diff --git a/share/doc/usd/06.bc/Makefile b/share/doc/usd/06.bc/Makefile new file mode 100644 index 000000000000..15e6aaca9539 --- /dev/null +++ b/share/doc/usd/06.bc/Makefile @@ -0,0 +1,5 @@ +VOLUME= usd/06.bc +SRCS= bc +MACROS= -ms + +.include <bsd.doc.mk> diff --git a/share/doc/usd/06.bc/bc b/share/doc/usd/06.bc/bc new file mode 100644 index 000000000000..c61756a4ecbf --- /dev/null +++ b/share/doc/usd/06.bc/bc @@ -0,0 +1,1239 @@ +.\" $OpenBSD: bc,v 1.9 2004/07/09 10:23:05 jmc 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. +.\" +.if n \{\ +.nr PO 5n +.nr LL 70n +.\} +.EH 'USD:6-%''BC \- An Arbitrary Precision Desk-Calculator Language' +.OH 'BC \- An Arbitrary Precision Desk-Calculator Language''USD:6-%' +.\".RP +.ND +.TL +BC \- An Arbitrary Precision Desk-Calculator Language +.AU +Lorinda Cherry +.AU +Robert Morris +.AI +.\" .MH +.AB +BC is a language and a compiler for doing arbitrary precision arithmetic +on the PDP-11 under the +.UX +time-sharing +system. The output of the compiler is interpreted and executed by +a collection of routines which can input, output, and do +arithmetic on indefinitely large integers and on scaled fixed-point +numbers. +.PP +These routines are themselves based on a dynamic storage allocator. +Overflow does not occur until all available core storage +is exhausted. +.PP +The language has a complete control structure as well as immediate-mode +operation. Functions can be defined and saved for later execution. +.PP +Two five hundred-digit numbers can be multiplied to give a +thousand digit result in about ten seconds. +.PP +A small collection of library functions is also available, +including sin, cos, arctan, log, exponential, and Bessel functions of +integer order. +.PP +Some of the uses of this compiler are +.IP \- +to do computation with large integers, +.IP \- +to do computation accurate to many decimal places, +.IP \- +conversion of numbers from one base to another base. +.AE +.PP +.SH +Introduction +.PP +BC is a language and a compiler for doing arbitrary precision +arithmetic on the +.UX +time-sharing system [1]. +The compiler was written to make conveniently available a +collection of routines (called DC [5]) which are capable of doing +arithmetic on integers of arbitrary size. The compiler +is by no means intended to provide a complete programming +language. +It is a minimal language facility. +.PP +There is a scaling provision that permits the +use of decimal point notation. +Provision is made for input and output in bases other than +decimal. Numbers can be converted from decimal to octal by +simply setting the output base to equal 8. +.PP +The actual limit on the number of digits that can +be handled depends on the amount of storage available on the machine. +Manipulation of numbers with many hundreds of digits +is possible even on the smallest versions of +.UX . +.PP +The syntax of BC has been deliberately selected to agree +substantially with the C language [2]. Those who +are familiar with C will find few surprises in this language. +.SH +Simple Computations with Integers +.PP +The simplest kind of statement is an arithmetic expression +on a line by itself. +For instance, if you type in the line: +.DS +.ft B +142857 + 285714 +.ft P +.DE +the program responds immediately with the line +.DS +.ft B +428571 +.ft P +.DE +The operators \-, *, /, %, and ^ can also be used; they +indicate subtraction, multiplication, division, remaindering, and +exponentiation, respectively. Division of integers produces an +integer result truncated toward zero. +Division by zero produces an error +comment. +.PP +Any term in an expression may be prefixed by a minus sign to +indicate that it is to be negated (the `unary' minus sign). +The expression +.DS +.ft B +7+\-3 +.ft P +.DE +is interpreted to mean that \-3 is to be added to 7. +.PP +More complex expressions with several operators and with +parentheses are interpreted just as in +Fortran, with ^ having the greatest binding +power, then * and % and /, and finally + and \-. +Contents of parentheses are evaluated before material +outside the parentheses. +Exponentiations are +performed from right to left and the other operators +from left to right. +The two expressions +.DS +.ft B +a^b^c and a^(b^c) +.ft P +.DE +are equivalent, as are the two expressions +.DS +.ft B +a*b*c and (a*b)*c +.ft P +.DE +BC shares with Fortran and C the undesirable convention that +.DS +\fBa/b*c\fP is equivalent to \fB(a/b)*c\fP +.ft P +.DE +.PP +Internal storage registers to hold numbers have single lower-case +letter names. The value of an expression can be assigned to +a register in the usual way. The statement +.DS +.ft B +x = x + 3 +.ft P +.DE +has the effect of increasing by three the value of the contents of the +register named x. +When, as in this case, the outermost operator is an =, the +assignment is performed but the result is not printed. +Only 26 of these named storage registers are available. +.PP +There is a built-in square root function whose +result is truncated to an integer (but see scaling below). +The lines +.DS +.ft B +x = sqrt(191) +x +.ft P +.DE +produce the printed result +.DS +.ft B +13 +.ft P +.DE +.SH +Bases +.PP +There are special internal quantities, called `ibase' and `obase'. +The contents of `ibase', initially set to 10, +determines the base used for interpreting numbers read in. +For example, the lines +.DS +.ft B +ibase = 8 +11 +.ft P +.DE +will produce the output line +.DS +.ft B +9 +.ft P +.DE +and you are all set up to do octal to decimal conversions. +Beware, however of trying to change the input base back +to decimal by typing +.DS +.ft B +ibase = 10 +.ft P +.DE +Because the number 10 is interpreted as octal, this statement will +have no effect. +For those who deal in hexadecimal notation, +the characters A\-F are permitted in numbers +(no matter what base is in effect) +and are +interpreted as digits having values 10\-15 respectively. +The statement +.DS +.ft B +ibase = A +.ft P +.DE +will change you back to decimal input base no matter what the +current input base is. +Negative and large positive input bases are +permitted but useless. +No mechanism has been provided for the input of arbitrary +numbers in bases less than 1 and greater than 16. +.PP +The contents of `obase', initially set to 10, are used as the base for output +numbers. The lines +.DS +.ft B +obase = 16 +1000 +.ft P +.DE +will produce the output line +.DS +.ft B +3E8 +.ft P +.DE +which is to be interpreted as a 3-digit hexadecimal number. +Very large output bases are permitted, and they are sometimes useful. +For example, large numbers can be output in groups of five digits +by setting `obase' to 100000. +Strange (i.e. 1, 0, or negative) output bases are +handled appropriately. +.PP +Very large numbers are split across lines with 70 characters per line. +Lines which are continued end with \\. +Decimal output conversion is practically instantaneous, but output +of very large numbers (i.e., more than 100 digits) with other bases +is rather slow. +Non-decimal output conversion of +a one hundred digit number takes about +three seconds. +.PP +It is best to remember that `ibase' and `obase' have no effect +whatever on the course of internal computation or +on the evaluation of expressions, but only affect input and +output conversion, respectively. +.SH +Scaling +.PP +A third special internal quantity called `scale' is +used to determine the scale of calculated +quantities. +Numbers may have +up to a specific number of decimal digits after the decimal point. +This fractional part is retained in further computations. +We refer to the number of digits after the decimal point of +a number as its scale. +The current implementation allows scales to be as large as can be +represented by a 32-bit unsigned number minus one. +This is a non-portable extension. +The original implementation allowed for a maximum scale of 99. +.PP +When two scaled numbers are combined by +means of one of the arithmetic operations, the result +has a scale determined by the following rules. For +addition and subtraction, the scale of the result is the larger +of the scales of the two operands. In this case, +there is never any truncation of the result. +For multiplications, the scale of the result is never +less than the maximum of the two scales of the operands, +never more than the sum of the scales of the operands +and, subject to those two restrictions, +the scale of the result is set equal to the contents of the internal +quantity `scale'. +The scale of a quotient is the contents of the internal +quantity `scale'. The scale of a remainder is +the sum of the scales of the quotient and the divisor. +The result of an exponentiation is scaled as if +the implied multiplications were performed. +An exponent must be an integer. +The scale of a square root is set to the maximum of the scale +of the argument and the contents of `scale'. +.PP +All of the internal operations are actually carried out in terms +of integers, with digits being discarded when necessary. +In every case where digits are discarded, truncation and +not rounding is performed. +.PP +The contents of +`scale' must be no greater than +4294967294 and no less than 0. It is initially set to 0. +.PP +The internal quantities `scale', `ibase', and `obase' can be +used in expressions just like other variables. +The line +.DS +.ft B +scale = scale + 1 +.ft P +.DE +increases the value of `scale' by one, and the line +.DS +.ft B +scale +.ft P +.DE +causes the current value of `scale' to be printed. +.PP +The value of `scale' retains its meaning as a +number of decimal digits to be retained in internal +computation even when `ibase' or `obase' are not equal to 10. +The internal computations (which are still conducted in decimal, +regardless of the bases) are performed to the specified number +of decimal digits, never hexadecimal or octal or any +other kind of digits. +.SH +Functions +.PP +The name of a function is a single lower-case letter. +Function names are permitted to collide with simple +variable names. +Twenty-six different defined functions are permitted +in addition to the twenty-six variable names. +The line +.DS +.ft B + define a(x){ +.ft P +.DE +begins the definition of a function with one argument. +This line must be followed by one or more statements, +which make up the body of the function, ending +with a right brace }. +Return of control from a function occurs when a return +statement is executed or when the end of the function is reached. +The return statement can take either +of the two forms +.DS +.ft B +return +return(x) +.ft P +.DE +In the first case, the value of the function is 0, and in +the second, the value of the expression in parentheses. +.PP +Variables used in the function can be declared as automatic +by a statement of the form +.DS +.ft B +auto x,y,z +.ft P +.DE +There can be only one `auto' statement in a function and it must +be the first statement in the definition. +These automatic variables are allocated space and initialized +to zero on entry to the function and thrown away on return. The +values of any variables with the same names outside the function +are not disturbed. +Functions may be called recursively and the automatic variables +at each level of call are protected. +The parameters named in a function definition are treated in +the same way as the automatic variables of that function +with the single exception that they are given a value +on entry to the function. +An example of a function definition is +.DS +.ft B + define a(x,y){ + auto z + z = x*y + return(z) + } +.ft P +.DE +The value of this function, when called, will be the +product of its +two arguments. +.PP +A function is called by the appearance of its name +followed by a string of arguments enclosed in +parentheses and separated by commas. +The result +is unpredictable if the wrong number of arguments is used. +.PP +Functions with no arguments are defined and called using +parentheses with nothing between them: b(). +.PP +If the function +.ft I +a +.ft +above has been defined, then the line +.DS +.ft B +a(7,3.14) +.ft P +.DE +would cause the result 21.98 to be printed and the line +.DS +.ft B +x = a(a(3,4),5) +.ft P +.DE +would cause the value of x to become 60. +.SH +Subscripted Variables +.PP +A single lower-case letter variable name +followed by an expression in brackets is called a subscripted +variable (an array element). +The variable name is called the array name and the expression +in brackets is called the subscript. +Only one-dimensional arrays are +permitted. The names of arrays are permitted to +collide with the names of simple variables and function names. +Any fractional +part of a subscript is discarded before use. +Subscripts must be greater than or equal to zero and +less than or equal to 2047. +.PP +Subscripted variables may be freely used in expressions, in +function calls, and in return statements. +.PP +An array name may be used as an argument to a function, +or may be declared as automatic in +a function definition by the use of empty brackets: +.DS +.ft B +f(a[\|]) +define f(a[\|]) +auto a[\|] +.ft P +.DE +When an array name is so used, the whole contents of the array +are copied for the use of the function, and thrown away on exit +from the function. +Array names which refer to whole arrays cannot be used +in any other contexts. +.SH +Control Statements +.PP +The `if', the `while', and the `for' statements +may be used to alter the flow within programs or to cause iteration. +The range of each of them is a statement or +a compound statement consisting of a collection of +statements enclosed in braces. +They are written in the following way +.DS +.ft B +if(relation) statement +if(relation) statement else statement +while(relation) statement +for(expression1; relation; expression2) statement +.ft P +.DE +or +.DS +.ft B +if(relation) {statements} +if(relation) {statements} else {statements} +while(relation) {statements} +for(expression1; relation; expression2) {statements} +.ft P +.DE +.PP +A relation in one of the control statements is an expression of the form +.DS +.ft B +x>y +.ft P +.DE +where two expressions are related by one of the six relational +operators `<', `>', `<=', `>=', `==', or `!='. +The relation `==' +stands for `equal to' and `!=' stands for `not equal to'. +The meaning of the remaining relational operators is +clear. +.PP +BEWARE of using `=' instead of `==' in a relational. Unfortunately, +both of them are legal, so you will not get a diagnostic +message, but `=' really will not do a comparison. +.PP +The `if' statement causes execution of its range +if and only if the relation is true. +Then control passes to the next statement in sequence. +If an `else' branch is present, the statements in this branch are +executed if the relation is false. +The `else' keyword is a non-portable extension. +.PP +The `while' statement causes execution of its range +repeatedly as long as the relation +is true. The relation is tested before each execution +of its range and if the relation +is false, control passes to the next statement beyond the range +of the while. +.PP +The `for' statement begins +by executing `expression1'. Then the relation is tested +and, if true, the statements in the range of the `for' are executed. +Then `expression2' is executed. The relation is tested, and so on. +The typical use of the `for' statement is for a controlled iteration, +as in the statement +.DS +.ft B +for(i=1; i<=10; i=i+1) i +.ft P +.DE +which will print the integers from 1 to 10. +Here are some examples of the use of the control statements. +.DS +.ft B +define f(n){ +auto i, x +x=1 +for(i=1; i<=n; i=i+1) x=x*i +return(x) +} +.ft P +.DE +The line +.DS +.ft B + f(a) +.ft P +.DE +will print +.ft I +a +.ft +factorial if +.ft I +a +.ft +is a positive integer. +Here is the definition of a function which will +compute values of the binomial coefficient +(m and n are assumed to be positive integers). +.DS +.ft B +define b(n,m){ +auto x, j +x=1 +for(j=1; j<=m; j=j+1) x=x*(n\-j+1)/j +return(x) +} +.ft P +.DE +The following function computes values of the exponential function +by summing the appropriate series +without regard for possible truncation errors: +.DS +.ft B +scale = 20 +define e(x){ + auto a, b, c, d, n + a = 1 + b = 1 + c = 1 + d = 0 + n = 1 + while(1==1){ + a = a*x + b = b*n + c = c + a/b + n = n + 1 + if(c==d) return(c) + d = c + } +} +.ft P +.DE +.SH +Some Details +.PP +There are some language features that every user should know +about even if he will not use them. +.PP +Normally statements are typed one to a line. It is also permissible +to type several statements on a line separated by semicolons. +.PP +If an assignment statement is parenthesized, it then has +a value and it can be used anywhere that an expression can. +For example, the line +.DS +.ft B +(x=y+17) +.ft P +.DE +not only makes the indicated assignment, but also prints the +resulting value. +.PP +Here is an example of a use of the value of an +assignment statement even when it is not parenthesized. +.DS +.ft B +x = a[i=i+1] +.ft P +.DE +causes a value to be assigned to x and also increments i +before it is used as a subscript. +.PP +The following constructs work in BC in exactly the same manner +as they do in the C language. Consult the appendix or the +C manuals [2] for their exact workings. +.DS +.ft B +.ta 2i +x=y=z is the same as x=(y=z) +x += y x = x+y +x \-= y x = x\-y +x *= y x = x*y +x /= y x = x/y +x %= y x = x%y +x ^= y x = x^y +x++ (x=x+1)\-1 +x\-\- (x=x\-1)+1 +++x x = x+1 +\-\-x x = x\-1 +.ft P +.DE +Even if you don't intend to use the constructs, +if you type one inadvertently, something correct but unexpected +may happen. +.SH +Three Important Things +.PP +1. To exit a BC program, type `quit'. +.PP +2. There is a comment convention identical to that of C and +of PL/I. Comments begin with `/*' and end with `*/'. +As a non-portable extension, comments may also start with a `#' and end with +a newline. +The newline is not part of the comment. +.PP +3. There is a library of math functions which may be obtained by +typing at command level +.DS +.ft B +bc \-l +.ft P +.DE +This command will load a set of library functions +which, at the time of writing, consists of sine (named `s'), +cosine (`c'), arctangent (`a'), natural logarithm (`l'), +exponential (`e') and Bessel functions of integer order (`j(n,x)'). Doubtless more functions will be added +in time. +The library sets the scale to 20. You can reset it to something +else if you like. +The design of these mathematical library routines +is discussed elsewhere [3]. +.PP +If you type +.DS +.ft B +bc file ... +.ft P +.DE +BC will read and execute the named file or files before accepting +commands from the keyboard. In this way, you may load your +favorite programs and function definitions. +.SH +Acknowledgement +.PP +The compiler is written in YACC [4]; its original +version was written by S. C. Johnson. +.SH +References +.IP [1] +K. Thompson and D. M. Ritchie, +.ft I +UNIX Programmer's Manual, +.ft +Bell Laboratories, +1978. +.IP [2] +B. W. Kernighan and +D. M. Ritchie, +.ft I +The C Programming Language, +.ft +Prentice-Hall, 1978. +.IP [3] +R. Morris, +.ft I +A Library of Reference Standard Mathematical Subroutines, +.ft +Bell Laboratories internal memorandum, 1975. +.IP [4] +S. C. Johnson, +.ft I +YACC \(em Yet Another Compiler-Compiler. +.ft +Bell Laboratories Computing Science Technical Report #32, 1978. +.IP [5] +R. Morris and L. L. Cherry, +.ft I +DC \- An Interactive Desk Calculator. +.ft +.LP +.bp +.ft B +.DS C +Appendix +.DE +.ft +.NH +Notation +.PP +In the following pages syntactic categories are in \fIitalics\fP; +literals are in \fBbold\fP; material in brackets [\|] is optional. +.NH +Tokens +.PP +Tokens consist of keywords, identifiers, constants, operators, +and separators. +Token separators may be blanks, tabs or comments. +Newline characters or semicolons separate statements. +.NH 2 +Comments +.PP +Comments are introduced by the characters /* and terminated by +*/. +As a non-portable extension, comments may also start with a # and +end with a newline. +The newline is not part of the comment. +.NH 2 +Identifiers +.PP +There are three kinds of identifiers \- ordinary identifiers, array identifiers +and function identifiers. +All three types consist of single lower-case letters. +Array identifiers are followed by square brackets, possibly +enclosing an expression describing a subscript. +Arrays are singly dimensioned and may contain up to 2048 +elements. +Indexing begins at zero so an array may be indexed from 0 to 2047. +Subscripts are truncated to integers. +Function identifiers are followed by parentheses, possibly enclosing arguments. +The three types of identifiers do not conflict; +a program can have a variable named \fBx\fP, +an array named \fBx\fP and a function named \fBx\fP, all of which are separate and +distinct. +.NH 2 +Keywords +.PP +The following are reserved keywords: +.ft B +.ta .5i 1.0i +.nf + ibase if + obase break + scale define + sqrt auto + length return + while quit + for continue + else last + print +.fi +.ft +.NH 2 +Constants +.PP +Constants consist of arbitrarily long numbers +with an optional decimal point. +The hexadecimal digits \fBA\fP\-\fBF\fP are also recognized as digits with +values 10\-15, respectively. +.NH 1 +Expressions +.PP +The value of an expression is printed unless the main +operator is an assignment. +The value printed is assigned to the special variable \fBlast\fP. +A single dot may be used as a synonym for \fBlast\fP. +This is a non-portable extension. +Precedence is the same as the order +of presentation here, with highest appearing first. +Left or right associativity, where applicable, is +discussed with each operator. +.bp +.NH 2 +Primitive expressions +.NH 3 +Named expressions +.PP +Named expressions are +places where values are stored. +Simply stated, +named expressions are legal on the left +side of an assignment. +The value of a named expression is the value stored in the place named. +.NH 4 +\fIidentifiers\fR +.PP +Simple identifiers are named expressions. +They have an initial value of zero. +.NH 4 +\fIarray-name\fP\|[\|\fIexpression\fP\|] +.PP +Array elements are named expressions. +They have an initial value of zero. +.NH 4 +\fBscale\fR, \fBibase\fR and \fBobase\fR +.PP +The internal registers +\fBscale\fP, \fBibase\fP and \fBobase\fP are all named expressions. +\fBscale\fP is the number of digits after the decimal point to be +retained in arithmetic operations. +\fBscale\fR has an initial value of zero. +\fBibase\fP and \fBobase\fP are the input and output number +radix respectively. +Both \fBibase\fR and \fBobase\fR have initial values of 10. +.NH 3 +Function calls +.NH 4 +\fIfunction-name\fB\|(\fR[\fIexpression\fR\|[\fB,\|\fIexpression\|\fR.\|.\|.\|]\|]\fB) +.PP +A function call consists of a function name followed by parentheses +containing a comma-separated list of +expressions, which are the function arguments. +A whole array passed as an argument is specified by the +array name followed by empty square brackets. +All function arguments are passed by +value. +As a result, changes made to the formal parameters have +no effect on the actual arguments. +If the function terminates by executing a return +statement, the value of the function is +the value of the expression in the parentheses of the return +statement or is zero if no expression is provided +or if there is no return statement. +.NH 4 +sqrt\|(\|\fIexpression\fP\|) +.PP +The result is the square root of the expression. +The result is truncated in the least significant decimal place. +The scale of the result is +the scale of the expression or the +value of +.ft B +scale, +.ft +whichever is larger. +.NH 4 +length\|(\|\fIexpression\fP\|) +.PP +The result is the total number of significant decimal digits in the expression. +The scale of the result is zero. +.NH 4 +scale\|(\|\fIexpression\fP\|) +.PP +The result is the scale of the expression. +The scale of the result is zero. +.NH 3 +Constants +.PP +Constants are primitive expressions. +.NH 3 +Parentheses +.PP +An expression surrounded by parentheses is +a primitive expression. +The parentheses are used to alter the +normal precedence. +.NH 2 +Unary operators +.PP +The unary operators +bind right to left. +.NH 3 +\-\|\fIexpression\fP +.PP +The result is the negative of the expression. +.NH 3 +++\|\fInamed-expression\fP +.PP +The named expression is +incremented by one. +The result is the value of the named expression after +incrementing. +.NH 3 +\-\-\|\fInamed-expression\fP +.PP +The named expression is +decremented by one. +The result is the value of the named expression after +decrementing. +.NH 3 +\fInamed-expression\fP\|++ +.PP +The named expression is +incremented by one. +The result is the value of the named expression before +incrementing. +.NH 3 +\fInamed-expression\fP\|\-\- +.PP +The named expression is +decremented by one. +The result is the value of the named expression before +decrementing. +.NH 2 +Exponentiation operator +.PP +The exponentiation operator binds right to left. +.NH 3 +\fIexpression\fP ^ \fIexpression\fP +.PP +The result is the first +expression raised to the power of the +second expression. +The second expression must be an integer. +If \fIa\fP +is the scale of the left expression +and \fIb\fP is the absolute value +of the right expression, +then the scale of the result is: +.PP +min\|(\|\fIa\(mub\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP\|)\|) +.NH 2 +Multiplicative operators +.PP +The operators *, /, % bind left to right. +.NH 3 +\fIexpression\fP * \fIexpression\fP +.PP +The result is the product +of the two expressions. +If \fIa\fP and \fIb\fP are the +scales of the two expressions, +then the scale of the result is: +.PP +min\|(\|\fIa+b\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP,\|\fIb\fP\|)\|) +.NH 3 +\fIexpression\fP / \fIexpression\fP +.PP +The result is the quotient of the two expressions. +The scale of the result is the value of \fBscale\fR. +.NH 3 +\fIexpression\fP % \fIexpression\fP +.PP +The % operator produces the remainder of the division +of the two expressions. +More precisely, +\fIa\fP%\fIb\fP is \fIa\fP\-\fIa\fP/\fIb\fP*\fIb\fP. +.PP +The scale of the result is the sum of the scale of +the divisor and the value of +.ft B +scale +.ft +.NH 2 +Additive operators +.PP +The additive operators bind left to right. +.NH 3 +\fIexpression\fP + \fIexpression\fP +.PP +The result is the sum of the two expressions. +The scale of the result is +the maximum of the scales of the expressions. +.NH 3 +\fIexpression\fP \- \fIexpression\fP +.PP +The result is the difference of the two expressions. +The scale of the result is the +maximum of the scales of the expressions. +.NH 2 +assignment operators +.PP +The assignment operators bind right to left. +.NH 3 +\fInamed-expression\fP = \fIexpression\fP +.PP +This expression results in assigning the value of the expression +on the right +to the named expression on the left. +.NH 3 +\fInamed-expression\fP += \fIexpression\fP +.NH 3 +\fInamed-expression\fP \-= \fIexpression\fP +.NH 3 +\fInamed-expression\fP *= \fIexpression\fP +.NH 3 +\fInamed-expression\fP /= \fIexpression\fP +.NH 3 +\fInamed-expression\fP %= \fIexpression\fP +.NH 3 +\fInamed-expression\fP ^= \fIexpression\fP +.PP +The result of the above expressions is equivalent +to ``named expression = named expression OP expression'', +where OP is the operator after the = sign. +.NH 1 +Relations +.PP +Unlike all other operators, the relational operators +are only valid as the object of an \fBif\fP, \fBwhile\fP, +or inside a \fBfor\fP statement. +.NH 2 +\fIexpression\fP < \fIexpression\fP +.NH 2 +\fIexpression\fP > \fIexpression\fP +.NH 2 +\fIexpression\fP <= \fIexpression\fP +.NH 2 +\fIexpression\fP >= \fIexpression\fP +.NH 2 +\fIexpression\fP == \fIexpression\fP +.NH 2 +\fIexpression\fP != \fIexpression\fP +.NH 1 +Storage classes +.PP +There are only two storage classes in BC, global and automatic +(local). +Only identifiers that are to be local to a function need be +declared with the \fBauto\fP command. +The arguments to a function +are local to the function. +All other identifiers are assumed to be global +and available to all functions. +All identifiers, global and local, have initial values +of zero. +Identifiers declared as \fBauto\fP are allocated on entry to the function +and released on returning from the function. +They therefore do not retain values between function calls. +\fBauto\fP arrays are specified by the array name followed by empty square brackets. +.PP +Automatic variables in BC do not work in exactly the same way +as in either C or PL/I. On entry to a function, the old values of +the names that appear as parameters and as automatic +variables are pushed onto a stack. +Until return is made from the function, reference to these +names refers only to the new values. +.NH 1 +Statements +.PP +Statements must be separated by semicolon or newline. +Except where altered by control statements, execution +is sequential. +.NH 2 +Expression statements +.PP +When a statement is an expression, unless +the main operator is an assignment, the value +of the expression is printed, followed by a newline character. +.NH 2 +Compound statements +.PP +Statements may be grouped together and used when one statement is expected +by surrounding them with { }. +.NH 2 +Quoted string statements +.PP +"any string" +.sp .5 +This statement prints the string inside the quotes. +.NH 2 +If statements +.sp .5 +\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fR +.PP +The substatement is executed if the relation is true. +.NH 2 +If-else statements +.sp .5 +\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fB\|else\|\fIstatement\fR +.PP +The first substatement is executed if the relation is true, the second +substatement if the relation is false. +The \fBif-else\fR statement is a non-portable extension. +.NH 2 +While statements +.sp .5 +\fBwhile\|(\|\fIrelation\fB\|)\|\fIstatement\fR +.PP +The statement is executed while the relation +is true. +The test occurs before each execution of the statement. +.NH 2 +For statements +.sp .5 +\fBfor\|(\|\fIexpression\fB; \fIrelation\fB; \fIexpression\fB\|)\|\fIstatement\fR +.PP +The \fBfor\fR statement is the same as +.nf +.ft I + first-expression + \fBwhile\|(\fPrelation\|\fB) {\fP + statement + last-expression + } +.ft R +.fi +.PP +All three expressions may be left out. +This is a non-portable extension. +.NH 2 +Break statements +.sp .5 +\fBbreak\fP +.PP +\fBbreak\fP causes termination of a \fBfor\fP or \fBwhile\fP statement. +.NH 2 +Continue statements +.sp .5 +\fBcontinue\fP +.PP +\fBcontinue\fP causes the next iteration of a \fBfor\fP or \fBwhile\fP +statement to start, skipping the remainder of the loop. +For a \fBwhile\fP statement, execution continues with the evaluation +of the condition. +For a \fBfor\fP statement, execution continues with evaluation of +the last-expression. +The \fBcontinue\fP statement is a non-portable extension. +.NH 2 +Auto statements +.sp .5 +\fBauto \fIidentifier\fR\|[\|\fB,\fIidentifier\fR\|] +.PP +The \fBauto\fR statement causes the values of the identifiers to be pushed down. +The identifiers can be ordinary identifiers or array identifiers. +Array identifiers are specified by following the array name by empty square +brackets. +The auto statement must be the first statement +in a function definition. +.NH 2 +Define statements +.sp .5 +.nf +\fBdefine(\|\fR[\fIparameter\|\fR[\fB\|,\|\fIparameter\|.\|.\|.\|\fR]\|]\|\fB)\|{\fI + statements\|\fB}\fR +.fi +.PP +The \fBdefine\fR statement defines a function. +The parameters may +be ordinary identifiers or array names. +Array names must be followed by empty square brackets. +As a non-portable extension, the opening brace may also appear on the +next line. +.NH 2 +Return statements +.sp .5 +\fBreturn\fP +.sp .5 +\fBreturn(\fI\|expression\|\fB)\fR +.PP +The \fBreturn\fR statement causes termination of a function, +popping of its auto variables, and +specifies the result of the function. +The first form is equivalent to \fBreturn(0)\fR. +The result of the function is the result of the expression +in parentheses. +Leaving out the expression between parentheses is equivalent to +\fBreturn(0)\fR. +As a non-portable extension, the parentheses may be left out. +.NH 2 +Print +.PP +The \fBprint\fR statement takes a list of comma-separated expressions. +Each expression in the list is evaluated and the computed +value is printed and assigned to the variable `last'. +No trailing newline is printed. +The expression may also be a string enclosed in double quotes. +Within these strings the following escape sequences may be used: +\ea +for bell (alert), +`\eb' +for backspace, +`\ef' +for formfeed, +`\en' +for newline, +`\er' +for carriage return, +`\et' +`for tab, +`\eq' +for double quote and +`\e\e' +for backslash. +Any other character following a backslash will be ignored. +Strings will not be assigned to `last'. +The \fBprint\fR statement is a non-portable extension. +.NH 2 +Quit +.PP +The \fBquit\fR statement stops execution of a BC program and returns +control to UNIX when it is first encountered. +Because it is not treated as an executable statement, +it cannot be used +in a function definition or in an +.ft B +if, for, +.ft +or +.ft B +while +.ft +statement. diff --git a/share/doc/usd/07.mail/Makefile b/share/doc/usd/07.mail/Makefile new file mode 100644 index 000000000000..a8592b1e77e6 --- /dev/null +++ b/share/doc/usd/07.mail/Makefile @@ -0,0 +1,7 @@ +VOLUME= usd/07.mail +SRCS= mail0.nr mail1.nr mail2.nr mail3.nr mail4.nr mail5.nr mail6.nr \ + mail7.nr mail8.nr mail9.nr maila.nr +MACROS= -me +USE_TBL= + +.include <bsd.doc.mk> diff --git a/share/doc/usd/07.mail/mail0.nr b/share/doc/usd/07.mail/mail0.nr new file mode 100644 index 000000000000..0740d0c00db5 --- /dev/null +++ b/share/doc/usd/07.mail/mail0.nr @@ -0,0 +1,64 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.eh 'USD:7-%''Mail Reference Manual' +.oh 'Mail Reference Manual''USD:7-%' +.if n \ +.nr fs .5v +.\".he 'Mail Reference Manual'\n(mo/\n(dy/\n(yr'%' +.tp +.sp 1.0i +.sz 12 +.rb +.(l C +MAIL REFERENCE MANUAL +.)l +.sz 10 +.sp 2 +.i +.(l C +Kurt Shoens +.)l +.r +.(l C +Revised by +.)l +.(l C +.i +Craig Leres\ \c +.r +and\ \c +.i +Mark Andrews +.)l +.r +.(l C +Version 5.5 + + +.)l +.pn 2 diff --git a/share/doc/usd/07.mail/mail1.nr b/share/doc/usd/07.mail/mail1.nr new file mode 100644 index 000000000000..452ba480134c --- /dev/null +++ b/share/doc/usd/07.mail/mail1.nr @@ -0,0 +1,86 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.sh 1 Introduction +.pp +.i Mail +provides a simple and friendly environment for sending and receiving mail. +It divides incoming mail into +its constituent messages and allows the user to deal with them +in any order. In addition, it provides a set of +.i ed -\c +like commands for manipulating messages and sending mail. +.i Mail +offers the user simple editing capabilities to ease the composition +of outgoing messages, as well as providing the ability to define and send +to names which address groups of users. Finally, +.i Mail +is able to send and receive messages across such networks as the +ARPANET, UUCP, and Berkeley network. +.pp +This document describes how to use the +.i Mail +program to send and receive messages. The reader is not assumed to +be familiar with other message handling systems, but should be +familiar with the \s-2UNIX\s0\** +.(f +\** \s-1UNIX\s0 is a trademark of Bell Laboratories. +.)f +shell, the text editor, and some of the common \s-2UNIX\s0 commands. +.q "The \s-2UNIX\s0 Programmer's Manual," +.q "An Introduction to Csh," +and +.q "Text Editing with Ex and Vi" +can be consulted for more information on these topics. +.pp +Here is how messages are handled: +the mail system accepts incoming +.i messages +for you from other people +and collects them in a file, called your +.i "system mailbox" . +When you login, the system notifies you if there are any messages +waiting in your system mailbox. If you are a +.i csh +user, you will be notified when new mail arrives if you inform +the shell of the location of your mailbox. On version 7 systems, +your system mailbox is located in the directory /var/mail +in a file with your login name. If your login name is +.q sam, +then you can make +.i csh +notify you of new mail by including the following line in your .cshrc +file: +.(l +set mail=/var/mail/sam +.)l +When you read your mail using +.i Mail , +it reads your system mailbox and separates that file into the +individual messages that have been sent to you. You can then +read, reply to, delete, or save these messages. +Each message is marked with its author and the date they sent it. diff --git a/share/doc/usd/07.mail/mail2.nr b/share/doc/usd/07.mail/mail2.nr new file mode 100644 index 000000000000..341fc237fbe4 --- /dev/null +++ b/share/doc/usd/07.mail/mail2.nr @@ -0,0 +1,611 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bp +.sh 1 "Common usage" +.pp +The +.i Mail +command has two distinct usages, according to whether one +wants to send or receive mail. Sending mail is simple: to send a +message to a user whose login name is, say, +\*(lqroot,\*(rq +use the shell +command: +.(l +% Mail root +.)l +then type your message. When you reach the end of the message, type +an EOT (control\-d) at the beginning of a line, which will cause +.i Mail +to echo \*(lqEOT\*(rq and return you to the Shell. When the user you sent mail +to next logs in, he will receive the message: +.(l +You have mail. +.)l +to alert him to the existence of your message. +.pp +If, while you are composing the message +you decide that you do not wish to send it after all, you can +abort the letter with a \s-2RUBOUT\s0. Typing a single \s-2RUBOUT\s0 +causes +.i Mail +to print +.(l +(Interrupt -- one more to kill letter) +.)l +Typing a second +\s-2RUBOUT\s0 causes +.i Mail +to save your partial letter on the file +.q dead.letter +in your home directory and abort the letter. +Once you have +sent mail to someone, there is no way to undo the act, so be +careful. +.pp +The message your recipient reads will consist of the message you +typed, preceded by a line telling who sent the message (your login name) +and the date and time it +was sent. +.pp +If you want to send the same message to several other people, you can list +their login names on the command line. +Thus, +.(l +% Mail sam bob john +Tuition fees are due next Friday. Don't forget!! +<Control\-d> +EOT +% +.)l +will send the reminder to sam, bob, and john. +.pp +If, when you log in, you see the message, +.(l +You have mail. +.)l +you can read the mail by typing simply: +.(l +% Mail +.)l +.i Mail +will respond by typing its version number and date and then listing +the messages you have waiting. Then it will type a prompt and await +your command. The messages are assigned numbers starting with 1 \*- you +refer to the messages with these numbers. +.i Mail +keeps track of which messages are +.i new +(have been sent since you last read your mail) and +.i read +(have been read by you). New messages have an +.b N +next to them in the header listing and old, but unread messages have +a +.b U +next to them. +.i Mail +keeps track of new/old and read/unread messages by putting a +header field called +.q Status +into your messages. +.pp +To look at a specific message, use the +.b type +command, which may be abbreviated to simply +.b t . +For example, if you had the following messages: +.(l +N 1 root Wed Sep 21 09:21 "Tuition fees" +N 2 sam Tue Sep 20 22:55 +.)l +you could examine the first message by giving the command: +.(l +type 1 +.)l +which might cause +.i Mail +to respond with, for example: +.(l +Message 1: +From root Wed Sep 21 09:21:45 1978 +Subject: Tuition fees +Status: R + +Tuition fees are due next Wednesday. Don't forget!! + +.)l +Many +.i Mail +commands that operate on messages take a message number as an +argument like the +.b type +command. For these commands, there is a notion of a current +message. When you enter the +.i Mail +program, the current message is initially the first one. Thus, +you can often omit the message number and use, for example, +.(l +t +.)l +to type the current message. As a further shorthand, you can type a message +by simply giving its message number. Hence, +.(l +1 +.)l +would type the first message. +.pp +Frequently, it is useful to read the messages in your mailbox in order, +one after another. You can read the next message in +.i Mail +by simply typing a newline. As a special case, you can type a newline +as your first command to +.i Mail +to type the first message. +.pp +If, after typing a message, you wish to immediately send a reply, +you can do so with the +.b reply +command. +.b Reply , +like +.b type , +takes a message number as an argument. +.i Mail +then begins a message addressed to the user who sent you the message. +You may then type in your letter in reply, followed by a <control-d> +at the beginning of a line, as before. +.i Mail +will type EOT, then type the ampersand prompt to indicate its readiness +to accept another command. In our example, if, after typing the +first message, you wished to reply to it, you might give the command: +.(l +reply +.)l +.i Mail +responds by typing: +.(l +To: root +Subject: Re: Tuition fees +.)l +and waiting for you to enter your letter. +You are now in the message collection mode described at the beginning +of this section and +.i Mail +will gather up your message up to a control\-d. +Note that it copies the subject +header from the original message. This is useful in that correspondence +about a particular matter will tend to retain the same subject heading, +making it easy to recognize. If there are other header fields in +the message, the information found will also be used. +For example, if the letter had a +.q "To:" +header listing several recipients, +.i Mail +would arrange to send your replay to the same people as well. +Similarly, if the original message contained a +.q "Cc:" +(carbon copies to) field, +.i Mail +would send your reply to +.i those +users, too. +.i Mail +is careful, though, not too send the message to +.i you , +even if you appear in the +.q "To:" +or +.q "Cc:" +field, unless you ask to be included explicitly. See section 4 for more +details. +.pp +After typing in your letter, the dialog with +.i Mail +might look like the following: +.(l +reply +To: root +Subject: Tuition fees + +Thanks for the reminder +EOT +& +.)l +.pp +The +.b reply +command is especially useful for sustaining extended conversations +over the message system, with other +.q listening +users receiving copies of the conversation. The +.b reply +command can be abbreviated to +.b r . +.pp +Sometimes you will receive a message that has been sent to +several people and wish to reply +.i only +to the person who sent it. +.b Reply +with a capital +.b R +replies to a message, but sends a copy to the sender only. +.pp +If you wish, while reading your mail, to send a message to someone, +but not as a reply to one of your messages, you can send the message +directly with the +.b mail +command, which takes as arguments the names of the recipients you wish +to send to. For example, to send a message to +.q frank, +you would do: +.(l +mail frank +This is to confirm our meeting next Friday at 4. +EOT +& +.)l +The +.b mail +command can be abbreviated to +.b m . +.pp +Normally, each message you receive is saved in the file +.i mbox +in your login directory at the time you leave +.i Mail . +Often, +however, you will not want to save a particular message you +have received because it is only of passing interest. To avoid +saving a message in +.i mbox +you can delete it using the +.b delete +command. In our example, +.(l +delete 1 +.)l +will prevent +.i Mail +from saving message 1 (from root) in +.i mbox . +In addition to not saving deleted messages, +.i Mail +will not let +you type them, either. The effect is to make the message disappear +altogether, along with its number. The +.b delete +command can be abbreviated to simply +.b d . +.pp +Many features of +.i Mail +can be tailored to your liking with the +.b set +command. The +.b set +command has two forms, depending on whether you are setting +a +.i binary +option or a +.i valued +option. +Binary options are either on or off. For example, the +.q ask +option informs +.i Mail +that each time you send a message, you want it to prompt you for +a subject header, to be included in the message. +To set the +.q ask +option, you would type +.(l +set ask +.)l +.pp +Another useful +.i Mail +option is +.q hold. +Unless told otherwise, +.i Mail +moves the messages from your system mailbox to the file +.i mbox +in your home directory when you leave +.i Mail . +If you want +.i Mail +to keep your letters in the system mailbox instead, you can set the +.q hold +option. +.pp +Valued options are values which +.i Mail +uses to adapt to your tastes. For example, the +.q SHELL +option tells +.i Mail +which shell you like to use, and is specified by +.(l +set SHELL=/bin/csh +.)l +for example. Note that no spaces are allowed in +.q "SHELL=/bin/csh." +A complete list of the +.i Mail +options appears in section 5. +.pp +Another important valued option is +.q crt. +If you use a fast video terminal, you will find that when you +print long messages, they fly by too quickly for you to read them. +With the +.q crt +option, you can make +.i Mail +print any message larger than a given number of lines by sending +it through a paging program. This program is specified by the +valued option \fBPAGER\fP. +If \fBPAGER\fP is not set, a default paginator is used. +For example, most CRT users with 24-line screens should do: +.(l +set crt=24 +.)l +to paginate messages that will not fit on their screens. +In the default state, \fImore\fP (default paginator) prints a screenful of +information, then types --More--. Type a space to see the next screenful. +.pp +Another adaptation to user needs that +.i Mail +provides is that of +.i aliases . +An alias is simply a name which stands for one or more +real user names. +.i Mail +sent to an alias is really sent to the list of real users +associated with it. For example, an alias can be defined for the +members of a project, so that you can send mail to the whole project +by sending mail to just a single name. The +.b alias +command in +.i Mail +defines an alias. Suppose that the users in a project are +named Sam, Sally, Steve, and Susan. To define an alias called +.q project +for them, you would use the +.i Mail +command: +.(l +alias project sam sally steve susan +.)l +The +.b alias +command can also be used to provide a convenient name for someone +whose user name is inconvenient. For example, if a user named +.q "Bob Anderson" +had the login name +.q anderson," +you might want to use: +.(l +alias bob anderson +.)l +so that you could send mail to the shorter name, +.q bob. +.pp +While the +.b alias +and +.b set +commands allow you to customize +.i Mail , +they have the drawback that they must be retyped each time you enter +.i Mail . +To make them more convenient to use, +.i Mail +always looks for two files when it is invoked. It first reads +a system wide file +.q /etc/mail.rc, +then a user specific file, +.q .mailrc, +which is found in the user's home directory. +The system wide file +is maintained by the system administrator and +contains +.b set +commands that are applicable to all users of the system. +The +.q .mailrc +file is usually used by each user to set options the way he likes +and define individual aliases. +For example, my .mailrc file looks like this: +.(l +set ask nosave SHELL=/bin/csh +.)l +As you can see, it is possible to set many options in the +same +.b set +command. The +.q nosave +option is described in section 5. +.pp +Mail aliasing is implemented +at the system-wide level +by the mail delivery +system +.i sendmail . +These aliases are stored in the file /usr/lib/aliases and are +accessible to all users of the system. +The lines in /usr/lib/aliases are of +the form: +.(l +alias: name\*<1\*>, name\*<2\*>, name\*<3\*> +.)l +where +.i alias +is the mailing list name and the +.i name\*<i\*> +are the members of the list. Long lists can be continued onto the next +line by starting the next line with a space or tab. Remember that you +must execute the shell command +.i newaliases +after editing /usr/lib/aliases since the delivery system +uses an indexed file created by +.i newaliases . +.pp +We have seen that +.i Mail +can be invoked with command line arguments which are people +to send the message to, or with no arguments to read mail. +Specifying the +.rb \-f +flag on the command line causes +.i Mail +to read messages from a file other than your system mailbox. +For example, if you have a collection of messages in +the file +.q letters +you can use +.i Mail +to read them with: +.(l +% Mail \-f letters +.)l +You can use all +the +.i Mail +commands described in this document to examine, modify, or delete +messages from your +.q letters +file, which will be rewritten when you leave +.i Mail +with the +.b quit +command described below. +.pp +Since mail that you read is saved in the file +.i mbox +in your home directory by default, you can read +.i mbox +in your home directory by using simply +.(l +% Mail \-f +.)l +.pp +Normally, messages that you examine using the +.b type +command are saved in the file +.q mbox +in your home directory if you leave +.i Mail +with the +.b quit +command described below. +If you wish to retain a message in your system mailbox +you can use the +.b preserve +command to tell +.i Mail +to leave it there. +The +.b preserve +command accepts a list of message numbers, just like +.b type +and may be abbreviated to +.b pre . +.pp +Messages in your system mailbox that you do not examine are +normally retained in your system mailbox automatically. +If you wish to have such a message saved in +.i mbox +without reading it, you may use the +.b mbox +command to have them so saved. For example, +.(l +mbox 2 +.)l +in our example would cause the second message (from sam) +to be saved in +.i mbox +when the +.b quit +command is executed. +.b Mbox +is also the way to direct messages to your +.i mbox +file if you have set the +.q hold +option described above. +.b Mbox +can be abbreviated to +.b mb . +.pp +When you have perused all the messages of interest, you can leave +.i Mail +with the +.b quit +command, which saves the messages you have typed but not +deleted in the file +.i mbox +in your login directory. Deleted messages are discarded irretrievably, +and messages left untouched are preserved in your system mailbox so +that you will see them the next time you type: +.(l +% Mail +.)l +The +.b quit +command can be abbreviated to simply +.b q . +.pp +If you wish for some reason to leave +.i Mail +quickly without altering either your system mailbox or +.i mbox , +you can type the +.b x +command (short for +.b exit ), +which will immediately return you to the Shell without changing anything. +.pp +If, instead, you want to execute a Shell command without leaving +.i Mail , +you +can type the command preceded by an exclamation point, just as in the +text editor. Thus, for instance: +.(l +!date +.)l +will print the current date without leaving +.i Mail . +.pp +Finally, the +.b help +command is available to print out a brief summary of the +.i Mail +commands, using only the single character command abbreviations. diff --git a/share/doc/usd/07.mail/mail3.nr b/share/doc/usd/07.mail/mail3.nr new file mode 100644 index 000000000000..1cd1e663290b --- /dev/null +++ b/share/doc/usd/07.mail/mail3.nr @@ -0,0 +1,127 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.sh 1 "Maintaining folders" +.pp +.i Mail +includes a simple facility for maintaining groups of messages together +in folders. This section describes this facility. +.pp +To use the folder facility, you must tell +.i Mail +where you wish to keep your folders. Each folder of messages will +be a single file. For convenience, all of your folders are kept in +a single directory of your choosing. To tell +.i Mail +where your folder directory is, put a line of the form +.(l +set folder=letters +.)l +in your +.i .mailrc +file. If, as in the example above, your folder directory does not +begin with a `/,' +.i Mail +will assume that your folder directory is to be found starting from +your home directory. Thus, if your home directory is +.b /home/person +the above example told +.i Mail +to find your folder directory in +.b /home/person/letters . +.pp +Anywhere a file name is expected, you can use a folder name, preceded +with `+.' For example, to put a message into a folder with the +.b save +command, you can use: +.(l +save +classwork +.)l +to save the current message in the +.i classwork +folder. If the +.i classwork +folder does not yet exist, it will be created. Note that messages +which are saved with the +.b save +command are automatically removed from your system mailbox. +.pp +In order to make a copy of a message in a folder without causing +that message to be removed from your system mailbox, use the +.b copy +command, which is identical in all other respects to the +.b save +command. For example, +.(l +copy +classwork +.)l +copies the current message into the +.i classwork +folder and leaves a copy in your system mailbox. +.pp +The +.b folder +command +can be used to direct +.i Mail +to the contents of a different folder. +For example, +.(l +folder +classwork +.)l +directs +.i Mail +to read the contents of the +.i classwork +folder. All of the commands that you can use on your system +mailbox are also applicable to folders, including +.b type , +.b delete , +and +.b reply . +To inquire which folder you are currently editing, use simply: +.(l +folder +.)l +.pp +To list your current set of folders, use the +.b folders +command. +.pp +To start +.i Mail +reading one of your folders, you can use the +.b \-f +option described in section 2. For example: +.(l +% Mail \-f +classwork +.)l +will cause +.i Mail +to read your +.i classwork +folder without looking at your system mailbox. diff --git a/share/doc/usd/07.mail/mail4.nr b/share/doc/usd/07.mail/mail4.nr new file mode 100644 index 000000000000..063cb002d9fa --- /dev/null +++ b/share/doc/usd/07.mail/mail4.nr @@ -0,0 +1,431 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bp +.sh 1 "More about sending mail" +.sh 2 "Tilde escapes" +.pp +While typing in a message to be sent to others, it is often +useful to be able to invoke the text editor on the partial message, +print the message, execute a shell command, or do some other +auxiliary function. +.i Mail +provides these capabilities through +.i "tilde escapes" , +which consist of a tilde (~) at the beginning of a line, followed by +a single character which indicates the function to be performed. For +example, to print the text of the message so far, use: +.(l +~p +.)l +which will print a line of dashes, the recipients of your message, and +the text of the message so far. +Since +.i Mail +requires two consecutive \s-2RUBOUT\s0's to abort a letter, you +can use a single \s-2RUBOUT\s0 to abort the output of ~p or any other +~ escape without killing your letter. +.pp +If you are dissatisfied with the message as +it stands, you can invoke the text editor on it using the escape +.(l +~e +.)l +which causes the message to be copied into a temporary file and an +instance of the editor to be spawned. After modifying the message to +your satisfaction, write it out and quit the editor. +.i Mail +will respond +by typing +.(l +(continue) +.)l +after which you may continue typing text which will be appended to your +message, or type <control-d> to end the message. +A standard text editor is provided by +.i Mail . +You can override this default by setting the valued option +.q EDITOR +to something else. For example, you might prefer: +.(l +set EDITOR=/usr/bin/ex +.)l +.pp +Many systems offer a screen editor as an alternative to the standard +text editor, such as the +.i vi +editor from UC Berkeley. +To use the screen, or +.i visual +editor, on your current message, you can use the escape, +.(l +~v +.)l +~v works like ~e, except that the screen editor is invoked instead. +A default screen editor is defined by +.i Mail . +If it does not suit you, you can set the valued option +.q VISUAL +to the path name of a different editor. +.pp +It is often useful to be able to include the contents of some +file in your message; the escape +.(l +~r filename +.)l +is provided for this purpose, and causes the named file to be appended +to your current message. +.i Mail +complains if the file doesn't exist +or can't be read. If the read is successful, the number of lines and +characters appended to your message is printed, after which you may continue +appending text. The filename may contain shell metacharacters like * and ? +which are expanded according to the conventions of your shell. +.pp +As a special case of ~r, the escape +.(l +~d +.)l +reads in the file +.q dead.letter +in your home directory. This is often useful since +.i Mail +copies the text +of your message there when you abort a message with \s-2RUBOUT\s0. +.pp +To save the current text of your message on a file you may use the +.(l +~w filename +.)l +escape. +.i Mail +will print out the number of lines and characters written +to the file, after which you may continue appending text to your message. +Shell metacharacters may be used in the filename, as in ~r and are expanded +with the conventions of your shell. +.pp +If you are sending mail from within +.i Mail's +command mode +you can read a message sent to you into the message +you are constructing with the escape: +.(l +~m 4 +.)l +which will read message 4 into the current message, shifted right by +one tab stop. You can name any non-deleted message, or list of messages. +Messages can also be forwarded without shifting by a tab stop with ~f. +This is the usual way to forward a message. +.pp +If, in the process of composing a message, you decide to add additional +people to the list of message recipients, you can do so with the escape +.(l +~t name1 name2 ... +.)l +You may name as few or many additional recipients as you wish. Note +that the users originally on the recipient list will still receive +the message; you cannot remove someone from the recipient +list with ~t. +.pp +If you wish, you can associate a subject with your message by using the +escape +.(l +~s Arbitrary string of text +.)l +which replaces any previous subject with +.q "Arbitrary string of text." +The subject, if given, is sent near the +top of the message prefixed with +.q "Subject:" +You can see what the message will look like by using ~p. +.pp +For political reasons, one occasionally prefers to list certain +people as recipients of carbon copies of a message rather than +direct recipients. The escape +.(l +~c name1 name2 ... +.)l +adds the named people to the +.q "Cc:" +list, similar to ~t. +Again, you can execute ~p to see what the message will look like. +.pp +The escape +.(l +~b name1 name2 ... +.)l +adds the named people to the +.q "Cc:" +list, but does not make the names visible in the +.q "Cc:" +line ("blind" carbon copy). +.pp +The recipients of the message together constitute the +.q "To:" +field, the subject the +.q "Subject:" +field, and the carbon copies the +.q "Cc:" +field. If you wish to edit these in ways impossible with the ~t, ~s, ~c +and ~b escapes, you can use the escape +.(l +~h +.)l +which prints +.q "To:" +followed by the current list of recipients and leaves the cursor +(or printhead) at the end of the line. If you type in ordinary +characters, they are appended to the end of the current list of +recipients. You can also use your erase character to erase back into +the list of recipients, or your kill character to erase them altogether. +Thus, for example, if your erase and kill characters are the standard +(on printing terminals) # and @ symbols, +.(l +~h +To: root kurt####bill +.)l +would change the initial recipients +.q "root kurt" +to +.q "root bill." +When you type a newline, +.i Mail +advances to the +.q "Subject:" +field, where the same rules apply. Another newline brings you to +the +.q "Cc:" +field, which may be edited in the same fashion. Another newline +brings you to the +.q "Bcc:" +("blind" carbon copy) field, which follows the same rules as the "Cc:" +field. Another newline +leaves you appending text to the end of your message. You can use +~p to print the current text of the header fields and the body +of the message. +.pp +To effect a temporary escape to the shell, the escape +.(l +~!command +.)l +is used, which executes +.i command +and returns you to mailing mode without altering the text of +your message. If you wish, instead, to filter the body of your +message through a shell command, then you can use +.(l +~|command +.)l +which pipes your message through the command and uses the output +as the new text of your message. If the command produces no output, +.i Mail +assumes that something is amiss and retains the old version +of your message. A frequently-used filter is the command +.i fmt , +designed to format outgoing mail. +.pp +To effect a temporary escape to +.i Mail +command mode instead, you can use the +.(l +~:\fIMail command\fP +.)l +escape. This is especially useful for retyping the message you are +replying to, using, for example: +.(l +~:t +.)l +It is also useful for setting options and modifying aliases. +.pp +If you wish abort the current message, you can use the escape +.(l +~q +.)l +This will terminate the current message and return you to the +shell (or \fIMail\fP if you were using the \fBmail\fP command). +If the \fBsave\fP option is set, the message will be copied +to the file +.q dead.letter +in your home directory. +.pp +If you wish (for some reason) to send a message that contains +a line beginning with a tilde, you must double it. Thus, for example, +.(l +~~This line begins with a tilde. +.)l +sends the line +.(l +~This line begins with a tilde. +.)l +.pp +Finally, the escape +.(l +~? +.)l +prints out a brief summary of the available tilde escapes. +.pp +On some terminals (particularly ones with no lower case) +tilde's are difficult to type. +.i Mail +allows you to change the escape character with the +.q escape +option. For example, I set +.(l +set escape=] +.)l +and use a right bracket instead of a tilde. If I ever need to +send a line beginning with right bracket, I double it, just as for ~. +Changing the escape character removes the special meaning of ~. +.sh 2 "Network access" +.pp +This section describes how to send mail to people on other machines. +Recall that sending to a plain login name sends mail to that person +on your machine. If your machine is directly (or sometimes, even, +indirectly) connected to the Arpanet, you can send messages to people +on the Arpanet using a name of the form +.(l +name@host.domain +.)l +where +.i name +is the login name of the person you're trying to reach, +.i host +is the name of the machine on the Arpanet, +and +.i domain +is the higher-level scope within which the hostname is known, e.g. EDU (for educational +institutions), COM (for commercial entities), GOV (for governmental agencies), +ARPA for many other things, BITNET or CSNET for those networks. +.pp +If your recipient logs in on a machine connected to yours by +UUCP (the Bell Laboratories supplied network that communicates +over telephone lines), sending mail can be a bit more complicated. +You must know the list of machines through which your message must +travel to arrive at his site. So, if his machine is directly connected +to yours, you can send mail to him using the syntax: +.(l +host!name +.)l +where, again, +.i host +is the name of the machine and +.i name +is the login name. +If your message must go through an intermediary machine first, you +must use the syntax: +.(l +intermediary!host!name +.)l +and so on. It is actually a feature of UUCP that the map of all +the systems in the network is not known anywhere (except where people +decide to write it down for convenience). Talk to your system administrator +about good ways to get places; the +.i uuname +command will tell you systems whose names are recognized, but not which +ones are frequently called or well-connected. +.pp +When you use the +.b reply +command to respond to a letter, there is a problem of figuring out the +names of the users in the +.q "To:" +and +.q "Cc:" +lists +.i "relative to the current machine" . +If the original letter was sent to you by someone on the local machine, +then this problem does not exist, but if the message came from a remote +machine, the problem must be dealt with. +.i Mail +uses a heuristic to build the correct name for each user relative +to the local machine. So, when you +.b reply +to remote mail, the names in the +.q "To:" +and +.q "Cc:" +lists may change somewhat. +.sh 2 "Special recipients" +.pp +As described previously, you can send mail to either user names or +.b alias +names. It is also possible to send messages directly to files or to +programs, using special conventions. If a recipient name has a +`/' in it or begins with a `+', it is assumed to be the +path name of a file into which +to send the message. If the file already exists, the message is +appended to the end of the file. If you want to name a file in +your current directory (ie, one for which a `/' would not usually +be needed) you can precede the name with `./' +So, to send mail to the file +.q memo +in the current directory, you can give the command: +.(l +% Mail ./memo +.)l +If the name begins with a `+,' it is expanded into the full path name +of the folder name in your folder directory. +This ability to send mail to files can be used for a variety of +purposes, such as maintaining a journal and keeping a record of +mail sent to a certain group of users. The second example can be +done automatically by including the full pathname of the record +file in the +.b alias +command for the group. Using our previous +.b alias +example, you might give the command: +.(l +alias project sam sally steve susan /usr/project/mail_record +.)l +Then, all mail sent to "project" would be saved on the file +.q /usr/project/mail_record +as well as being sent to the members of the project. This file +can be examined using +.i "Mail \-f" . +.pp +It is sometimes useful to send mail directly to a program, for +example one might write a project billboard program and want to access +it using +.i Mail . +To send messages to the billboard program, one can send mail +to the special name `|billboard' for example. +.i Mail +treats recipient names that begin with a `|' as a program to send +the mail to. An +.b alias +can be set up to reference a `|' prefaced name if desired. +.i Caveats : +the shell treats `|' specially, so it must be quoted on the command +line. Also, the `| program' must be presented as a single argument to +mail. The safest course is to surround the entire name with double +quotes. This also applies to usage in the +.b alias +command. For example, if we wanted to alias `rmsgs' to `rmsgs \-s' +we would need to say: +.(l +alias rmsgs "| rmsgs -s" +.)l diff --git a/share/doc/usd/07.mail/mail5.nr b/share/doc/usd/07.mail/mail5.nr new file mode 100644 index 000000000000..6b5f57c00c2d --- /dev/null +++ b/share/doc/usd/07.mail/mail5.nr @@ -0,0 +1,1035 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bp +.sh 1 "Additional features" +.pp +This section describes some additional commands useful for +reading your mail, setting options, and handling lists of messages. +.sh 2 "Message lists" +.pp +Several +.i Mail +commands accept a list of messages as an argument. +Along with +.b type +and +.b delete , +described in section 2, +there is the +.b from +command, which prints the message headers associated with the +message list passed to it. +The +.b from +command is particularly useful in conjunction with some of the +message list features described below. +.pp +A +.i "message list" +consists of a list of message numbers, ranges, and names, +separated by spaces or tabs. Message numbers may be either +decimal numbers, which directly specify messages, or one of the +special characters +.q \(ua +.q "." +or +.q "$" +to specify the first relevant, current, or last +relevant message, respectively. +.i Relevant +here means, for most commands +.q "not deleted" +and +.q "deleted" +for the +.b undelete +command. +.pp +A range of messages consists of two message numbers (of the form +described in the previous paragraph) separated by a dash. +Thus, to print the first four messages, use +.(l +type 1\-4 +.)l +and to print all the messages from the current message to the last +message, use +.(l +type .\-$ +.)l +.pp +A +.i name +is a user name. The user names given in the message list are +collected together and each message selected by other means +is checked to make sure it was sent by one of the named users. +If the message consists entirely of user names, then every +message sent by one of those users that is +.i relevant +(in the sense described earlier) +is selected. Thus, to print every message sent to you by +.q root, +do +.(l +type root +.)l +.pp +As a shorthand notation, you can specify simply +.q * +to get every +.i relevant +(same sense) +message. Thus, +.(l +type * +.)l +prints all undeleted messages, +.(l +delete * +.)l +deletes all undeleted messages, and +.(l +undelete * +.)l +undeletes all deleted messages. +.pp +You can search for the presence of a word in subject lines with +.b / . +For example, to print the headers of all messages that contain the +word +.q PASCAL, +do: +.(l +from /pascal +.)l +Note that subject searching ignores upper/lower case differences. +.sh 2 "List of commands" +.pp +This section describes all the +.i Mail +commands available when +receiving mail. +.ip "\fB\-\fP\ \ " +The +.rb \- +command goes to the previous message and prints it. The +.rb \- +command may be given a decimal number +.i n +as an argument, in which case the +.i n th +previous message is gone to and printed. +.ip "\fB?\fP\ \ " +Prints a brief summary of commands. +.ip "\fB!\fP\ \ " +Used to preface a command to be executed by the shell. +.ip "\fBPrint\fP\ \ " +Like +.b print , +but also print out ignored header fields. See also +\fBprint\fP, \fBignore\fP and \fBretain\fP. +\fBPrint\fP can be abbreviated to \fBP\fP. +.ip "\fBReply\fP or \fBRespond\fP\ \ " +Note the capital \fBR\fP in the name. +Frame a reply to a one or more messages. +The reply (or replies if you are using this on multiple messages) +will be sent ONLY to the person who sent you the message +(respectively, the set of people who sent the messages you are +replying to). +You can +add people using the \fB~t\fP, \fB~c\fP and \fB~b\fP +tilde escapes. The subject in your reply is formed by prefacing the +subject in the original message with +.q "Re:" +unless it already began thus. +If the original message included a +.q "reply-to" +header field, the reply will go +.i only +to the recipient named by +.q "reply-to." +You type in your message using the same conventions available to you +through the +.b mail +command. +The +.b Reply +command is especially useful for replying to messages that were sent +to enormous distribution groups when you really just want to +send a message to the originator. Use it often. +\fBReply\fP (and \fBRespond\fP) can be abbreviated to \fBR\fP. +.ip "\fBType\fP\ \ " +Identical to the +.b Print +command. +\fBType\fP can be abbreviated to \fBT\fP. +.ip "\fBalias\fP\ \ " +Define a name to stand for a set of other names. +This is used when you want to send messages to a certain +group of people and want to avoid retyping their names. +For example +.(l +alias project john sue willie kathryn +.)l +creates an alias +.i project +which expands to the four people John, Sue, Willie, and Kathryn. +If no arguments are given, all currently-defined aliases are printed. +If one argument is given, that alias is printed (if it exists). +\fBAlias\fP can be abbreviated to \fBa\fP. +.ip "\fBalternates\fP\ \ " +If you have accounts on several machines, you may find it convenient +to use the /usr/lib/aliases on all the machines except one to direct +your mail to a single account. +The +.b alternates +command is used to inform +.i Mail +that each of these other addresses is really +.i you . +.i Alternates +takes a list of user names and remembers that they are all actually you. +When you +.b reply +to messages that were sent to one of these alternate names, +.i Mail +will not bother to send a copy of the message to this other address (which +would simply be directed back to you by the alias mechanism). +If +.i alternates +is given no argument, it lists the current set of alternate names. +.b Alternates +is usually used in the .mailrc file. +\fBAlternates\fP can be abbreviated to \fBalt\fP. +.ip "\fBchdir\fP\ \ " +The +.b chdir +command allows you to change your current directory. +.b Chdir +takes a single argument, which is taken to be the pathname of +the directory to change to. If no argument is given, +.b chdir +changes to your home directory. +\fBChdir\fP can be abbreviated to \fBc\fP. +.ip "\fBcopy\fP\ \ " +The +.b copy +command does the same thing that +.b save +does, except that it does not mark the messages it is used on +for deletion when you quit. +\fBCopy\fP can be abbreviated to \fBco\fP. +.ip "\fBdelete\fP\ \ " +Deletes a list of messages. Deleted messages can be reclaimed +with the +.b undelete +command. +\fBDelete\fP can be abbreviated to \fBd\fP. +.ip "\fBdp\fP or \fBdt\fP\ \ " +These +commands delete the current message and print the next message. +They are useful for quickly reading and disposing of mail. +If there is no next message, \fImail\fP says ``at EOF.'' +.ip "\fBedit\fP\ \ " +To edit individual messages using the text editor, the +.b edit +command is provided. The +.b edit +command takes a list of messages as described under the +.b type +command and processes each by writing it into the file +Message\c +.i x +where +.i x +is the message number being edited and executing the text editor on it. +When you have edited the message to your satisfaction, write the message +out and quit, upon which +.i Mail +will read the message back and remove the file. +.b Edit +can be abbreviated to +.b e . +.ip "\fBelse\fP\ \ " +Marks the end of the then-part of an +.b if +statement and the beginning of the +part to take effect if the condition of the +.b if +statement is false. +.ip "\fBendif\fP\ \ " +Marks the end of an +.b if +statement. +.ip "\fBexit\fP or \fBxit\fP\ \ " +Leave +.i Mail +without updating the system mailbox or the file your were reading. +Thus, if you accidentally delete several messages, you can use +.b exit +to avoid scrambling your mailbox. +\fBExit\fP can be abbreviated to \fBex\fP or \fBx\fP. +.ip "\fBfile\fP\ \ " +The same as +.b folder . +\fBFile\fP can be abbreviated to \fBfi\fP. +.ip "\fBfolders\fP\ \ " +List the names of the folders in your folder directory. +.ip "\fBfolder\fP\ \ " +The +.b folder +command switches to a new mail file or folder. With no arguments, it +tells you which file you are currently reading. If you give +it an argument, it will write out changes (such as deletions) +you have made in the current file and read the new file. +Some special conventions are recognized for the name: +.(b +.TS +center; +c c +l a. +Name Meaning +_ +# Previous file read +% Your system mailbox +%name \fIName\fP's system mailbox +& Your ~/mbox file ++folder A file in your folder directory +.TE +.)b +\fBFolder\fP can be abbreviated to \fBfo\fP. +.ip "\fBfrom\fP\ \ " +The +.b from +command takes a list of messages and prints out the header lines for each one; +hence +.(l +from joe +.)l +is the easy way to display all the message headers from \*(lqjoe.\*(rq +\fBFrom\fP can be abbreviated to \fBf\fP. +.ip "\fBheaders\fP\ \ " +When you start up +.i Mail +to read your mail, it lists the message headers that you have. +These headers tell you who each message is from, when they were +received, how many lines and characters each message is, and the +.q "Subject:" +header field of each message, if present. In addition, +.i Mail +tags the message header of each message that has been the object +of the +.b preserve +command with a +.q P. +Messages that have been +.b saved +or +.b written +are flagged with a +.q *. +Finally, +.b deleted +messages are not printed at all. If you wish to reprint the current +list of message headers, you can do so with the +.b headers +command. The +.b headers +command (and thus the initial header listing) +only lists the first so many message headers. +The number of headers listed depends on the speed of your +terminal. +This can be overridden by specifying the number of headers you +want with the +.i window +option. +.i Mail +maintains a notion of the current +.q window +into your messages for the purposes of printing headers. +Use the +.b z +command to move forward and back a window. +You can move +.i Mail's +notion of the current window directly to a particular message by +using, for example, +.(l +headers 40 +.)l +to move +.i Mail's +attention to the messages around message 40. +If a ``+'' argument is given, then the next screenful of message headers is +printed, and if a ``\-'' argument is given, the previous screenful of message +headers is printed. +\fBHeaders\fP can be abbreviated to \fBh\fP. +.ip "\fBhelp\fP\ \ " +Print a brief and usually out of date help message about the commands +in +.i Mail . +The +.i man +page for +.i mail +is usually more up-to-date than either the help message or this manual. +It is also a synonym for \fB?\fP. +.ip "\fBhold\fP\ \ " +Arrange to hold a list of messages in the system mailbox, instead +of moving them to the file +.i mbox +in your home directory. If you set the binary option +.i hold , +this will happen by default. +It does not override the \fBdelete\fP command. +\fBHold\fP can be abbreviated to \fBho\fP. +.ip "\fBif\fP\ \ " +Commands in your +.q .mailrc +file can be executed conditionally depending on whether you are +sending or receiving mail with the +.b if +command. For example, you can do: +.(l +if receive + \fIcommands\fP... +endif +.)l +An +.b else +form is also available: +.(l +if send + \fIcommands\fP... +else + \fIcommands\fP... +endif +.)l +Note that the only allowed conditions are +.b receive +and +.b send . +.ip "\fBignore\fP \ \ " +.b N.B.: +.i Ignore +has been superseded by +.i retain. +.br +Add the list of header fields named to the +.i "ignore list" . +Header fields in the ignore list are not printed on your +terminal when you print a message. This allows you to suppress +printing of certain machine-generated header fields, such as +.i Via +which are not usually of interest. The +.b Type +and +.b Print +commands can be used to print a message in its entirety, including +ignored fields. +If +.b ignore +is executed with no arguments, it lists the current set of ignored fields. +.ip "\fBlist\fP\ \ " +List the valid +.i Mail +commands. +\fBList\fP can be abbreviated to \fBl\fP. +.\".ip \fBlocal\fP +.\"Define a list of local names for this host. This command is useful +.\"when the host is known by more than one name. Names in the list +.\"may be qualified be the domain of the host. The first name on the local +.\"list is the +.\".i distinguished +.\"name of the host. +.\"The names on the local list are used by +.\".i Mail +.\"to decide which addresses are local to the host. +.\"For example: +.\".(l +.\"local ucbarpa.BERKELEY.ARPA arpa.BERKELEY.ARPA \\ +.\" arpavax.BERKELEY.ARPA r.BERKELEY.ARPA \\ +.\" ucb-arpa.ARPA +.\".)l +.\"From this list we see that +.\".i "fred@ucbarpa.BERKELEY.ARPA", +.\".i "harold@arpa.BERKELEY", +.\"and +.\".i "larry@r" +.\"are all addresses of users on the local host. +.\"The +.\".b local +.\"command is usually not used be general users since it is designed for +.\"local configuration; it is usually found in the file /etc/mail.rc. +.ip "\fBmail\fP\ \ " +Send mail to one or more people. If you have the +.i ask +option set, +.i Mail +will prompt you for a subject to your message. Then you +can type in your message, using tilde escapes as described in +section 4 to edit, print, or modify your message. To signal your +satisfaction with the message and send it, type control-d at the +beginning of a line, or a . alone on a line if you set the option +.i dot . +To abort the message, type two interrupt characters (\s-2RUBOUT\s0 +by default) in a row or use the +.b ~q +escape. +The \fBmail\fP command can be abbreviated to \fBm\fP. +.ip "\fBmbox\fP\ \ " +Indicate that a list of messages be sent to +.i mbox +in your home directory when you quit. This is the default +action for messages if you do +.i not +have the +.i hold +option set. +.ip "\fBnext\fP or \fB+\fP\ \ " +The +.b next +command goes to the next message and types it. If given a message list, +.b next +goes to the first such message and types it. Thus, +.(l +next root +.)l +goes to the next message sent by +.q root +and types it. The +.b next +command can be abbreviated to simply a newline, which means that one +can go to and type a message by simply giving its message number or +one of the magic characters +.q "^" +.q "." +or +.q "$". +Thus, +.(l +\&. +.)l +prints the current message and +.(l +4 +.)l +prints message 4, as described previously. +\fBNext\fP can be abbreviated to \fBn\fP. +.ip "\fBpreserve\fP\ \ " +Same as +.b hold . +Cause a list of messages to be held in your system mailbox when you quit. +\fBPreserve\fP can be abbreviated to \fBpre\fP. +.ip "\fBprint\fP\ \ " +Print the specified messages. If the +.b crt +variable is set, messages longer than the number of lines it indicates +are paged through the command specified by the \fBPAGER\fP variable. +The \fBprint\fP command can be abbreviated to \fBp\fP. +.ip "\fBquit\fP\ \ " +Terminates the session, saving all undeleted, unsaved and unwritten messages +in the user's \fImbox\fP file in their login directory +(messages marked as having been read), preserving all +messages marked with \fBhold\fP or \fBpreserve\fP or never referenced +in their system mailbox. +Any messages that were deleted, saved, written or saved to \fImbox\fP are +removed from their system mailbox. +If new mail has arrived during the session, the message +``You have new mail'' is given. If given while editing a mailbox file +with the \fB\-f\fP flag, then the edit file is rewritten. +A return to the Shell is effected, unless the rewrite of edit file fails, +in which case the user can escape with the \fBexit\fP command. +\fBQuit\fP can be abbreviated to \fBq\fP. +.ip "\fBreply\fP or \fBrespond\fP\ \ " +Frame a reply to a single message. +The reply will be sent to the +person who sent you the message (to which you are replying), plus all +the people who received the original message, except you. You can +add people using the \fB~t\fP, \fB~c\fP and \fB~b\fP +tilde escapes. The subject in your reply is formed by prefacing the +subject in the original message with +.q "Re:" +unless it already began thus. +If the original message included a +.q "reply-to" +header field, the reply will go +.i only +to the recipient named by +.q "reply-to." +You type in your message using the same conventions available to you +through the +.b mail +command. +The \fBreply\fP (and \fBrespond\fP) command can be abbreviated to \fBr\fP. +.ip "\fBretain\fP\ \ " +Add the list of header fields named to the \fIretained list\fP. +Only the header fields in the retain list +are shown on your terminal when you print a message. +All other header fields are suppressed. +The +.b Type +and +.b Print +commands can be used to print a message in its entirety. +If +.b retain +is executed with no arguments, it lists the current set of +retained fields. +.ip "\fBsave\fP\ \ " +It is often useful to be able to save messages on related topics +in a file. The +.b save +command gives you the ability to do this. The +.b save +command takes as an argument a list of message numbers, followed by +the name of the file in which to save the messages. The messages +are appended to the named file, thus allowing one to keep several +messages in the file, stored in the order they were put there. +The filename in quotes, followed by the line +count and character count is echoed on the user's terminal. +An example of the +.b save +command relative to our running example is: +.(l +s 1 2 tuitionmail +.)l +.b Saved +messages are not automatically saved in +.i mbox +at quit time, nor are they selected by the +.b next +command described above, unless explicitly specified. +\fBSave\fP can be abbreviated to \fBs\fP. +.ip "\fBset\fP\ \ " +Set an option or give an option a value. Used to customize +.i Mail . +Section 5.3 contains a list of the options. Options can be +.i binary , +in which case they are +.i on +or +.i off , +or +.i valued . +To set a binary option +.i option +.i on , +do +.(l +set option +.)l +To give the valued option +.i option +the value +.i value , +do +.(l +set option=value +.)l +There must be no space before or after the ``='' sign. +If no arguments are given, all variable values are printed. +Several options can be specified in a single +.b set +command. +\fBSet\fP can be abbreviated to \fBse\fP. +.ip "\fBshell\fP\ \ " +The +.b shell +command allows you to +escape to the shell. +.b Shell +invokes an interactive shell and allows you to type commands to it. +When you leave the shell, you will return to +.i Mail . +The shell used is a default assumed by +.i Mail ; +you can override this default by setting the valued option +.q SHELL, +eg: +.(l +set SHELL=/bin/csh +.)l +\fBShell\fP can be abbreviated to \fBsh\fP. +.ip "\fBsize\fP\ \ " +Takes a message list and prints out the size in characters of each +message. +.ip "\fBsource\fP\ \ " +The +.b source +command reads +.i mail +commands from a file. It is useful when you are trying to fix your +.q .mailrc +file and you need to re-read it. +\fBSource\fP can be abbreviated to \fBso\fP. +.ip "\fBtop\fP\ \ " +The +.b top +command takes a message list and prints the first five lines +of each addressed message. +If you wish, you can change the number of lines that +.b top +prints out by setting the valued option +.q "toplines." +On a CRT terminal, +.(l +set toplines=10 +.)l +might be preferred. +\fBTop\fP can be abbreviated to \fBto\fP. +.ip "\fBtype\fP\ \ " +Same as \fBprint\fP. +Takes a message list and types out each message on the terminal. +The \fBtype\fP command can be abbreviated to \fBt\fP. +.ip "\fBundelete\fP \ \" +Takes a message list and marks each message as \fInot\fP +being deleted. +\fBUndelete\fP can be abbreviated to \fBu\fP. +.ip "\fBunread\fP\ \ " +Takes a message list and marks each message as +.i not +having been read. +\fBUnread\fP can be abbreviated to \fBU\fP. +.ip "\fBunset\fP\ \ " +Takes a list of option names and discards their remembered values; +the inverse of \fBset\fP . +.ip "\fBvisual\fP\ \ " +It is often useful to be able to invoke one of two editors, +based on the type of terminal one is using. To invoke +a display oriented editor, you can use the +.b visual +command. The operation of the +.b visual +command is otherwise identical to that of the +.b edit +command. +.ne 2v+\n(psu +.sp \n(psu +Both the +.b edit +and +.b visual +commands assume some default text editors. These default editors +can be overridden by the valued options +.q EDITOR +and +.q VISUAL +for the standard and screen editors. You might want to do: +.(l +set EDITOR=/usr/bin/ex VISUAL=/usr/bin/vi +.)l +\fBVisual\fP can be abbreviated to \fBv\fP. +.ip "\fBwrite\fP\ \ " +The +.b save +command always writes the entire message, including the headers, +into the file. If you want to write just the message itself, you +can use the +.b write +command. The +.b write +command has the same syntax as the +.b save +command, and can be abbreviated to simply +.b w . +Thus, we could write the second message by doing: +.(l +w 2 file.c +.)l +As suggested by this example, the +.b write +command is useful for such tasks as sending and receiving +source program text over the message system. +The filename in quotes, followed by the line +count and character count is echoed on the user's terminal. +.ip "\fBz\fP\ \ " +.i Mail +presents message headers in windowfuls as described under +the +.b headers +command. +You can move +.i Mail's +attention forward to the next window by giving the +.(l +z+ +.)l +command. Analogously, you can move to the previous window with: +.(l +z\- +.)l +.sh 2 "Custom options" +.pp +Throughout this manual, we have seen examples of binary and valued options. +This section describes each of the options in alphabetical order, including +some that you have not seen yet. +To avoid confusion, please note that the options are either +all lower case letters or all upper case letters. When I start a sentence +such as: +.q "Ask" +causes +.i Mail +to prompt you for a subject header, +I am only capitalizing +.q ask +as a courtesy to English. +.ip "\fBEDITOR\fP\ \ " +The valued option +.q EDITOR +defines the pathname of the text editor to be used in the +.b edit +command and ~e. If not defined, a standard editor is used. +.ip "\fBPAGER\fP\ \ " +Pathname of the program to use for paginating output when +it exceeds \fIcrt\fP lines. +A default paginator is used if this option is not defined. +.ip "\fBSHELL\fP\ \ " +The valued option +.q SHELL +gives the path name of your shell. This shell is used for the +.b ! +command and ~! escape. In addition, this shell expands +file names with shell metacharacters like * and ? in them. +.ip "\fBVISUAL\fP\ \ " +The valued option +.q VISUAL +defines the pathname of the screen editor to be used in the +.b visual +command +and ~v escape. A standard screen editor is used if you do not define one. +.ip "\fBappend\fP\ \ " +The +.q append +option is binary and +causes messages saved in +.i mbox +to be appended to the end rather than prepended. +Normally, \fIMail\fP will put messages in \fImbox\fP +in the same order that the system puts messages in your system mailbox. +By setting +.q append, +you are requesting that +.i mbox +be appended to regardless. It is in any event quicker to append. +.ip "\fBask\fP\ \ " +.q "Ask" +is a binary option which +causes +.i Mail +to prompt you for the subject of each message you send. +If you respond with simply a newline, no subject field will be sent. +.ip "\fBaskcc\fP\ \ " +.q Askcc +is a binary option which +causes you to be prompted for additional carbon copy recipients at the +end of each message. Responding with a newline shows your +satisfaction with the current list. +.ip "\fBautoprint\fP\ \ " +.q Autoprint +is a binary option which +causes the +.b delete +command to behave like +.b dp +\*- thus, after deleting a message, the next one will be typed +automatically. This is useful when quickly scanning and deleting +messages in your mailbox. +.ip "\fBcrt\fP \ \ " +The valued option +.q crt +is used as a threshold to determine how long a message must +be before +.b PAGER +is used to read it. +.ip "\fBdebug\fP \ \ " +The binary option +.q debug +causes debugging information to be displayed. Use of this +option is the same as using the \fB\-d\fP command line flag. +.ip "\fBdot\fP\ \ " +.q Dot +is a binary option which, if set, causes +.i Mail +to interpret a period alone on a line as the terminator +of the message you are sending. +.ip "\fBescape\fP\ \ " +To allow you to change the escape character used when sending +mail, you can set the valued option +.q escape. +Only the first character of the +.q escape +option is used, and it must be doubled if it is to appear as +the first character of a line of your message. If you change your escape +character, then ~ loses all its special meaning, and need no longer be doubled +at the beginning of a line. +.ip "\fBfolder\fP\ \ " +The name of the directory to use for storing folders of messages. +If this name begins with a `/' +.i Mail +considers it to be an absolute pathname; otherwise, the folder directory +is found relative to your home directory. +.ip "\fBhold\fP\ \ " +The binary option +.q hold +causes messages that have been read but not manually dealt with +to be held in the system mailbox. This prevents such messages from +being automatically swept into your \fImbox\fP file. +.ip "\fBignore\fP\ \ " +The binary option +.q ignore +causes \s-2RUBOUT\s0 characters from your terminal to be ignored and echoed +as @'s while you are sending mail. \s-2RUBOUT\s0 characters retain their +original meaning in +.i Mail +command mode. +Setting the +.q ignore +option is equivalent to supplying the +.b \-i +flag on the command line as described in section 6. +.ip "\fBignoreeof\fP\ \ " +An option related to +.q dot +is +.q ignoreeof +which makes +.i Mail +refuse to accept a control\-d as the end of a message. +.q Ignoreeof +also applies to +.i Mail +command mode. +.ip "\fBkeep\fP\ \ " +The +.q keep +option causes +.i Mail +to truncate your system mailbox instead of deleting it when it +is empty. This is useful if you elect to protect your mailbox, which +you would do with the shell command: +.(l +chmod 600 /var/mail/yourname +.)l +where +.i yourname +is your login name. If you do not do this, anyone can probably read +your mail, although people usually don't. +.ip "\fBkeepsave\fP\ \ " +When you +.b save +a message, +.i Mail +usually discards it when you +.b quit . +To retain all saved messages, set the +.q keepsave +option. +.ip "\fBmetoo\fP\ \ " +When sending mail to an alias, +.i Mail +makes sure that if you are included in the alias, that mail will not +be sent to you. This is useful if a single alias is being used by +all members of the group. If however, you wish to receive a copy of +all the messages you send to the alias, you can set the binary option +.q metoo. +.ip "\fBnoheader\fP\ \ " +The binary option +.q noheader +suppresses the printing of the version and headers when +.i Mail +is first invoked. Setting this option is the same as using +.b \-N +on the command line. +.ip "\fBnosave\fP\ \ " +Normally, +when you abort a message with two \s-2RUBOUTs\s0, +.i Mail +copies the partial letter to the file +.q dead.letter +in your home directory. Setting the binary option +.q nosave +prevents this. +.ip "\fBReplyall\fP\ \ " +Reverses the sense of +.i reply +and +.i Reply +commands. +.ip "\fBquiet\fP\ \ " +The binary option +.q quiet +suppresses the printing of the version when +.i Mail +is first invoked, +as well as printing the for example +.q "Message 4:" +from the +.b type +command. +.ip "\fBrecord\fP\ \ " +If you love to keep records, then the +valued option +.q record +can be set to the name of a file to save your outgoing mail. +Each new message you send is appended to the end of the file. +.ip "\fBscreen\fP\ \ " +When +.i Mail +initially prints the message headers, it determines the number to +print by looking at the speed of your terminal. The faster your +terminal, the more it prints. +The valued option +.q screen +overrides this calculation and +specifies how many message headers you want printed. +This number is also used for scrolling with the +.b z +command. +.ip "\fBsendmail\fP\ \ " +To use an alternate mail delivery system, set the +.q sendmail +option to the full pathname of the program to use. Note: this is not +for everyone! Most people should use the default delivery system. +.ip "\fBtoplines\fP\ \ " +The valued option +.q toplines +defines the number of lines that the +.q top +command will print out instead of the default five lines. +.ip "\fBverbose\fP\ \ " +The binary option "verbose" causes +.i Mail +to invoke sendmail with the +.b \-v +flag, which causes it to go into verbose mode and announce expansion +of aliases, etc. Setting the "verbose" option is equivalent to +invoking +.i Mail +with the +.b \-v +flag as described in section 6. diff --git a/share/doc/usd/07.mail/mail6.nr b/share/doc/usd/07.mail/mail6.nr new file mode 100644 index 000000000000..a213e6a27dcd --- /dev/null +++ b/share/doc/usd/07.mail/mail6.nr @@ -0,0 +1,119 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bp +.sh 1 "Command line options" +.pp +This section describes command line options for +.i Mail +and what they are used for. +.ip \-N +Suppress the initial printing of headers. +.ip \-d +Turn on debugging information. Not of general interest. +.ip "\-f file\ \ " +Show the messages in +.i file +instead of your system mailbox. If +.i file +is omitted, +.i Mail +reads +.i mbox +in your home directory. +.ip \-i +Ignore tty interrupt signals. Useful on noisy phone lines, which +generate spurious RUBOUT or DELETE characters. It's usually +more effective to change your interrupt character to control\-c, +for which see the +.i stty +shell command. +.ip \-n +Inhibit reading of /etc/mail.rc. Not generally useful, since +/etc/mail.rc is usually empty. +.ip "\-s string" +Used for sending mail. +.i String +is used as the subject of the message being composed. If +.i string +contains blanks, you must surround it with quote marks. +.ip "\-u name" +Read +.i names's +mail instead of your own. Unwitting others often neglect to protect +their mailboxes, but discretion is advised. Essentially, +.b "\-u user" +is a shorthand way of doing +.b "\-f /var/mail/user". +.ip "\-v" +Use the +.b \-v +flag when invoking sendmail. This feature may also be enabled +by setting the option "verbose". +.pp +The following command line flags are also recognized, but are +intended for use by programs invoking +.i Mail +and not for people. +.ip "\-T file" +Arrange to print on +.i file +the contents of the +.i article-id +fields of all messages that were either read or deleted. +.b \-T +is for the +.i readnews +program and should NOT be used for reading your mail. +.ip "\-h number" +Pass on hop count information. +.i Mail +will take the number, increment it, and pass it with +.b \-h +to the mail delivery system. +.b \-h +only has effect when sending mail and is used for network mail +forwarding. +.ip "\-r name" +Used for network mail forwarding: interpret +.i name +as the sender of the message. The +.i name +and +.b \-r +are simply sent along to the mail delivery system. Also, +.i Mail +will wait for the message to be sent and return the exit status. +Also restricts formatting of message. +.pp +Note that +.b \-h +and +.b \-r , +which are for network mail forwarding, are not used in practice +since mail forwarding is now handled separately. They may +disappear soon. diff --git a/share/doc/usd/07.mail/mail7.nr b/share/doc/usd/07.mail/mail7.nr new file mode 100644 index 000000000000..1639392fa9cf --- /dev/null +++ b/share/doc/usd/07.mail/mail7.nr @@ -0,0 +1,101 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.sh 1 "Format of messages" +.pp +This section describes the format of messages. +Messages begin with a +.i from +line, which consists of the word +.q From +followed by a user name, followed by anything, followed by +a date in the format returned by the +.i ctime +library routine described in section 3 of the Unix Programmer's +Manual. A possible +.i ctime +format date is: +.(l +Tue Dec 1 10:58:23 1981 +.)l +The +.i ctime +date may be optionally followed by a single space and a +time zone indication, which +should be three capital letters, such as PDT. +.pp +Following the +.i from +line are zero or more +.i "header field" +lines. +Each header field line is of the form: +.(l +name: information +.)l +.i Name +can be anything, but only certain header fields are recognized as +having any meaning. The recognized header fields are: +.i article-id , +.i bcc , +.i cc , +.i from , +.i reply-to , +.i sender , +.i subject , +and +.i to . +Other header fields are also significant to other systems; see, +for example, the current Arpanet message standard for much more +information on this topic. +A header field can be continued onto following lines by making the +first character on the following line a space or tab character. +.pp +If any headers are present, they must be followed by a blank line. +The part that follows is called the +.i body +of the message, and must be ASCII text, not containing null characters. +Each line in the message body must be no longer than 512 characters and +terminated with an ASCII newline character. +If binary data must be passed through the mail system, it is suggested +that this data be encoded in a system which encodes six bits into +a printable character (i.e.: uuencode). +For example, one could use the upper and lower case letters, the digits, +and the characters comma and period to make up the 64 characters. +Then, one can send a 16-bit binary number +as three characters. These characters should be packed into lines, +preferably lines about 70 characters long as long lines are transmitted +more efficiently. +.pp +The message delivery system always adds a blank line to the end of +each message. This blank line must not be deleted. +.pp +The UUCP message delivery system sometimes adds a blank line to +the end of a message each time it is forwarded through a machine. +.pp +It should be noted that some network transport protocols enforce +limits to the lengths of messages. diff --git a/share/doc/usd/07.mail/mail8.nr b/share/doc/usd/07.mail/mail8.nr new file mode 100644 index 000000000000..b9be47d0fa2c --- /dev/null +++ b/share/doc/usd/07.mail/mail8.nr @@ -0,0 +1,69 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bp +.sh 1 "Glossary" +.pp +This section contains the definitions of a few phrases +peculiar to +.i Mail . +.ip "\fIalias\fP" +An alternative name for a person or list of people. +.ip "\fIflag\fP" +An option, given on the command line of +.i Mail , +prefaced with a \-. For example, +.b \-f +is a flag. +.ip "\fIheader field\fP" +At the beginning of a message, a line which contains information +that is part of the structure of the message. Popular header fields +include +.i to , +.i cc , +and +.i subject . +.ip "\fImail\ \ \fP" +A collection of messages. Often used in the phrase, +.q "Have you read your mail?" +.ip "\fImailbox\fP" +The place where your mail is stored, typically in the directory +/var/mail. +.ip "\fImessage\fP" +A single letter from someone, initially stored in your +.i mailbox . +.ip "\fImessage list\fP" +A string used in +.i Mail +command mode to describe a sequence of messages. +.ip "\fIoption\fP" +A piece of special purpose information used to tailor +.i Mail +to your taste. +Options are specified with the +.b set +command. diff --git a/share/doc/usd/07.mail/mail9.nr b/share/doc/usd/07.mail/mail9.nr new file mode 100644 index 000000000000..61a0746d1d4e --- /dev/null +++ b/share/doc/usd/07.mail/mail9.nr @@ -0,0 +1,197 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bp +.sh 1 "Summary of commands, options, and escapes" +.pp +This section gives a quick summary of the +.i Mail +commands, binary and valued options, and tilde escapes. +.pp +The following table describes the commands: +.TS +center ; +c ci +lb l. +Command Description +_ ++ Same as \fBnext\fP +- Back up to previous message +? Print brief summary of \fIMail\fP commands +! Single command escape to shell +Print Type message with ignored fields +Reply Reply to author of message only +Respond Same as \fBReply\fP +Type Type message with ignored fields +alias Define an alias as a set of user names +alternates List other names you are known by +chdir Change working directory, home by default +copy Copy a message to a file or folder +delete Delete a list of messages +dp Same as \fBdt\fP +dt Delete current message, type next message +edit Edit a list of messages +else Start of else part of conditional; see \fBif\fP +endif End of conditional statement; see \fBif\fP +exit Leave mail without changing anything +file Interrogate/change current mail file +folder Same as \fBfile\fP +folders List the folders in your folder directory +from List headers of a list of messages +headers List current window of messages +help Same as \fB?\fP +hold Same as \fBpreserve\fP +if Conditional execution of \fIMail\fP commands +ignore Set/examine list of ignored header fields +list List valid \fIMail\fP commands +local List other names for the local host +mail Send mail to specified names +mbox Arrange to save a list of messages in \fImbox\fP +next Go to next message and type it +preserve Arrange to leave list of messages in system mailbox +print Print messages +quit Leave \fIMail\fP; update system mailbox, \fImbox\fP as appropriate +reply Compose a reply to a message +respond Same as \fBreply\fP +retain Supersedes \fBignore\fP +save Append messages, headers included, on a file +set Set binary or valued options +shell Invoke an interactive shell +size Prints out size of message list +source Read \fImail\fP commands from a file +top Print first so many (5 by default) lines of list of messages +type Same as \fBprint\fP +undelete Undelete list of messages +unread Marks list of messages as not been read +unset Undo the operation of a \fBset\fP +visual Invoke visual editor on a list of messages +write Append messages to a file, don't include headers +xit Same as \fBexit\fP +z Scroll to next/previous screenful of headers +.TE +.bp +.(b +.pp +The following table describes the options. Each option is +shown as being either a binary or valued option. +.TS +center; +c ci ci +l ci l. +Option Type Description +_ +EDITOR valued Pathname of editor for ~e and \fBedit\fP +PAGER valued Pathname of paginator for \fBPrint\fP, \fBprint\fP, \fBType\fP and \fBtype\fP +SHELL valued Pathname of shell for \fBshell\fP, ~! and \fB!\fP +VISUAL valued Pathname of screen editor for ~v, \fBvisual\fP +append binary Always append messages to end of \fImbox\fP +ask binary Prompt user for Subject: field when sending +askcc binary Prompt user for additional Cc's at end of message +autoprint binary Print next message after \fBdelete\fP +crt valued Minimum number of lines before using \fBPAGER\fP +debug binary Print out debugging information +dot binary Accept . alone on line to terminate message input +escape valued Escape character to be used instead of\ \ ~ +folder valued Directory to store folders in +hold binary Hold messages in system mailbox by default +ignore binary Ignore \s-2RUBOUT\s0 while sending mail +ignoreeof binary Don't terminate letters/command input with \fB\(uaD\fP +keep binary Don't unlink system mailbox when empty +keepsave binary Don't delete \fBsave\fPd messages by default +metoo binary Include sending user in aliases +noheader binary Suppress initial printing of version and headers +nosave binary Don't save partial letter in \fIdead.letter\fP +quiet binary Suppress printing of \fIMail\fP version and message numbers +record valued File to save all outgoing mail in +screen valued Size of window of message headers for \fBz\fP, etc. +sendmail valued Choose alternate mail delivery system +toplines valued Number of lines to print in \fBtop\fP +verbose binary Invoke sendmail with the \fB\-v\fP flag +.TE +.)b +.(b +.pp +The following table summarizes the tilde escapes available +while sending mail. +.TS +center; +c ci ci +l li l. +Escape Arguments Description +_ +~! command Execute shell command +~b name ... Add names to "blind" Cc: list +~c name ... Add names to Cc: field +~d Read \fIdead.letter\fP into message +~e Invoke text editor on partial message +~f messages Read named messages +~h Edit the header fields +~m messages Read named messages, right shift by tab +~p Print message entered so far +~q Abort entry of letter; like \s-2RUBOUT\s0 +~r filename Read file into message +~s string Set Subject: field to \fIstring\fP +~t name ... Add names to To: field +~v Invoke screen editor on message +~w filename Write message on file +~| command Pipe message through \fIcommand\fP +~: Mail command Execute a \fIMail\fP command +~~ string Quote a ~ in front of \fIstring\fP +.TE +.)b +.(b +.pp +The following table shows the command line flags that +.i Mail +accepts: +.TS +center; +c c +l a. +Flag Description +_ +\-N Suppress the initial printing of headers +\-T \fIfile\fP Article-id's of read/deleted messages to \fIfile\fP +\-d Turn on debugging +\-f \fIfile\fP Show messages in \fIfile\fP or \fI~/mbox\fP +\-h \fInumber\fP Pass on hop count for mail forwarding +\-i Ignore tty interrupt signals +\-n Inhibit reading of /etc/mail.rc +\-r \fIname\fP Pass on \fIname\fP for mail forwarding +\-s \fIstring\fP Use \fIstring\fP as subject in outgoing mail +\-u \fIname\fP Read \fIname's\fP mail instead of your own +\-v Invoke sendmail with the \fB\-v\fP flag +.TE +.)b +.lp +Notes: +.b \-T , +.b \-d , +.b \-h , +and +.b \-r +are not for human use. diff --git a/share/doc/usd/07.mail/maila.nr b/share/doc/usd/07.mail/maila.nr new file mode 100644 index 000000000000..4edaeca934ef --- /dev/null +++ b/share/doc/usd/07.mail/maila.nr @@ -0,0 +1,27 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" diff --git a/share/doc/usd/10.exref/Makefile b/share/doc/usd/10.exref/Makefile new file mode 100644 index 000000000000..b5732c655131 --- /dev/null +++ b/share/doc/usd/10.exref/Makefile @@ -0,0 +1,4 @@ +SUBDIR= exref summary + +.include <bsd.subdir.mk> + diff --git a/share/doc/usd/10.exref/Makefile.inc b/share/doc/usd/10.exref/Makefile.inc new file mode 100644 index 000000000000..c5dd0a9aac67 --- /dev/null +++ b/share/doc/usd/10.exref/Makefile.inc @@ -0,0 +1,2 @@ +VOLUME= usd/10.exref +MACROS= -ms diff --git a/share/doc/usd/10.exref/exref/Makefile b/share/doc/usd/10.exref/exref/Makefile new file mode 100644 index 000000000000..23d10e553164 --- /dev/null +++ b/share/doc/usd/10.exref/exref/Makefile @@ -0,0 +1,3 @@ +SRCS= ex.rm + +.include <bsd.doc.mk> diff --git a/share/doc/usd/10.exref/exref/ex.rm b/share/doc/usd/10.exref/exref/ex.rm new file mode 100644 index 000000000000..ea09f545f69c --- /dev/null +++ b/share/doc/usd/10.exref/exref/ex.rm @@ -0,0 +1,2212 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr LL 6.5i +.nr FL 6.5i +.EH 'USD:12-%''Ex Reference Manual' +.OH 'Ex Reference Manual''USD:12-%' +.ND +.nr )P 0 +.de ZP +.nr pd \\n()P +.nr )P 0 +.if \\n(.$=0 .IP +.if \\n(.$=1 .IP "\\$1" +.if \\n(.$>=2 .IP "\\$1" "\\$2" +.nr )P \\n(pd +.rm pd +.. +.de LC +.br +.sp .1i +.ne 4 +.LP +.ta 4.0i +.. +.bd S B 3 +.\".RP +.TL +Ex Reference Manual +.br +Version 3.7 +.AU +William Joy +.AU +Mark Horton +.AI +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, Ca. 94720 +.AB +.I Ex +a line oriented text editor, which supports both command and display +oriented editing. +This reference manual describes the command oriented part of +.I ex; +the display editing features of +.I ex +are described in +.I "An Introduction to Display Editing with Vi." +Other documents about the editor include the introduction +.I "Edit: A tutorial", +the +.I "Ex/edit Command Summary", +and a +.I "Vi Quick Reference" +card. +.AE +.NH 1 +Starting ex +.PP +.FS +The financial support of an \s-2IBM\s0 Graduate Fellowship and the National +Science Foundation under grants MCS74-07644-A03 and MCS78-07291 is gratefully +acknowledged. +.FE +Each instance of the editor has a set of options, +which can be set to tailor it to your liking. +The command +.I edit +invokes a version of +.I ex +designed for more casual or beginning +users by changing the default settings of some of these options. +To simplify the description which follows we +assume the default settings of the options. +.PP +When invoked, +.I ex +determines the terminal type from the \s-2TERM\s0 variable in the environment. +It there is a \s-2TERMCAP\s0 variable in the environment, and the type +of the terminal described there matches the \s-2TERM\s0 variable, +then that description +is used. Also if the \s-2TERMCAP\s0 variable contains a pathname (beginning +with a \fB/\fR) then the editor will seek the description of the terminal +in that file (rather than the default /etc/termcap). +If there is a variable \s-2EXINIT\s0 in the environment, then the editor +will execute the commands in that variable, +otherwise if there is a file +.I \&.exrc +in your \s-2HOME\s0 directory +.I ex +reads commands from that file, simulating a +.I source +command. +Option setting commands placed in +\s-2EXINIT\s0 or +.I \&.exrc +will be executed before each editor session. +.PP +A command to enter +.I ex +has the following prototype:\(dg +.FS +\(dg Brackets `[' `]' surround optional parameters here. +.FE +.DS +\fBex\fP [ \fB\-\fP ] [ \fB\-v\fP ] [ \fB\-t\fP \fItag\fP ] [ \fB\-r\fP ] [ \fB\-l\fP ] [ \fB\-w\fP\fIn\fP ] [ \fB\-x\fP ] [ \fB\-R\fP ] [ \fB+\fP\fIcommand\fP ] name ... +.DE +The most common case edits a single file with no options, i.e.: +.DS +\fBex\fR name +.DE +The +.B \- +command line option +option suppresses all interactive-user feedback +and is useful in processing editor scripts in command files. +The +.B \-v +option is equivalent to using +.I vi +rather than +.I ex. +The +.B \-t +option is equivalent to an initial +.I tag +command, editing the file containing the +.I tag +and positioning the editor at its definition. +The +.B \-r +option is used in recovering after an editor or system crash, +retrieving the last saved version of the named file or, +if no file is specified, +typing a list of saved files. +The +.B \-l +option sets up for editing \s-2LISP\s0, setting the +.I showmatch +and +.I lisp +options. +The +.B \-w +option sets the default window size to +.I n, +and is useful on dialups to start in small windows. +The +.B \-x +option causes +.I ex +to prompt for a +.I key , +which is used to encrypt and decrypt the contents of the file, +which should already be encrypted using the same key, +see +.I crypt (1). +The +.B \-R +option sets the +.I readonly +option at the start. +.I Name +arguments indicate files to be edited. +An argument of the form +\fB+\fIcommand\fR +indicates that the editor should begin by executing the specified command. +If +.I command +is omitted, then it defaults to ``$'', positioning the editor at the last +line of the first file initially. Other useful commands here are scanning +patterns of the form ``/pat'' or line numbers, e.g. ``+100'' starting +at line 100. +.NH 1 +File manipulation +.NH 2 +Current file +.PP +.I Ex +is normally editing the contents of a single file, +whose name is recorded in the +.I current +file name. +.I Ex +performs all editing actions in a buffer +(actually a temporary file) +into which the text of the file is initially read. +Changes made to the buffer have no effect on the file being +edited unless and until the buffer contents are written out to the +file with a +.I write +command. +After the buffer contents are written, +the previous contents of the written file are no longer accessible. +When a file is edited, +its name becomes the current file name, +and its contents are read into the buffer. +.PP +The current file is almost always considered to be +.I edited. +This means that the contents of the buffer are logically +connected with the current file name, +so that writing the current buffer contents onto that file, +even if it exists, +is a reasonable action. +If the current file is not +.I edited +then +.I ex +will not normally write on it if it already exists.* +.FS +* The +.I file +command will say ``[Not edited]'' if the current file is not considered +edited. +.FE +.NH 2 +Alternate file +.PP +Each time a new value is given to the current file name, +the previous current file name is saved as the +.I alternate +file name. +Similarly if a file is mentioned but does not become the current file, +it is saved as the alternate file name. +.NH 2 +Filename expansion +.PP +Filenames within the editor may be specified using the normal +shell expansion conventions. +In addition, +the character `%' in filenames is replaced by the +.I current +file name and the character +`#' by the +.I alternate +file name.\(dg +.FS +\(dg This makes it easy to deal alternately with +two files and eliminates the need for retyping the +name supplied on an +.I edit +command after a +.I "No write since last change" +diagnostic is received. +.FE +.NH 2 +Multiple files and named buffers +.PP +If more than one file is given on the command line, +then the first file is edited as described above. +The remaining arguments are placed with the first file in the +.I "argument list." +The current argument list may be displayed with the +.I args +command. +The next file in the argument list may be edited with the +.I next +command. +The argument list may also be respecified by specifying +a list of names to the +.I next +command. +These names are expanded, +the resulting list of names becomes the new argument list, +and +.I ex +edits the first file on the list. +.PP +For saving blocks of text while editing, and especially when editing +more than one file, +.I ex +has a group of named buffers. +These are similar to the normal buffer, except that only a limited number +of operations are available on them. +The buffers have names +.I a +through +.I z.\(dd +.FS +\(dd It is also possible to refer to +.I A +through +.I Z; +the upper case buffers are the same as the lower but commands +append to named buffers rather than replacing +if upper case names are used. +.FE +.NH 2 +Read only +.PP +It is possible to use +.I ex +in +.I "read only" +mode to look at files that you have no intention of modifying. +This mode protects you from accidently overwriting the file. +Read only mode is on when the +.I readonly +option is set. +It can be turned on with the +.B \-R +command line option, +by the +.I view +command line invocation, +or by setting the +.I readonly +option. +It can be cleared by setting +.I noreadonly . +It is possible to write, even while in read only mode, by indicating +that you really know what you are doing. +You can write to a different file, or can use the ! form of write, +even while in read only mode. +.NH 1 +Exceptional Conditions +.NH 2 +Errors and interrupts +.PP +When errors occur +.I ex +(optionally) rings the terminal bell and, in any case, prints an error +diagnostic. If the primary input is from a file, editor processing +will terminate. If an interrupt signal is received, +.I ex +prints ``Interrupt'' and returns to its command level. If the primary +input is a file, then +.I ex +will exit when this occurs. +.NH 2 +Recovering from hangups and crashes +.PP +If a hangup signal is received and the buffer has been modified since +it was last written out, or if the system crashes, either the editor +(in the first case) or the system (after it reboots in the second) will +attempt to preserve the buffer. The next time you log in you should be +able to recover the work you were doing, losing at most a few lines of +changes from the last point before the hangup or editor crash. To +recover a file you can use the +.B \-r +option. If you were editing the file +.I resume, +then you should change +to the directory where you were when the crash occurred, giving the command +.DS +\fBex \-r\fP\fI resume\fP +.DE +After checking that the retrieved file is indeed ok, you can +.I write +it over the previous contents of that file. +.PP +You will normally get mail from the system telling you when a file has +been saved after a crash. The command +.DS +\fBex\fP \-\fBr\fP +.DE +will print a list of the files which have been saved for you. +(In the case of a hangup, +the file will not appear in the list, +although it can be recovered.) +.NH 1 +Editing modes +.PP +.I Ex +has five distinct modes. The primary mode is +.I command +mode. Commands are entered in command mode when a `:' prompt is +present, and are executed each time a complete line is sent. In +.I "text input" +mode +.I ex +gathers input lines and places them in the file. The +.I append, +.I insert, +and +.I change +commands use text input mode. +No prompt is printed when you are in text input mode. +This mode is left by typing a `.' alone at the beginning of a line, and +.I command +mode resumes. +.PP +The last three modes are +.I open +and +.I visual +modes, entered by the commands of the same name, and, within open and +visual modes +.I "text insertion" +mode. +.I Open +and +.I visual +modes allow local editing operations to be performed on the text in the +file. The +.I open +command displays one line at a time on any terminal while +.I visual +works on \s-2CRT\s0 terminals with random positioning cursors, using the +screen as a (single) window for file editing changes. +These modes are described (only) in +.I "An Introduction to Display Editing with Vi." +.NH +Command structure +.PP +Most command names are English words, +and initial prefixes of the words are acceptable abbreviations. +The ambiguity of abbreviations is resolved in favor of the more commonly +used commands.* +.FS +* As an example, the command +.I substitute +can be abbreviated `s' +while the shortest available abbreviation for the +.I set +command is `se'. +.FE +.NH 2 +Command parameters +.PP +Most commands accept prefix addresses specifying the lines in the file +upon which they are to have effect. +The forms of these addresses will be discussed below. +A number of commands also may take a trailing +.I count +specifying the number of lines to be involved in the command.\(dg +.FS +\(dg Counts are rounded down if necessary. +.FE +Thus the command ``10p'' will print the tenth line in the buffer while +``delete 5'' will delete five lines from the buffer, +starting with the current line. +.PP +Some commands take other information or parameters, +this information always being given after the command name.\(dd +.FS +\(dd Examples would be option names in a +.I set +command i.e. ``set number'', +a file name in an +.I edit +command, +a regular expression in a +.I substitute +command, +or a target address for a +.I copy +command, i.e. ``1,5 copy 25''. +.FE +.NH 2 +Command variants +.PP +A number of commands have two distinct variants. +The variant form of the command is invoked by placing an +`!' immediately after the command name. +Some of the default variants may be controlled by options; +in this case, the `!' serves to toggle the default. +.NH 2 +Flags after commands +.PP +The characters `#', `p' and `l' may be placed after many commands.** +.FS +** +A `p' or `l' must be preceded by a blank or tab +except in the single special case `dp'. +.FE +In this case, the command abbreviated by these characters +is executed after the command completes. +Since +.I ex +normally prints the new current line after each change, `p' is rarely necessary. +Any number of `+' or `\-' characters may also be given with these flags. +If they appear, the specified offset is applied to the current line +value before the printing command is executed. +.NH 2 +Comments +.PP +It is possible to give editor commands which are ignored. +This is useful when making complex editor scripts +for which comments are desired. +The comment character is the double quote: ". +Any command line beginning with " is ignored. +Comments beginning with " may also be placed at the ends +of commands, except in cases where they could be confused as part +of text (shell escapes and the substitute and map commands). +.NH 2 +Multiple commands per line +.PP +More than one command may be placed on a line by separating each pair +of commands by a `|' character. +However the +.I global +commands, +comments, +and the shell escape `!' +must be the last command on a line, as they are not terminated by a `|'. +.NH 2 +Reporting large changes +.PP +Most commands which change the contents of the editor buffer give +feedback if the scope of the change exceeds a threshold given by the +.I report +option. +This feedback helps to detect undesirably large changes so that they may +be quickly and easily reversed with an +.I undo. +After commands with more global effect such as +.I global +or +.I visual, +you will be informed if the net change in the number of lines +in the buffer during this command exceeds this threshold. +.NH 1 +Command addressing +.NH 2 +Addressing primitives +.IP \fB.\fR 20 +The current line. +Most commands leave the current line as the last line which they affect. +The default address for most commands is the current line, +thus `\fB.\fR' is rarely used alone as an address. +.IP \fIn\fR 20 +The \fIn\fRth line in the editor's buffer, lines being numbered +sequentially from 1. +.IP \fB$\fR 20 +The last line in the buffer. +.IP \fB%\fR 20 +An abbreviation for ``1,$'', the entire buffer. +.IP \fI+n\fR\ \fI\-n\fR 20 +An offset relative to the current buffer line.\(dg +.FS +\(dg +The forms `.+3' `+3' and `+++' are all equivalent; +if the current line is line 100 they all address line 103. +.FE +.IP \fB/\fIpat\fR\fB/\fR\ \fB?\fIpat\fR\fB?\fR 20 +Scan forward and backward respectively for a line containing \fIpat\fR, a +regular expression (as defined below). The scans normally wrap around the end +of the buffer. +If all that is desired is to print the next line containing \fIpat\fR, then +the trailing \fB/\fR or \fB?\fR may be omitted. +If \fIpat\fP is omitted or explicitly empty, then the last +regular expression specified is located.\(dd +.FS +\(dd The forms \fB\e/\fP and \fB\e?\fP scan +using the last regular expression used in a scan; after a substitute +\fB//\fP and \fB??\fP would scan using the substitute's regular expression. +.FE +.IP \fB\(aa\(aa\fP\ \fB\(aa\fP\fIx\fP 20 +Before each non-relative motion of the current line `\fB.\fP', +the previous current line is marked with a tag, subsequently referred to as +`\(aa\(aa'. +This makes it easy to refer or return to this previous context. +Marks may also be established by the +.I mark +command, using single lower case letters +.I x +and the marked lines referred to as +`\(aa\fIx\fR'. +.NH 2 +Combining addressing primitives +.PP +Addresses to commands consist of a series of addressing primitives, +separated by `,' or `;'. +Such address lists are evaluated left-to-right. +When addresses are separated by `;' the current line `\fB.\fR' +is set to the value of the previous addressing expression +before the next address is interpreted. +If more addresses are given than the command requires, +then all but the last one or two are ignored. +If the command takes two addresses, the first addressed line must +precede the second in the buffer.\(dg +.FS +\(dg Null address specifications are permitted in a list of addresses, +the default in this case is the current line `.'; +thus `,100' is equivalent to `\fB.\fR,100'. +It is an error to give a prefix address to a command which expects none. +.FE +.NH 1 +Command descriptions +.PP +The following form is a prototype for all +.I ex +commands: +.DS +\fIaddress\fR \fBcommand\fR \fI! parameters count flags\fR +.DE +All parts are optional; the degenerate case is the empty command which prints +the next line in the file. For sanity with use from within +.I visual +mode, +.I ex +ignores a ``:'' preceding any command. +.PP +In the following command descriptions, the +default addresses are shown in parentheses, +which are +.I not, +however, +part of the command. +.LC +\fBabbreviate\fR \fIword rhs\fP abbr: \fBab\fP +.ZP +Add the named abbreviation to the current list. +When in input mode in visual, if +.I word +is typed as a complete word, it will be changed to +.I rhs . +.LC +( \fB.\fR ) \fBappend\fR abbr: \fBa\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +Reads the input text and places it after the specified line. +After the command, `\fB.\fR' +addresses the last line input or the +specified line if no lines were input. +If address `0' is given, +text is placed at the beginning of the buffer. +.LC +\fBa!\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +The variant flag to +.I append +toggles the setting for the +.I autoindent +option during the input of +.I text. +.LC +\fBargs\fR +.ZP +The members of the argument list are printed, with the current argument +delimited by `[' and `]'. +.ig +.PP +\fBcd\fR \fIdirectory\fR +.ZP +The +.I cd +command is a synonym for +.I chdir. +.. +.LC +( \fB.\fP , \fB.\fP ) \fBchange\fP \fIcount\fP abbr: \fBc\fP +.br +\fItext\fP +.br +\&\fB.\fP +.ZP +Replaces the specified lines with the input \fItext\fP. +The current line becomes the last line input; +if no lines were input it is left as for a +\fIdelete\fP. +.LC +\fBc!\fP +.br +\fItext\fP +.br +\&\fB.\fP +.ZP +The variant toggles +.I autoindent +during the +.I change. +.ig +.LC +\fBchdir\fR \fIdirectory\fR +.ZP +The specified \fIdirectory\fR becomes the current directory. +If no directory is specified, the current value of the +.I home +option is used as the target directory. +After a +.I chdir +the current file is not considered to have been +edited so that write restrictions on pre-existing files apply. +.. +.LC +( \fB.\fP , \fB.\fP )\|\fBcopy\fP \fIaddr\fP \fIflags\fP abbr: \fBco\fP +.ZP +A +.I copy +of the specified lines is placed after +.I addr, +which may be `0'. +The current line +`\fB.\fR' +addresses the last line of the copy. +The command +.I t +is a synonym for +.I copy. +.LC +( \fB.\fR , \fB.\fR )\|\fBdelete\fR \fIbuffer\fR \fIcount\fR \fIflags\fR abbr: \fBd\fR +.ZP +Removes the specified lines from the buffer. +The line after the last line deleted becomes the current line; +if the lines deleted were originally at the end, +the new last line becomes the current line. +If a named +.I buffer +is specified by giving a letter, +then the specified lines are saved in that buffer, +or appended to it if an upper case letter is used. +.LC +\fBedit\fR \fIfile\fR abbr: \fBe\fR +.br +\fBex\fR \fIfile\fR +.ZP +Used to begin an editing session on a new file. +The editor +first checks to see if the buffer has been modified since the last +.I write +command was issued. +If it has been, +a warning is issued and the +command is aborted. +The +command otherwise deletes the entire contents of the editor buffer, +makes the named file the current file and prints the new filename. +After insuring that this file is sensible\(dg +.FS +\(dg I.e., that it is not a binary file such as a directory, +a block or character special file other than +.I /dev/tty, +a terminal, +or a binary or executable file +(as indicated by the first word). +.FE +the editor reads the file into its buffer. +.IP +If the read of the file completes without error, +the number of lines and characters read is typed. +If there were any non-\s-2ASCII\s0 characters +in the file they are stripped of their non-\s-2ASCII\s0 +high bits, +and any null characters in the file are discarded. +If none of these errors occurred, the file is considered +.I edited. +If the last line of the input file is missing the trailing +newline character, it will be supplied and a complaint will be issued. +This command leaves the current line `\fB.\fR' at the last line read.\(dd +.FS +\(dd If executed from within +.I open +or +.I visual, +the current line is initially the first line of the file. +.FE +.LC +\fBe!\fR \fIfile\fR +.ZP +The variant form suppresses the complaint about modifications having +been made and not written from the editor buffer, thus +discarding all changes which have been made before editing the new file. +.LC +\fBe\fR \fB+\fIn\fR \fIfile\fR +.ZP +Causes the editor to begin at line +.I n +rather than at the last line; +\fIn\fR may also be an editor command containing no spaces, e.g.: ``+/pat''. +.LC +\fBfile\fR abbr: \fBf\fR +.ZP +Prints the current file name, +whether it has been `[Modified]' since the last +.I write +command, +whether it is +.I "read only" , +the current line, +the number of lines in the buffer, +and the percentage of the way through the buffer of the current line.* +.FS +* In the rare case that the current file is `[Not edited]' this is +noted also; in this case you have to use the form \fBw!\fR to write to +the file, since the editor is not sure that a \fBwrite\fR will not +destroy a file unrelated to the current contents of the buffer. +.FE +.LC +\fBfile\fR \fIfile\fR +.ZP +The current file name is changed to +.I file +which is considered +`[Not edited]'. +.LC +( 1 , $ ) \fBglobal\fR /\fIpat\|\fR/ \fIcmds\fR abbr: \fBg\fR +.ZP +First marks each line among those specified which matches +the given regular expression. +Then the given command list is executed with `\fB.\fR' initially +set to each marked line. +.IP +The command list consists of the remaining commands on the current +input line and may continue to multiple lines by ending all but the +last such line with a `\e'. +If +.I cmds +(and possibly the trailing \fB/\fR delimiter) is omitted, each line matching +.I pat +is printed. +.I Append, +.I insert, +and +.I change +commands and associated input are permitted; +the `\fB.\fR' terminating input may be omitted if it would be on the +last line of the command list. +.I Open +and +.I visual +commands are permitted in the command list and take input from the terminal. +.IP +The +.I global +command itself may not appear in +.I cmds. +The +.I undo +command is also not permitted there, +as +.I undo +instead can be used to reverse the entire +.I global +command. +The options +.I autoprint +and +.I autoindent +are inhibited during a +.I global, +(and possibly the trailing \fB/\fR delimiter) and the value of the +.I report +option is temporarily infinite, +in deference to a \fIreport\fR for the entire global. +Finally, the context mark `\'\'' is set to the value of +`.' before the global command begins and is not changed during a global +command, +except perhaps by an +.I open +or +.I visual +within the +.I global. +.LC +\fBg!\fR \fB/\fIpat\fB/\fR \fIcmds\fR abbr: \fBv\fR +.IP +The variant form of \fIglobal\fR runs \fIcmds\fR at each line not matching +\fIpat\fR. +.LC +( \fB.\fR )\|\fBinsert\fR abbr: \fBi\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +Places the given text before the specified line. +The current line is left at the last line input; +if there were none input it is left at the line before the addressed line. +This command differs from +.I append +only in the placement of text. +.KS +.LC +\fBi!\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +The variant toggles +.I autoindent +during the +.I insert. +.KE +.LC +( \fB.\fR , \fB.\fR+1 ) \fBjoin\fR \fIcount\fR \fIflags\fR abbr: \fBj\fR +.ZP +Places the text from a specified range of lines +together on one line. +White space is adjusted at each junction to provide at least +one blank character, two if there was a `\fB.\fR' at the end of the line, +or none if the first following character is a `)'. +If there is already white space at the end of the line, +then the white space at the start of the next line will be discarded. +.LC +\fBj!\fR +.ZP +The variant causes a simpler +.I join +with no white space processing; the characters in the lines are simply +concatenated. +.LC +( \fB.\fR ) \fBk\fR \fIx\fR +.ZP +The +.I k +command is a synonym for +.I mark. +It does not require a blank or tab before the following letter. +.LC +( \fB.\fR , \fB.\fR ) \fBlist\fR \fIcount\fR \fIflags\fR +.ZP +Prints the specified lines in a more unambiguous way: +tabs are printed as `^I' +and the end of each line is marked with a trailing `$'. +The current line is left at the last line printed. +.LC +\fBmap\fR \fIlhs\fR \fIrhs\fR +.ZP +The +.I map +command is used to define macros for use in +.I visual +mode. +.I Lhs +should be a single character, or the sequence ``#n'', for n a digit, +referring to function key \fIn\fR. When this character or function key +is typed in +.I visual +mode, it will be as though the corresponding \fIrhs\fR had been typed. +On terminals without function keys, you can type ``#n''. +See section 6.9 of the ``Introduction to Display Editing with Vi'' +for more details. +.LC +( \fB.\fR ) \fBmark\fR \fIx\fR +.ZP +Gives the specified line mark +.I x, +a single lower case letter. +The +.I x +must be preceded by a blank or a tab. +The addressing form `\'x' then addresses this line. +The current line is not affected by this command. +.LC +( \fB.\fR , \fB.\fR ) \fBmove\fR \fIaddr\fR abbr: \fBm\fR +.ZP +The +.I move +command repositions the specified lines to be after +.I addr . +The first of the moved lines becomes the current line. +.LC +\fBnext\fR abbr: \fBn\fR +.ZP +The next file from the command line argument list is edited. +.LC +\fBn!\fR +.ZP +The variant suppresses warnings about the modifications to the buffer not +having been written out, discarding (irretrievably) any changes which may +have been made. +.LC +\fBn\fR \fIfilelist\fR +.br +\fBn\fR \fB+\fIcommand\fR \fIfilelist\fR +.ZP +The specified +.I filelist +is expanded and the resulting list replaces the +current argument list; +the first file in the new list is then edited. +If +.I command +is given (it must contain no spaces), then it is executed after editing the first such file. +.LC +( \fB.\fR , \fB.\fR ) \fBnumber\fR \fIcount\fR \fIflags\fR abbr: \fB#\fR or \fBnu\fR +.ZP +Prints each specified line preceded by its buffer line +number. +The current line is left at the last line printed. +.KS +.LC +( \fB.\fR ) \fBopen\fR \fIflags\fR abbr: \fBo\fR +.br +( \fB.\fR ) \fBopen\fR /\fIpat\|\fR/ \fIflags\fR +.ZP +Enters intraline editing \fIopen\fR mode at each addressed line. +If +.I pat +is given, +then the cursor will be placed initially at the beginning of the +string matched by the pattern. +To exit this mode use Q. +See +.I "An Introduction to Display Editing with Vi" +for more details. +.KE +.LC +\fBpreserve\fR +.ZP +The current editor buffer is saved as though the system had just crashed. +This command is for use only in emergencies when a +.I write +command has resulted in an error and you don't know how to save your work. +After a +.I preserve +you should seek help. +.LC +( \fB.\fR , \fB.\fR )\|\fBprint\fR \fIcount\fR abbr: \fBp\fR or \fBP\fR +.ZP +Prints the specified lines +with non-printing characters printed as control characters `^\fIx\fR\|'; +delete (octal 177) is represented as `^?'. +The current line is left at the last line printed. +.LC +( \fB.\fR )\|\fBput\fR \fIbuffer\fR abbr: \fBpu\fR +.ZP +Puts back +previously +.I deleted +or +.I yanked +lines. +Normally used with +.I delete +to effect movement of lines, +or with +.I yank +to effect duplication of lines. +If no +.I buffer +is specified, then the last +.I deleted +or +.I yanked +text is restored.* +.FS +* But no modifying commands may intervene between the +.I delete +or +.I yank +and the +.I put, +nor may lines be moved between files without using a named buffer. +.FE +By using a named buffer, text may be restored that was saved there at any +previous time. +.LC +\fBquit\fR abbr: \fBq\fR +.ZP +Causes +.I ex +to terminate. +No automatic write of the editor buffer to a file is performed. +However, +.I ex +issues a warning message if the file has changed +since the last +.I write +command was issued, and does not +.I quit.\(dg +.FS +\(dg \fIEx\fR +will also issue a diagnostic if there are more files in the argument +list. +.FE +Normally, you will wish to save your changes, and you +should give a \fIwrite\fR command; +if you wish to discard them, use the \fBq!\fR command variant. +.LC +\fBq!\fR +.ZP +Quits from the editor, discarding changes to the buffer without complaint. +.LC +( \fB.\fR ) \fBread\fR \fIfile\fR abbr: \fBr\fR +.ZP +Places a copy of the text of the given file in the +editing buffer after the specified line. +If no +.I file +is given the current file name is used. +The current file name is not changed unless there is none in which +case +.I file +becomes the current name. +The sensibility restrictions for the +.I edit +command apply here also. +If the file buffer is empty and there is no current name then +.I ex +treats this as an +.I edit +command. +.IP +Address `0' is legal for this command and causes the file to be read at +the beginning of the buffer. +Statistics are given as for the +.I edit +command when the +.I read +successfully terminates. +After a +.I read +the current line is the last line read.\(dd +.FS +\(dd Within +.I open +and +.I visual +the current line is set to the first line read rather than the last. +.FE +.LC +( \fB.\fR ) \fBread\fR \fB!\fR\fIcommand\fR +.ZP +Reads the output of the command +.I command +into the buffer after the specified line. +This is not a variant form of the command, rather a read +specifying a +.I command +rather than a +.I filename; +a blank or tab before the \fB!\fR is mandatory. +.LC +\fBrecover \fIfile\fR +.ZP +Recovers +.I file +from the system save area. +Used after a accidental hangup of the phone** +.FS +** The system saves a copy of the file you were editing only if you +have made changes to the file. +.FE +or a system crash** or +.I preserve +command. +Except when you use +.I preserve +you will be notified by mail when a file is saved. +.LC +\fBrewind\fR abbr: \fBrew\fR +.ZP +The argument list is rewound, and the first file in the list is edited. +.LC +\fBrew!\fR +.ZP +Rewinds the argument list discarding any changes made to the current buffer. +.LC +\fBset\fR \fIparameter\fR +.ZP +With no arguments, prints those options whose values have been +changed from their defaults; +with parameter +.I all +it prints all of the option values. +.IP +Giving an option name followed by a `?' +causes the current value of that option to be printed. +The `?' is unnecessary unless the option is Boolean valued. +Boolean options are given values either by the form +`set \fIoption\fR' to turn them on or +`set no\fIoption\fR' to turn them off; +string and numeric options are assigned via the form +`set \fIoption\fR=value'. +.IP +More than one parameter may be given to +.I set \|; +they are interpreted left-to-right. +.LC +\fBshell\fR abbr: \fBsh\fR +.IP +A new shell is created. +When it terminates, editing resumes. +.LC +\fBsource\fR \fIfile\fR abbr: \fBso\fR +.IP +Reads and executes commands from the specified file. +.I Source +commands may be nested. +.LC +( \fB.\fR , \fB.\fR ) \fBsubstitute\fR /\fIpat\fR\|/\fIrepl\fR\|/ \fIoptions\fR \fIcount\fR \fIflags\fR abbr: \fBs\fR +.IP +On each specified line, the first instance of pattern +.I pat +is replaced by replacement pattern +.I repl. +If the +.I global +indicator option character `g' +appears, then all instances are substituted; +if the +.I confirm +indication character `c' appears, +then before each substitution the line to be substituted +is typed with the string to be substituted marked +with `\(ua' characters. +By typing an `y' one can cause the substitution to be performed, +any other input causes no change to take place. +After a +.I substitute +the current line is the last line substituted. +.IP +Lines may be split by substituting +new-line characters into them. +The newline in +.I repl +must be escaped by preceding it with a `\e'. +Other metacharacters available in +.I pat +and +.I repl +are described below. +.LC +.B stop +.ZP +Suspends the editor, returning control to the top level shell. +If +.I autowrite +is set and there are unsaved changes, +a write is done first unless the form +.B stop ! +is used. +This commands is only available where supported by the teletype driver +and operating system. +.LC +( \fB.\fR , \fB.\fR ) \fBsubstitute\fR \fIoptions\fR \fIcount\fR \fIflags\fR abbr: \fBs\fR +.ZP +If +.I pat +and +.I repl +are omitted, then the last substitution is repeated. +This is a synonym for the +.B & +command. +.LC +( \fB.\fR , \fB.\fR ) \fBt\fR \fIaddr\fR \fIflags\fR +.ZP +The +.I t +command is a synonym for +.I copy . +.LC +\fBta\fR \fItag\fR +.ZP +The focus of editing switches to the location of +.I tag, +switching to a different line in the current file where it is defined, +or if necessary to another file.\(dd +.FS +\(dd If you have modified the current file before giving a +.I tag +command, you must write it out; giving another +.I tag +command, specifying no +.I tag +will reuse the previous tag. +.FE +.IP +The tags file is normally created by a program such as +.I ctags, +and consists of a number of lines with three fields separated by blanks +or tabs. The first field gives the name of the tag, +the second the name of the file where the tag resides, and the third +gives an addressing form which can be used by the editor to find the tag; +this field is usually a contextual scan using `/\fIpat\fR/' to be immune +to minor changes in the file. Such scans are always performed as if +.I nomagic +was set. +.PP +The tag names in the tags file must be sorted alphabetically. +.LC +\fBunabbreviate\fR \fIword\fP abbr: \fBuna\fP +.ZP +Delete +.I word +from the list of abbreviations. +.LC +\fBundo\fR abbr: \fBu\fR +.ZP +Reverses the changes made in the buffer by the last +buffer editing command. +Note that +.I global +commands are considered a single command for the purpose of +.I undo +(as are +.I open +and +.I visual.) +Also, the commands +.I write +and +.I edit +which interact with the +file system cannot be undone. +.I Undo +is its own inverse. +.IP +.I Undo +always marks the previous value of the current line `\fB.\fR' +as `\'\''. +After an +.I undo +the current line is the first line restored +or the line before the first line deleted if no lines were restored. +For commands with more global effect +such as +.I global +and +.I visual +the current line regains it's pre-command value after an +.I undo. +.LC +\fBunmap\fR \fIlhs\fR +.ZP +The macro expansion associated by +.I map +for +.I lhs +is removed. +.LC +( 1 , $ ) \fBv\fR /\fIpat\fR\|/ \fIcmds\fR +.ZP +A synonym for the +.I global +command variant \fBg!\fR, running the specified \fIcmds\fR on each +line which does not match \fIpat\fR. +.LC +\fBversion\fR abbr: \fBve\fR +.ZP +Prints the current version number of the editor +as well as the date the editor was last changed. +.LC +( \fB.\fR ) \fBvisual\fR \fItype\fR \fIcount\fR \fIflags\fR abbr: \fBvi\fR +.ZP +Enters visual mode at the specified line. +.I Type +is optional and may be `\-' , `\(ua' or `\fB.\fR' +as in the +.I z +command to specify the placement of the specified line on the screen. +By default, if +.I type +is omitted, the specified line is placed as the first on the screen. +A +.I count +specifies an initial window size; the default is the value of the option +.I window. +See the document +.I "An Introduction to Display Editing with Vi" +for more details. +To exit this mode, type Q. +.LC +\fBvisual\fP file +.br +\fBvisual\fP +\fIn\fP file +.ZP +From visual mode, +this command is the same as edit. +.LC +( 1 , $ ) \fBwrite\fR \fIfile\fR abbr: \fBw\fR +.ZP +Writes changes made back to \fIfile\fR, printing the number of lines and +characters written. +Normally \fIfile\fR is omitted and the text goes back where it came from. +If a \fIfile\fR is specified, then text will be written to that file.* +.FS +* The editor writes to a file only if it is +the current file and is +.I edited , +if the file does not exist, +or if the file is actually a teletype, +.I /dev/tty, +.I /dev/null. +Otherwise, you must give the variant form \fBw!\fR to force the write. +.FE +If the file does not exist it is created. +The current file name is changed only if there is no current file +name; the current line is never changed. +.IP +If an error occurs while writing the current and +.I edited +file, the editor +considers that there has been ``No write since last change'' +even if the buffer had not previously been modified. +.LC +( 1 , $ ) \fBwrite>>\fR \fIfile\fR abbr: \fBw>>\fR +.ZP +Writes the buffer contents at the end of +an existing file. +.IP +.LC +\fBw!\fR \fIname\fR +.ZP +Overrides the checking of the normal \fIwrite\fR command, +and will write to any file which the system permits. +.LC +( 1 , $ ) \fBw\fR \fB!\fR\fIcommand\fR +.ZP +Writes the specified lines into +.I command. +Note the difference between \fBw!\fR which overrides checks and +\fBw\ \ !\fR which writes to a command. +.LC +\fBwq\fR \fIname\fR +.ZP +Like a \fIwrite\fR and then a \fIquit\fR command. +.LC +\fBwq!\fR \fIname\fR +.ZP +The variant overrides checking on the sensibility of the +.I write +command, as \fBw!\fR does. +.LC +\fBxit\fP \fIname\fR +.ZP +If any changes have been made and not written, writes the buffer out. +Then, in any case, quits. +.LC +( \fB.\fR , \fB.\fR )\|\fByank\fR \fIbuffer\fR \fIcount\fR abbr: \fBya\fR +.ZP +Places the specified lines in the named +.I buffer, +for later retrieval via +.I put. +If no buffer name is specified, the lines go to a more volatile place; +see the \fIput\fR command description. +.LC +( \fB.+1\fR ) \fBz\fR \fIcount\fR +.ZP +Print the next \fIcount\fR lines, default \fIwindow\fR. +.LC +( \fB.\fR ) \fBz\fR \fItype\fR \fIcount\fR +.ZP +Prints a window of text with the specified line at the top. +If \fItype\fR is `\-' the line is placed at the bottom; a `\fB.\fR' causes +the line to be placed in the center.* +A count gives the number of lines to be displayed rather than +double the number specified by the \fIscroll\fR option. +On a \s-2CRT\s0 the screen is cleared before display begins unless a +count which is less than the screen size is given. +The current line is left at the last line printed. +.FS +* Forms `z=' and `z\(ua' also exist; `z=' places the current line in the +center, surrounds it with lines of `\-' characters and leaves the current +line at this line. The form `z\(ua' prints the window before `z\-' +would. The characters `+', `\(ua' and `\-' may be repeated for cumulative +effect. +On some v2 editors, no +.I type +may be given. +.FE +.LC +\fB!\fR \fIcommand\fR\fR +.ZP +The remainder of the line after the `!' character is sent to a shell +to be executed. +Within the text of +.I command +the characters +`%' and `#' are expanded as in filenames and the character +`!' is replaced with the text of the previous command. +Thus, in particular, +`!!' repeats the last such shell escape. +If any such expansion is performed, the expanded line will be echoed. +The current line is unchanged by this command. +.IP +If there has been ``[No\ write]'' of the buffer contents since the last +change to the editing buffer, then a diagnostic will be printed +before the command is executed as a warning. +A single `!' is printed when the command completes. +.LC +( \fIaddr\fR , \fIaddr\fR ) \fB!\fR \fIcommand\fR\fR +.ZP +Takes the specified address range and supplies it as +standard input to +.I command; +the resulting output then replaces the input lines. +.LC +( $ ) \fB=\fR +.ZP +Prints the line number of the +addressed line. +The current line is unchanged. +.KS +.LC +( \fB.\fR , \fB.\fR ) \fB>\fR \fIcount\fR \fIflags\fR +.br +( \fB.\fR , \fB.\fR ) \fB<\fR \fIcount\fR \fIflags\fR +.IP +Perform intelligent shifting on the specified lines; +\fB<\fR shifts left and \fB>\fR shift right. +The quantity of shift is determined by the +.I shiftwidth +option and the repetition of the specification character. +Only white space (blanks and tabs) is shifted; +no non-white characters are discarded in a left-shift. +The current line becomes the last line which changed due to the +shifting. +.KE +.LC +\fB^D\fR +.ZP +An end-of-file from a terminal input scrolls through the file. +The +.I scroll +option specifies the size of the scroll, normally a half screen of text. +.LC +( \fB.\fR+1 , \fB.\fR+1 ) +.br +( \fB.\fR+1 , \fB.\fR+1 ) | +.ZP +An address alone causes the addressed lines to be printed. +A blank line prints the next line in the file. +.LC +( \fB.\fR , \fB.\fR ) \fB&\fR \fIoptions\fR \fIcount\fR \fIflags\fR +.ZP +Repeats the previous +.I substitute +command. +.LC +( \fB.\fR , \fB.\fR ) \fB\s+2~\s0\fR \fIoptions\fR \fIcount\fR \fIflags\fR +.ZP +Replaces the previous regular expression with the previous +replacement pattern from a substitution. +.NH 1 +Regular expressions and substitute replacement patterns +.NH 2 +Regular expressions +.PP +A regular expression specifies a set of strings of characters. +A member of this set of strings is said to be +.I matched +by the regular expression. +.I Ex +remembers two previous regular expressions: +the previous regular expression used in a +.I substitute +command +and the previous regular expression used elsewhere +(referred to as the previous \fIscanning\fR regular expression.) +The previous regular expression +can always be referred to by a null \fIre\fR, e.g. `//' or `??'. +.NH 2 +Magic and nomagic +.PP +The regular expressions allowed by +.I ex +are constructed in one of two ways depending on the setting of +the +.I magic +option. +The +.I ex +and +.I vi +default setting of +.I magic +gives quick access to a powerful set of regular expression +metacharacters. +The disadvantage of +.I magic +is that the user must remember that these metacharacters are +.I magic +and precede them with the character `\e' +to use them as ``ordinary'' characters. +With +.I nomagic, +the default for +.I edit, +regular expressions are much simpler, +there being only two metacharacters. +The power of the other metacharacters is still available by preceding +the (now) ordinary character with a `\e'. +Note that `\e' is thus always a metacharacter. +.PP +The remainder of the discussion of regular expressions assumes +that +that the setting of this option is +.I magic.\(dg +.FS +\(dg To discern what is true with +.I nomagic +it suffices to remember that the only +special characters in this case will be `\(ua' at the beginning +of a regular expression, +`$' at the end of a regular expression, +and `\e'. +With +.I nomagic +the characters `\s+2~\s0' and `&' also lose their special meanings +related to the replacement pattern of a substitute. +.FE +.NH 2 +Basic regular expression summary +.PP +The following basic constructs are used to construct +.I magic +mode regular expressions. +.IP \fIchar\fR 15 +An ordinary character matches itself. +The characters `\(ua' at the beginning of a line, +`$' at the end of line, +`*' as any character other than the first, +`.', `\e', `[', and `\s+2~\s0' are not ordinary characters and +must be escaped (preceded) by `\e' to be treated as such. +.IP \fB\(ua\fR +At the beginning of a pattern +forces the match to succeed only at the beginning of a line. +.IP \fB$\fR +At the end of a regular expression forces the match to +succeed only at the end of the line. +.IP \&\fB.\fR +Matches any single character except +the new-line character. +.IP \fB\e<\fR +Forces the match +to occur only at the beginning of a ``variable'' or ``word''; +that is, either at the beginning of a line, or just before +a letter, digit, or underline and after a character not one of +these. +.IP \fB\e>\fR +Similar to `\e<', but matching the end of a ``variable'' +or ``word'', i.e. either the end of the line or before character +which is neither a letter, nor a digit, nor the underline character. +.IP \fB[\fIstring\fR]\fR +Matches any (single) character in the class defined by +.I string. +Most characters in +.I string +define themselves. +A pair of characters separated by `\-' in +.I string +defines the set of characters collating between the specified lower and upper +bounds, thus `[a\-z]' as a regular expression matches +any (single) lower-case letter. +If the first character of +.I string +is an `\(ua' then the construct +matches those characters which it otherwise would not; +thus `[\(uaa\-z]' matches anything but a lower-case letter (and of course a +newline). +To place any of the characters +`\(ua', `[', or `\-' in +.I string +you must escape them with a preceding `\e'. +.NH 2 +Combining regular expression primitives +.PP +The concatenation of two regular expressions matches the leftmost and +then longest string +which can be divided with the first piece matching the first regular +expression and the second piece matching the second. +Any of the (single character matching) regular expressions mentioned +above may be followed by the character `*' to form a regular expression +which matches any number of adjacent occurrences (including 0) of characters +matched by the regular expression it follows. +.PP +The character `\s+2~\s0' may be used in a regular expression, +and matches the text which defined the replacement part +of the last +.I substitute +command. +A regular expression may be enclosed between the sequences +`\e(' and `\e)' with side effects in the +.I substitute +replacement patterns. +.NH 2 +Substitute replacement patterns +.PP +The basic metacharacters for the replacement pattern are +`&' and `~'; these are +given as `\e&' and `\e~' when +.I nomagic +is set. +Each instance of `&' is replaced by the characters +which the regular expression matched. +The metacharacter `~' stands, in the replacement pattern, +for the defining text of the previous replacement pattern. +.PP +Other metasequences possible in the replacement pattern +are always introduced by the escaping character `\e'. +The sequence `\e\fIn\fR' is replaced by the text matched +by the \fIn\fR-th regular subexpression enclosed between +`\e(' and `\e)'.\(dg +.FS +\(dg When nested, parenthesized subexpressions are present, +\fIn\fR is determined by counting occurrences of `\e(' starting from the left. +.FE +The sequences `\eu' and `\el' cause the immediately following character in +the replacement to be converted to upper- or lower-case respectively +if this character is a letter. +The sequences `\eU' and `\eL' turn such conversion on, either until +`\eE' or `\ee' is encountered, or until the end of the replacement pattern. +.de LC +.br +.sp .1i +.ne 4 +.LP +.ta 3i +.. +.NH 1 +Option descriptions +.PP +.LC +\fBautoindent\fR, \fBai\fR default: noai +.ZP +Can be used to ease the preparation of structured program text. +At the beginning of each +.I append , +.I change +or +.I insert +command +or when a new line is +.I opened +or created by an +.I append , +.I change , +.I insert , +or +.I substitute +operation within +.I open +or +.I visual +mode, +.I ex +looks at the line being appended after, +the first line changed +or the line inserted before and calculates the amount of white space +at the start of the line. +It then aligns the cursor at the level of indentation so determined. +.IP +If the user then types lines of text in, +they will continue to be justified at the displayed indenting level. +If more white space is typed at the beginning of a line, +the following line will start aligned with the first non-white character +of the previous line. +To back the cursor up to the preceding tab stop one can hit +\fB^D\fR. +The tab stops going backwards are defined at multiples of the +.I shiftwidth +option. +You +.I cannot +backspace over the indent, +except by sending an end-of-file with a \fB^D\fR. +.IP +Specially processed in this mode is a line with no characters added +to it, which turns into a completely blank line (the white +space provided for the +.I autoindent +is discarded.) +Also specially processed in this mode are lines beginning with +an `\(ua' and immediately followed by a \fB^D\fR. +This causes the input to be repositioned at the beginning of the line, +but retaining the previous indent for the next line. +Similarly, a `0' followed by a \fB^D\fR +repositions at the beginning but without +retaining the previous indent. +.IP +.I Autoindent +doesn't happen in +.I global +commands or when the input is not a terminal. +.LC +\fBautoprint\fR, \fBap\fR default: ap +.ZP +Causes the current line to be printed after each +.I delete , +.I copy , +.I join , +.I move , +.I substitute , +.I t , +.I undo +or +shift command. +This has the same effect as supplying a trailing `p' +to each such command. +.I Autoprint +is suppressed in globals, +and only applies to the last of many commands on a line. +.LC +\fBautowrite\fR, \fBaw\fR default: noaw +.ZP +Causes the contents of the buffer to be written to the current file +if you have modified it and give a +.I next, +.I rewind, +.I stop, +.I tag, +or +.I ! +command, or a \fB^\(ua\fR (switch files) or \fB^]\fR (tag goto) command +in +.I visual. +Note, that the +.I edit +and +.I ex +commands do +.B not +autowrite. +In each case, there is an equivalent way of switching when autowrite +is set to avoid the +.I autowrite +(\fIedit\fR +for +.I next , +.I rewind! +for .I rewind , +.I stop! +for +.I stop , +.I tag! +for +.I tag , +.I shell +for +.I ! , +and +\fB:e\ #\fR and a \fB:ta!\fR command from within +.I visual). +.LC +\fBbeautify\fR, \fBbf\fR default: nobeautify +.ZP +Causes all control characters except tab, newline and form-feed +to be discarded from the input. +A complaint is registered the first time a +backspace character is discarded. +.I Beautify +does not apply to command input. +.LC +\fBdirectory\fR, \fBdir\fR default: dir=/tmp +.ZP +Specifies the directory in which +.I ex +places its buffer file. +If this directory in not +writable, then the editor will exit abruptly when it fails to be +able to create its buffer there. +.LC +\fBedcompatible\fR default: noedcompatible +.ZP +Causes the presence of absence of +.B g +and +.B c +suffixes on substitute commands to be remembered, and to be toggled +by repeating the suffices. The suffix +.B r +makes the substitution be as in the +.I ~ +command, instead of like +.I &. +.LC +\fBerrorbells\fR, \fBeb\fR default: noeb +.ZP +Error messages are preceded by a bell.* +.FS +* Bell ringing in +.I open +and +.I visual +on errors is not suppressed by setting +.I noeb. +.FE +If possible the editor always places the error message in a standout mode of the +terminal (such as inverse video) instead of ringing the bell. +.LC +\fBhardtabs\fR, \fBht\fR default: ht=8 +.ZP +Gives the boundaries on which terminal hardware tabs are set (or +on which the system expands tabs). +.LC +\fBignorecase\fR, \fBic\fR default: noic +.ZP +All upper case characters in the text are mapped to lower case in regular +expression matching. +In addition, all upper case characters in regular expressions are mapped +to lower case except in character class specifications. +.LC +\fBlisp\fR default: nolisp +.ZP +\fIAutoindent\fR indents appropriately for +.I lisp +code, and the \fB( ) { } [[\fR and \fB]]\fR commands in +.I open +and +.I visual +are modified to have meaning for \fIlisp\fR. +.LC +\fBlist\fR default: nolist +.ZP +All printed lines will be displayed (more) unambiguously, +showing tabs and end-of-lines as in the +.I list +command. +.LC +\fBmagic\fR default: magic for \fIex\fR and \fIvi\fR\(dg +.FS +\(dg \fINomagic\fR for \fIedit\fR. +.FE +.ZP +If +.I nomagic +is set, the number of regular expression metacharacters is greatly reduced, +with only `\(ua' and `$' having special effects. +In addition the metacharacters +`~' +and +`&' +of the replacement pattern are treated as normal characters. +All the normal metacharacters may be made +.I magic +when +.I nomagic +is set by preceding them with a `\e'. +.LC +\fBmesg\fR default: mesg +.ZP +Causes write permission to be turned off to the terminal +while you are in visual mode, if +.I nomesg +is set. +.LC +\fBmodeline\fR default: nomodeline +.ZP +If +.I modeline +is set, then the first 5 lines and the last five lines of the file +will be checked for ex command lines and the comands issued. +To be recognized as a command line, the line must have the string +.B ex: +or +.B vi: +preceeded by a tab or a space. This string may be anywhere in the +line and anything after the +.I : +is interpeted as editor commands. This option defaults to off because +of unexpected behavior when editting files such as +.I /etc/passwd. +.LC +\fBnumber, nu\fR default: nonumber +.ZP +Causes all output lines to be printed with their +line numbers. +In addition each input line will be prompted for by supplying the line number +it will have. +.LC +\fBopen\fR default: open +.ZP +If \fInoopen\fR, the commands +.I open +and +.I visual +are not permitted. +This is set for +.I edit +to prevent confusion resulting from accidental entry to +open or visual mode. +.LC +\fBoptimize, opt\fR default: optimize +.ZP +Throughput of text is expedited by setting the terminal +to not do automatic carriage returns +when printing more than one (logical) line of output, +greatly speeding output on terminals without addressable +cursors when text with leading white space is printed. +.LC +\fBparagraphs,\ para\fR default: para=IPLPPPQPP\0LIbp +.ZP +Specifies the paragraphs for the \fB{\fR and \fB}\fR operations in +.I open +and +.I visual. +The pairs of characters in the option's value are the names +of the macros which start paragraphs. +.LC +\fBprompt\fR default: prompt +.ZP +Command mode input is prompted for with a `:'. +.LC +\fBredraw\fR default: noredraw +.ZP +The editor simulates (using great amounts of output), an intelligent +terminal on a dumb terminal (e.g. during insertions in +.I visual +the characters to the right of the cursor position are refreshed +as each input character is typed.) +Useful only at very high speed. +.LC +\fBremap\fP default: remap +.ZP +If on, macros are repeatedly tried until they are unchanged. +For example, if +.B o +is mapped to +.B O , +and +.B O +is mapped to +.B I , +then if +.I remap +is set, +.B o +will map to +.B I , +but if +.I noremap +is set, it will map to +.B O . +.LC +\fBreport\fR default: report=5\(dg +.FS +\(dg 2 for \fIedit\fR. +.FE +.ZP +Specifies a threshold for feedback from commands. +Any command which modifies more than the specified number of lines +will provide feedback as to the scope of its changes. +For commands such as +.I global , +.I open , +.I undo , +and +.I visual +which have potentially more far reaching scope, +the net change in the number of lines in the buffer is +presented at the end of the command, subject to this same threshold. +Thus notification is suppressed during a +.I global +command on the individual commands performed. +.LC +\fBscroll\fR default: scroll=\(12 window +.ZP +Determines the number of logical lines scrolled when an end-of-file +is received from a terminal input in command mode, +and the number of lines printed by a command mode +.I z +command (double the value of +.I scroll ). +.LC +\fBsections\fR default: sections=SHNHH\0HU +.ZP +Specifies the section macros for the \fB[[\fR and \fB]]\fR operations +in +.I open +and +.I visual. +The pairs of characters in the options's value are the names +of the macros which start paragraphs. +.LC +\fBshell\fR, \fBsh\fR default: sh=/bin/sh +.ZP +Gives the path name of the shell forked for +the shell escape command `!', and by the +.I shell +command. +The default is taken from SHELL in the environment, if present. +.LC +\fBshiftwidth\fR, \fBsw\fR default: sw=8 +.ZP +Gives the width a software tab stop, +used in reverse tabbing with \fB^D\fR when using +.I autoindent +to append text, +and by the shift commands. +.LC +\fBshowmatch, sm\fR default: nosm +.ZP +In +.I open +and +.I visual +mode, when a \fB)\fR or \fB}\fR is typed, move the cursor to the matching +\fB(\fR or \fB{\fR for one second if this matching character is on the +screen. Extremely useful with +.I lisp. +.LC +\fBslowopen, slow\fR terminal dependent +.ZP +Affects the display algorithm used in +.I visual +mode, holding off display updating during input of new text to improve +throughput when the terminal in use is both slow and unintelligent. +See +.I "An Introduction to Display Editing with Vi" +for more details. +.LC +\fBtabstop,\ ts\fR default: ts=8 +.ZP +The editor expands tabs in the input file to be on +.I tabstop +boundaries for the purposes of display. +.LC +\fBtaglength,\ tl\fR default: tl=0 +.ZP +Tags are not significant beyond this many characters. +A value of zero (the default) means that all characters are significant. +.LC +\fBtags\fR default: tags=tags /usr/lib/tags +.ZP +A path of files to be used as tag files for the +.I tag +command. +A requested tag is searched for in the specified files, sequentially. +By default, files called +.B tags +are searched for in the current directory and in /usr/lib +(a master file for the entire system). +.LC +\fBterm\fR from environment TERM +.ZP +The terminal type of the output device. +.LC +\fBterse\fR default: noterse +.ZP +Shorter error diagnostics are produced for the experienced user. +.LC +\fBwarn\fR default: warn +.ZP +Warn if there has been `[No write since last change]' before a `!' +command escape. +.LC +\fBwindow\fR default: window=speed dependent +.ZP +The number of lines in a text window in the +.I visual +command. +The default is 8 at slow speeds (600 baud or less), +16 at medium speed (1200 baud), +and the full screen (minus one line) at higher speeds. +.LC +\fBw300,\ w1200\, w9600\fR +.ZP +These are not true options but set +.B window +only if the speed is slow (300), medium (1200), or high (9600), +respectively. +They are suitable for an EXINIT +and make it easy to change the 8/16/full screen rule. +.LC +\fBwrapscan\fR, \fBws\fR default: ws +.ZP +Searches using the regular expressions in addressing +will wrap around past the end of the file. +.LC +\fBwrapmargin\fR, \fBwm\fR default: wm=0 +.ZP +Defines a margin for automatic wrapover of text during input in +.I open +and +.I visual +modes. See +.I "An Introduction to Text Editing with Vi" +for details. +.LC +\fBwriteany\fR, \fBwa\fR default: nowa +.IP +Inhibit the checks normally made before +.I write +commands, allowing a write to any file which the system protection +mechanism will allow. +.NH 1 +Acknowledgements +.PP +Chuck Haley contributed greatly to the early development of +.I ex. +Bruce Englar encouraged the redesign which led to +.I ex +version 1. +Bill Joy wrote versions 1 and 2.0 through 2.7, +and created the framework that users see in the present editor. +Mark Horton added macros and other features and made the +editor work on a large number of terminals and Unix systems. diff --git a/share/doc/usd/10.exref/summary/Makefile b/share/doc/usd/10.exref/summary/Makefile new file mode 100644 index 000000000000..fe2d338a961e --- /dev/null +++ b/share/doc/usd/10.exref/summary/Makefile @@ -0,0 +1,5 @@ +DOC= summary +SRCS= ex.summary +USE_TBL= + +.include <bsd.doc.mk> diff --git a/share/doc/usd/10.exref/summary/ex.summary b/share/doc/usd/10.exref/summary/ex.summary new file mode 100644 index 000000000000..4657b77fd895 --- /dev/null +++ b/share/doc/usd/10.exref/summary/ex.summary @@ -0,0 +1,728 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.ds p \v'-0.2'.\v'+0.2' +.ds U \s-2UNIX\s+2 +.ds c \v'-0.2':\v'+0.2' +.nr LL 6.5i +.lt 6.5i +.ll 6.5i +.ds CH +.ds LF Computing Services, U.C. Berkeley +.ds RF April 3, 1979 +.de SP +.sp 1v +.. +.nr PI 3n +.nr PD 0 +.ND +.ps 12 +.ft B +.ce 1 +Ex/Edit Command Summary (Version 2.0) +.sp 1 +.ft R +.nr VS 11 +.nr PS 9 +.2C +.PP +.I Ex +and +.I edit +are text editors, used for creating +and modifying files of text on the \*U +computer system. +.I Edit +is a variant of +.I ex +with features designed to +make it less complicated +to learn and use. +In terms of command syntax and effect +the editors are essentially identical, +and this command summary applies to both. +.PP +The summary is meant as a quick reference +for users already acquainted +with +.I edit +or \fIex\fP. +Fuller explanations of the editors are available +in the documents +.I +Edit: A Tutorial +.R +(a self-teaching introduction) and the +.I +Ex Reference Manual +.R +(the comprehensive reference source for +both \fIedit\fP and \fIex\fP). +Both of these writeups are available in the +Computing Services Library. +.PP +In the examples included with the +summary, commands and text entered by +the user are printed in \fBboldface\fR to +distinguish them from responses printed +by the computer. +.sp 0.45v +.LP +.B +The Editor Buffer +.PP +In order to perform its tasks +the editor sets aside a temporary +work space, +called a \fIbuffer\fR, +separate from the user's permanent +file. +Before starting to work on an existing +file the editor makes a copy of it in the +buffer, leaving the original untouched. +All editing changes are made to the +buffer copy, which must then +be written back to the permanent +file in order to update the +old version. +The buffer disappears +at the end of the editing session. +.sp 0.45v +.LP +.B +Editing: Command and Text Input Modes +.PP +.R +During an editing session there are +two usual modes of operation: +\fIcommand\fP mode and \fItext input\fP +mode. +(This disregards, for the moment, +.I open +and +.I visual +modes, discussed below.) +In command mode, the editor issues a +colon prompt (:) +to show that it is ready to +accept and execute a command. +In text input mode, on the other hand, there is +no prompt and the editor merely accepts text to +be added to the buffer. +Text input mode is initiated by the commands +\fIappend\fP, \fIinsert\fP, and \fIchange\fP, +and is terminated by typing a period as the +first and only character on a line. +.sp 0.45v +.LP +.B +Line Numbers and Command Syntax +.PP +.R +The editor keeps track of lines of text +in the buffer by numbering them consecutively +starting with 1 and renumbering +as lines are added or deleted. +At any given time the editor is positioned +at one of these lines; this position is +called the \fIcurrent line\fP. +Generally, commands that change the +contents of the buffer print the +new current line at the end of their +execution. +.PP +Most commands can be preceded by one or two +line-number addresses which indicate the lines +to be affected. +If one number is given the command operates on +that line only; if two, on an inclusive range +of lines. +Commands that can take line-number prefixes also +assume default prefixes if none are given. +The default assumed by each command is designed +to make it convenient to use in many instances +without any line-number prefix. +For the most part, a command used without a +prefix operates on the current line, +though exceptions to this rule should be noted. +The \fIprint\fP command +by itself, for instance, causes +one line, the current line, to be +printed at the terminal. +.PP +The summary shows the number of line addresses +that can be +prefixed to each command as well as +the defaults assumed if they are omitted. +For example, +.I (.,.) +means that up to 2 line-numbers may be given, +and that if none is given the +command operates on the current line. +(In the address prefix notation, ``.'' stands +for the current line and ``$'' stands for +the last line of the buffer.) +If no such notation appears, no +line-number prefix may be used. +.PP +Some commands take trailing +information; +only +the more important instances of this +are mentioned in the summary. +.sp 0.25v +.LP +.B +Open and Visual Modes +.PP +.R +Besides command and text input modes, +.I ex +and +.I edit +provide on some CRT terminals other modes of editing, +.I open +and +.I visual . +In these modes the cursor can +be moved to individual words +or characters in a line. +The commands then given are very different +from the standard editor commands; most do not appear on the screen when +typed. +.I +An Introduction to Display Editing with Vi +.R +provides a full discussion. +.sp 0.25v +.LP +.B +Special Characters +.PP +.R +.fi +Some characters take on special meanings +when used in context searches +and in patterns given to the \fIsubstitute\fP command. +For \fIedit\fR, these are ``^'' and ``$'', +meaning the beginning and end of a line, +respectively. +.I Ex +has the following additional special characters: +.B +.ce 1 +\&. & * [ ] ~ +.R +To use one of the special characters as its +simple graphic representation +rather than with its special meaning, +precede it by a backslash (\\). +The backslash always has a special meaning. +.1C +.TS +cp10 cp10 cp10 cp10 +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +Name Abbr Description Examples +.sp 1.75 +(.)\fBappend a T{ +Begins text input mode, +adding lines to the buffer after +the line specified. Appending continues +until ``.'' is typed alone at the +beginning of a new line, followed by +a carriage return. \fI0a\fR places +lines at the beginning of the buffer. +T} T{ +.nf +\fR:\fBa +Three lines of text +are added to the buffer +after the current line. +\*p +.R +\*c +.fi +T} +.SP +\fR(.,.)\fBchange c T{ +Deletes indicated line(s) and +initiates text input mode to +replace them with new text which follows. +New text is terminated the same way +as with \fIappend\fR. +T} T{ +.nf +:\fB5,6c +Lines 5 and 6 are +deleted and replaced by +these three lines. +\*p +.R +\*c +.fi +T} +.SP +\fR(.,.)\fBcopy \fIaddr co T{ +Places a copy of the specified lines +after the line indicated by \fIaddr\fR. +The example places a copy of lines 8 through +12, inclusive, after line 25. +T} T{ +.nf +\fR:\fB8,12co 25 +\fRLast line copied is printed +\fR\*c +.fi +T} +.SP +\fR(.,.)\fBdelete d T{ +Removes lines from the buffer +and prints the current line after the deletion. +T} T{ +.nf +\fR:\fB13,15d +\fRNew current line is printed +\*c +.fi +T} +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +T{ +\fBedit \fIfile\fP +.br +\fBedit! \fIfile\fP +T} T{ +e +.br +e! +T} T{ +.fi +\fRClears the editor buffer and then +copies into it the named \fIfile\fR, +which becomes the current file. +This is a way of shifting to a different +file +without leaving the editor. +The editor issues a warning +message if this command is used before +saving changes +made to the file already in the buffer; +using the form \fBe!\fR overrides this protective mechanism. +T} T{ +.nf +\fR:\fBe ch10\fR +No write since last change +:\fBe! ch10\fR +"ch10" 3 lines, 62 characters +\*c +.fi +T} +.SP +\fBfile \fIname\fR f T{ +\fRIf followed by a \fIname\fR, renames +the current file to \fIname\fR. +If used without \fIname\fR, prints +the name of the current file. +T} T{ +.nf +\fR:\fBf ch9 +\fR"ch9" [Modified] 3 lines ... +:\fBf +\fR"ch9" [Modified] 3 lines ... +\*c +.fi +T} +.SP +(1,$)\fBglobal g \fBglobal/\fIpattern\fB/\fIcommands T{ +.nf +:\fBg/nonsense/d +\fR\*c +.fi +T} +\fR(1,$)\fBglobal! g!\fR or \fBv T{ +Searches the entire buffer (unless a smaller +range is specified by line-number prefixes) and +executes \fIcommands\fR on every line with +an expression matching \fIpattern\fR. +The second form, abbreviated +either \fBg!\fR or \fBv\fR, +executes \fIcommands\fR on lines that \fIdo +not\fR contain the expression \fIpattern\fR. +T} \^ +.SP +\fR(.)\fBinsert i T{ +Inserts new lines of text immediately before the specified line. +Differs from +.I append +only in that text is placed before, rather than after, the indicated line. +In other words, \fB1i\fR has the same effect as \fB0a\fR. +T} T{ +.nf +:\fB1i +These lines of text will +be added prior to line 1. +\&. +\fR: +.fi +T} +.SP +\fR(.,.+1)\fBjoin j T{ +Join lines together, adjusting white space (spaces +and tabs) as necessary. +T} T{ +.nf +:\fB2,5j\fR +Resulting line is printed +: +.fi +T} +.TE +.bp +.TS +cp10 cp10 cp10 cp10 +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +Name Abbr Description Examples +.sp 1.75 +\fR(.,.)\fBlist l T{ +\fRPrints lines in a more +unambiguous way than the \fIprint\fR +command does. The end of a line, +for example, is marked with a ``$'', +and tabs printed as ``^I''. +T} T{ +.nf +:\fB9l +\fRThis is line 9$ +\*c +.fi +T} +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +\fR(.,.)\fBmove \fIaddr\fB m T{ +\fRMoves the specified lines +to a position after the line +indicated by \fIaddr\fR. +T} T{ +.nf +\fR:\fB12,15m 25\fR +New current line is printed +\*c +.fi +T} +.SP +\fR(.,.)\fBnumber nu T{ +Prints each line preceded +by its buffer line number. +T} T{ +.nf +\fR:\fBnu +\0\0\fR10\0 This is line 10 +\*c +.fi +T} +.SP +\fR(.)\fBopen o T{ +Too involved to discuss here, +but if you enter open mode +accidentally, press +the \s-2ESC\s0 key followed by +\fBq\fR to +get back into normal editor +command mode. +\fIEdit\fP is designed to +prevent accidental use of +the open command. +T} +.SP +\fBpreserve pre T{ +Saves a copy of the current buffer contents as though the system had +just crashed. This is for use in an emergency when a +.I write +command has failed and you don't know how else to save your work.\(dg +T} T{ +.nf +:\fBpreserve\fR +File preserved. +: +.fi +T} +.SP +\fR(.,.)\fBprint p Prints the text of line(s). T{ +.nf +:\fB+2,+3p\fR +The second and third lines +after the current line +: +.fi +T} +.TE +.FS +.ll 6.5i +\(dg You should seek assistance from a system administrator as soon as +possible after saving a file with the +.I preserve +command, because the preserved copy of the file is saved in a +directory used to store temporary files, and thus, the preserved +copy may only be available for a short period of time. +.FE +.SP +.nf +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +T{ +.nf +\fBquit +quit! +.fi +T} T{ +.nf +q +q! +T} T{ +.fi +\fREnds the editing session. +You will receive a +warning if you have changed the buffer +since last writing its contents +to the file. In this event you +must either type \fBw\fR to write, +or type \fBq!\fR to exit from +the editor without saving your changes. +T} T{ +.nf +\fR:\fBq +\fRNo write since last change +:\fBq! +\fR% +.fi +T} +.SP +\fR(.)\fBread \fIfile\fP r T{ +.fi +\fRPlaces a copy of \fIfile\fR in the +buffer after the specified line. +Address 0 is permissible and causes +the copy of \fIfile\fR to be placed +at the beginning of the buffer. +The \fIread\fP command does not +erase any text already in the buffer. +If no line number is specified, +\fIfile\fR is placed after the +current line. +T} T{ +.nf +\fR:\fB0r newfile +\fR"newfile" 5 lines, 86 characters +\*c +.fi +T} +.SP +\fBrecover \fIfile\fP rec T{ +.fi +Retrieves a copy of the editor buffer +after a system crash, editor crash, +phone line disconnection, or +\fIpreserve\fR command. +T} +.SP +\fR(.,.)\fBsubstitute s T{ +.nf +\fBsubstitute/\fIpattern\fB/\fIreplacement\fB/ +substitute/\fIpattern\fB/\fIreplacement\fB/gc +.fi +\fRReplaces the first occurrence of \fIpattern\fR +on a line +with \fIreplacement\fP. +Including a \fBg\fR after the command +changes all occurrences of \fIpattern\fP +on the line. +The \fBc\fR option allows the user to +confirm each substitution before it is +made; see the manual for details. +T} T{ +.nf +:\fB3p +\fRLine 3 contains a misstake +:\fBs/misstake/mistake/ +\fRLine 3 contains a mistake +\*c +.fi +T} +.TE +.bp +.TS +cp10 cp10 cp10 cp10 +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +Name Abbr Description Examples +.sp 1.75 +\fBundo u T{ +.fi +\fRReverses the changes made in +the buffer by the last buffer-editing +command. +Note that this example contains +a notification about the number of +lines affected. +T} T{ +.nf +\fR:\fB1,15d +\fR15 lines deleted +new line number 1 is printed +:\fBu +\fR15 more lines in file ... +old line number 1 is printed +\*c +.fi +T} +.SP +\fR(1,$)\fBwrite \fIfile\fR w T{ +.fi +\fRCopies data from the buffer onto +a permanent file. If no \fIfile\fR +is named, the current filename +is used. +The file is automatically created +if it does not yet exist. +A response containing the number of +lines and characters in the file +indicates that the write +has been completed successfully. +The editor's built-in protections +against overwriting existing files +will in some circumstances +inhibit a write. +The form \fBw!\fR forces the +write, confirming that +an existing file is to be overwritten. +T} T{ +.nf +\fR:\fBw +\fR"file7" 64 lines, 1122 characters +:\fBw file8 +\fR"file8" File exists ... +:\fBw! file8 +\fR"file8" 64 lines, 1122 characters +\*c +.fi +T} +\fR(1,$)\fBwrite! \fIfile\fP w! \^ \^ +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +\fR(.)\fBz \fIcount\fP z T{ +.fi +\fRPrints a screen full of text starting +with the line indicated; +or, if \fIcount\fR is specified, +prints that number of lines. +Variants of the \fIz\fR command +are described in the manual. +T} +.SP +\fB!\fIcommand T{ +.fi +Executes the remainder of the line +after \fB!\fR as a \*U command. +The buffer is unchanged by this, and +control is returned to the editor when +the execution of \fIcommand\fR is complete. +T} T{ +.nf +\fR:\fB!date +\fRFri Jun 9 12:15:11 PDT 1978 +! +\*c +.fi +T} +.SP +\fRcontrol-d T{ +.fi +Prints the next \fIscroll\fR of text, +normally half of a screen. See the +manual for details of the \fIscroll\fR +option. +T} +.SP +\fR(.+1)<cr> T{ +.fi +An address alone followed by a carriage +return causes the line to be printed. +A carriage return by itself prints the +line following the current line. +T} T{ +.nf +:\fR<cr> +the line after the current line +\*c +.fi +T} +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +\fB/\fIpattern\fB/ T{ +.fi +\fRSearches for the next line in which +\fIpattern\fR occurs and prints it. +T} T{ +.nf +\fR:\fB/This pattern/ +\fRThis pattern next occurs here. +\*c +.fi +T} +.SP +\fB// T{ +Repeats the most recent search. +T} T{ +.nf +\fR:\fB// +\fRThis pattern also occurs here. +\*c +.fi +T} +.SP +\fB?\fIpattern\fB? T{ +Searches in the reverse direction +for \fIpattern\fP. +T} +.SP +\fB?? T{ +Repeats the most recent search, +moving in the reverse direction +through the buffer. +T} +.TE diff --git a/share/doc/usd/11.vitut/Makefile b/share/doc/usd/11.vitut/Makefile new file mode 100644 index 000000000000..e6aa1e72e546 --- /dev/null +++ b/share/doc/usd/11.vitut/Makefile @@ -0,0 +1,14 @@ +VOLUME= usd/11.edit +SRCS= edittut.ms +MACROS= -ms +USE_TBL= + +# index for versatec is different from the one in edit.tut +# because the fonts are different and entries reference page +# rather than section numbers. if you have a typesetter +# you should just use the index in edit.tut, and ignore editvindex. + +#editvindex: +# ${TROFF} ${MACROS} -n22 edit.vindex + +.include <bsd.doc.mk> diff --git a/share/doc/usd/11.vitut/edittut.ms b/share/doc/usd/11.vitut/edittut.ms new file mode 100644 index 000000000000..70fe087830cb --- /dev/null +++ b/share/doc/usd/11.vitut/edittut.ms @@ -0,0 +1,2278 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.ll 6.5i +.nr LL 6.5i +.EH 'USD:11-%''Edit: A Tutorial' +.OH 'Edit: A Tutorial''USD:11-%' +.LP +.ds u \s-2UNIX\s0 +.ND +.sp 4 +.ce +\f3\s+2Edit: A Tutorial\s0\f1 +.sp +.ce 3 +.I +Ricki Blau +.sp +James Joyce +.R +.sp +.ce 3 +Computing Services +University of California +Berkeley, California 94720 +.sp 3 +.ce +.I +ABSTRACT +.R +.sp +.LP +This narrative introduction to the use of the text editor +.I edit +assumes no prior familiarity with computers or with text editing. +Its aim is to lead the beginning \s-2UNIX\(dg\s+2 user through the +.FS +\(dgUNIX is a trademark of Bell Laboratories. +.FE +fundamental steps of writing and revising a file of text. +Edit, +a version of the text editor +.I ex, +was designed to provide an informative environment +for new and casual users. +.PP +We welcome comments and suggestions about this tutorial +and the \s-2UNIX\s+2 documentation in general. +.sp .5v +September 1981 +.bp +.ll 6.5i +.nr LL 6.5i +.nr LT 6.5i +.ds u \s-2UNIX\s0 +.ce +\s+2\f3Contents\f1\s0 +.LP +.nf +Introduction\ \ \ 3 +.sp +Session 1\ \ 4 +.in +.5i +Making contact with \s-2UNIX\s+2\ \ \ 4 +Logging in\ \ 4 +Asking for \fIedit\fR\ \ \ 4 +The ``Command not found'' message\ \ \ 5 +A summary\ \ 5 +Entering text\ \ \ 5 +Messages from \fIedit\fR\ \ \ 5 +Text input mode\ \ \ 6 +Making corrections\ \ \ 6 +Writing text to disk\ \ \ 7 +Signing off\ \ 7 +.in -.5i +.sp +Session 2\ \ \ 8 +.in +.5i +Adding more text to the file\ \ \ 8 +Interrupt\ \ \ 8 +Making corrections\ \ \ 8 +Listing what's in the buffer (p)\ \ \ 9 +Finding things in the buffer\ \ \ 9 +The current line\ \ \ 10 +Numbering lines (nu)\ \ \ 10 +Substitute command (s)\ \ \ 10 +Another way to list what's in the buffer (z)\ \ \ 11 +Saving the modified text\ \ \ 12 +.in -.5i +.sp +Session 3\ \ \ 13 +.in +.5i +Bringing text into the buffer (e)\ \ \ 13 +Moving text in the buffer (m)\ \ \ 13 +Copying lines (copy)\ \ \ 14 +Deleting lines (d)\ \ \ 14 +A word or two of caution\ \ \ 15 +Undo (u) to the rescue\ \ \ 15 +More about the dot (.) and buffer end ($)\ \ \ 16 +Moving around in the buffer (+ and \-)\ \ \ 16 +Changing lines (c)\ \ \ 17 +.in -.5i +.sp +Session 4\ \ \ 18 +.in +.5i +Making commands global (g)\ \ \ 18 +More about searching and substituting\ \ \ 19 +Special characters\ \ \ 19 +Issuing \s-2UNIX\s+2 commands from the editor\ \ \ 20 +Filenames and file manipulation\ \ \ 20 +The file (f) command\ \ \ 20 +Reading additional files (r)\ \ \ 21 +Writing parts of the buffer\ \ \ 21 +Recovering files\ \ \ 21 +Other recovery techniques\ \ \ 21 +Further reading and other information\ \ \ 22 +Using \fIex\fR\ \ \ 22 +.in -.5i +.sp +Index\ \ \ 23 +.bp +.SH +.ce +\s+2Introduction\s0 +.PP +Text editing using a terminal connected to a computer +allows you to create, modify, and print text +easily. +A +.I +text editor +.R +is a program +that assists you +as you create and modify text. +The text editor you will learn here is named +.I edit. +Creating text using edit is as easy as typing it +on an electric typewriter. +Modifying text involves telling the text editor +what you want to add, change, or delete. +You can review your text +by typing a command +to print the file contents +as they are currently. +Another program (which we do not discuss in this +document), a text formatter, +rearranges your text +for you into ``finished form.'' +.PP +These lessons assume no prior familiarity with computers +or with text editing. +They consist of a series of text editing sessions +which lead you through the fundamental steps +of creating and revising text. +After scanning each lesson and before beginning the next, +you should try the examples at a terminal to get a feeling +for the actual process of text editing. +If you set aside some time for experimentation, +you will soon become familiar with using the +computer to write and modify text. +In addition to the actual use of the text editor, +other features of \s-2UNIX\s0 will be very important to your work. +You can begin to +learn about these other features by +reading one of the other tutorials +that provide a general introduction to the system. +You will be ready to proceed with this lesson as soon as +you are familiar with (1) your terminal and its special keys, +(2) how to login, +(3) and the ways of correcting typing errors. +Let's first define some terms: +.sp .5 +.IP program 12 +A set of instructions, given to the computer, +describing the sequence of steps the computer performs +in order to accomplish a specific task. +The task must be specific, +such as balancing your checkbook +or editing your text. +A general task, +such as working for world peace, +is something we can all do, +but not something we can currently write programs to do. +.IP UNIX +\s-2UNIX\s0 is a special type of program, +called an operating system, that supervises the machinery +and all other programs comprising the total +computer system. +.IP edit +.I edit +is the name of the \s-2UNIX\s0 text editor you will be learning to use, +and is a program that aids you in writing or revising text. +Edit was designed for beginning users, +and is a simplified version of an editor named +.I ex. +.IP file +Each \s-2UNIX\s0 account is allotted +space for the permanent storage of information, +such as programs, data or text. +A file is a logical unit of data, +for example, an essay, a program, +or a chapter from a book, +which is stored on a computer system. +Once you create a file, +it is kept until you instruct the system to remove it. +You may create a file during one \s-2UNIX\s0 session, +end the session, +and return to use it at a later time. +Files contain anything you choose to write and store in them. +The sizes of files vary to suit your needs; +one file might hold only a single number, +yet another might contain +a very long document or program. +The only way to save +information from one session to the next is to store it in a file, +which you will learn in Session 1. +.IP filename +Filenames are used to distinguish one file from another, +serving the same purpose as the labels of manila +folders in a file cabinet. +In order to write or access information in a file, +you use the name of that file in a \s-2UNIX\s0 command, +and the system will automatically locate the file. +.IP disk +Files are stored on an input/output device called a disk, +which looks something like a stack of phonograph records. +Each surface is coated with a material similar to that +on magnetic recording tape, +and information is recorded on it. +.IP buffer +A temporary work space, made available to the user +for the duration of a session of text editing +and used for creating and modifying +the text file. +We can think of the buffer as a blackboard that is +erased after each class, where each session with the editor +is a class. +.bp +.SH +.ce 1 +\s+2Session 1\s0 +.sp 1 +.SH +Making contact with \s-1UNIX\s0 +.PP +To use the editor you must first make contact with the computer +by logging in to \s-2UNIX\s0. +We'll quickly review the standard \s-2UNIX\s0 login procedure +for the two ways you can make contact: +on a terminal that is directly linked to the computer, +or over a telephone line where the computer answers your call. +.SH +Directly-linked terminals +.PP +Turn on your terminal and press the \s-1RETURN\s0 key. +You are now ready to login. +.SH +Dial-up terminals +.PP +If your terminal connects with the computer over a telephone line, +turn on the terminal, dial the system access number, +and, when you hear a high-pitched tone, place the +telephone handset in the acoustic coupler, if you are using one. +You are now ready to login. +.SH +Logging in +.PP +The message inviting you to login is: +.DS I 1i +login: +.DE +.LP +Type your login name, which identifies you to \s-2UNIX\s0, +on the same line as the login message, +and press \s-2RETURN\s+2. +If the terminal you are using +has both upper and lower case, +.B +be sure you enter your login name in lower case; +.R +otherwise \s-2UNIX\s0 assumes your terminal +has only upper case and will not recognize lower case +letters you may type. +\s-2UNIX\s0 types ``login:'' and you reply +with your login name, for example ``susan'': +.DS I 1i +login: \fBsusan\fR \fI(and press the \s-2RETURN\s0 key)\fR +.DE +(In the examples, input you would type appears in +.B "bold face" +to distinguish it from the responses from \s-2UNIX\s0.) +.PP +\s-2UNIX\s0 will next respond with a request for a password +as an additional precaution to prevent +unauthorized people from using your account. +The password will not appear when you type it, +to prevent others from seeing it. +The message is: +.DS I 1i +Password: \fI(type your password and press \s-2RETURN\s+2)\fR +.DE +If any of the information you gave during the login +sequence was mistyped or incorrect, +\s-2UNIX\s0 will respond with +.DS I 1i +Login incorrect. +.if t .sp .2v +.if n .sp 1 +login: +.DE +in which case you should start the login process anew. +Assuming that you have successfully +logged in, \s-2UNIX\s0 +will print the message of the day and eventually will present +you with a % at the beginning of a fresh line. +The % is the \s-2UNIX\s0 prompt symbol +which tells you that \s-2UNIX\s0 is ready to accept a command. +.bd I 3 +.SH +Asking for \fIedit\fP +.fl +.bd I +.PP +You are ready to tell \s-2UNIX\s0 that you +want to work with edit, the text editor. +Now is a convenient time to choose +a name for the file of text you are about to create. +To begin your editing session, +type +.B edit +followed by a space and then the filename +you have selected; for example, ``text''. +After that, +press the \s-2RETURN\s0 key and wait for edit's response: +.DS I 1i +% \fBedit text\fP \fI(followed by a \s-2RETURN\s+2)\fR +"text" No such file or directory +: +.DE +If you typed the command correctly, +you will now be in communication with edit. +Edit has set aside a buffer for use as +a temporary working space during your current editing session. +Since ``text'' is a new file we are about to create +the editor was unable to find that file, which it +confirms by saying: +.DS I 1i +"text" No such file or directory +.DE +On the next line appears edit's prompt ``:'', +announcing that you are in \f2command mode\f1 and +edit expects a command from you. +You may now begin to create the new file. +.SH +The ``Command not found'' message +.PP +If you misspelled edit by typing, say, ``editor'', +this might appear: +.DS I 1i +% \fBeditor\fP +editor: Command not found +% +.DE +Your mistake in calling edit ``editor'' was +treated by \s-2UNIX\s0 as a request +for a program named ``editor''. +Since there is no program +named ``editor'', +\s-2UNIX\s0 reported that the program was ``not found''. +A new % indicates that \s-2UNIX\s0 is ready for another command, +and you may then enter the correct command. +.SH +A summary +.PP +Your exchange with \s-2UNIX\s0 as you logged in and made contact with edit +should look something like this: +.DS I 1i +login: \fBsusan\fP +Password: +\&... A Message of General Interest ... +% \fBedit text\fP +"text" No such file or directory +: +.DE +.SH +Entering text +.PP +You may now begin entering text into the buffer. +This is done by \fIappending\fP (or adding) text to whatever +is currently in the buffer. +Since there is nothing in the buffer at the moment, +you are appending text to nothing; +in effect, +since you are adding text to nothing +you are creating text. +Most edit commands have two equivalent forms: +a word that suggests what the command does, +and a shorter abbreviation of that word. +Many beginners find the full command names +easier to remember at first, +but once you are familiar with editing you may +prefer to type the shorter abbreviations. +The command to input text is ``append''. +(It may be abbreviated ``a''.) +Type +.B append +and press the \s-2RETURN\s0 key. +.DS I 1i +% \fBedit text +\fR:\|\fBappend +.R +.DE +.SH +.bd I 3 +Messages from +.I edit +.fl +.bd I +.PP +If you make a mistake in entering a command and +type something that edit does not recognize, +edit will respond with a message +intended to help you diagnose your error. +For example, if you misspell the command to input text by typing, +perhaps, ``add'' instead of ``append'' or ``a'', +you will receive this message: +.DS I 1i +:\|\fBadd\fR +add: Not an editor command +: +.DE +When you receive a diagnostic message, +check what you typed in order to determine what +part of your command confused edit. +The message above means that edit +was unable to recognize your mistyped command +and, therefore, did not execute it. +Instead, a new ``:'' +appeared to let you know that +edit is again ready to execute a command. +.SH +Text input mode +.PP +By giving the command ``append'' (or using the abbreviation ``a''), +you entered +.I +text input mode, +.R +also known as +.I +append mode. +.R +When you enter text input mode, +edit stops sending you a prompt. +You will not receive any prompts +or error messages +while in text input mode. +You can enter +pretty much anything you want on the lines. +The lines are transmitted one by one to the buffer +and held there during the editing session. +You may append as much text as you want, and +.I +when you wish to stop entering text lines you should +type a period as the only character on the line +and press the \s-2RETURN\s0 key. +.R +When you type the period and press \s-2RETURN\s0, +you signal that you want to stop appending text, +and edit responds by allowing +you to exit text input mode and reenter command mode. +Edit will again +prompt you for a command by printing ``:''. +.PP +Leaving append mode does not destroy the text in +the buffer. +You have to leave append +mode to do any of the other kinds of editing, +such as changing, adding, or printing text. +If you type a period as the first character and +type any other character on the same line, +edit will believe you want to remain in append mode +and will not let you out. +As this can be very frustrating, +be sure to type +.B only +the period and the \s-2RETURN\s0 key. +.PP +This is a good place to learn an important +lesson about computers and text: a blank space is +a character as far as a computer is concerned. +If you so much as type a period followed by a blank +(that is, type a period and then the space bar on the keyboard), +you will remain in append mode with the last line of text +being: +.DS I 1i +.B +.ps +2 +\&. +.ps -2 +.R +.DE +Let's say that you enter the lines +(try to type +.B exactly +what you see, including ``thiss''): +.DS I 1i +.B +This is some sample text. +And thiss is some more text. +Text editing is strange, but nice. +\&. +.R +.DE +The last line is the period followed by a \s-2RETURN\s0 +that gets you out of append mode. +.SH +Making corrections +.PP +If you have read a general introduction to \s-2UNIX\s0, +you will recall that it is possible to erase individual +letters that you have typed. +This is done by typing the designated erase character +as many times as there are characters +you want to erase. +.PP +The usual erase character varies from place to place and +user to user. Often it +is the backspace (control-H), +so you can correct typing errors +in the line you are typing +by holding down the \s-1CTRL\s+1 key +and typing the ``H'' key. (Sometimes it is the DEL key.) +If you type the erase character +you will notice +that the terminal backspaces in the line you are on. +You can backspace over your error, +and then type what you want to be the rest of the line. +.PP +If you make a bad start +in a line +and would like to begin again, +you can either backspace to the beginning of the line +or you can use the at-sign ``@'' to erase everything on the line: +.DS I 1i +.B +Text edtiing is strange, but@ +Text editing is strange, but nice. +.R +.fl +.bd S +.DE +When you type the at-sign (@), you erase +the entire line typed so far +and are given a fresh line to type on. +You may immediately begin to retype the line. +This, unfortunately, does not work after you type the +line and press \s-2RETURN\s+2. +To make corrections in lines that have been completed, +it is necessary to use the editing commands +covered in the next sessions. +.SH +Writing text to disk +.PP +You are now ready to edit the text. One common operation +is to write the text to disk as a file for safekeeping +after the session is over. +This is the only way to save information from one session to the next, +since the editor's buffer is temporary and will last only until the +end of the editing session. +Learning how to write a file to disk is second in +importance only to entering the text. +To write the contents of the buffer to a disk +file, use the command ``write'' +(or its abbreviation ``w''): +.DS I 1i +:\|\fBwrite +.R +.DE +Edit will copy the contents of the buffer to a disk file. +If the file does not yet exist, +a new file will be created automatically +and the presence of a ``[New file]'' will be noted. +The newly-created file will be given the name specified when +you entered the editor, in this case ``text''. +To confirm that the disk file has been successfully written, +edit will repeat the filename and give +the number of lines and the total +number of characters in the file. +The buffer remains unchanged by the ``write'' command. +All of the lines that were written to disk will still be +in the buffer, +should you want to modify or add to them. +.PP +Edit must have a name for the file to be written. +If you forgot to indicate the name of the file +when you began to edit, +edit will print in response to your write command: +.DS I 1i +No current filename +.DE +If this happens, you can specify the filename in a new write command: +.DS I 1i +:\|\fBwrite text +.R +.DE +After the ``write'' (or ``w''), type a space and then the name of the file. +.SH +Signing off +.PP +We have done enough for this first lesson on using the +\s-2UNIX\s0 text editor, and are ready to quit the session with edit. +To do this we type ``quit'' (or ``q'') and press \s-2RETURN\s+2: +.DS I 1i +:\|\fBwrite +.R +"text" [New file] 3 lines, 90 characters +:\|\fBquit\fR +% +.DE +The % is from \s-2UNIX\s0 to tell you that your session with edit is +over and you may command \s-2UNIX\s0 further. +Since we want +to end the entire session at the terminal, we also need to +exit from \s-2UNIX\s0. +In response to the \s-2UNIX\s0 prompt of ``\|%\|'' +type the command +.DS I 1i +%\|\fBlogout\fR +.DE +This will end your session with \s-2UNIX\s0, and will ready the +terminal for the next user. +It is always important to type \fBlogout\fR at the end of a session +to make absolutely sure no one +could accidentally stumble into your abandoned +session and thus gain access to your files, +tempting even the most honest of souls. +.sp 1 +.PP +This is the end of the first session on \s-2UNIX\s0 text editing. +.bp +.TL +Session 2 +.sp +.PP +Login with \s-2UNIX\s0 as in the first session: +.DS I 1i +login: \fBsusan\fP \fI(carriage return)\fR +Password: \fI(give password and carriage return)\fR +.if t .sp .2v +.if n .sp 1 +\&... A Message of General Interest ... +% +.DE +When you indicate you want to edit, +you can specify the name of the file you worked on last time. +This will +start edit working, and it will fetch the contents of the +file into the buffer, so that you can resume editing the same file. +When edit has copied the file into the buffer, it +will repeat its name and tell +you the number of lines and characters it contains. +Thus, +.DS I 1i +.B +% edit text +.R +"text" 3 lines, 90 characters +: +.DE +means you asked edit to fetch +the file named ``text'' for editing, +causing it to copy the +90 characters of text into the buffer. +Edit awaits +your further instructions, +and indicates this by its prompt character, the colon (:). +In this session, we will append more text to our file, +print the contents of the buffer, and learn to change the text of a line. +.SH +Adding more text to the file +.PP +If you want to add more to the end of your +text you may do so by using the append command to enter text input mode. +When ``append'' is the first command +of your editing session, +the lines you enter +are placed at the end of the buffer. +Here we'll use the abbreviation for the append command, ``a'': +.DS I 1i +:\|\fBa +This is text added in Session 2. +It doesn't mean much here, but +it does illustrate the editor. +\|\fB\s+2\&.\s-2 +.R +.DE +You may recall that once you enter append mode +using the ``a'' (or ``append'') command, +you need to type a line containing only a period (.) +to exit append mode. +.SH +Interrupt +.PP +Should you press the \s-2RUB\s+2 key (sometimes labelled \s-2DELETE\s+2) +while working with edit, +it will send this message to you: +.DS I 1i +Interrupt +: +.DE +Any command that edit might be executing +is terminated by rub or delete, +causing edit to prompt you for a new command. +If you are appending text at the time, +you will exit from append mode +and be expected to give another command. +The line of text you were typing +when the append command was interrupted +will not be entered into the buffer. +.SH +Making corrections +.PP +If while typing the line you hit an incorrect key, +recall that +you may delete the incorrect character +or cancel the entire line of input by erasing in the usual way. +Refer either +to the last few pages of Session 1 +if you need to review +the procedures for making a correction. +The most important idea to remember is that +erasing a character or cancelling a line must be done +before you press the \s-2RETURN\s+2 key. +.SH +Listing what's in the buffer (p) +.PP +Having appended text to what you wrote in Session 1, +you might want to see all the lines in the buffer. +To print the contents of the buffer, type the command: +.DS I 1i +:\|\fB1,$p +.R +.DE +The ``1''\(dg +.FS +\(dgThe numeral ``one'' is the top left-most key, +and should not be confused with the letter ``el''. +.FE +stands for line 1 of the buffer, +the ``$'' is a special symbol designating the last line +of the buffer, +and ``p'' (or \fBprint\fR) is the command to print from line 1 +to the end of the buffer. +The command ``1,$p'' gives you: +.DS I 1i +This is some sample text. +And thiss is some more text. +Text editing is strange, but nice. +This is text added in Session 2. +It doesn't mean much here, but +it does illustrate the editor. +.DE +Occasionally, you may accidentally +type a character that can't be printed, +which can be done by striking a key +while the \s-2CTRL\s0 key is pressed. +In printing lines, edit uses a special notation to +show the existence of non-printing characters. +Suppose you had introduced the non-printing character ``control-A'' +into the word ``illustrate'' +by accidently pressing the \s-2CTRL\s0 key while +typing ``a''. +This can happen on many terminals +because the \s-2CTRL\s+2 key and the ``A'' key +are beside each other. +If your finger presses between the two keys, +control-A results. +When asked to print the contents of the buffer, +edit would display +.DS I 1i +it does illustr^Ate the editor. +.DE +To represent the control-A, edit shows ``^A''. +The sequence ``^'' followed by a capital +letter stands for the one character +entered by holding down the \s-2CTRL\s0 key and typing the letter +which appears after the ``^''. +We'll soon discuss the commands that can be used +to correct this typing error. +.PP +In looking over the text we see that +``this'' is typed as ``thiss'' in the second line, +a deliberate error so we can learn to make corrections. +Let's correct the spelling. +.SH +Finding things in the buffer +.PP +In order to change something in the buffer we first need to +find it. +We can find ``thiss'' in the text we have +entered by looking at a listing +of the lines. +Physically speaking, we search the lines +of text looking for ``thiss'' and stop searching when +we have found it. +The way to tell edit to search for something +is to type it inside slash marks: +.DS I 1i +:\|\fB/thiss/ +.R +.DE +By typing +.B /thiss/ +and pressing \s-1RETURN\s0, +you instruct edit to search for ``thiss''. +If you ask edit to look for a pattern of characters +which it cannot find in the buffer, +it will respond ``Pattern not found''. +When edit finds +the characters ``thiss'', it will print the line of text +for your inspection: +.DS I 1i +And thiss is some more text. +.DE +Edit is now positioned in the buffer at the +line it just printed, +ready to make a change in the line. +.bp +.SH +The current line +.PP +Edit keeps track of the line in the buffer where it is located +at all times during an editing session. +In general, the line that has been most recently +printed, entered, or changed +is the current location in the buffer. +The editor is prepared to make changes +at the current location in the buffer, +unless you direct it to another location. +.PP +In particular, +when you bring a file into the buffer, +you will be located at the last line in the file, +where the editor left off copying the lines +from the file to the buffer. +If your first editing command is ``append'', +the lines you enter are added +to the end of the file, +after the current line \(em +the last line in the file. +.PP +You can refer to your current location in the buffer by the +symbol +period (.) usually known by the name ``dot''. +If you type ``.'' and carriage +return you will be instructing edit to print the current line: +.DS I 1i +:\|\fB\s+2\&.\s-2 +.R +And thiss is some more text. +.DE +.PP +If you want to know the number of the current line, +you can type +.B \&.= +and press \s-2RETURN\s+2, +and edit will respond with the line number: +.DS I 1i +:\|\fB\s+2.\s-2= +.R +2 +.DE +If you type the number of any line and press \s-2RETURN\s+2, +edit will position you at that line and +print its contents: +.DS I 1i +:\|\fB2 +.R +And thiss is some more text. +.DE +You should experiment with these commands +to gain experience in using them to make changes. +.SH +Numbering lines (nu) +.PP +The +.B +number (nu) +.R +command is similar to print, +giving both the number and the text of each printed line. +To see the number and the text of the current line type +.DS I 1i +:\|\fBnu +.R +\0\0\0\0\02\0\0And thiss is some more text. +.DE +Note that the shortest abbreviation for the number command is +``nu'' (and not ``n'', which is used for a different command). +You may specify a range of lines +to be listed by the number command in the same way that lines +are specified for print. +For example, \f31,$nu\f1 lists all lines in the buffer with their +corresponding line numbers. +.SH +Substitute command (s) +.PP +Now that you have found the misspelled word, +you can change it from ``thiss'' to ``this''. +As far as edit is concerned, +changing things is a matter of +substituting one thing for another. +As +.I a +stood for +.I append, +so +.I s +stands for +.I substitute. +We will use the abbreviation ``s'' to reduce the chance +of mistyping the substitute command. +This command will instruct edit to make the change: +.DS I 1i +\f32s/thiss/this/\f1 +.DE +We first indicate the line to be changed, line 2, +and then +type an ``s'' to indicate we want +edit to make a substitution. +Inside the first set of slashes +are the characters that we want to change, +followed by the characters to replace them, +and then a closing slash mark. +To summarize: +.DS I 1i +2s/ \fIwhat is to be changed\fR / \fIwhat to change it to \fR/ +.DE +If edit finds an exact match of the characters to be +changed it will make the change +.B only +in the first occurrence of the characters. +If it does not find the characters +to be changed, it will respond: +.DS I 1i +Substitute pattern match failed +.DE +indicating that your instructions could not be carried out. +When edit does find the characters that you want to change, +it will make the substitution and automatically print +the changed line, so that you can check that the correct substitution +was made. +In the example, +.DS I 1i +:\|\fB2s/thiss/this/ +.R +And this is some more text. +.DE +line 2 (and line 2 only) will be searched for the characters +``thiss'', and when the first exact match is found, ``thiss'' +will be changed to ``this''. +Strictly speaking, it was not necessary above to +specify the number of the line to be changed. +In +.DS I 1i +:\|\fBs/thiss/this/ +.R +.DE +edit will assume that we mean to change +the line where we are currently located (``.''). +In this case, +the command without a line number would have produced the same result +because we were already located +at the line we wished to change. +.PP +For another illustration of the substitute command, +let us choose the line: +.DS I 1i +Text editing is strange, but nice. +.DE +You can make this line a bit more positive +by taking out the characters ``strange, but\ '' so the line +reads: +.DS I 1i +Text editing is nice. +.DE +A command that will first position edit at the desired line +and then make the substitution is: +.DS I 1i +:\|\fB/strange/s/strange, but // +.R +.DE +.LP +What we have done here is combine our search with +our substitution. +Such combinations are perfectly legal, +and speed up editing quite a bit +once you get used to them. +That is, you do not necessarily have to use +line numbers to identify a line to edit. +Instead, you may identify the line you want to change +by asking edit to search for a specified pattern of letters +that occurs in that line. +The parts of the above command are: +.in +1i +.TS +l l. +\fB/strange/\fP tells edit to find the characters ``strange'' in the text +\fBs\fP tells edit to make a substitution +\fB/strange, but //\fP substitutes nothing at all for the characters ``strange, but '' +.TE +.in -1i +.PP +You should note the space after ``but'' in ``/strange, but /''. +If you do not indicate that the space is to be taken out, +your line will read: +.DS I 1i +.if t Text editing is nice. +.if n Text editing is nice. +.DE +which looks a little funny +because of the extra space between ``is'' and ``nice''. +Again, we realize from this that a blank space +is a real character to a computer, and in editing text +we need to be aware of spaces +within a line just as we would be aware of an ``a'' or +a ``4''. +.SH +Another way to list what's in the buffer (z) +.PP +Although the print command is useful for looking at specific lines +in the buffer, +other commands may be more convenient for +viewing large sections of text. +You can ask to see a screen full of text at a time +by using the command +.B z. +If you type +.DS I 1i +:\|\fB1z +.R +.DE +edit will start with line 1 and continue printing lines, +stopping either when the screen of +your terminal is full +or when the last line in the buffer has been printed. +If you want to read the next segment of text, type the command +.DS I 1i +:\|\fBz +.DE +If no starting line number is given for the z command, +printing will start at the ``current'' line, in this case the +last line printed. +Viewing lines in the buffer one screen full at a time +is known as \fIpaging\fR. +Paging can also be used to print +a section of text on a hard-copy terminal. +.SH +Saving the modified text +.PP +This seems to be a good place to pause in our work, +and so we should end the second session. +If you (in haste) type ``q'' to quit the session +your dialogue with edit will be: +.DS I 1i +:\|\fBq +.R +No write since last change (:quit! overrides) +: +.DE +This is edit's warning that you have not written +the modified contents of the buffer to disk. +You run the risk of losing the work you did +during the editing session since you typed the latest write +command. +Because in this lesson we have not written +to disk at all, everything we have done +would have been lost +if edit had obeyed the \fBq\fR command. +If you did not want to save the work done during +this editing session, you would have to type ``q!'' +or (``quit!'') +to confirm that you indeed wanted to end the session +immediately, +leaving the file as it was +after the most recent ``write'' command. +However, +since you want to save what +you have edited, you need to type: +.DS I 1i +:\|\fBw +.R +"text" 6 lines, 171 characters +.DE +and then follow with the commands to quit and logout: +.DS I 1i +:\|\fBq +% \fBlogout\fR +.DE +and hang up the phone or turn off the terminal when +\s-2UNIX\s0 asks for a name. +Terminals connected to the port selector +will stop after the logout command, +and pressing keys on the keyboard will do nothing. +.sp 1 +.PP +This is the end of the second session on \s-2UNIX\s0 text editing. +.bp +.TL +Session 3 +.SH +Bringing text into the buffer (e) +.PP +Login to \s-2UNIX\s0 and make contact with edit. +You should try to login without +looking at the notes, but if you must +then by all means do. +.PP +Did you remember to give the name of the file +you wanted to edit? +That is, did you type +.DS I 1i +% \fBedit text\fR +.DE +or simply +.DS I 1i +% \fBedit\fR +.DE +Both ways get you in contact with edit, but the first way +will bring a copy of the file named ``text'' into +the buffer. +If you did forget to tell edit the name of your file, +you can get it into the buffer by +typing: +.DS I 1i +:\|\fBe text +.R +"text" 6 lines, 171 characters +.DE +The command +.B edit, +which may be abbreviated \fBe\fR, +tells edit that you want +to erase anything that might already be in +the buffer and bring a copy of the file ``text'' into the buffer +for editing. +You may also use the edit (e) command to change files in +the middle of an editing session, +or to give edit the name of a new file that you want to create. +Because the edit command clears the buffer, +you will receive a warning if you try to edit a new file without +having saved a copy of the old file. +This gives you a chance to write the contents of the buffer to disk +before editing the next file. +.SH +Moving text in the buffer (m) +.PP +Edit allows you to move lines of text +from one location in the buffer to another +by means of the +.B move +(\fBm\fR) command. +The first two examples are for illustration only, +though after you have read this Session +you are welcome to return to them for practice. +The command +.DS I 1i +:\|\fB2,4m$ +.R +.DE +directs edit to move lines 2, 3, and 4 +to the end of the buffer ($). +The format for the move command is that you specify +the first line to be moved, the last line to be moved, +the move command ``m'', and the line after which +the moved text is to be placed. +So, +.DS I 1i +:\|\fB1,3m6 +.R +.DE +would instruct edit to move lines 1 through 3 (inclusive) +to a location after line 6 in the buffer. +To move only one line, say, line 4, +to a location in the buffer after line 5, +the command would be ``4m5''. +.PP +Let's move some text using the command: +.DS I 1i +:\|\fB5,$m1 +.R +2 lines moved +it does illustrate the editor. +.DE +After executing a command that moves more than one line of the buffer, +edit tells how many lines were affected by the move +and prints the last moved line for your inspection. +If you want to see more than just the last line, +you can then +use the print (p), z, or number (nu) command to view more text. +The buffer should now contain: +.DS I 1i +This is some sample text. +It doesn't mean much here, but +it does illustrate the editor. +And this is some more text. +Text editing is nice. +This is text added in Session 2. +.DE +You can restore the original order by typing: +.DS I 1i +:\|\fB4,$m1 +.R +.DE +or, combining context searching and the move command: +.DS I 1i +:\|\fB/And this is some/,/This is text/m/This is some sample/ +.R +.DE +(Do not type both examples here!) +The problem with combining context searching +with the move command +is that your chance of making a typing error +in such a long command is greater than +if you type line numbers. +.SH +Copying lines (copy) +.PP +The +.B copy +command +is used to make a second copy of specified lines, +leaving the original lines where they were. +Copy +has the same format as the move command, for example: +.DS I 1i +:\|\fB2,5copy $ +.R +.DE +makes a copy of lines 2 through 5, +placing the added lines after the buffer's end ($). +Experiment with the copy command +so that you can become familiar with how it works. +Note that the shortest abbreviation for copy is +\f3co\f1 (and +not the letter ``c'', which has another meaning). +.SH +Deleting lines (d) +.PP +Suppose you want to delete +the line +.DS I 1i +This is text added in Session 2. +.DE +from the buffer. +If you know the number of the line to be deleted, +you can type +that number followed by +\fBdelete\fR or \fBd\fR. +This example deletes line 4, +which is ``This is text added in Session 2.'' +if you typed the commands +suggested so far. +.DS I 1i +:\|\fB4d +.R +It doesn't mean much here, but +.DE +Here ``4'' is the number of the line to be deleted, +and ``delete'' or ``d'' is the command to delete the line. +After executing the delete command, +edit prints the line that has become the current line (``.''). +.PP +If you do not happen to know the line number +you can search for the line and then delete it using this +sequence of commands: +.DS I 1i +:\|\fB/added in Session 2./ +.R +This is text added in Session 2. +:\|\fBd +.R +It doesn't mean much here, but +.DE +The ``/added in Session 2./'' +asks edit to locate and print +the line containing the indicated text, +starting its search at the current line +and moving line by line +until it finds the text. +Once you are sure that you have correctly specified the line +you want to delete, +you can enter the delete (d) command. +In this case it is not necessary to +specify a line number before the ``d''. +If no line number is given, +edit deletes the current line (``.''), +that is, the line found by our search. +After the deletion, your buffer should contain: +.DS I 1i +This is some sample text. +And this is some more text. +Text editing is nice. +It doesn't mean much here, but +it does illustrate the editor. +And this is some more text. +Text editing is nice. +This is text added in Session 2. +It doesn't mean much here, but +.DE +To delete both lines 2 and 3: +.DS I 1i +And this is some more text. +Text editing is nice. +.DE +you type +.DS I 1i +:\|\f32,3d\f1 +2 lines deleted +.DE +which specifies the range of lines from 2 to 3, +and the operation on those lines \(em ``d'' for delete. +If you delete more than one line +you will receive a message +telling you the number of lines deleted, +as indicated in the example above. +.PP +The previous example assumes that you know the line numbers for +the lines to be deleted. +If you do not you might combine the search command +with the delete command: +.DS I 1i +:\|\fB/And this is some/,/Text editing is nice./d +.R +.DE +.SH +A word or two of caution +.PP +In using the search function to locate lines to +be deleted you should be +.B +absolutely sure +.R +the characters you give as the basis for the search +will take edit to the line you want deleted. +Edit will search for the first +occurrence of the characters starting from where +you last edited \- +that is, from the line you see printed if you type dot (.). +.PP +A search based on too few +characters may result in the wrong lines being deleted, +which edit will do as easily as if you had meant it. +For this reason, it is usually safer +to specify the search and then delete in two separate steps, +at least until you become familiar enough with using the editor +that you understand how best to specify searches. +For a beginner it is not a bad idea to double-check +each command before pressing \s-2RETURN\s+2 to send the command on its way. +.SH +Undo (u) to the rescue +.PP +The +.B +undo (u) +.R +command has the ability to +reverse the effects of the last command that changed the buffer. +To undo the previous command, type +``u'' or ``undo''. +Undo can rescue +the contents of the buffer from many an unfortunate mistake. +However, its powers are not unlimited, +so it is still wise to be reasonably +careful about the commands you give. +.PP +It is possible to undo only commands which +have the power to change the buffer \(em for example, +delete, append, move, copy, substitute, and even undo itself. +The commands write (w) and edit (e), which interact with disk files, +cannot be undone, nor can commands that do not change +the buffer, such as print. +Most importantly, +the +.B only +command that can be reversed by undo +is the +last ``undo-able'' command you typed. +You can use control-H and @ to change +commands while you are typing them, +and undo to reverse the effect of the commands +after you have typed them and pressed \s-2RETURN\s+2. +.PP +To illustrate, +let's issue an undo command. +Recall that the last buffer-changing command we gave deleted +the lines formerly numbered 2 and 3. +Typing undo at this moment will reverse the effects +of the deletion, causing those two lines to be +replaced in the buffer. +.DS I 1i +:\|\fBu +.R +2 more lines in file after undo +And this is some more text. +.DE +Here again, edit informs you if the command affects more +than one line, +and prints +the text of the line which is now ``dot'' (the current line). +.SH +More about the dot (.) and buffer end ($) +.PP +The function assumed by the symbol dot depends on its context. +It can be used: +.IP +1. to exit from append mode; we type dot (and only a dot) on +a line and press \s-2RETURN\s+2; +.IP +2. to refer to the line we are at in the buffer. +.LP +Dot can also be combined with the equal sign to get +the number of the line currently being edited: +.DS I 1i +:\|\fB\&.= +.R +.DE +If we type ``\fB.\fR='' we are asking for the number of the line, +and if we type ``\fB.\fR'' we are asking for the text of the line. +.PP +In this editing session and the last, we used the dollar +sign to indicate the end of the buffer +in commands such as print, copy, and move. +The dollar sign as a command asks edit to print the last +line in the buffer. +If the dollar sign is combined with the equal sign (\f3$=\f1) +edit will print the line number corresponding to the +last line in the buffer. +.PP +``\fB.\fR'' and ``$'', then, represent line numbers. +Whenever appropriate, these symbols can be used in +place of line numbers in commands. +For example +.DS I 1i +:\|\fB\s+2.\s-2,$d +.R +.DE +instructs edit to delete all lines from the current line (\fB.\fR) +to the end of the buffer. +.SH +Moving around in the buffer (+ and \-) +.PP +When you are editing +you often want +to go back and re-read a previous line. +You could specify a context search for a line you want to +read if you remember some of its text, +but if you simply want to see what was written a few, say 3, lines +ago, you can type +.DS I 1i +\-3p +.DE +This tells edit to move back to a position 3 lines +before the current line (.) +and print that line. +You can move forward in the buffer similarly: +.DS I 1i ++2p +.DE +instructs edit to print the line that is 2 +ahead of your current position. +.PP +You may use ``+'' and ``\-'' in any command where edit +accepts line numbers. +Line numbers specified with ``+'' or ``\-'' +can be combined to print a range of lines. +The command +.DS I 1i +:\|\fB\-1,+2copy$ +.R +.DE +makes a copy of 4 lines: the current line, the line before it, +and the two after it. +The copied lines will be placed after the last line +in the buffer ($), +and the original lines referred to by ``\-1'' and ``+2'' +remain where they are. +.PP +Try typing only ``\-''; you will move back one line just as +if you had typed ``\-1p''. +Typing the command ``+'' works similarly. +You might also try typing a few plus or minus signs in a row +(such as ``+++'') to see edit's response. +Typing \s-2RETURN\s+2 alone on a line is the equivalent +of typing ``+1p''; it will move you one line ahead in the buffer +and print that line. +.PP +If you are at the last line of the buffer and try +to move further ahead, perhaps by typing a ``+'' or +a carriage return alone on the line, +edit will remind you that you are at the end of the buffer: +.sp +.nf +.ti 1i +At end-of-file +.br +or +.ti 1i +Not that many lines in buffer +.fi +.LP +Similarly, if you try to move to a position before the first line, +edit will print one of these messages: +.sp +.nf +.ti 1i +Nonzero address required on this command +.br +or +.ti 1i +Negative address \- first buffer line is 1 +.fi +.LP +The number associated with a buffer line is the line's ``address'', +in that it can be used to locate the line. +.SH +Changing lines (c) +.PP +You can also delete certain lines and +insert new text in their place. +This can be accomplished easily with the +.B "change (c)" +command. +The change command instructs edit to delete specified lines +and then switch to text input mode to +accept the text that will replace them. +Let's say you want to change the first two lines in the buffer: +.DS I 1i +This is some sample text. +And this is some more text. +.DE +to read +.DS I 1i +This text was created with the \s-2UNIX\s0 text editor. +.DE +To do so, you type: +.DS I 1i +:\|\fB1,2c +.R +2 lines changed +.B +This text was created with the \s-2UNIX\s0 text editor. +\s+2\&.\s-2 +.R +: +.DE +In the command +.B 1,2c +we specify that we want to change +the range of lines beginning with 1 and ending with 2 +by giving line numbers as with the print command. +These lines will be deleted. +After you type \s-2RETURN\s+2 to end the change command, +edit notifies you if more than one line will be changed +and places you in text input mode. +Any text typed on the following lines will be inserted into +the position where lines were deleted by the change command. +.B +You will remain in text input mode until you exit in the usual way, +by typing a period alone on a line. +.R +Note that the number of lines added to the buffer need not be +the same as the number of lines deleted. +.sp 1 +.PP +This is the end of the third session on text editing with \s-2UNIX\s0. +.bp +.SH +.ce 1 +\s+2Session 4\s0 +.sp +.PP +This lesson covers several topics, starting with +commands that apply throughout the buffer, +characters with special meanings, +and how to issue \s-2UNIX\s0 commands while in the editor. +The next topics deal with files: +more on reading and writing, +and methods of recovering files lost in a crash. +The final section suggests sources of further information. +.SH +Making commands global (g) +.PP +One disadvantage to the commands we have used for +searching or substituting is that if you +have a number of instances of a word to change +it appears that you have to type the command +repeatedly, once for +each time the change needs to be made. +Edit, however, provides a way to make commands +apply to the entire contents of the buffer \- +the +.B +global (g) +.R +command. +.PP +To print all lines +containing a certain sequence of characters +(say, ``text'') +the command is: +.DS I 1i +:\|\fBg/text/p +.R +.DE +The ``g'' instructs edit to +make a global search for all lines +in the buffer containing the characters ``text''. +The ``p'' prints the lines found. +.PP +To issue a global command, start by typing a ``g'' and then a search +pattern identifying +the lines to be affected. +Then, on the same line, type the command to be +executed for the identified lines. +Global substitutions are frequently useful. +For example, +to change all instances of the word ``text'' to the word ``material'' +the command would be a combination of the global search and the +substitute command: +.DS I 1i +:\|\fBg/text/s/text/material/g +.R +.DE +Note the ``g'' at the end of the global command, +which instructs edit to change +each and every instance of ``text'' to ``material''. +If you do not type the ``g'' at the end of the command +only the +.I first +instance of ``text'' \fIin each line\fR will be changed +(the normal result of the substitute command). +The ``g'' at the end of the command is independent of the ``g'' +at the beginning. +You may give a command such as: +.DS I 1i +:\|\fB5s/text/material/g +.R +.DE +to change every instance of ``text'' in line 5 alone. +Further, neither command will change ``text'' to ``material'' +if ``Text'' begins with a capital rather than a lower-case +.I t. +.PP +Edit does not automatically print the lines modified by a +global command. +If you want the lines to be printed, type a ``p'' +at the end of the global command: +.DS I 1i +:\|\fBg/text/s/text/material/gp +.R +.DE +You should be careful +about using the global command in combination with any other \- +in essence, be sure of what you are telling edit to do +to the entire buffer. +For example, +.DS I 1i +:\|\fBg/ /d +.R +72 less lines in file after global +.DE +will delete every line containing a blank anywhere in it. +This could adversely affect +your document, since most lines have spaces between words +and thus would be deleted. +After executing the global command, +edit will print a warning if the command added or deleted more than one line. +Fortunately, the undo command can reverse +the effects of a global command. +You should experiment with the global command +on a small file of text to see what it can do for you. +.SH +More about searching and substituting +.PP +In using slashes to identify a character string +that we want to search for or change, +we have always specified the exact characters. +There is a less tedious way to +repeat the same string of characters. +To change ``text'' to ``texts'' we may type either +.DS I 1i +:\|\fB/text/s/text/texts/ +.R +.DE +as we have done in the past, +or a somewhat abbreviated command: +.DS I 1i +:\|\fB/text/s//texts/ +.R +.DE +In this example, the characters to be changed +are not specified \- +there are no characters, not even a space, +between the two slash marks +that indicate what is to be changed. +This lack of characters between the slashes +is taken by the editor to mean +``use the characters we last searched for as the characters to be changed.'' +.PP +Similarly, the last context search may be repeated +by typing a pair of slashes with nothing between them: +.DS I 1i +:\|\fB/does/ +.R +It doesn't mean much here, but +:\|\fB// +.R +it does illustrate the editor. +.DE +(You should note that the search command found the characters ``does'' +in the word ``doesn't'' in the first search request.) +Because no characters are specified for the second search, +the editor scans the buffer for the next occurrence of the +characters ``does''. +.PP +Edit normally searches forward through the buffer, +wrapping around from the end of the buffer to the beginning, +until the specified character string is found. +If you want to search in the reverse direction, +use question marks (?) instead of slashes +to surround the characters you are searching for. +.PP +It is also possible +to repeat the last substitution +without having to retype the entire command. +An ampersand (&) used as a command +repeats the most recent substitute command, +using the same search and replacement patterns. +After altering the current line by typing +.DS I 1i +:\|\fBs/text/texts/ +.R +.DE +you type +.DS I 1i +:\|\fB/text/& +.R +.DE +or simply +.DS I 1i +:\|\fB//& +.R +.DE +to make the same change on the next line in the buffer +containing the characters ``text''. +.SH +Special characters +.PP +Two characters have special meanings when +used in specifying searches: ``$'' and ``^''. +``$'' is taken by the editor to mean ``end of the line'' +and is used to identify strings +that occur at the end of a line. +.DS I 1i +:\|\fBg/text.$/s//material./p +.R +.DE +tells the editor to search for all lines ending in ``text.'' +(and nothing else, not even a blank space), +to change each final ``text.'' to ``material.'', +and print the changed lines. +.PP +The symbol ``^'' indicates the beginning of a line. +Thus, +.DS I 1i +:\|\fBs/^/1. / +.R +.DE +instructs the editor to insert ``1.'' and a space at the beginning +of the current line. +.PP +The characters ``$'' and ``^'' have special meanings only in the context +of searching. +At other times, they are ordinary characters. +If you ever need to search for a character that has a special meaning, +you must indicate that the +character is to lose temporarily +its special significance by typing another special character, +the backslash (\\), before it. +.DS I 1i +:\|\fBs/\\\\\&$/dollar/ +.R +.DE +looks for the character ``$'' in the current +line and replaces it by the word ``dollar''. +Were it not for the backslash, the ``$'' would have represented +``the end of the line'' in your search +rather than the character ``$''. +The backslash retains its special significance +unless it is preceded by another backslash. +.SH +Issuing \s-2UNIX\s0 commands from the editor +.PP +After creating several files with the editor, +you may want to delete files +no longer useful to you or ask for a list of your files. +Removing and listing files are not functions of the editor, +and so they require the use of \s-2UNIX\s0 system commands +(also referred to as ``shell'' commands, as +``shell'' is the name of the program that processes \s-2UNIX\s0 commands). +You do not need to quit the editor to execute a \s-2UNIX\s0 command +as long as you indicate that it +is to be sent to the shell for execution. +To use the \s-2UNIX\s0 command +.B rm +to remove the file named ``junk'' type: +.DS I 1i +:\|\fB!rm junk +.R +! +: +.DE +The exclamation mark (!) +indicates that the rest of the line is to be processed as a shell command. +If the buffer contents have not been written since the last change, +a warning will be printed before the command is executed: +.DS I 1i +[No write since last change] +.DE +The editor prints a ``!'' when the command is completed. +Other tutorials describe useful features of the system, +of which an editor is only one part. +.SH +Filenames and file manipulation +.PP +Throughout each editing session, +edit keeps track of the name of the file being edited as the +.I "current filename." +Edit remembers as the current filename the name given +when you entered the editor. +The current filename changes whenever the edit (e) command +is used to specify a new file. +Once edit has recorded a current filename, +it inserts that name into any command where a filename has been omitted. +If a write command does not specify a file, +edit, as we have seen, supplies the current filename. +If you are editing a file named ``draft3'' having 283 lines in it, +you can have the editor write onto a different file +by including its name in the write command: +.DS I 1i +:\fB\|w chapter3 +.R +"chapter3" [new file] 283 lines, 8698 characters +.DE +The current filename remembered by the editor +.I +will not be changed as a result of the write command. +.R +Thus, if the next write command +does not specify a name, +edit will write onto the current file (``draft3'') +and not onto the file ``chapter3''. +.SH +The file (f) command +.PP +To ask for the current filename, type +.B file +(or +.B f ). +In response, the editor provides current information about the buffer, +including the filename, your current position, the number of +lines in the buffer, +and the percent of the distance through the file +your current location is. +.DS I 1i +:\|\fBf +.R +"text" [Modified] line 3 of 4 --75%-- +.DE +.\"The expression ``[Edited]'' indicates that the buffer contains +.\"either the editor's copy of the existing file ``text'' +.\"or a file which you are just now creating. +If the contents of the buffer have changed +since the last time the file was written, +the editor will tell you that the file has been ``[Modified]''. +After you save the changes by writing onto a disk file, +the buffer will no longer be considered modified: +.DS I 1i +:\|\fBw +.R +"text" 4 lines, 88 characters +:\|\fBf +.R +"text" line 3 of 4 --75%-- +.DE +.SH +Reading additional files (r) +.PP +The +\f3read (r)\f1 command allows you to add the contents of a file +to the buffer +at a specified location, +essentially copying new lines +between two existing lines. +To use it, specify the line after which the new text will be placed, +the \f3read (r)\f1 command, +and then the name of the file. +If you have a file named ``example'', the command +.DS I 1i +:\|\fB$r example +.R +"example" 18 lines, 473 characters +.DE +reads the file ``example'' +and adds it to the buffer after the last line. +The current filename is not changed by the read command. +.SH +Writing parts of the buffer +.PP +The +.B +write (w) +.R +command can write all or part of the buffer +to a file you specify. +We are already familiar with +writing the entire contents of the +buffer to a disk file. +To write only part of the buffer onto a file, +indicate the beginning and ending lines before the write command, +for example +.DS I 1i +:\|\fB45,$w ending +.R +.DE +Here all lines from 45 through the end of the buffer +are written onto the file named +.I ending. +The lines remain in the buffer +as part of the document you are editing, +and you may continue to edit the entire buffer. +Your original file is unaffected +by your command to write part of the buffer +to another file. +Edit still remembers whether you have saved changes to the buffer +in your original file or not. +.SH +Recovering files +.PP +Although it does not happen very often, +there are times \s-2UNIX\s+2 stops working +because of some malfunction. +This situation is known as a \fIcrash\fR. +Under most circumstances, +edit's crash recovery feature +is able to save work to within a few lines of changes +before a crash (or an accidental phone hang up). +If you lose the contents of an editing buffer in a system crash, +you will normally receive mail when you login that gives +the name of the recovered file. +To recover the file, +enter the editor and type the command +.B recover +(\fBrec\fR), +followed by the name of the lost file. +For example, +to recover the buffer for an edit session +involving the file ``chap6'', the command is: +.DS I 1i +.R +:\|\fBrecover chap6 +.R +.DE +Recover is sometimes unable to save the entire buffer successfully, +so always check the contents of the saved buffer carefully +before writing it back onto the original file. +For best results, +write the buffer to a new file temporarily +so you can examine it without risk to the original file. +Unfortunately, +you cannot use the recover command +to retrieve a file you removed +using the shell command \f3rm\f1. +.SH +Other recovery techniques +.PP +If something goes wrong when you are using the editor, +it may be possible to save your work by using the command +.B preserve +(\fBpre\fR), +which saves the buffer as if the system had crashed. +If you are writing a file and you get the message +``Quota exceeded'', you have tried to use more disk storage +than is allotted to your account. +.I +Proceed with caution +.R +because it is likely that only a part +of the editor's buffer is now present in the file you tried to write. +In this case you should use the shell escape from the editor (!) +to remove some files you don't need and try to write +the file again. +If this is not possible and you cannot find someone to help you, +enter the command +.DS I 1i +:\|\fBpreserve +.R +.DE +and wait for the reply, +.DS I 1i +File preserved. +.DE +If you do not receive this reply, +seek help immediately. +Do not simply leave the editor. +If you do, the buffer will be lost, +and you may not be able to save your file. +If the reply is ``File preserved.'' +you can leave the editor +(or logout) +to remedy the situation. +After a preserve, you can use the recover command +once the problem has been corrected, +or the \fB\-r\fR option of the edit command +if you leave the editor and want to return. +.PP +If you make an undesirable change to the buffer +and type a write command before discovering your mistake, +the modified version will replace any previous version of the file. +Should you ever lose a good version of a document in this way, +do not panic and leave the editor. +As long as you stay in the editor, +the contents of the buffer remain accessible. +Depending on the nature of the problem, +it may be possible +to restore the buffer to a more complete +state with the undo command. +After fixing the damaged buffer, you can again write the file +to disk. +.SH +Further reading and other information +.PP +Edit is an editor designed for beginning and casual users. +It is actually a version of a more powerful editor called +.I ex. +These lessons are intended to introduce you to the editor +and its more commonly-used commands. +We have not covered all of the editor's commands, +but a selection of commands +that should be sufficient to accomplish most of your editing tasks. +You can find out more about the editor in the +.I +Ex Reference Manual, +.R +which is applicable to both +.I ex +and +.I edit. +One way to become familiar with the manual is to begin by reading +the description of commands that you already know. +.bd I 3 +.SH +Using +.I ex +.fl +.bd I +.PP +As you become more experienced with using the editor, +you may still find that edit continues to meet your needs. +However, should you become interested in using +.I ex, +it is easy to switch. +To begin an editing session with +.I ex, +use the name +.B ex +in your command instead of +.B edit. +.PP +Edit commands also work in +.I ex, +but the editing environment is somewhat different. +You should be aware of a few differences +between +.I ex +and +.I edit. +In edit, only the characters ``^'', ``$'', and ``\\'' have +special meanings in searching the buffer +or indicating characters to be changed by a substitute command. +Several additional characters have special +meanings in ex, as described in the +.I +Ex Reference Manual. +.R +Another feature of the edit environment prevents users from +accidently entering two alternative modes of editing, +.I open +and +.I visual, +in which +the editor behaves quite differently from normal command mode. +If you are using ex and you encounter strange behavior, +you may have accidently entered open mode by typing ``o''. +Type the \s-2ESC\s0 key and then a ``Q'' +to get out of open or visual mode and back into +the regular editor command mode. +The document +.I +An Introduction to Display Editing with Vi\|\| +.R +provide full details of visual mode. +.bp +.SH +.ce 1 +\s+2Index\s0 +.LP +.sp 2 +.2C +.nf +addressing, \fIsee\fR line numbers +ampersand, 20 +append mode, 6-7 +append (a) command, 6, 7, 9 +``At end of file'' (message), 18 +backslash (\\), 21 +buffer, 3 +caret (^), 10, 20 +change (c) command, 18 +command mode, 5-6 +``Command not found'' (message), 6 +context search, 10-12, 19-21 +control characters (``^'' notation), 10 +control-H, 7 +copy (co) command, 15 +corrections, 7, 16 +current filename, 21 +current line (\|.\|), 11, 17 +delete (d) command, 15-16 +dial-up, 5 +disk, 3 +documentation, 3, 23 +dollar ($), 10, 11, 17, 20-21 +dot (\f3\|.\|\f1) 11, 17 +edit (text editor), 3, 5, 23 +edit (e) command, 5, 9, 14 +editing commands: +.in +.25i +append (a), 6, 7, 9 +change (c), 18 +copy (co), 15 +delete (d), 15-16 +edit (text editor), 3, 5, 23 +edit (e), 5, 9, 14 +file (f), 21-22 +global (g), 19 +move (m), 14-15 +number (nu), 11 +preserve (pre), 22-23 +print (p), 10 +quit (q), 8, 13 +read (r), 22 +recover (rec), 22, 23 +substitute (s), 11-12, 19, 20 +undo (u), 16-17, 23 +write (w), 8, 13, 21, 22 +z, 12-13 +! (shell escape), 21 +$=, 17 ++, 17 +\-, 17 +//, 12, 20 +??, 20 +\&., 11, 17 +\&.=, 11, 17 +.in -.25i +entering text, 3, 6-7 +erasing +.in +.25i +characters (^H), 7 +lines (@), 7 +.in -.25i +error corrections, 7, 16 +ex (text editor), 23 +\fIEx Reference Manual\fR, 23 +exclamation (!), 21 +file, 3 +file (f) command, 21-22 +file recovery, 22-23 +filename, 3, 21 +global (g) command, 19 +input mode, 6-7 +Interrupt (message), 9 +line numbers, \fIsee also\fR current line +.in +.25i +dollar sign ($), 10, 11, 17 +dot (\|.\|), 11, 17 +relative (+ and \-), 17 +.in -.25i +list, 10 +logging in, 4-6 +logging out, 8 +``Login incorrect'' (message), 5 +minus (\-), 17 +move (m) command, 14-15 +``Negative address\(emfirst buffer line is 1'' (message), 18 +``No current filename'' (message), 8 +``No such file or directory'' (message), 5, 6 +``No write since last change'' (message), 21 +non-printing characters, 10 +``Nonzero address required'' (message), 18 +``Not an editor command'' (message), 6 +``Not that many lines in buffer'' (message), 18 +number (nu) command, 11 +password, 5 +period (\|.\|), 11, 17 +plus (+), 17 +preserve (pre) command, 22-23 +print (p) command, 10 +program, 3 +prompts +.in .25i +% (\s-2UNIX\s0), 5 +: (edit), 5, 6, 7 +\0 (append), 7 +.in -.25i +question (?), 20 +quit (q) command, 8, 13 +read (r) command, 22 +recover (rec) command, 22, 23 +recovery, \fIsee\fR\| file recovery +references, 3, 23 +remove (rm) command, 21, 22 +reverse command effects (undo), 16-17, 23 +searching, 10-12, 19-21 +shell, 21 +shell escape (!), 21 +slash (/), 11-12, 20 +special characters (^, $, \\), 10, 11, 17, 20-21 +substitute (s) command, 11-12, 19, 20 +terminals, 4-5 +text input mode, 7 +undo (u) command, 16-17, 23 +\s-1UNIX\s0, 3 +write (w) command, 8, 13, 21, 22 +z command, 12-13 + diff --git a/share/doc/usd/12.vi/Makefile b/share/doc/usd/12.vi/Makefile new file mode 100644 index 000000000000..9896d75fb419 --- /dev/null +++ b/share/doc/usd/12.vi/Makefile @@ -0,0 +1,4 @@ +SUBDIR= vi viapwh summary + +.include <bsd.subdir.mk> + diff --git a/share/doc/usd/12.vi/Makefile.inc b/share/doc/usd/12.vi/Makefile.inc new file mode 100644 index 000000000000..0fa6960311d4 --- /dev/null +++ b/share/doc/usd/12.vi/Makefile.inc @@ -0,0 +1,2 @@ +VOLUME= usd/12.vi +MACROS= -ms diff --git a/share/doc/usd/12.vi/summary/Makefile b/share/doc/usd/12.vi/summary/Makefile new file mode 100644 index 000000000000..16482e203b72 --- /dev/null +++ b/share/doc/usd/12.vi/summary/Makefile @@ -0,0 +1,5 @@ +DOC= summary +SRCS= vi.summary +USE_TBL= + +.include <bsd.doc.mk> diff --git a/share/doc/usd/12.vi/summary/vi.summary b/share/doc/usd/12.vi/summary/vi.summary new file mode 100644 index 000000000000..762faf154a77 --- /dev/null +++ b/share/doc/usd/12.vi/summary/vi.summary @@ -0,0 +1,466 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.ds CH +.ds CF +.de TS +.br +.if !\\n(1T .RT +.ul 0 +.ti \\n(.iu +.if t .sp 0.25 +.if n .sp +.if \\$1H .TQ +.nr IX 1 +.. +.nr PS 9 +.ps 9 +.nr VS 11 +.vs 11 +.nr HM .50i +.nr FM .25i +.nr PO 1.0i +.po 1.0i +.nr LL 4.5i +.ll 4.5i +.de nc +.bp +.. +.de h +.LG +.B +\\$1 +.R +.NL +.. +.LG +.LG +.B +.ce +Ex Quick Reference +.R +.NL +.LP +.LP +.h "Entering/leaving ex" +.TS +aw(1.4i)b aw(1.8i). +% ex \fIname\fP edit \fIname\fP, start at end +% ex +\fIn\fP \fIname\fP ... at line \fIn\fP +% ex \-t \fItag\fP start at \fItag\fP +% ex \-r list saved files +% ex \-r \fIname\fP recover file \fIname\fP +% ex \fIname\fP ... edit first; rest via \fB:n\fP +% ex \-R \fIname\fP read only mode +: x exit, saving changes +: q! exit, discarding changes +.TE +.h "Ex states" +.TS +lw(1i) lw(2.0i). +Command T{ +Normal and initial state. Input prompted for by \fB:\fP. +Your kill character cancels partial command. +T} +Insert T{ +Entered by \fBa\fP \fBi\fP and \fBc\fP. +Arbitrary text then terminates with line having only \fB.\fP +character on it or abnormally with interrupt. +T} +Open/visual T{ +Entered by \fBopen\fP or \fBvi\fP, terminates with \fBQ\fP +or ^\e. +T} +.TE +.h "Ex commands" +.TS +lw(.45i) lw(.08i)b lw(.45i) lw(.08i)b lw(.45i) lw(.08i)b. +abbrev ab next n unabbrev una +append a number nu undo u +args ar open o unmap unm +change c preserve pre version ve +copy co print p visual vi +delete d put pu write w +edit e quit q xit x +file f read re yank ya +global g recover rec \fIwindow\fP z +insert i rewind rew \fIescape\fP ! +join j set se \fIlshift\fP < +list l shell sh \fIprint next\fP \fRCR\fP +map source so \fIresubst\fP & +mark ma stop st \fIrshift\fP > +move m substitute s \fIscroll\fP ^D +.TE +.h "Ex command addresses" +.TS +lw(.3i)b lw(0.8i) lw(.3i)b lw(0.8i). +\fIn\fP line \fIn\fP /\fIpat\fP next with \fIpat\fP +\&. current ?\fIpat\fP previous with \fIpat\fP +$ last \fIx\fP-\fIn\fP \fIn\fP before \fIx\fP ++ next \fIx\fP,\fIy\fP \fIx\fP through \fIy\fP +\- previous \(aa\fIx\fP marked with \fIx\fP ++\fIn\fP \fIn\fP forward \(aa\(aa previous context +% 1,$ +.TE +.nc +.h "Specifying terminal type" +.TS +aw(1.7i)b aw(1.5i). +% setenv TERM \fItype\fP \fIcsh\fP and all version 6 +$ TERM=\fItype\fP; export TERM \fIsh\fP in Version 7 +See also \fItset\fR(1) +.TE +.h "Some terminal types" +.TS +lw(.4i) lw(.4i) lw(.4i) lw(.4i) lw(.4i). +2621 43 adm31 dw1 h19 +2645 733 adm3a dw2 i100 +300s 745 c100 gt40 mime +33 act4 dm1520 gt42 owl +37 act5 dm2500 h1500 t1061 +4014 adm3 dm3025 h1510 vt52 +.TE +.h "Initializing options" +.TS +lw(.9i)b aw(1.5i). +EXINIT place \fBset\fP's here in environment var. +set \fIx\fP enable option +set no\fIx\fP disable option +set \fIx\fP=\fIval\fP give value \fIval\fP +set show changed options +set all show all options +set \fIx\fP? show value of option \fIx\fP +.TE +.h "Useful options" +.TS +lw(.9i)b lw(.3i) lw(1.0i). +autoindent ai supply indent +autowrite aw write before changing files +ignorecase ic in scanning +lisp \fB( ) { }\fP are s-exp's +list print ^I for tab, $ at end +magic \fB. [ *\fP special in patterns +number nu number lines +paragraphs para macro names which start ... +redraw simulate smart terminal +scroll command mode lines +sections sect macro names ... +shiftwidth sw for \fB< >\fP, and input \fB^D\fP +showmatch sm to \fB)\fP and \fB}\fP as typed +slowopen slow choke updates during insert +window visual mode lines +wrapscan ws around end of buffer? +wrapmargin wm automatic line splitting +.TE +.LP +.h "Scanning pattern formation" +.TS +aw(.9i)b aw(1.0i). +\(ua beginning of line +$ end of line +\fB.\fR any character +\e< beginning of word +\e> end of word +[\fIstr\fP] any char in \fIstr\fP +[\(ua\fIstr\fP] ... not in \fIstr\fP +[\fIx\-y\fP] ... between \fIx\fP and \fIy\fP +* any number of preceding +.TE +.nc +.LP +.LG +.LG +.B +.ce +Vi Quick Reference +.NL +.R +.LP +.LP +.h "Entering/leaving vi" +.TS +aw(1.4i)b aw(1.8i). +% vi \fIname\fP edit \fIname\fP at top +% vi +\fIn\fP \fIname\fP ... at line \fIn\fP +% vi + \fIname\fP ... at end +% vi \-r list saved files +% vi \-r \fIname\fP recover file \fIname\fP +% vi \fIname\fP ... edit first; rest via \fB:n\fP +% vi \-t \fItag\fP start at \fItag\fP +% vi +/\fIpat\fP \fIname\fP search for \fIpat\fP +% view \fIname\fP read only mode +ZZ exit from vi, saving changes +^Z stop vi for later resumption +.TE +.h "The display" +.TS +lw(.75i) lw(2.2i). +Last line T{ +Error messages, echoing input to \fB: / ?\fP and \fB!\fR, +feedback about i/o and large changes. +T} +@ lines On screen only, not in file. +~ lines Lines past end of file. +^\fIx\fP Control characters, ^? is delete. +tabs Expand to spaces, cursor at last. +.TE +.LP +.h "Vi states" +.TS +lw(.75i) lw(2.2i). +Command T{ +Normal and initial state. Others return here. +ESC (escape) cancels partial command. +T} +Insert T{ +Entered by \fBa i A I o O c C s S\fP \fBR\fP. +Arbitrary text then terminates with ESC character, +or abnormally with interrupt. +T} +Last line T{ +Reading input for \fB: / ?\fP or \fB!\fP; terminate +with ESC or CR to execute, interrupt to cancel. +T} +.TE +.h "Counts before vi commands" +.TS +lw(1.5i) lw(1.7i)b. +line/column number z G | +scroll amount ^D ^U +replicate insert a i A I +repeat effect \fRmost rest\fP +.TE +.h "Simple commands" +.TS +lw(1.5i)b lw(1.7i). +dw delete a word +de ... leaving punctuation +dd delete a line +3dd ... 3 lines +i\fItext\fP\fRESC\fP insert text \fIabc\fP +cw\fInew\fP\fRESC\fP change word to \fInew\fP +ea\fIs\fP\fRESC\fP pluralize word +xp transpose characters +.TE +.nc +.h "Interrupting, cancelling" +.TS +aw(0.75i)b aw(1.6i). +ESC end insert or incomplete cmd +^? (delete or rubout) interrupts +^L reprint screen if \fB^?\fR scrambles it +.TE +.h "File manipulation" +.TS +aw(0.75i)b aw(1.6i). +:w write back changes +:wq write and quit +:q quit +:q! quit, discard changes +:e \fIname\fP edit file \fIname\fP +:e! reedit, discard changes +:e + \fIname\fP edit, starting at end +:e +\fIn\fR edit starting at line \fIn\fR +:e # edit alternate file +^\(ua synonym for \fB:e #\fP +:w \fIname\fP write file \fIname\fP +:w! \fIname\fP overwrite file \fIname\fP +:sh run shell, then return +:!\fIcmd\fP run \fIcmd\fR, then return +:n edit next file in arglist +:n \fIargs\fP specify new arglist +:f show current file and line +^G synonym for \fB:f\fP +:ta \fItag\fP to tag file entry \fItag\fP +^] \fB:ta\fP, following word is \fItag\fP +.TE +.h "Positioning within file" +.TS +aw(0.75i)b aw(1.6i). +^F forward screenfull +^B backward screenfull +^D scroll down half screen +^U scroll up half screen +G goto line (end default) +/\fIpat\fR next line matching \fIpat\fR +?\fIpat\fR prev line matching \fIpat\fR +n repeat last \fB/\fR or \fB?\fR +N reverse last \fB/\fR or \fB?\fR +/\fIpat\fP/+\fIn\fP n'th line after \fIpat\fR +?\fIpat\fP?\-\fIn\fP n'th line before \fIpat\fR +]] next section/function +[[ previous section/function +% find matching \fB( ) {\fP or \fB}\fP +.TE +.h "Adjusting the screen" +.TS +aw(0.75i)b aw(1.6i). +^L clear and redraw +^R retype, eliminate @ lines +z\fRCR\fP redraw, current at window top +z\- ... at bottom +z\|. ... at center +/\fIpat\fP/z\- \fIpat\fP line at bottom +z\fIn\fP\|. use \fIn\fP line window +^E scroll window down 1 line +^Y scroll window up 1 line +.TE +.nc +.h "Marking and returning +.TS +aw(0.5i)b aw(2.0i). +\(ga\(ga previous context +\(aa\(aa ... at first non-white in line +m\fIx\fP mark position with letter \fIx\fP +\(ga\fIx\fP to mark \fIx\fP +\(aa\fIx\fP ... at first non-white in line +.TE +.h "Line positioning" +.TS +aw(0.5i)b aw(2.0i). +H home window line +L last window line +M middle window line ++ next line, at first non-white +\- previous line, at first non-white +\fRCR\fP return, same as + +\(da \fRor\fP j next line, same column +\(ua \fRor\fP k previous line, same column +.TE +.h "Character positioning" +.TS +aw(0.5i)b aw(2.0i). +\(ua first non white +0 beginning of line +$ end of line +h \fRor\fP \(-> forward +l \fRor\fP \(<- backwards +^H same as \fB\(<-\fP +\fRspace\fP same as \fB\(->\fP +f\fIx\fP find \fIx\fP forward +F\fIx\fP \fBf\fR backward +t\fIx\fP upto \fIx\fP forward +T\fIx\fP back upto \fIx\fP +; repeat last \fBf F t\fP or \fBT\fP +, inverse of \fB;\fP +| to specified column +% find matching \fB( { )\fP or \fB}\fR +.TE +.h "Words, sentences, paragraphs" +.TS +aw(0.5i)b aw(2.0i). +w word forward +b back word +e end of word +) to next sentence +} to next paragraph +( back sentence +{ back paragraph +W blank delimited word +B back \fBW\fP +E to end of \fBW\fP +.TE +.h "Commands for \s-2LISP\s0" +.TS +aw(0.5i)b aw(2.0i). +) Forward s-expression +} ... but don't stop at atoms +( Back s-expression +{ ... but don't stop at atoms +.TE +.nc +.h "Corrections during insert" +.TS +aw(.5i)b aw(2.0i). +^H erase last character +^W erases last word +\fRerase\fP your erase, same as \fB^H\fP +\fRkill\fP your kill, erase input this line +\e escapes \fB^H\fR, your erase and kill +\fRESC\fP ends insertion, back to command +^? interrupt, terminates insert +^D backtab over \fIautoindent\fP +\(ua^D kill \fIautoindent\fP, save for next +0^D ... but at margin next also +^V quote non-printing character +.TE +.h "Insert and replace" +.TS +aw(.5i)b aw(2.0i). +a append after cursor +i insert before +A append at end of line +I insert before first non-blank +o open line below +O open above +r\fIx\fP replace single char with \fIx\fP +R replace characters +.TE +.h "Operators (double to affect lines)" +.TS +aw(0.5i)b aw(2.0i). +d delete +c change +< left shift +> right shift +! filter through command +\&= indent for \s-2LISP\s0 +y yank lines to buffer +.TE +.h "Miscellaneous operations" +.TS +aw(0.5i)b aw(2.0i). +C change rest of line +D delete rest of line +s substitute chars +S substitute lines +J join lines +x delete characters +X ... before cursor +Y yank lines +.TE +.h "Yank and put" +.TS +aw(0.5i)b aw(2.0i). +p put back lines +P put before +"\fIx\fPp put from buffer \fIx\fP +"\fIx\fPy yank to buffer \fIx\fP +"\fIx\fPd delete into buffer \fIx\fP +.TE +.h "Undo, redo, retrieve" +.TS +aw(0.5i)b aw(2.0i). +u undo last change +U restore current line +\fB.\fP repeat last change +"\fId\fP\|p retrieve \fId\fP'th last delete +.TE diff --git a/share/doc/usd/12.vi/vi/Makefile b/share/doc/usd/12.vi/vi/Makefile new file mode 100644 index 000000000000..b7281ebcdc86 --- /dev/null +++ b/share/doc/usd/12.vi/vi/Makefile @@ -0,0 +1,4 @@ +SRCS= vi.in vi.chars +USE_TBL= + +.include <bsd.doc.mk> diff --git a/share/doc/usd/12.vi/vi/vi.chars b/share/doc/usd/12.vi/vi/vi.chars new file mode 100644 index 000000000000..366cbb94f31f --- /dev/null +++ b/share/doc/usd/12.vi/vi/vi.chars @@ -0,0 +1,643 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.bd S 3 +.pn 21 +.de iP +.IP "\fB\\$1\fR" \\$2 +.. +.SH +Appendix: character functions +.PP +This appendix gives the uses the editor makes of each character. The +characters are presented in their order in the \s-2ASCII\s0 character +set: Control characters come first, then most special characters, then +the digits, upper and then lower case characters. +.PP +For each character we tell a meaning it has as a command and any meaning it +has during an insert. +If it has only meaning as a command, then only this is discussed. +Section numbers in parentheses indicate where the character is discussed; +a `f' after the section number means that the character is mentioned +in a footnote. +.iP "^@" 15 +Not a command character. +If typed as the first character of an insertion it is replaced with the +last text inserted, and the insert terminates. Only 128 characters are +saved from the last insert; if more characters were inserted the mechanism +is not available. +A \fB^@\fR cannot be part of the file due to the editor implementation +(7.5f). +.iP "^A" 15 +Unused. +.iP "^B" 15 +Backward window. +A count specifies repetition. +Two lines of continuity are kept if possible (2.1, 6.1, 7.2). +.iP "^C" 15 +Unused. +.iP "^D" 15 +As a command, scrolls down a half-window of text. +A count gives the number of (logical) lines to scroll, and is remembered +for future \fB^D\fR and \fB^U\fR commands (2.1, 7.2). +During an insert, backtabs over \fIautoindent\fR white space at the beginning +of a line (6.6, 7.5); this white space cannot be backspaced over. +.iP "^E" 15 +Exposes one more line below the current screen in the file, leaving +the cursor where it is if possible. +(Version 3 only.) +.iP "^F" 15 +Forward window. A count specifies repetition. +Two lines of continuity are kept if possible (2.1, 6.1, 7.2). +.iP "^G" 15 +Equivalent to \fB:f\fR\s-2CR\s0, printing the current file, whether +it has been modified, the current line number and the number of lines +in the file, and the percentage of the way through the file that you +are. +.iP "^H (\fR\s-2BS\s0\fP)" 15 +Same as +.B "left arrow" . +(See +.B h ). +During an insert, eliminates the last input character, backing over it +but not erasing it; it remains so you can see what you typed if you +wish to type something only slightly different (3.1, 7.5). +.iP "^I\ (\fR\s-2TAB\s0\fP)" 15 +Not a command character. +When inserted it prints as some +number of spaces. +When the cursor is at a tab character it rests at the last of the spaces +which represent the tab. +The spacing of tabstops is controlled by the \fItabstop\fR option (4.1, 6.6). +.iP "^J\ (\fR\s-2LF\s0\fP)" 15 +Same as +.B "down arrow" +(see +.B j ). +.iP "^K" 15 +Unused. +.iP "^L" 15 +The \s-2ASCII\s0 formfeed character, this causes the screen to be cleared +and redrawn. This is useful after a transmission error, if characters +typed by a program other than the editor scramble the screen, +or after output is stopped by an interrupt (5.4, 7.2f). +.ne 1i +.iP "^M\ (\fR\s-2CR\s0\fP)" 15 +A carriage return advances to the next line, at the first non-white position +in the line. Given a count, it advances that many lines (2.3). +During an insert, a \s-2CR\s0 causes the insert to continue onto +another line (3.1). +.iP "^N" 15 +Same as +.B "down arrow" +(see +.B j ). +.iP "^O" 15 +Unused. +.iP "^P" 15 +Same as +.B "up arrow" +(see +.B k ). +.iP "^Q" 15 +Not a command character. +In input mode, +.B ^Q +quotes the next character, the same as +.B ^V , +except that some teletype drivers will eat the +.B ^Q +so that the editor never sees it. +.iP "^R" 15 +Redraws the current screen, eliminating logical lines not corresponding +to physical lines (lines with only a single @ character on them). +On hardcopy terminals in \fIopen\fR mode, retypes the current line +(5.4, 7.2, 7.8). +.iP "^S" 15 +Unused. Some teletype drivers use +.B ^S +to suspend output until +.B ^Q is pressed. +.iP "^T" 15 +Not a command character. +During an insert, with \fIautoindent\fR set and at the beginning of the +line, inserts \fIshiftwidth\fR white space. +.iP "^U" 15 +Scrolls the screen up, inverting \fB^D\fR which scrolls down. Counts work as +they do for \fB^D\fR, and the previous scroll amount is common to both. +On a dumb terminal, \fB^U\fR will often necessitate clearing and redrawing +the screen further back in the file (2.1, 7.2). +.iP "^V" 15 +Not a command character. +In input mode, quotes the next character so that it is possible +to insert non-printing and special characters into the file (4.2, 7.5). +.iP "^W" 15 +Not a command character. +During an insert, backs up as \fBb\fR would in command mode; the deleted +characters remain on the display (see \fB^H\fR) (7.5). +.iP "^X" 15 +Unused. +.iP "^Y" 15 +Exposes one more line above the current screen, leaving the cursor where +it is if possible. (No mnemonic value for this key; however, it is next +to \fB^U\fR which scrolls up a bunch.) +(Version 3 only.) +.iP "^Z" 15 +If supported by the Unix system, +stops the editor, exiting to the top level shell. +Same as \fB:stop\fP\s-2CR\s0. +Otherwise, unused. +.iP "^[\ (\fR\s-2ESC\s0\fP)" 15 +Cancels a partially formed command, such as a \fBz\fR when no following +character has yet been given; terminates inputs on the last line (read +by commands such as \fB: /\fR and \fB?\fR); ends insertions of new text +into the buffer. +If an \s-2ESC\s0 is given when quiescent in command state, the editor +rings the bell or flashes the screen. You can thus hit \s-2ESC\s0 if +you don't know what is happening till the editor rings the bell. +If you don't know if you are in insert mode you can type \s-2ESC\s0\fBa\fR, +and then material to be input; the material will be inserted correctly +whether or not you were in insert mode when you started (1.5, 3.1, 7.5). +.iP "^\e" 15 +Unused. +.iP "^]" 15 +Searches for the word which is after the cursor as a tag. Equivalent +to typing \fB:ta\fR, this word, and then a \s-2CR\s0. +Mnemonically, this command is ``go right to'' (7.3). +.iP "^\(ua" 15 +Equivalent to \fB:e #\fR\s-2CR\s0, returning to the previous position +in the last edited file, or editing a file which you specified if you +got a `No write since last change diagnostic' and do not want to have +to type the file name again (7.3). +(You have to do a \fB:w\fR before \fB^\(ua\fR +will work in this case. If you do not wish to write the file you should +do \fB:e!\ #\fR\s-2CR\s0 instead.) +.iP "^_" 15 +Unused. +Reserved as the command character for the +Tektronix 4025 and 4027 terminal. +.iP "\fR\s-2SPACE\s0\fP" 15 +Same as +.B "right arrow" +(see +.B l ). +.iP "!" 15 +An operator, which processes lines from the buffer with reformatting commands. +Follow \fB!\fR with the object to be processed, and then the command name +terminated by \s-2CR\s0. Doubling \fB!\fR and preceding it by a count +causes count lines to be filtered; otherwise the count +is passed on to the object after the \fB!\fR. Thus \fB2!}\fR\fIfmt\fR\s-2CR\s0 +reformats the next two paragraphs by running them through the program +\fIfmt\fR. If you are working on \s-2LISP\s0, +the command \fB!%\fR\fIgrind\fR\s-2CR\s0,* +.FS +*Both +.I fmt +and +.I grind +are Berkeley programs and may not be present at all installations. +.FE +given at the beginning of a +function, will run the text of the function through the \s-2LISP\s0 grinder +(6.7, 7.3). +To read a file or the output of a command into the buffer use \fB:r\fR (7.3). +To simply execute a command use \fB:!\fR (7.3). +.tr " +.iP 15 +Precedes a named buffer specification. There are named buffers \fB1\-9\fR +used for saving deleted text and named buffers \fBa\-z\fR into which you can +place text (4.3, 6.3) +.tr +.iP "#" 15 +The macro character which, when followed by a number, will substitute +for a function key on terminals without function keys (6.9). +In input mode, +if this is your erase character, it will delete the last character +you typed in input mode, and must be preceded with a \fB\e\fR to insert +it, since it normally backs over the last input character you gave. +.iP "$" 15 +Moves to the end of the current line. If you \fB:se list\fR\s-2CR\s0, +then the end of each line will be shown by printing a \fB$\fR after the +end of the displayed text in the line. Given a count, advances to the +count'th following end of line; thus \fB2$\fR advances to the end of the +following line. +.iP "%" 15 +Moves to the parenthesis or brace \fB{ }\fR which balances the parenthesis +or brace at the current cursor position. +.iP "&" 15 +A synonym for \fB:&\fR\s-2CR\s0, by analogy with the +.I ex +.B & +command. +.iP "\(aa" 15 +When followed by a \fB\(aa\fR returns to the previous context at the +beginning of a line. The previous context is set whenever the current +line is moved in a non-relative way. +When followed by a letter \fBa\fR\-\fBz\fR, returns to the line which +was marked with this letter with a \fBm\fR command, at the first non-white +character in the line. (2.2, 5.3). +When used with an operator such as \fBd\fR, the operation takes place +over complete lines; if you use \fB\(ga\fR, the operation takes place +from the exact marked place to the current cursor position within the +line. +.iP "(" 15 +Retreats to the beginning of a +sentence, or to the beginning of a \s-2LISP\s0 s-expression +if the \fIlisp\fR option is set. +A sentence ends at a \fB. !\fR or \fB?\fR which is followed by either +the end of a line or by two spaces. Any number of closing \fB) ] "\fR +and \fB\(aa\fR characters may appear after the \fB. !\fR or \fB?\fR, +and before the spaces or end of line. Sentences also begin +at paragraph and section boundaries +(see \fB{\fR and \fB[[\fR below). +A count advances that many sentences (4.2, 6.8). +.iP ")" 15 +Advances to the beginning of a sentence. +A count repeats the effect. +See \fB(\fR above for the definition of a sentence (4.2, 6.8). +.iP "*" 15 +Unused. +.iP "+" 15 +Same as \s-2CR\s0 when used as a command. +.iP "," 15 +Reverse of the last \fBf F t\fR or \fBT\fR command, looking the other way +in the current line. Especially useful after hitting too many \fB;\fR +characters. A count repeats the search. +.iP "\-" 15 +Retreats to the previous line at the first non-white character. +This is the inverse of \fB+\fR and \s-2RETURN\s0. +If the line moved to is not on the screen, the screen is scrolled, or +cleared and redrawn if this is not possible. +If a large amount of scrolling would be required the screen is also cleared +and redrawn, with the current line at the center (2.3). +.iP "\&." 15 +Repeats the last command which changed the buffer. Especially useful +when deleting words or lines; you can delete some words/lines and then +hit \fB.\fR to delete more and more words/lines. +Given a count, it passes it on to the command being repeated. Thus after +a \fB2dw\fR, \fB3.\fR deletes three words (3.3, 6.3, 7.2, 7.4). +.iP "/" 15 +Reads a string from the last line on the screen, and scans forward for +the next occurrence of this string. The normal input editing sequences may +be used during the input on the bottom line; an returns to command state +without ever searching. +The search begins when you hit \s-2CR\s0 to terminate the pattern; +the cursor moves to the beginning of the last line to indicate that the search +is in progress; the search may then +be terminated with a \s-2DEL\s0 or \s-2RUB\s0, or by backspacing when +at the beginning of the bottom line, returning the cursor to +its initial position. +Searches normally wrap end-around to find a string +anywhere in the buffer. +.IP +When used with an operator the enclosed region is normally affected. +By mentioning an +offset from the line matched by the pattern you can force whole lines +to be affected. To do this give a pattern with a closing +a closing \fB/\fR and then an offset \fB+\fR\fIn\fR or \fB\-\fR\fIn\fR. +.IP +To include the character \fB/\fR in the search string, you must escape +it with a preceding \fB\e\fR. +A \fB\(ua\fR at the beginning of the pattern forces the match to occur +at the beginning of a line only; this speeds the search. A \fB$\fR at +the end of the pattern forces the match to occur at the end of a line +only. +More extended pattern matching is available, see section 7.4; +unless you set \fBnomagic\fR in your \fI\&.exrc\fR file you will have +to preceed the characters \fB. [ *\fR and \fB~\fR in the search pattern +with a \fB\e\fR to get them to work as you would naively expect (1.5, 2,2, +6.1, 7.2, 7.4). +.iP "0" 15 +Moves to the first character on the current line. +Also used, in forming numbers, after an initial \fB1\fR\-\fB9\fR. +.iP "1\-9" 15 +Used to form numeric arguments to commands (2.3, 7.2). +.iP ":" 15 +A prefix to a set of commands for file and option manipulation and escapes +to the system. Input is given on the bottom line and terminated with +an \s-2CR\s0, and the command then executed. You can return to where +you were by hitting \s-2DEL\s0 or \s-2RUB\s0 if you hit \fB:\fR accidentally +(see primarily 6.2 and 7.3). +.iP ";" 15 +Repeats the last single character find which used \fBf F t\fR or \fBT\fR. +A count iterates the basic scan (4.1). +.iP "<" 15 +An operator which shifts lines left one \fIshiftwidth\fR, normally 8 +spaces. Like all operators, affects lines when repeated, as in +\fB<<\fR. Counts are passed through to the basic object, thus \fB3<<\fR +shifts three lines (6.6, 7.2). +.iP "=" 15 +Reindents line for \s-2LISP\s0, as though they were typed in with \fIlisp\fR +and \fIautoindent\fR set (6.8). +.iP ">" 15 +An operator which shifts lines right one \fIshiftwidth\fR, normally 8 +spaces. Affects lines when repeated as in \fB>>\fR. Counts repeat the +basic object (6.6, 7.2). +.iP "?" 15 +Scans backwards, the opposite of \fB/\fR. See the \fB/\fR description +above for details on scanning (2.2, 6.1, 7.4). +.iP "@" 15 +A macro character (6.9). If this is your kill character, you must escape it with a \e +to type it in during input mode, as it normally backs over the input you +have given on the current line (3.1, 3.4, 7.5). +.iP "A" 15 +Appends at the end of line, a synonym for \fB$a\fR (7.2). +.iP "B" 15 +Backs up a word, where words are composed of non-blank sequences, placing +the cursor at the beginning of the word. A count repeats the effect +(2.4). +.iP "C" 15 +Changes the rest of the text on the current line; a synonym for \fBc$\fR. +.iP "D" 15 +Deletes the rest of the text on the current line; a synonym for \fBd$\fR. +.iP "E" 15 +Moves forward to the end of a word, defined as blanks and non-blanks, +like \fBB\fR and \fBW\fR. A count repeats the effect. +.iP "F" 15 +Finds a single following character, backwards in the current line. +A count repeats this search that many times (4.1). +.iP "G" 15 +Goes to the line number given as preceding argument, or the end of the +file if no preceding count is given. The screen is redrawn with the +new current line in the center if necessary (7.2). +.iP "H" 15 +.B "Home arrow" . +Homes the cursor to the top line on the screen. If a count is given, +then the cursor is moved to the count'th line on the screen. +In any case the cursor is moved to the first non-white character on the +line. If used as the target of an operator, full lines are affected +(2.3, 3.2). +.iP "I" 15 +Inserts at the beginning of a line; a synonym for \fB\(uai\fR. +.iP "J" 15 +Joins together lines, supplying appropriate white space: one space between +words, two spaces after a \fB.\fR, and no spaces at all if the first +character of the joined on line is \fB)\fR. A count causes that many +lines to be joined rather than the default two (6.5, 7.1f). +.iP "K" 15 +Unused. +.iP "L" 15 +Moves the cursor to the first non-white character of the last line on +the screen. With a count, to the first non-white of the count'th line +from the bottom. Operators affect whole lines when used with \fBL\fR +(2.3). +.iP "M" 15 +Moves the cursor to the middle line on the screen, at the first non-white +position on the line (2.3). +.iP "N" 15 +Scans for the next match of the last pattern given to +\fB/\fR or \fB?\fR, but in the reverse direction; this is the reverse +of \fBn\fR. +.iP "O" 15 +Opens a new line above the current line and inputs text there up to an +\s-2ESC\s0. A count can be used on dumb terminals to specify a number +of lines to be opened; this is generally obsolete, as the \fIslowopen\fR +option works better (3.1). +.iP "P" 15 +Puts the last deleted text back before/above the cursor. The text goes +back as whole lines above the cursor if it was deleted as whole lines. +Otherwise the text is inserted between the characters before and at the +cursor. May be preceded by a named buffer specification \fB"\fR\fIx\fR +to retrieve the contents of the buffer; buffers \fB1\fR\-\fB9\fR contain +deleted material, buffers \fBa\fR\-\fBz\fR are available for general +use (6.3). +.iP "Q" 15 +Quits from \fIvi\fR to \fIex\fR command mode. In this mode, whole lines +form commands, ending with a \s-2RETURN\s0. You can give all the \fB:\fR +commands; the editor supplies the \fB:\fR as a prompt (7.7). +.iP "R" 15 +Replaces characters on the screen with characters you type (overlay fashion). +Terminates with an \s-2ESC\s0. +.iP "S" 15 +Changes whole lines, a synonym for \fBcc\fR. A count substitutes for +that many lines. The lines are saved in the numeric buffers, and erased +on the screen before the substitution begins. +.iP "T" 15 +Takes a single following character, locates the character before the +cursor in the current line, and places the cursor just after that character. +A count repeats the effect. Most useful with operators such as \fBd\fR +(4.1). +.iP "U" 15 +Restores the current line to its state before you started changing it +(3.5). +.iP "V" 15 +Unused. +.iP "W" 15 +Moves forward to the beginning of a word in the current line, +where words are defined as sequences of blank/non-blank characters. +A count repeats the effect (2.4). +.iP "X" 15 +Deletes the character before the cursor. A count repeats the effect, +but only characters on the current line are deleted. +.iP "Y" 15 +Yanks a copy of the current line into the unnamed buffer, to be put back +by a later \fBp\fR or \fBP\fR; a very useful synonym for \fByy\fR. +A count yanks that many lines. May be preceded by a buffer name to put +lines in that buffer (7.4). +.iP "ZZ" 15 +Exits the editor. +(Same as \fB:x\fP\s-2CR\s0.) +If any changes have been made, the buffer is written out to the current file. +Then the editor quits. +.iP "[[" 15 +Backs up to the previous section boundary. A section begins at each +macro in the \fIsections\fR option, +normally a `.NH' or `.SH' and also at lines which which start +with a formfeed \fB^L\fR. Lines beginning with \fB{\fR also stop \fB[[\fR; +this makes it useful for looking backwards, a function at a time, in C +programs. If the option \fIlisp\fR is set, stops at each \fB(\fR at the +beginning of a line, and is thus useful for moving backwards at the top +level \s-2LISP\s0 objects. (4.2, 6.1, 6.6, 7.2). +.iP "\e" 15 +Unused. +.iP "]]" 15 +Forward to a section boundary, see \fB[[\fR for a definition (4.2, 6.1, +6.6, 7.2). +.iP "\(ua" 15 +Moves to the first non-white position on the current line (4.4). +.iP "_" 15 +Unused. +.iP "\(ga" 15 +When followed by a \fB\(ga\fR returns to the previous context. +The previous context is set whenever the current +line is moved in a non-relative way. +When followed by a letter \fBa\fR\-\fBz\fR, returns to the position which +was marked with this letter with a \fBm\fR command. +When used with an operator such as \fBd\fR, the operation takes place +from the exact marked place to the current position within the line; +if you use \fB\(aa\fR, the operation takes place over complete lines +(2.2, 5.3). +.iP "a" 15 +Appends arbitrary text after the current cursor position; the insert +can continue onto multiple lines by using \s-2RETURN\s0 within the insert. +A count causes the inserted text to be replicated, but only if the inserted +text is all on one line. +The insertion terminates with an \s-2ESC\s0 (3.1, 7.2). +.iP "b" 15 +Backs up to the beginning of a word in the current line. A word is a +sequence of alphanumerics, or a sequence of special characters. +A count repeats the effect (2.4). +.iP "c" 15 +An operator which changes the following object, replacing it with the +following input text up to an \s-2ESC\s0. If more than part of a single +line is affected, the text which is changed away is saved in the numeric named +buffers. If only part of the current line is affected, then the last +character to be changed away is marked with a \fB$\fR. +A count causes that many objects to be affected, thus both +\fB3c)\fR and \fBc3)\fR change the following three sentences (7.4). +.iP "d" 15 +An operator which deletes the following object. If more than part of +a line is affected, the text is saved in the numeric buffers. +A count causes that many objects to be affected; thus \fB3dw\fR is the +same as \fBd3w\fR (3.3, 3.4, 4.1, 7.4). +.iP "e" 15 +Advances to the end of the next word, defined as for \fBb\fR and \fBw\fR. +A count repeats the effect (2.4, 3.1). +.iP "f" 15 +Finds the first instance of the next character following the cursor on +the current line. A count repeats the find (4.1). +.iP "g" 15 +Unused. +.sp +Arrow keys +.B h , +.B j , +.B k , +.B l , +and +.B H . +.iP "h" 15 +.B "Left arrow" . +Moves the cursor one character to the left. +Like the other arrow keys, either +.B h , +the +.B "left arrow" +key, or one of the synonyms (\fB^H\fP) has the same effect. +On v2 editors, arrow keys on certain kinds of terminals +(those which send escape sequences, such as vt52, c100, or hp) +cannot be used. +A count repeats the effect (3.1, 7.5). +.iP "i" 15 +Inserts text before the cursor, otherwise like \fBa\fR (7.2). +.iP "j" 15 +.B "Down arrow" . +Moves the cursor one line down in the same column. +If the position does not exist, +.I vi +comes as close as possible to the same column. +Synonyms include +.B ^J +(linefeed) and +.B ^N . +.iP "k" 15 +.B "Up arrow" . +Moves the cursor one line up. +.B ^P +is a synonym. +.iP "l" 15 +.B "Right arrow" . +Moves the cursor one character to the right. +\s-2SPACE\s0 is a synonym. +.iP "m" 15 +Marks the current position of the cursor in the mark register which is +specified by the next character \fBa\fR\-\fBz\fR. Return to this position +or use with an operator using \fB\(ga\fR or \fB\(aa\fR (5.3). +.iP "n" 15 +Repeats the last \fB/\fR or \fB?\fR scanning commands (2.2). +.iP "o" 15 +Opens new lines below the current line; otherwise like \fBO\fR (3.1). +.iP "p" 15 +Puts text after/below the cursor; otherwise like \fBP\fR (6.3). +.iP "q" 15 +Unused. +.iP "r" 15 +Replaces the single character at the cursor with a single character you +type. The new character may be a \s-2RETURN\s0; this is the easiest +way to split lines. A count replaces each of the following count characters +with the single character given; see \fBR\fR above which is the more +usually useful iteration of \fBr\fR (3.2). +.iP "s" 15 +Changes the single character under the cursor to the text which follows +up to an \s-2ESC\s0; given a count, that many characters from the current +line are changed. The last character to be changed is marked with \fB$\fR +as in \fBc\fR (3.2). +.iP "t" 15 +Advances the cursor upto the character before the next character typed. +Most useful with operators such as \fBd\fR and \fBc\fR to delete the +characters up to a following character. You can use \fB.\fR to delete +more if this doesn't delete enough the first time (4.1). +.iP "u" 15 +Undoes the last change made to the current buffer. If repeated, will +alternate between these two states, thus is its own inverse. When used +after an insert which inserted text on more than one line, the lines are +saved in the numeric named buffers (3.5). +.iP "v" 15 +Unused. +.iP "w" 15 +Advances to the beginning of the next word, as defined by \fBb\fR (2.4). +.iP "x" 15 +Deletes the single character under the cursor. With a count deletes +deletes that many characters forward from the cursor position, but only +on the current line (6.5). +.iP "y" 15 +An operator, yanks the following object into the unnamed temporary buffer. +If preceded by a named buffer specification, \fB"\fR\fIx\fR, the text +is placed in that buffer also. Text can be recovered by a later \fBp\fR +or \fBP\fR (7.4). +.iP "z" 15 +Redraws the screen with the current line placed as specified by the following +character: \s-2RETURN\s0 specifies the top of the screen, \fB.\fR the +center of the screen, and \fB\-\fR at the bottom of the screen. +A count may be given after the \fBz\fR and before the following character +to specify the new screen size for the redraw. +A count before the \fBz\fR gives the number of the line to place in the +center of the screen instead of the default current line. (5.4) +.iP "{" 15 +Retreats to the beginning of the beginning of the preceding paragraph. +A paragraph begins at each macro in the \fIparagraphs\fR option, normally +`.IP', `.LP', `.PP', `.QP' and `.bp'. +A paragraph also begins after a completely +empty line, and at each section boundary (see \fB[[\fR above) (4.2, 6.8, +7.6). +.iP "|" 15 +Places the cursor on the character in the column specified +by the count (7.1, 7.2). +.iP "}" 15 +Advances to the beginning of the next paragraph. See \fB{\fR for the +definition of paragraph (4.2, 6.8, 7.6). +.iP "~" 15 +Unused. +.iP "^?\ (\s-2\fRDEL\fP\s0)" 15 +Interrupts the editor, returning it to command accepting state (1.5, +7.5) +.bp +\&. diff --git a/share/doc/usd/12.vi/vi/vi.in b/share/doc/usd/12.vi/vi/vi.in new file mode 100644 index 000000000000..566ba3b37d8d --- /dev/null +++ b/share/doc/usd/12.vi/vi/vi.in @@ -0,0 +1,2072 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr LL 6.5i +.nr FL 6.5i +.EH 'USD:11-%''An Introduction to Display Editing with Vi' +.OH 'An Introduction to Display Editing with Vi''USD:11-%' +.bd S 3 +.if t .ds dg \(dg +.if n .ds dg + +.if t .ds dd \(dd +.if n .ds dd ++ +.\".RP +.TL +An Introduction to Display Editing with Vi +.AU +William Joy +.AU +Mark Horton +.AI +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, Ca. 94720 +.AB +.PP +.I Vi +(visual) is a display oriented interactive text editor. +When using +.I vi +the screen of your terminal acts as a window into the file which you +are editing. Changes which you make to the file are reflected +in what you see. +.PP +Using +.I vi +you can insert new text any place in the file quite easily. +Most of the commands to +.I vi +move the cursor around in the file. +There are commands to move the cursor +forward and backward in units of characters, words, +sentences and paragraphs. +A small set of operators, like +.B d +for delete and +.B c +for change, are combined with the motion commands to form operations +such as delete word or change paragraph, in a simple and natural way. +This regularity and the mnemonic assignment of commands to keys makes the +editor command set easy to remember and to use. +.PP +.I Vi +will work on a large number of display terminals, +and new terminals are easily driven after editing a terminal description file. +While it is advantageous to have an intelligent terminal which can locally +insert and delete lines and characters from the display, the editor will +function quite well on dumb terminals over slow phone lines. +The editor makes allowance for the low bandwidth in these situations +and uses smaller window sizes and +different display updating algorithms to make best use of the +limited speed available. +.PP +It is also possible to use the command set of +.I vi +on hardcopy terminals, storage tubes and ``glass tty's'' using a one line +editing window; thus +.I vi's +command set is available on all terminals. +The full command set of the more traditional, line +oriented editor +.I ex +is available within +.I vi; +it is quite simple to switch between the two modes of editing. +.AE +.NH 1 +Getting started +.PP +.FS +The financial support of an \s-2IBM\s0 Graduate Fellowship and the +National Science Foundation under grants MCS74-07644-A03 and MCS78-07291 +is gratefully acknowledged. +.FE +This document provides a quick introduction to +.I vi. +(Pronounced \fIvee-eye\fP.) +You should be running +.I vi +on a file you are familiar with while you are reading this. +The first part of this document (sections 1 through 5) +describes the basics of using +.I vi. +Some topics of special interest are presented in section 6, and +some nitty-gritty details of how the editor functions are saved for section +7 to avoid cluttering the presentation here. +.PP +There is also a short appendix here, which gives for each character the +special meanings which this character has in \fIvi\fR. Attached to +this document should be a quick reference card. +This card summarizes the commands of +.I vi +in a very compact format. You should have the card handy while you are +learning +.I vi. +.NH 2 +Specifying terminal type +.PP +Before you can start +.I vi +you must tell the system what kind of terminal you are using. +Here is a (necessarily incomplete) list of terminal type codes. +If your terminal does not appear here, you should consult with one of +the staff members on your system to find out the code for your terminal. +If your terminal does not have a code, one can be assigned and a description +for the terminal can be created. +.LP +.TS +center; +ab ab ab +a a a. +Code Full name Type +_ +2621 Hewlett-Packard 2621A/P Intelligent +2645 Hewlett-Packard 264x Intelligent +act4 Microterm ACT-IV Dumb +act5 Microterm ACT-V Dumb +adm3a Lear Siegler ADM-3a Dumb +adm31 Lear Siegler ADM-31 Intelligent +c100 Human Design Concept 100 Intelligent +dm1520 Datamedia 1520 Dumb +dm2500 Datamedia 2500 Intelligent +dm3025 Datamedia 3025 Intelligent +fox Perkin-Elmer Fox Dumb +h1500 Hazeltine 1500 Intelligent +h19 Heathkit h19 Intelligent +i100 Infoton 100 Intelligent +mime Imitating a smart act4 Intelligent +t1061 Teleray 1061 Intelligent +vt52 Dec VT-52 Dumb +.TE +.PP +Suppose for example that you have a Hewlett-Packard HP2621A +terminal. The code used by the system for this terminal is `2621'. +In this case you can use one of the following commands to tell the system +the type of your terminal: +.DS +% \fBsetenv TERM\fP 2621 +.DE +This command works with the +.I csh +shell. +If you are using the standard Bourne shell +.I sh +then you should give the commands +.DS +$ \fBTERM=\fP2621 +$ \fBexport TERM\fP +.DE +.PP +If you want to arrange to have your terminal type set up automatically +when you log in, you can use the +.I tset +program. +If you dial in on a +.I mime , +but often use hardwired ports, a typical line for your +.I .login +file (if you use csh) would be +.DS +\fBsetenv TERM \(gatset\fP \- \-d mime\(ga +.DE +or for your +.I .profile +file (if you use sh) +.DS +\fBTERM=\(gatse\fPt \- \-d mime\(ga +.DE +.I Tset +knows which terminals are hardwired to each port +and needs only to be told that when you dial in you +are probably on a +.I mime . +.I Tset +is usually used to change the erase and kill characters, too. +.NH 2 +Editing a file +.PP +After telling the system which kind of terminal you have, you should +make a copy of a file you are familiar with, and run +.I vi +on this file, giving the command +.DS +% \fBvi\fR \fIname\fR +.DE +replacing \fIname\fR with the name of the copy file you just created. +The screen should clear and the text of your file should appear on the +screen. If something else happens refer to the footnote.\*(dd +.FS +\*(dd If you gave the system an incorrect terminal type code then the +editor may have just made a mess out of your screen. This happens when +it sends control codes for one kind of terminal to some other +kind of terminal. In this case hit +the keys \fB:q\fR (colon and the q key) and then hit the \s-2RETURN\s0 key. +This should get you back to the command level interpreter. +Figure out what you did wrong (ask someone else if necessary) and try again. + Another thing which can go wrong is that you typed the wrong file name and +the editor just printed an error diagnostic. In this case you should +follow the above procedure for getting out of the editor, and try again +this time spelling the file name correctly. + If the editor doesn't seem to respond to the commands which you type +here, try sending an interrupt to it by hitting the \s-2DEL\s0 or \s-2RUB\s0 +key on your terminal, and then hitting the \fB:q\fR command again followed +by a carriage return. +.sp +.FE +.NH 2 +The editor's copy: the buffer +.PP +The editor does not directly modify the file which you are editing. +Rather, the editor makes a copy of this file, in a place called the +.I buffer, +and remembers the file's +name. You do not affect the contents of the file unless and until you +write the changes you make back into the original file. +.NH 2 +Notational conventions +.PP +In our examples, input which must be typed as is will be presented in +\fBbold face\fR. Text which should be replaced with appropriate input +will be given in \fIitalics\fR. We will represent special characters +in \s-2SMALL CAPITALS\s0. +.NH 2 +Arrow keys +.PP +The editor command set is independent of the terminal +you are using. On most terminals with cursor positioning keys, these keys +will also work within the editor. +If you don't have cursor positioning keys, or even if you do, you can use +the \fBh j k\fR and \fBl\fR keys as cursor positioning +keys (these are labelled with arrows on an +.I adm3a).* +.PP +(Particular note for the HP2621: on this terminal the function keys +must be \fIshifted\fR (ick) to send to the machine, otherwise they +only act locally. Unshifted use will leave the cursor positioned +incorrectly.) +.FS +* As we will see later, +.I h +moves back to the left (like control-h which is a backspace), +.I j +moves down (in the same column), +.I k +moves up (in the same column), +and +.I l +moves to the right. +.FE +.NH 2 +Special characters: \s-2ESC\s0, \s-2CR\s0 and \s-2DEL\s0 +.PP +Several of these special characters are very important, so be sure to +find them right now. Look on your keyboard for a key labelled \s-2ESC\s0 +or \s-2ALT\s0. It should be near the upper left corner of your terminal. +Try hitting this key a few times. The editor will ring the bell +to indicate that it is in a quiescent state.\*(dd +.FS +\*(dd On smart terminals where it is possible, the editor will quietly +flash the screen rather than ringing the bell. +.FE +Partially formed commands are cancelled by \s-2ESC\s0, and when you insert +text in the file you end the text insertion +with \s-2ESC\s0. This key is a fairly +harmless one to hit, so you can just hit it if you don't know +what is going on until the editor rings the bell. +.PP +The \s-2CR\s0 or \s-2RETURN\s0 key is important because it is used +to terminate certain commands. +It is usually at the right side of the keyboard, +and is the same command used at the end of each shell command. +.PP +Another very useful key is the \s-2DEL\s0 or \s-2RUB\s0 key, which generates +an interrupt, telling the editor to stop what it is doing. +It is a forceful way of making the editor listen +to you, or to return it to the quiescent state if you don't know or don't +like what is going on. Try hitting the `/' key on your terminal. This +key is used when you want to specify a string to be searched for. The +cursor should now be positioned at the bottom line of the terminal after +a `/' printed as a prompt. You can get the cursor back to the current +position by hitting the \s-2DEL\s0 or \s-2RUB\s0 key; try this now.* +.FS +* Backspacing over the `/' will also cancel the search. +.FE +From now on we will simply refer to hitting the \s-2DEL\s0 or \s-2RUB\s0 +key as ``sending an interrupt.''** +.FS +** On some systems, this interruptibility comes at a price: you cannot type +ahead when the editor is computing with the cursor on the bottom line. +.FE +.PP +The editor often echoes your commands on the last line of the terminal. +If the cursor is on the first position of this last line, then the editor +is performing a computation, such as computing a new position in the +file after a search or running a command to reformat part of the buffer. +When this is happening you can stop the editor by +sending an interrupt. +.NH 2 +Getting out of the editor +.PP +After you have worked with this introduction for a while, and you wish +to do something else, you can give the command \fBZZ\fP +to the editor. +This will write the contents of the editor's buffer back into +the file you are editing, if you made any changes, and then quit from +the editor. You can also end an editor +session by giving the command \fB:q!\fR\s-2CR\s0;\*(dg +.FS +\*(dg All commands which read from the last display line can also be +terminated with a \s-2ESC\s0 as well as an \s-2CR\s0. +.FE +this is a dangerous but occasionally essential +command which ends the editor session and discards all your changes. +You need to know about this command in case you change the editor's +copy of a file you wish only to look at. Be very careful +not to give this command when you really want to save +the changes you have made. +.NH 1 +Moving around in the file +.NH 2 +Scrolling and paging +.PP +The editor has a number of commands for moving around in the file. +The most useful of these is generated by hitting the control and D keys +at the same time, a control-D or `^D'. We will use this two character +notation for referring to these control keys from now on. You may have +a key labelled `^' on your terminal. This key will be represented as `\(ua' +in this document; `^' is exclusively used as part of the `^x' notation +for control characters.\*(dd +.FS +\*(dd If you don't have a `^' key on your terminal +then there is probably a key labelled `\(ua'; in any case these characters +are one and the same. +.FE +.PP +As you know now if you tried hitting \fB^D\fR, this command scrolls down in +the file. The \fBD\fR thus stands for down. Many editor commands are mnemonic +and this makes them much easier to remember. For instance the command +to scroll up is \fB^U\fR. Many dumb terminals can't scroll up at all, in which +case hitting \fB^U\fR clears the screen and refreshes it +with a line which is farther back in the file at the top. +.PP +If you want to see more of the file below where you are, you can +hit \fB^E\fR to expose one more line at the bottom of the screen, +leaving the cursor where it is. +The command \fB^Y\fR (which is hopelessly non-mnemonic, but next to \fB^U\fR +on the keyboard) exposes one more line at the top of the screen. +.PP +There are other ways to move around in the file; the keys \fB^F\fR and \fB^B\fR +move forward and backward a page, +keeping a couple of lines of continuity between screens +so that it is possible to read through a file using these rather than +\fB^D\fR and \fB^U\fR if you wish. +.PP +Notice the difference between scrolling and paging. If you are trying +to read the text in a file, hitting \fB^F\fR to move forward a page +will leave you only a little context to look back at. Scrolling on the +other hand leaves more context, and happens more smoothly. You can continue +to read the text as scrolling is taking place. +.NH 2 +Searching, goto, and previous context +.PP +Another way to position yourself in the file is by giving the editor a string +to search for. Type the character \fB/\fR followed by a string of characters +terminated by \s-2CR\s0. The editor will position the cursor +at the next occurrence of this string. +Try hitting \fBn\fR to then go to the next occurrence of this string. +The character \fB?\fR will search backwards from where you are, and is +otherwise like \fB/\fR.\*(dg +.FS +\*(dg These searches will normally wrap around the end of the file, and thus +find the string even if it is not on a line in the direction you search +provided it is anywhere else in the file. You can disable this wraparound +in scans by giving the command \fB:se nowrapscan\fR\s-2CR\s0, +or more briefly \fB:se nows\fR\s-2CR\s0. +.FE +.PP +If the search string you give the editor is not present in the +file the editor will print +a diagnostic on the last line of the screen, and the cursor will be returned +to its initial position. +.PP +If you wish the search to match only at the beginning of a line, begin +the search string with an \fB\(ua\fR. To match only at the end of +a line, end the search string with a \fB$\fR. +Thus \fB/\(uasearch\fR\s-2CR\s0 will search for the word `search' at +the beginning of a line, and \fB/last$\fR\s-2CR\s0 searches for the +word `last' at the end of a line.* +.FS +*Actually, the string you give to search for here can be a +.I "regular expression" +in the sense of the editors +.I ex (1) +and +.I ed (1). +If you don't wish to learn about this yet, you can disable this more +general facility by doing +\fB:se\ nomagic\fR\s-2CR\s0; +by putting this command in +EXINIT +in your environment, you can have this always be in effect (more +about +.I EXINIT +later.) +.FE +.PP +The command \fBG\fR, when preceded by a number will position the cursor +at that line in the file. +Thus \fB1G\fR will move the cursor to +the first line of the file. If you give \fBG\fR no count, then it moves +to the end of the file. +.PP +If you are near the end of the file, and the last line is not at the bottom +of the screen, the editor will place only the character `~' on each remaining +line. This indicates that the last line in the file is on the screen; +that is, the `~' lines are past the end of the file. +.PP +You can find out the state of the file you are editing by typing a \fB^G\fR. +The editor will show you the name of the file you are editing, the number +of the current line, the number of lines in the buffer, and the percentage +of the way through the buffer which you are. +Try doing this now, and remember the number of the line you are on. +Give a \fBG\fR command to get to the end and then another \fBG\fR command +to get back where you were. +.PP +You can also get back to a previous position by using the command +\fB\(ga\(ga\fR (two back quotes). +This is often more convenient than \fBG\fR because it requires no advance +preparation. +Try giving a \fBG\fR or a search with \fB/\fR or \fB?\fR and then a +\fB\(ga\(ga\fR to get back to where you were. If you accidentally hit +\fBn\fR or any command which moves you far away from a context of interest, you +can quickly get back by hitting \fB\(ga\(ga\fR. +.NH 2 +Moving around on the screen +.PP +Now try just moving the cursor around on the screen. +If your terminal has arrow keys (4 or 5 keys with arrows +going in each direction) try them and convince yourself +that they work. +If you don't have working arrow keys, you can always use +.B h , +.B j , +.B k , +and +.B l . +Experienced users of +.I vi +prefer these keys to arrow keys, +because they are usually right underneath their fingers. +.PP +Hit the \fB+\fR key. Each time you do, notice that the cursor +advances to the next line in the file, at the first non-white position +on the line. The \fB\-\fR key is like \fB+\fR but goes the other way. +.PP +These are very common keys for moving up and down lines in the file. +Notice that if you go off the bottom or top with these keys then the +screen will scroll down (and up if possible) to bring a line at a time +into view. The \s-2RETURN\s0 key has the same effect as the \fB+\fR +key. +.PP +.I Vi +also has commands to take you to the top, middle and bottom of the screen. +\fBH\fR will take you to the top (home) line on the screen. +Try preceding it with a +number as in \fB3H\fR. +This will take you to the third line on the screen. +Many +.I vi +commands take preceding numbers and do interesting things with them. +Try \fBM\fR, +which takes you to the middle line on the screen, +and \fBL\fR, +which takes you to the last line on the screen. +\fBL\fR also takes counts, thus +\fB5L\fR will take you to the fifth line from the bottom. +.NH 2 +Moving within a line +.PP +Now try picking a word on some line on the screen, not the +first word on the line. +move the cursor using \s-2RETURN\s0 and \fB\-\fR to be on the line where +the word is. +Try hitting the \fBw\fR key. This will advance the cursor to the +next word on the line. +Try hitting the \fBb\fR key to back up words +in the line. +Also try the \fBe\fR key which advances you to the end of the current +word rather than to the beginning of the next word. +Also try \s-2SPACE\s0 (the space bar) which moves right one character +and the \s-2BS\s0 (backspace or \fB^H\fR) key which moves left one character. +The key \fBh\fR works as \fB^H\fR does and is useful if you don't have +a \s-2BS\s0 key. +(Also, as noted just above, \fBl\fR will move to the right.) +.PP +If the line had punctuation in it you may have noticed that +that the \fBw\fR and \fBb\fR +keys stopped at each group of punctuation. You can also go back and +forwards words without stopping at punctuation by using \fBW\fR and \fBB\fR +rather than the lower case equivalents. Think of these as bigger words. +Try these on a few lines with punctuation to see how they differ from +the lower case \fBw\fR and \fBb\fR. +.PP +The word keys wrap around the end of line, +rather than stopping at the end. Try moving to a word on a line below +where you are by repeatedly hitting \fBw\fR. +.NH 2 +Summary +.IP +.TS +lw(.50i)b a. +\fR\s-2SPACE\s0\fP advance the cursor one position +^B backwards to previous page +^D scrolls down in the file +^E exposes another line at the bottom +^F forward to next page +^G tell what is going on +^H backspace the cursor +^N next line, same column +^P previous line, same column +^U scrolls up in the file +^Y exposes another line at the top ++ next line, at the beginning +\- previous line, at the beginning +/ scan for a following string forwards +? scan backwards +B back a word, ignoring punctuation +G go to specified line, last default +H home screen line +M middle screen line +L last screen line +W forward a word, ignoring punctuation +b back a word +e end of current word +n scan for next instance of \fB/\fR or \fB?\fR pattern +w word after this word +.TE +.NH 2 +View +.PP +If you want to use the editor to look at a file, +rather than to make changes, +invoke it as +.I view +instead of +.I vi . +This will set the +.I readonly +option which will prevent you from +accidently overwriting the file. +.sp +.NH 1 +Making simple changes +.NH 2 +Inserting +.PP +One of the most useful commands is the +\fBi\fR (insert) command. +After you type \fBi\fR, everything you type until you hit \s-2ESC\s0 +is inserted into the file. +Try this now; position yourself to some word in the file and try inserting +text before this word. +If you are on an dumb terminal it will seem, for a minute, +that some of the characters in your line have been overwritten, but they will +reappear when you hit \s-2ESC\s0. +.PP +Now try finding a word which can, but does not, end in an `s'. +Position yourself at this word and type \fBe\fR (move to end of word), then +\fBa\fR for append and then `s\s-2ESC\s0' to terminate the textual insert. +This sequence of commands can be used to easily pluralize a word. +.PP +Try inserting and appending a few times to make sure you understand how +this works; \fBi\fR placing text to the left of the cursor, \fBa\fR to +the right. +.PP +It is often the case that you want to add new lines to the file you are +editing, before or after some specific line in the file. Find a line +where this makes sense and then give the command \fBo\fR to create a +new line after the line you are on, or the command \fBO\fR to create +a new line before the line you are on. After you create a new line in +this way, text you type up to an \s-2ESC\s0 is inserted on the new line. +.PP +Many related editor commands +are invoked by the same letter key and differ only in that one is given +by a lower +case key and the other is given by +an upper case key. In these cases, the +upper case key often differs from the lower case key in its sense of +direction, with +the upper case key working backward and/or up, while the lower case +key moves forward and/or down. +.PP +Whenever you are typing in text, you can give many lines of input or +just a few characters. +To type in more than one line of text, +hit a \s-2RETURN\s0 at the middle of your input. A new line will be created +for text, and you can continue to type. If you are on a slow +and dumb terminal the editor may choose to wait to redraw the +tail of the screen, and will let you type over the existing screen lines. +This avoids the lengthy delay which would occur if the editor attempted +to keep the tail of the screen always up to date. The tail of the screen will +be fixed up, and the missing lines will reappear, when you hit \s-2ESC\s0. +.PP +While you are inserting new text, you can use the characters you normally use +at the system command level (usually \fB^H\fR or \fB#\fR) to backspace +over the last +character which you typed, and the character which you use to kill input lines +(usually \fB@\fR, \fB^X\fR, or \fB^U\fR) +to erase the input you have typed on the current line.\*(dg +.FS +\*(dg In fact, the character \fB^H\fR (backspace) always works to erase the +last input character here, regardless of what your erase character is. +.FE +The character \fB^W\fR +will erase a whole word and leave you after the space after the previous +word; it is useful for quickly backing up in an insert. +.PP +Notice that when you backspace during an insertion the characters you +backspace over are not erased; the cursor moves backwards, and the characters +remain on the display. This is often useful if you are planning to type +in something similar. In any case the characters disappear when when +you hit \s-2ESC\s0; if you want to get rid of them immediately, hit an +\s-2ESC\s0 and then \fBa\fR again. +.PP +Notice also that you can't erase characters which you didn't insert, and that +you can't backspace around the end of a line. If you need to back up +to the previous line to make a correction, just hit \s-2ESC\s0 and move +the cursor back to the previous line. After making the correction you +can return to where you were and use the insert or append command again. +.sp .5 +.NH 2 +Making small corrections +.PP +You can make small corrections in existing text quite easily. +Find a single character which is wrong or just pick any character. +Use the arrow keys to find the character, or +get near the character with the word motion keys and then either +backspace (hit the \s-2BS\s0 key or \fB^H\fR or even just \fBh\fR) or +\s-2SPACE\s0 (using the space bar) +until the cursor is on the character which is wrong. +If the character is not needed then hit the \fBx\fP key; this deletes +the character from the file. It is analogous to the way you \fBx\fP +out characters when you make mistakes on a typewriter (except it's not +as messy). +.PP +If the character +is incorrect, you can replace it with the correct character by giving +the command \fBr\fR\fIc\fR, +where \fIc\fR is replaced by the correct character. +Finally if the character which is incorrect should be replaced +by more than one character, give the command \fBs\fR which substitutes +a string of characters, ending with \s-2ESC\s0, for it. +If there are a small number of characters +which are wrong you can precede \fBs\fR with a count of the number of +characters to be replaced. Counts are also useful with \fBx\fR to specify +the number of characters to be deleted. +.NH 2 +More corrections: operators +.PP +You already know almost enough to make changes at a higher level. +All you need to know now is that the +.B d +key acts as a delete operator. Try the command +.B dw +to delete a word. +Try hitting \fB.\fR a few times. Notice that this repeats the effect +of the \fBdw\fR. The command \fB.\fR repeats the last command which +made a change. You can remember it by analogy with an ellipsis `\fB...\fR'. +.PP +Now try +\fBdb\fR. +This deletes a word backwards, namely the preceding word. +Try +\fBd\fR\s-2SPACE\s0. This deletes a single character, and is equivalent +to the \fBx\fR command. +.PP +Another very useful operator is +.B c +or change. The command +.B cw +thus changes the text of a single word. +You follow it by the replacement text ending with an \s-2ESC\s0. +Find a word which you can change to another, and try this +now. +Notice that the end of the text to be changed was marked with the character +`$' so that you can see this as you are typing in the new material. +.sp .5 +.NH 2 +Operating on lines +.PP +It is often the case that you want to operate on lines. +Find a line which you want to delete, and type +\fBdd\fR, +the +.B d +operator twice. This will delete the line. +If you are on a dumb terminal, the editor may just erase the line on +the screen, replacing it with a line with only an @ on it. This line +does not correspond to any line in your file, but only acts as a place +holder. It helps to avoid a lengthy redraw of the rest of the screen +which would be necessary to close up the hole created by the deletion +on a terminal without a delete line capability. +.PP +Try repeating the +.B c +operator twice; this will change a whole line, erasing its previous contents and +replacing them with text you type up to an \s-2ESC\s0.\*(dg +.FS +\*(dg The command \fBS\fR is a convenient synonym for for \fBcc\fR, by +analogy with \fBs\fR. Think of \fBS\fR as a substitute on lines, while +\fBs\fR is a substitute on characters. +.FE +.PP +You can delete or change more than one line by preceding the +.B dd +or +.B cc +with a count, i.e. \fB5dd\fR deletes 5 lines. +You can also give a command like \fBdL\fR to delete all the lines up to +and including +the last line on the screen, or \fBd3L\fR to delete through the third from +the bottom line. Try some commands like this now.* +.FS +* One subtle point here involves using the \fB/\fR search after a \fBd\fR. +This will normally delete characters from the current position to the +point of the match. If what is desired is to delete whole lines +including the two points, give the pattern as \fB/pat/+0\fR, a line address. +.FE +Notice that the editor lets you know when you change a large number of +lines so that you can see the extent of the change. +The editor will also always tell you when a change you make affects text which +you cannot see. +.NH 2 +Undoing +.PP +Now suppose that the last change which you made was incorrect; +you could use the insert, delete and append commands to put the correct +material back. However, since it is often the case that we regret a +change or make a change incorrectly, the editor provides a +.B u +(undo) command to reverse the last change which you made. +Try this a few times, and give it twice in a row to notice that an +.B u +also undoes a +.B u. +.PP +The undo command lets you reverse only a single change. After you make +a number of changes to a line, you may decide that you would rather have +the original state of the line back. The +.B U +command restores the current line to the state before you started changing +it. +.PP +You can recover text which you delete, even if +undo will not bring it back; see the section on recovering lost text +below. +.NH 2 +Summary +.IP +.TS +lw(.50i)b a. +\fR\s-2SPACE\s0\fP advance the cursor one position +^H backspace the cursor +^W erase a word during an insert +\fRerase\fP your erase (usually ^H or #), erases a character during an insert +\fRkill\fP your kill (usually @, ^X, or ^U), kills the insert on this line +\&\fB.\fP repeats the changing command +O opens and inputs new lines, above the current +U undoes the changes you made to the current line +a appends text after the cursor +c changes the object you specify to the following text +d deletes the object you specify +i inserts text before the cursor +o opens and inputs new lines, below the current +u undoes the last change +.TE +.NH 1 +Moving about; rearranging and duplicating text +.NH 2 +Low level character motions +.PP +Now move the cursor to a line where there is a punctuation or a bracketing +character such as a parenthesis or a comma or period. Try the command +\fBf\fR\fIx\fR where \fIx\fR is this character. This command finds +the next \fIx\fR character to the right of the cursor in the current +line. Try then hitting a \fB;\fR, which finds the next instance of the +same character. By using the \fBf\fR command and then a sequence of +\fB;\fR's you can often +get to a particular place in a line much faster than with a sequence +of word motions or \s-2SPACE\s0s. +There is also a \fBF\fR command, which is like \fBf\fR, but searches +backward. The \fB;\fR command repeats \fBF\fR also. +.PP +When you are operating on the text in a line it is often desirable to +deal with the characters up to, but not including, the first instance of +a character. Try \fBdf\fR\fIx\fR for some \fIx\fR now and +notice that the \fIx\fR character is deleted. Undo this with \fBu\fR +and then try \fBdt\fR\fIx\fR; the \fBt\fR here stands for to, i.e. +delete up to the next \fIx\fR, but not the \fIx\fR. The command \fBT\fR +is the reverse of \fBt\fR. +.PP +When working with the text of a single line, an \fB\(ua\fR moves the +cursor to the first non-white position on the line, and a +\fB$\fR moves it to the end of the line. Thus \fB$a\fR will append new +text at the end of the current line. +.PP +Your file may have tab (\fB^I\fR) characters in it. These +characters are represented as a number of spaces expanding to a tab stop, +where tab stops are every 8 positions.* +.FS +* This is settable by a command of the form \fB:se ts=\fR\fIx\fR\s-2CR\s0, +where \fIx\fR is 4 to set tabstops every four columns. This has +effect on the screen representation within the editor. +.FE +When the cursor is at a tab, it sits on the last of the several spaces +which represent that tab. Try moving the cursor back and forth over +tabs so you understand how this works. +.PP +On rare occasions, your file may have nonprinting characters in it. +These characters are displayed in the same way they are represented in +this document, that is with a two character code, the first character +of which is `^'. On the screen non-printing characters resemble a `^' +character adjacent to another, but spacing or backspacing over the character +will reveal that the two characters are, like the spaces representing +a tab character, a single character. +.PP +The editor sometimes discards control characters, +depending on the character and the setting of the +.I beautify +option, +if you attempt to insert them in your file. +You can get a control character in the file by beginning +an insert and then typing a \fB^V\fR before the control +character. The +\fB^V\fR quotes the following character, causing it to be +inserted directly into the file. +.PP +.NH 2 +Higher level text objects +.PP +In working with a document it is often advantageous to work in terms +of sentences, paragraphs, and sections. The operations \fB(\fR and \fB)\fR +move to the beginning of the previous and next sentences respectively. +Thus the command \fBd)\fR will delete the rest of the current sentence; +likewise \fBd(\fR will delete the previous sentence if you are at the +beginning of the current sentence, or the current sentence up to where +you are if you are not at the beginning of the current sentence. +.PP +A sentence is defined to end at a `.', `!' or `?' which is followed by +either the end of a line, or by two spaces. Any number of closing `)', +`]', `"' and `\(aa' characters may appear after the `.', `!' or `?' before +the spaces or end of line. +.PP +The operations \fB{\fR and \fB}\fR move over paragraphs and the operations +\fB[[\fR and \fB]]\fR move over sections.\*(dg +.FS +\*(dg The \fB[[\fR and \fB]]\fR operations +require the operation character to be doubled because they can move the +cursor far from where it currently is. While it is easy to get back +with the command \fB\(ga\(ga\fP, +these commands would still be frustrating +if they were easy to hit accidentally. +.FE +.PP +A paragraph begins after each empty line, and also +at each of a set of paragraph macros, specified by the pairs of characters +in the definition of the string valued option \fIparagraphs\fR. +The default setting for this option defines the paragraph macros of the +\fI\-ms\fR and \fI\-mm\fR macro packages, i.e. the `.IP', `.LP', `.PP' +and `.QP', `.P' and `.LI' macros.\*(dd +.FS +\*(dd You can easily change or extend this set of macros by assigning a +different string to the \fIparagraphs\fR option in your EXINIT. +See section 6.2 for details. +The `.bp' directive is also considered to start a paragraph. +.FE +Each paragraph boundary is also a sentence boundary. The sentence +and paragraph commands can +be given counts to operate over groups of sentences and paragraphs. +.PP +Sections in the editor begin after each macro in the \fIsections\fR option, +normally `.NH', `.SH', `.H' and `.HU', and each line with a formfeed \fB^L\fR +in the first column. +Section boundaries are always line and paragraph boundaries also. +.PP +Try experimenting with the sentence and paragraph commands until you are +sure how they work. If you have a large document, try looking through +it using the section commands. +The section commands interpret a preceding count as a different window size in +which to redraw the screen at the new location, and this window size +is the base size for newly drawn windows until another size is specified. +This is very useful +if you are on a slow terminal and are looking for a particular section. +You can give the first section command a small count to then see each successive +section heading in a small window. +.NH 2 +Rearranging and duplicating text +.PP +The editor has a single unnamed buffer where the last deleted or +changed away text is saved, and a set of named buffers \fBa\fR\-\fBz\fR +which you can use to save copies of text and to move text around in +your file and between files. +.PP +The operator +.B y +yanks a copy of the object which follows into the unnamed buffer. +If preceded by a buffer name, \fB"\fR\fIx\fR\|\fBy\fR, where +\fIx\fR here is replaced by a letter \fBa\-z\fR, it places the text in the named +buffer. The text can then be put back in the file with the commands +.B p +and +.B P; +\fBp\fR puts the text after or below the cursor, while \fBP\fR puts the text +before or above the cursor. +.PP +If the text which you +yank forms a part of a line, or is an object such as a sentence which +partially spans more than one line, then when you put the text back, +it will be placed after the cursor (or before if you +use \fBP\fR). If the yanked text forms whole lines, they will be put +back as whole lines, without changing the current line. In this case, +the put acts much like a \fBo\fR or \fBO\fR command. +.PP +Try the command \fBYP\fR. This makes a copy of the current line and +leaves you on this copy, which is placed before the current line. +The command \fBY\fR is a convenient abbreviation for \fByy\fR. +The command \fBYp\fR will also make a copy of the current line, and place +it after the current line. You can give \fBY\fR a count of lines to +yank, and thus duplicate several lines; try \fB3YP\fR. +.PP +To move text within the buffer, you need to delete it in one place, and +put it back in another. You can precede a delete operation by the +name of a buffer in which the text is to be stored as in \fB"a5dd\fR +deleting 5 lines into the named buffer \fIa\fR. You can then move the +cursor to the eventual resting place of the these lines and do a \fB"ap\fR +or \fB"aP\fR to put them back. +In fact, you can switch and edit another file before you put the lines +back, by giving a command of the form \fB:e \fR\fIname\fR\s-2CR\s0 where +\fIname\fR is the name of the other file you want to edit. You will +have to write back the contents of the current editor buffer (or discard +them) if you have made changes before the editor will let you switch +to the other file. +An ordinary delete command saves the text in the unnamed buffer, +so that an ordinary put can move it elsewhere. +However, the unnamed buffer is lost when you change files, +so to move text from one file to another you should use an unnamed buffer. +.NH 2 +Summary. +.IP +.TS +lw(.50i)b a. +\(ua first non-white on line +$ end of line +) forward sentence +} forward paragraph +]] forward section +( backward sentence +{ backward paragraph +[[ backward section +f\fIx\fR find \fIx\fR forward in line +p put text back, after cursor or below current line +y yank operator, for copies and moves +t\fIx\fR up to \fIx\fR forward, for operators +F\fIx\fR f backward in line +P put text back, before cursor or above current line +T\fIx\fR t backward in line +.TE +.ne 1i +.NH 1 +High level commands +.NH 2 +Writing, quitting, editing new files +.PP +So far we have seen how to enter +.I vi +and to write out our file using either +\fBZZ\fR or \fB:w\fR\s-2CR\s0. The first exits from +the editor, +(writing if changes were made), +the second writes and stays in the editor. +.PP +If you have changed the editor's copy of the file but do not wish to +save your changes, either because you messed up the file or decided that the +changes are not an improvement to the file, then you can give the command +\fB:q!\fR\s-2CR\s0 to quit from the editor without writing the changes. +You can also reedit the same file (starting over) by giving the command +\fB:e!\fR\s-2CR\s0. These commands should be used only rarely, and with +caution, as it is not possible to recover the changes you have made after +you discard them in this manner. +.PP +You can edit a different file without leaving the editor by giving the +command \fB:e\fR\ \fIname\fR\s-2CR\s0. If you have not written out +your file before you try to do this, then the editor will tell you this, +and delay editing the other file. You can then give the command +\fB:w\fR\s-2CR\s0 to save your work and then the \fB:e\fR\ \fIname\fR\s-2CR\s0 +command again, or carefully give the command \fB:e!\fR\ \fIname\fR\s-2CR\s0, +which edits the other file discarding the changes you have made to the +current file. +To have the editor automatically save changes, +include +.I "set autowrite" +in your EXINIT, +and use \fB:n\fP instead of \fB:e\fP. +.NH 2 +Escaping to a shell +.PP +You can get to a shell to execute a single command by giving a +.I vi +command of the form \fB:!\fIcmd\fR\s-2CR\s0. +The system will run the single command +.I cmd +and when the command finishes, the editor will ask you to hit a \s-2RETURN\s0 +to continue. When you have finished looking at the output on the screen, +you should hit \s-2RETURN\s0 and the editor will clear the screen and +redraw it. You can then continue editing. +You can also give another \fB:\fR command when it asks you for a \s-2RETURN\s0; +in this case the screen will not be redrawn. +.PP +If you wish to execute more than one command in the shell, then you can +give the command \fB:sh\fR\s-2CR\s0. +This will give you a new shell, and when you finish with the shell, ending +it by typing a \fB^D\fR, the editor will clear the screen and continue. +.PP +On systems which support it, \fB^Z\fP will suspend the editor +and return to the (top level) shell. +When the editor is resumed, the screen will be redrawn. +.NH 2 +Marking and returning +.PP +The command \fB\(ga\(ga\fR returned to the previous place +after a motion of the cursor by a command such as \fB/\fR, \fB?\fR or +\fBG\fR. You can also mark lines in the file with single letter tags +and return to these marks later by naming the tags. Try marking the +current line with the command \fBm\fR\fIx\fR, where you should pick some +letter for \fIx\fR, say `a'. Then move the cursor to a different line +(any way you like) and hit \fB\(gaa\fR. The cursor will return to the +place which you marked. +Marks last only until you edit another file. +.PP +When using operators such as +.B d +and referring to marked lines, it is often desirable to delete whole lines +rather than deleting to the exact position in the line marked by \fBm\fR. +In this case you can use the form \fB\(aa\fR\fIx\fR rather than +\fB\(ga\fR\fIx\fR. Used without an operator, \fB\(aa\fR\fIx\fR will move to +the first non-white character of the marked line; similarly \fB\(aa\(aa\fR +moves to the first non-white character of the line containing the previous +context mark \fB\(ga\(ga\fR. +.NH 2 +Adjusting the screen +.PP +If the screen image is messed up because of a transmission error to your +terminal, or because some program other than the editor wrote output +to your terminal, you can hit a \fB^L\fR, the \s-2ASCII\s0 form-feed +character, to cause the screen to be refreshed. +.PP +On a dumb terminal, if there are @ lines in the middle of the screen +as a result of line deletion, you may get rid of these lines by typing +\fB^R\fR to cause the editor to retype the screen, closing up these holes. +.PP +Finally, if you wish to place a certain line on the screen at the top +middle or bottom of the screen, you can position the cursor to that line, +and then give a \fBz\fR command. +You should follow the \fBz\fR command with a \s-2RETURN\s0 if you want +the line to appear at the top of the window, a \fB.\fR if you want it +at the center, or a \fB\-\fR if you want it at the bottom. +.NH 1 +Special topics +.NH 2 +Editing on slow terminals +.PP +When you are on a slow terminal, it is important to limit the amount +of output which is generated to your screen so that you will not suffer +long delays, waiting for the screen to be refreshed. We have already +pointed out how the editor optimizes the updating of the screen during +insertions on dumb terminals to limit the delays, and how the editor erases +lines to @ when they are deleted on dumb terminals. +.PP +The use of the slow terminal insertion mode is controlled by the +.I slowopen +option. You can force the editor to use this mode even on faster terminals +by giving the command \fB:se slow\fR\s-2CR\s0. If your system is sluggish +this helps lessen the amount of output coming to your terminal. +You can disable this option by \fB:se noslow\fR\s-2CR\s0. +.PP +The editor can simulate an intelligent terminal on a dumb one. Try +giving the command \fB:se redraw\fR\s-2CR\s0. This simulation generates +a great deal of output and is generally tolerable only on lightly loaded +systems and fast terminals. You can disable this by giving the command + \fB:se noredraw\fR\s-2CR\s0. +.PP +The editor also makes editing more pleasant at low speed by starting +editing in a small window, and letting the window expand as you edit. +This works particularly well on intelligent terminals. The editor can +expand the window easily when you insert in the middle of the screen +on these terminals. If possible, try the editor on an intelligent terminal +to see how this works. +.PP +You can control the size of the window which is redrawn each time the +screen is cleared by giving window sizes as argument to the commands +which cause large screen motions: +.DS +.B ": / ? [[ ]] \(ga \(aa" +.DE +Thus if you are searching for a particular instance of a common string +in a file you can precede the first search command by a small number, +say 3, and the editor will draw three line windows around each instance +of the string which it locates. +.PP +You can easily expand or contract the window, placing the current line +as you choose, by giving a number on a \fBz\fR command, after the \fBz\fR +and before the following \s-2RETURN\s0, \fB.\fR or \fB\-\fR. Thus the +command \fBz5.\fR redraws the screen with the current line in the center +of a five line window.\*(dg +.FS +\*(dg Note that the command \fB5z.\fR has an entirely different effect, +placing line 5 in the center of a new window. +.FE +.PP +If the editor is redrawing or otherwise updating large portions of the +display, you can interrupt this updating by hitting a \s-2DEL\s0 or \s-2RUB\s0 +as usual. If you do this you may partially confuse the editor about +what is displayed on the screen. You can still edit the text on +the screen if you wish; clear up the confusion +by hitting a \fB^L\fR; or move or search again, ignoring the +current state of the display. +.PP +See section 7.8 on \fIopen\fR mode for another way to use the +.I vi +command set on slow terminals. +.NH 2 +Options, set, and editor startup files +.PP +The editor has a set of options, some of which have been mentioned above. +The most useful options are given in the following table. +.PP +The options are of three kinds: numeric options, string options, and +toggle options. You can set numeric and string options by a statement +of the form +.DS +\fBset\fR \fIopt\fR\fB=\fR\fIval\fR +.DE +and toggle options can be set or unset by statements of one of the forms +.DS +\fBset\fR \fIopt\fR +\fBset\fR \fBno\fR\fIopt\fR +.DE +.KF +.TS +lb lb lb lb +l l l a. +Name Default Description +_ +autoindent noai Supply indentation automatically +autowrite noaw Automatic write before \fB:n\fR, \fB:ta\fR, \fB^\(ua\fR, \fB!\fR +ignorecase noic Ignore case in searching +lisp nolisp \fB( { ) }\fR commands deal with S-expressions +list nolist Tabs print as ^I; end of lines marked with $ +magic nomagic The characters . [ and * are special in scans +number nonu Lines are displayed prefixed with line numbers +paragraphs para=IPLPPPQPbpP LI Macro names which start paragraphs +redraw nore Simulate a smart terminal on a dumb one +sections sect=NHSHH HU Macro names which start new sections +shiftwidth sw=8 Shift distance for <, > and input \fB^D\fP and \fB^T\fR +showmatch nosm Show matching \fB(\fP or \fB{\fP as \fB)\fP or \fB}\fR is typed +slowopen slow Postpone display updates during inserts +term dumb The kind of terminal you are using. +.TE +.KE +These statements can be placed in your EXINIT in your environment, +or given while you are running +.I vi +by preceding them with a \fB:\fR and following them with a \s-2CR\s0. +.PP +You can get a list of all options which you have changed by the +command \fB:set\fR\s-2CR\s0, or the value of a single option by the +command \fB:set\fR \fIopt\fR\fB?\fR\s-2CR\s0. +A list of all possible options and their values is generated by +\fB:set all\fP\s-2CR\s0. +Set can be abbreviated \fBse\fP. +Multiple options can be placed on one line, e.g. +\fB:se ai aw nu\fP\s-2CR\s0. +.PP +Options set by the \fBset\fP command only last +while you stay in the editor. +It is common to want to have certain options set whenever you +use the editor. +This can be accomplished by creating a list of \fIex\fP commands\*(dg +.FS +\*(dg +All commands which start with +.B : +are \fIex\fP commands. +.FE +which are to be run every time you start up \fIex\fP, \fIedit\fP, +or \fIvi\fP. +A typical list includes a \fBset\fP command, and possibly a few +\fBmap\fP commands. +Since it is advisable to get these commands on one line, they can +be separated with the | character, for example: +.DS +\fBset\fP ai aw terse|\fBmap\fP @ dd|\fBmap\fP # x +.DE +which sets the options \fIautoindent\fP, \fIautowrite\fP, \fIterse\fP, +(the +.B set +command), +makes @ delete a line, +(the first +.B map ), +and makes # delete a character, +(the second +.B map ). +(See section 6.9 for a description of the \fBmap\fP command) +This string should be placed in the variable EXINIT in your environment. +If you use the shell \fIcsh\fP, +put this line in the file +.I .login +in your home directory: +.DS +setenv EXINIT \(aa\fBset\fP ai aw terse|\fBmap\fP @ dd|\fBmap\fP # x\(aa +.DE +If you use the standard shell \fIsh\fP, +put these lines in the file +.I .profile +in your home directory: +.DS +EXINIT=\(aa\fBset\fP ai aw terse|\fBmap\fP @ dd|\fBmap\fP # x\(aa +export EXINIT +.DE +Of course, the particulars of the line would depend on which options +you wanted to set. +.NH 2 +Recovering lost lines +.PP +You might have a serious problem if you delete a number of lines and then +regret that they were deleted. Despair not, the editor saves the last +9 deleted blocks of text in a set of numbered registers 1\-9. +You can get the \fIn\fR'th previous deleted text back in your file by +the command +"\fR\fIn\fR\|\fBp\fR. +The "\fR here says that a buffer name is to follow, +\fIn\fR is the number of the buffer you wish to try +(use the number 1 for now), +and +.B p +is the put command, which puts text in the buffer after the cursor. +If this doesn't bring back the text you wanted, hit +.B u +to undo this and then +\fB\&.\fR +(period) +to repeat the put command. +In general the +\fB\&.\fR +command will repeat the last change you made. +As a special case, when the last command refers to a numbered text buffer, +the \fB.\fR command increments the number of the buffer before repeating +the command. Thus a sequence of the form +.DS +\fB"1pu.u.u.\fR +.DE +will, if repeated long enough, show you all the deleted text which has +been saved for you. +You can omit the +.B u +commands here to gather up all this text in the buffer, or stop after any +\fB\&.\fR command to keep just the then recovered text. +The command +.B P +can also be used rather than +.B p +to put the recovered text before rather than after the cursor. +.NH 2 +Recovering lost files +.PP +If the system crashes, you can recover the work you were doing +to within a few changes. You will normally receive mail when you next +login giving you the name of the file which has been saved for you. +You should then change to the directory where you were when the system +crashed and give a command of the form: +.DS +% \fBvi \-r\fR \fIname\fR +.DE +replacing \fIname\fR with the name of the file which you were editing. +This will recover your work to a point near where you left off.\*(dg +.FS +\*(dg In rare cases, some of the lines of the file may be lost. The +editor will give you the numbers of these lines and the text of the lines +will be replaced by the string `LOST'. These lines will almost always +be among the last few which you changed. You can either choose to discard +the changes which you made (if they are easy to remake) or to replace +the few lost lines by hand. +.FE +.PP +You can get a listing of the files which are saved for you by giving +the command: +.DS +% \fBvi \-r\fR +.DE +If there is more than one instance of a particular file saved, the editor +gives you the newest instance each time you recover it. You can thus +get an older saved copy back by first recovering the newer copies. +.PP +For this feature to work, +.I vi +must be correctly installed by a super user on your system, +and the +.I mail +program must exist to receive mail. +The invocation ``\fIvi -r\fP'' will not always list all saved files, +but they can be recovered even if they are not listed. +.NH 2 +Continuous text input +.PP +When you are typing in large amounts of text it is convenient to have +lines broken near the right margin automatically. You can cause this +to happen by giving the command +\fB:se wm=10\fR\s-2CR\s0. +This causes all lines to be broken at a space at least 10 columns +from the right hand edge of the screen. +.PP +If the editor breaks an input line and you wish to put it back together +you can tell it to join the lines with \fBJ\fR. You can give \fBJ\fR +a count of the number of lines to be joined as in \fB3J\fR to join 3 +lines. The editor supplies white space, if appropriate, +at the juncture of the joined +lines, and leaves the cursor at this white space. +You can kill the white space with \fBx\fR if you don't want it. +.NH 2 +Features for editing programs +.PP +The editor has a number of commands for editing programs. +The thing that most distinguishes editing of programs from editing of text +is the desirability of maintaining an indented structure to the body of +the program. The editor has a +.I autoindent +facility for helping you generate correctly indented programs. +.PP +To enable this facility you can give the command \fB:se ai\fR\s-2CR\s0. +Now try opening a new line with \fBo\fR and type some characters on the +line after a few tabs. If you now start another line, notice that the +editor supplies white space at the beginning of the line to line it up +with the previous line. You cannot backspace over this indentation, +but you can use \fB^D\fR key to backtab over the supplied indentation. +.PP +Each time you type \fB^D\fR you back up one position, normally to an +8 column boundary. This amount is settable; the editor has an option +called +.I shiftwidth +which you can set to change this value. +Try giving the command \fB:se sw=4\fR\s-2CR\s0 +and then experimenting with autoindent again. +.PP +For shifting lines in the program left and right, there are operators +.B < +and +.B >. +These shift the lines you specify right or left by one +.I shiftwidth. +Try +.B << +and +.B >> +which shift one line left or right, and +.B <L +and +.B >L +shifting the rest of the display left and right. +.PP +If you have a complicated expression and wish to see how the parentheses +match, put the cursor at a left or right parenthesis and hit \fB%\fR. +This will show you the matching parenthesis. +This works also for braces { and }, and brackets [ and ]. +.PP +If you are editing C programs, you can use the \fB[[\fR and \fB]]\fR keys +to advance or retreat to a line starting with a \fB{\fR, i.e. a function +declaration at a time. When \fB]]\fR is used with an operator it stops +after a line which starts with \fB}\fR; this is sometimes useful with +\fBy]]\fR. +.NH 2 +Filtering portions of the buffer +.PP +You can run system commands over portions of the buffer using the operator +\fB!\fR. +You can use this to sort lines in the buffer, or to reformat portions +of the buffer with a pretty-printer. +Try typing in a list of random words, one per line and ending them +with a blank line. Back up to the beginning of the list, and then give +the command \fB!}sort\fR\s-2CR\s0. This says to sort the next paragraph +of material, and the blank line ends a paragraph. +.NH 2 +Commands for editing \s-2LISP\s0 +.PP +If you are editing a \s-2LISP\s0 program you should set the option +.I lisp +by doing +\fB:se\ lisp\fR\s-2CR\s0. +This changes the \fB(\fR and \fB)\fR commands to move backward and forward +over s-expressions. +The \fB{\fR and \fB}\fR commands are like \fB(\fR and \fB)\fR but don't +stop at atoms. These can be used to skip to the next list, or through +a comment quickly. +.PP +The +.I autoindent +option works differently for \s-2LISP\s0, supplying indent to align at +the first argument to the last open list. If there is no such argument +then the indent is two spaces more than the last level. +.PP +There is another option which is useful for typing in \s-2LISP\s0, the +.I showmatch +option. +Try setting it with +\fB:se sm\fR\s-2CR\s0 +and then try typing a `(' some words and then a `)'. Notice that the +cursor shows the position of the `(' which matches the `)' briefly. +This happens only if the matching `(' is on the screen, and the cursor +stays there for at most one second. +.PP +The editor also has an operator to realign existing lines as though they +had been typed in with +.I lisp +and +.I autoindent +set. This is the \fB=\fR operator. +Try the command \fB=%\fR at the beginning of a function. This will realign +all the lines of the function declaration. +.PP +When you are editing \s-2LISP\s0,, the \fB[[\fR and \fR]]\fR advance +and retreat to lines beginning with a \fB(\fR, and are useful for dealing +with entire function definitions. +.NH 2 +Macros +.PP +.I Vi +has a parameterless macro facility, which lets you set it up so that +when you hit a single keystroke, the editor will act as though +you had hit some longer sequence of keys. You can set this up if +you find yourself typing the same sequence of commands repeatedly. +.PP +Briefly, there are two flavors of macros: +.IP a) +Ones where you put the macro body in a buffer register, say \fIx\fR. +You can then type \fB@x\fR to invoke the macro. The \fB@\fR may be followed +by another \fB@\fR to repeat the last macro. +.IP b) +You can use the +.I map +command from +.I vi +(typically in your +.I EXINIT ) +with a command of the form: +.DS +:map \fIlhs\fR \fIrhs\fR\s-2CR +.DE +mapping +.I lhs +into +.I rhs. +There are restrictions: +.I lhs +should be one keystroke (either 1 character or one function key) +since it must be entered within one second +(unless +.I notimeout +is set, in which case you can type it as slowly as you wish, +and +.I vi +will wait for you to finish it before it echoes anything). +The +.I lhs +can be no longer than 10 characters, the +.I rhs +no longer than 100. +To get a space, tab or newline into +.I lhs +or +.I rhs +you should escape them with a \fB^V\fR. +(It may be necessary to double the \fB^V\fR if the map +command is given inside +.I vi, +rather than in +.I ex.) +Spaces and tabs inside the +.I rhs +need not be escaped. +.PP +Thus to make the \fBq\fR key write and exit the editor, you can give +the command +.DS +:map q :wq\fB^V^V\fP\s-2CR CR\s0 +.DE +which means that whenever you type \fBq\fR, it will be as though you +had typed the four characters \fB:wq\fR\s-2CR\s0. +A \fB^V\fR's is needed because without it the \s-2CR\s0 would end the +\fB:\fR command, rather than becoming part of the +.I map +definition. +There are two +.B ^V 's +because from within +.I vi , +two +.B ^V 's +must be typed to get one. +The first \s-2CR\s0 is part of the +.I rhs , +the second terminates the : command. +.PP +Macros can be deleted with +.DS +unmap lhs +.DE +.PP +If the +.I lhs +of a macro is ``#0'' through ``#9'', this maps the particular function key +instead of the 2 character ``#'' sequence. So that terminals without +function keys can access such definitions, the form ``#x'' will mean function +key +.I x +on all terminals (and need not be typed within one second.) +The character ``#'' can be changed by using a macro in the usual way: +.DS +:map \fB^V^V^I\fP # +.DE +to use tab, for example. (This won't affect the +.I map +command, which still uses +.B #, +but just the invocation from visual mode. +.PP +The undo command reverses an entire macro call as a unit, +if it made any changes. +.PP +Placing a `!' after the word +.B map +causes the mapping to apply +to input mode, rather than command mode. +Thus, to arrange for \fB^T\fP to be the same as 4 spaces in input mode, +you can type: +.DS +:map \fB^T\fP \fB^V\fP\o'b/'\o'b/'\o'b/'\o'b/' +.DE +where +.B \o'b/' +is a blank. +The \fB^V\fP is necessary to prevent the blanks from being taken as +white space between the +.I lhs +and +.I rhs . +.NH +Word Abbreviations +.PP +A feature similar to macros in input mode is word abbreviation. +This allows you to type a short word and have it expanded into +a longer word or words. +The commands are +.B :abbreviate +and +.B :unabbreviate +(\fB:ab\fP +and +.B :una ) +and have the same syntax as +.B :map . +For example: +.DS +:ab eecs Electrical Engineering and Computer Sciences +.DE +causes the word `eecs' to always be changed into the +phrase `Electrical Engineering and Computer Sciences'. +Word abbreviation is different from macros in that +only whole words are affected. +If `eecs' were typed as part of a larger word, it would +be left alone. +Also, the partial word is echoed as it is typed. +There is no need for an abbreviation to be a single keystroke, +as it should be with a macro. +.NH 2 +Abbreviations +.PP +The editor has a number of short +commands which abbreviate longer commands which we +have introduced here. You can find these commands easily +on the quick reference card. +They often save a bit of typing and you can learn them as convenient. +.NH 1 +Nitty-gritty details +.NH 2 +Line representation in the display +.PP +The editor folds long logical lines onto many physical lines in the display. +Commands which advance lines advance logical lines and will skip +over all the segments of a line in one motion. The command \fB|\fR moves +the cursor to a specific column, and may be useful for getting near the +middle of a long line to split it in half. Try \fB80|\fR on a line which +is more than 80 columns long.\*(dg +.FS +\*(dg You can make long lines very easily by using \fBJ\fR to join together +short lines. +.FE +.PP +The editor only puts full lines on the display; if there is not enough +room on the display to fit a logical line, the editor leaves the physical +line empty, placing only an @ on the line as a place holder. When you +delete lines on a dumb terminal, the editor will often just clear the +lines to @ to save time (rather than rewriting the rest of the screen.) +You can always maximize the information on the screen by giving the \fB^R\fR +command. +.PP +If you wish, you can have the editor place line numbers before each line +on the display. Give the command \fB:se nu\fR\s-2CR\s0 to enable +this, and the command \fB:se nonu\fR\s-2CR\s0 to turn it off. +You can have tabs represented as \fB^I\fR and the ends of lines indicated +with `$' by giving the command \fB:se list\fR\s-2CR\s0; +\fB:se nolist\fR\s-2CR\s0 turns this off. +.PP +Finally, lines consisting of only the character `~' are displayed when +the last line in the file is in the middle of the screen. These represent +physical lines which are past the logical end of file. +.NH 2 +Counts +.PP +Most +.I vi +commands will use a preceding count to affect their behavior in some way. +The following table gives the common ways in which the counts are used: +.DS +.TS +l lb. +new window size : / ? [[ ]] \` \' +scroll amount ^D ^U +line/column number z G | +repeat effect \fRmost of the rest\fP +.TE +.DE +.PP +The editor maintains a notion of the current default window size. +On terminals which run at speeds greater than 1200 baud +the editor uses the full terminal screen. +On terminals which are slower than 1200 baud +(most dialup lines are in this group) +the editor uses 8 lines as the default window size. +At 1200 baud the default is 16 lines. +.PP +This size is the size used when the editor clears and refills the screen +after a search or other motion moves far from the edge of the current window. +The commands which take a new window size as count all often cause the +screen to be redrawn. If you anticipate this, but do not need as large +a window as you are currently using, you may wish to change the screen +size by specifying the new size before these commands. +In any case, the number of lines used on the screen will expand if you +move off the top with a \fB\-\fR or similar command or off the bottom +with a command such as \s-2RETURN\s0 or \fB^D\fR. +The window will revert to the last specified size the next time it is +cleared and refilled.\*(dg +.FS +\*(dg But not by a \fB^L\fR which just redraws the screen as it is. +.FE +.PP +The scroll commands \fB^D\fR and \fB^U\fR likewise remember the amount +of scroll last specified, using half the basic window size initially. +The simple insert commands use a count to specify a repetition of the +inserted text. Thus \fB10a+\-\-\-\-\fR\s-2ESC\s0 will insert a grid-like +string of text. +A few commands also use a preceding count as a line or column number. +.PP +Except for a few commands which ignore any counts (such as \fB^R\fR), +the rest of the editor commands use a count to indicate a simple repetition +of their effect. Thus \fB5w\fR advances five words on the current line, +while \fB5\fR\s-2RETURN\s0 advances five lines. A very useful instance +of a count as a repetition is a count given to the \fB.\fR command, which +repeats the last changing command. If you do \fBdw\fR and then \fB3.\fR, +you will delete first one and then three words. You can then delete +two more words with \fB2.\fR. +.NH 2 +More file manipulation commands +.PP +The following table lists the file manipulation commands which you can +use when you are in +.I vi. +.KF +.DS +.TS +lb l. +:w write back changes +:wq write and quit +:x write (if necessary) and quit (same as ZZ). +:e \fIname\fP edit file \fIname\fR +:e! reedit, discarding changes +:e + \fIname\fP edit, starting at end +:e +\fIn\fP edit, starting at line \fIn\fP +:e # edit alternate file +:w \fIname\fP write file \fIname\fP +:w! \fIname\fP overwrite file \fIname\fP +:\fIx,y\fPw \fIname\fP write lines \fIx\fP through \fIy\fP to \fIname\fP +:r \fIname\fP read file \fIname\fP into buffer +:r !\fIcmd\fP read output of \fIcmd\fP into buffer +:n edit next file in argument list +:n! edit next file, discarding changes to current +:n \fIargs\fP specify new argument list +:ta \fItag\fP edit file containing tag \fItag\fP, at \fItag\fP +.TE +.DE +.KE +All of these commands are followed by a \s-2CR\s0 or \s-2ESC\s0. +The most basic commands are \fB:w\fR and \fB:e\fR. +A normal editing session on a single file will end with a \fBZZ\fR command. +If you are editing for a long period of time you can give \fB:w\fR commands +occasionally after major amounts of editing, and then finish +with a \fBZZ\fR. When you edit more than one file, you can finish +with one with a \fB:w\fR and start editing a new file by giving a \fB:e\fR +command, +or set +.I autowrite +and use \fB:n\fP <file>. +.PP +If you make changes to the editor's copy of a file, but do not wish to +write them back, then you must give an \fB!\fR after the command you +would otherwise use; this forces the editor to discard any changes +you have made. Use this carefully. +.ne 1i +.PP +The \fB:e\fR command can be given a \fB+\fR argument to start at the +end of the file, or a \fB+\fR\fIn\fR argument to start at line \fIn\fR\^. +In actuality, \fIn\fR may be any editor command not containing a space, +usefully a scan like \fB+/\fIpat\fR or \fB+?\fIpat\fR. +In forming new names to the \fBe\fR command, you can use the character +\fB%\fR which is replaced by the current file name, or the character +\fB#\fR which is replaced by the alternate file name. +The alternate file name is generally the last name you typed other than +the current file. Thus if you try to do a \fB:e\fR and get a diagnostic +that you haven't written the file, you can give a \fB:w\fR command and +then a \fB:e #\fR command to redo the previous \fB:e\fR. +.PP +You can write part of the buffer to a file by finding out the lines +that bound the range to be written using \fB^G\fR, and giving these +numbers after the \fB:\fR +and before the \fBw\fP, separated by \fB,\fR's. +You can also mark these lines with \fBm\fR and +then use an address of the form \fB\(aa\fR\fIx\fR\fB,\fB\(aa\fR\fIy\fR +on the \fBw\fR command here. +.PP +You can read another file into the buffer after the current line by using +the \fB:r\fR command. +You can similarly read in the output from a command, just use \fB!\fR\fIcmd\fR +instead of a file name. +.PP +If you wish to edit a set of files in succession, you can give all the +names on the command line, and then edit each one in turn using the command +\fB:n\fR. It is also possible to respecify the list of files to be edited +by giving the \fB:n\fR command a list of file names, or a pattern to +be expanded as you would have given it on the initial +.I vi +command. +.PP +If you are editing large programs, you will find the \fB:ta\fR command +very useful. It utilizes a data base of function names and their locations, +which can be created by programs such as +.I ctags, +to quickly find a function whose name you give. +If the \fB:ta\fR command will require the editor to switch files, then +you must \fB:w\fR or abandon any changes before switching. You can repeat +the \fB:ta\fR command without any arguments to look for the same tag +again. +.NH 2 +More about searching for strings +.PP +When you are searching for strings in the file with \fB/\fR and \fB?\fR, +the editor normally places you at the next or previous occurrence +of the string. If you are using an operator such as \fBd\fR, +\fBc\fR or \fBy\fR, then you may well wish to affect lines up to the +line before the line containing the pattern. You can give a search of +the form \fB/\fR\fIpat\fR\fB/\-\fR\fIn\fR to refer to the \fIn\fR'th line +before the next line containing \fIpat\fR, or you can use \fB+\fR instead +of \fB\-\fR to refer to the lines after the one containing \fIpat\fR. +If you don't give a line offset, then the editor will affect characters +up to the match place, rather than whole lines; thus use ``+0'' to affect +to the line which matches. +.PP +You can have the editor ignore the case of words in the searches it does +by giving the command \fB:se ic\fR\s-2CR\s0. +The command \fB:se noic\fR\s-2CR\s0 turns this off. +.ne 1i +.PP +Strings given to searches may actually be regular expressions. +If you do not want or need this facility, you should +.DS +set nomagic +.DE +in your EXINIT. +In this case, +only the characters \fB\(ua\fR and \fB$\fR are special in patterns. +The character \fB\e\fR is also then special (as it is most everywhere in +the system), and may be used to get at the +an extended pattern matching facility. +It is also necessary to use a \e before a +\fB/\fR in a forward scan or a \fB?\fR in a backward scan, in any case. +The following table gives the extended forms when \fBmagic\fR is set. +.DS +.TS +lb l. +\(ua at beginning of pattern, matches beginning of line +$ at end of pattern, matches end of line +\fB\&.\fR matches any character +\e< matches the beginning of a word +\e> matches the end of a word +[\fIstr\fP] matches any single character in \fIstr\fP +[\(ua\fIstr\fP] matches any single character not in \fIstr\fP +[\fIx\fP\-\fIy\fP] matches any character between \fIx\fP and \fIy\fP +* matches any number of the preceding pattern +.TE +.DE +If you use \fBnomagic\fR mode, then +the \fB. [\fR and \fB*\fR primitives are given with a preceding +\e. +.NH 2 +More about input mode +.PP +There are a number of characters which you can use to make corrections +during input mode. These are summarized in the following table. +.sp .5 +.DS +.TS +lb l. +^H deletes the last input character +^W deletes the last input word, defined as by \fBb\fR +erase your erase character, same as \fB^H\fP +kill your kill character, deletes the input on this line +\e escapes a following \fB^H\fP and your erase and kill +\s-2ESC\s0 ends an insertion +\s-2DEL\s0 interrupts an insertion, terminating it abnormally +\s-2CR\s0 starts a new line +^D backtabs over \fIautoindent\fP +0^D kills all the \fIautoindent\fP +\(ua^D same as \fB0^D\fP, but restores indent next line +^V quotes the next non-printing character into the file +.TE +.DE +.sp .5 +.PP +The most usual way of making corrections to input is by typing \fB^H\fR +to correct a single character, or by typing one or more \fB^W\fR's to +back over incorrect words. If you use \fB#\fR as your erase character +in the normal system, it will work like \fB^H\fR. +.PP +Your system kill character, normally \fB@\fR, \fB^X\fP or \fB^U\fR, +will erase all +the input you have given on the current line. +In general, you can neither +erase input back around a line boundary nor can you erase characters +which you did not insert with this insertion command. To make corrections +on the previous line after a new line has been started you can hit \s-2ESC\s0 +to end the insertion, move over and make the correction, and then return +to where you were to continue. The command \fBA\fR which appends at the +end of the current line is often useful for continuing. +.PP +If you wish to type in your erase or kill character (say # or @) then +you must precede it with a \fB\e\fR, just as you would do at the normal +system command level. A more general way of typing non-printing characters +into the file is to precede them with a \fB^V\fR. The \fB^V\fR echoes +as a \fB\(ua\fR character on which the cursor rests. This indicates that +the editor expects you to type a control character. In fact you may +type any character and it will be inserted into the file at that point.* +.FS +* This is not quite true. The implementation of the editor does +not allow the \s-2NULL\s0 (\fB^@\fR) character to appear in files. Also +the \s-2LF\s0 (linefeed or \fB^J\fR) character is used by the editor +to separate lines in the file, so it cannot appear in the middle of a +line. You can insert any other character, however, if you wait for the +editor to echo the \fB\(ua\fR before you type the character. In fact, +the editor will treat a following letter as a request for the corresponding +control character. This is the only way to type \fB^S\fR or \fB^Q\fP, +since the system normally uses them to suspend and resume output +and never gives them to the editor to process. +.FE +.PP +If you are using \fIautoindent\fR you can backtab over the indent which +it supplies by typing a \fB^D\fR. This backs up to a \fIshiftwidth\fR +boundary. +This only works immediately after the supplied \fIautoindent\fR. +.PP +When you are using \fIautoindent\fR you may wish to place a label at +the left margin of a line. The way to do this easily is to type \fB\(ua\fR +and then \fB^D\fR. The editor will move the cursor to the left margin +for one line, and restore the previous indent on the next. You can also +type a \fB0\fR followed immediately by a \fB^D\fR if you wish to kill +all the indent and not have it come back on the next line. +.NH 2 +Upper case only terminals +.PP +If your terminal has only upper case, you can still use +.I vi +by using the normal +system convention for typing on such a terminal. +Characters which you normally type are converted to lower case, and you +can type upper case letters by preceding them with a \e. +The characters { ~ } | \(ga are not available on such terminals, but you +can escape them as \e( \e\(ua \e) \e! \e\(aa. +These characters are represented on the display in the same way they +are typed.\*(dd +.FS +\*(dd The \e character you give will not echo until you type another +key. +.FE +.NH 2 +Vi and ex +.PP +.I Vi +is actually one mode of editing within the editor +.I ex. +When you are running +.I vi +you can escape to the line oriented editor of +.I ex +by giving the command +\fBQ\fR. +All of the +.B : +commands which were introduced above are available in +.I ex. +Likewise, most +.I ex +commands can be invoked from +.I vi +using :. +Just give them without the \fB:\fR and follow them with a \s-2CR\s0. +.PP +In rare instances, an internal error may occur in +.I vi. +In this case you will get a diagnostic and be left in the command mode of +.I ex. +You can then save your work and quit if you wish by giving a command +\fBx\fR after the \fB:\fR which \fIex\fR prompts you with, or you can +reenter \fIvi\fR by giving +.I ex +a +.I vi +command. +.PP +There are a number of things which you can do more easily in +.I ex +than in +.I vi. +Systematic changes in line oriented material are particularly easy. +You can read the advanced editing documents for the editor +.I ed +to find out a lot more about this style of editing. +Experienced +users often mix their use of +.I ex +command mode and +.I vi +command mode to speed the work they are doing. +.NH 2 +Open mode: vi on hardcopy terminals and ``glass tty's'' +\(dd +.PP +If you are on a hardcopy terminal or a terminal which does not have a cursor +which can move off the bottom line, you can still use the command set of +.I vi, +but in a different mode. +When you give a +.I vi +command, the editor will tell you that it is using +.I open +mode. +This name comes from the +.I open +command in +.I ex, +which is used to get into the same mode. +.PP +The only difference between +.I visual +mode +and +.I open +mode is the way in which the text is displayed. +.PP +In +.I open +mode the editor uses a single line window into the file, and moving backward +and forward in the file causes new lines to be displayed, always below the +current line. +Two commands of +.I vi +work differently in +.I open: +.B z +and +\fB^R\fR. +The +.B z +command does not take parameters, but rather draws a window of context around +the current line and then returns you to the current line. +.PP +If you are on a hardcopy terminal, +the +.B ^R +command will retype the current line. +On such terminals, the editor normally uses two lines to represent the +current line. +The first line is a copy of the line as you started to edit it, and you work +on the line below this line. +When you delete characters, the editor types a number of \e's to show +you the characters which are deleted. The editor also reprints the current +line soon after such changes so that you can see what the line looks +like again. +.PP +It is sometimes useful to use this mode on very slow terminals which +can support +.I vi +in the full screen mode. +You can do this by entering +.I ex +and using an +.I open +command. +.LP +.SH +Acknowledgements +.PP +Bruce Englar encouraged the early development of this display editor. +Peter Kessler helped bring sanity to version 2's command layout. +Bill Joy wrote versions 1 and 2.0 through 2.7, +and created the framework that users see in the present editor. +Mark Horton added macros and other features and made the +editor work on a large number of terminals and Unix systems. diff --git a/share/doc/usd/12.vi/viapwh/Makefile b/share/doc/usd/12.vi/viapwh/Makefile new file mode 100644 index 000000000000..a8de9a151e0a --- /dev/null +++ b/share/doc/usd/12.vi/viapwh/Makefile @@ -0,0 +1,4 @@ +DOC= viapwh +SRCS= vi.apwh.ms + +.include <bsd.doc.mk> diff --git a/share/doc/usd/12.vi/viapwh/vi.apwh.ms b/share/doc/usd/12.vi/viapwh/vi.apwh.ms new file mode 100644 index 000000000000..c694da4f254b --- /dev/null +++ b/share/doc/usd/12.vi/viapwh/vi.apwh.ms @@ -0,0 +1,1079 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. 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 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 by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr LL 6.5i +.nr FL 6.5i +.TL +Vi Command & Function Reference +.AU CB 2675 +Alan P.W. Hewett +.sp +Revised for version 2.12 by Mark Horton +.CB +.NH 1 +Author's Disclaimer +.LP +This document does not claim to be 100% complete. There are a +few commands listed in the original document that I was unable +to test either because I do not speak \fBlisp\fR, because they +required programs we don't have, or because I wasn't able to make +them work. In these cases I left the command out. The commands +listed in this document have been tried and are known to work. +It is expected that prospective users of this document will read +it once to get the flavor of everything that \fBvi\fR can do +and then use it as a reference document. Experimentation is +recommended. If you don't understand a command, try it and +see what happens. +.LP +[Note: In revising this document, I have attempted to make it +completely reflect version 2.12 of +.B vi . +It does not attempt to document the VAX version (version 3), +but with one or two exceptions (wrapmargin, arrow keys) +everything said about 2.12 should apply to 3.1. +.I "Mark Horton" ] +.NH 1 +Notation +.LP +\fB[option]\fR is used to denote optional parts of a command. +Many \fBvi\fR commands have an optional count. \fB[cnt]\fR +means that an optional number may precede the command to +multiply or iterate the command. +\fB{variable item}\fR is used to denote parts of the command +which must appear, but can take a number of different values. +\fB<character [-character]>\fR means that the character or +one of the characters in the range described between the +two angle brackets is to be typed. +For example \fB<esc>\fR means +the \fBescape\fR key is to be typed. \fB<a-z>\fR means that a +lower case letter is to be typed. \fB^<character>\fR means that +the character is to be typed as a \fBcontrol\fR character, that is, +with the \fB<cntl>\fR key held down while simultaneously typing +the specified character. In this document control characters will +be denoted using the \fIupper case\fR character, but +^<uppercase chr> and ^<lowercase chr> are equivalent. That is, for +example, \fB<^D>\fR is equal to \fB<^d>\fR. +The most common character abbreviations +used in this list are as follows: +.VL 8 +.IP <esc> 8 +escape, octal 033 +.IP <cr> 8 +carriage return, ^M, octal 015 +.IP <lf> 8 +linefeed ^J, octal 012 +.IP <nl> 8 +newline, ^J, octal 012 (same as linefeed) +.IP <bs> 8 +backspace, ^H, octal 010 +.IP <tab> 8 +tab, ^I, octal 011 +.IP <bell> 8 +bell, ^G, octal 07 +.IP <ff> 8 +formfeed, ^L, octal 014 +.IP <sp> 8 +space, octal 040 +.IP <del> 8 +delete, octal 0177 +.LE +.sp 1 +.NH 1 +Basics +.LP +To run \fBvi\fR the shell variable \fBTERM\fR must be defined and +exported to your environment. +How you do this depends on which shell you are using. +You can tell which shell you have by the character it +prompts you for commands with. +The Bourne shell prompts with `$', and the C shell prompts with `%'. +For these examples, we will suppose +that you are using an HP 2621 terminal, whose termcap name is ``2621''. +.NH 2 +Bourne Shell +.LP +To manually set your terminal type to 2621 you would type: +.DS +TERM=2621 +export TERM +.DE +.PP +There are various ways of having this automatically or +semi-automatically done when you log in. +Suppose you usually dial in on a 2621. +You want to tell this to the machine, but still have it +work when you use a hardwired terminal. +The recommended way, if you have the +.B tset +program, is to use the sequence +.DS +tset \-s \-d 2621 > tset$$ +\&. tset$$ +rm tset$$ +.DE +in your .login (for csh) or the same thing using `.' instead of `source' +in your .profile (for sh). +The above line says that if you are dialing in you are on a 2621, +but if you are on a hardwired terminal it figures out your terminal +type from an on-line list. +.NH 2 +The C Shell +.LP +To manually set your terminal type to 2621 you would type: +.DS +setenv TERM 2621 +.DE +.PP +There are various ways of having this automatically or +semi-automatically done when you log in. +Suppose you usually dial in on a 2621. +You want to tell this to the machine, but still have it +work when you use a hardwired terminal. +The recommended way, if you have the +.B tset +program, is to use the sequence +.DS +tset \-s \-d 2621 > tset$$ +source tset$$ +rm tset$$ +.DE +in your .login.* +.FS +* On a version 6 system +without environments, the invocation of tset +is simpler, just add the line ``tset \-d 2621'' +to your .login or .profile. +.FE +The above line says that if you are dialing in you are on a 2621, +but if you are on a hardwired terminal it figures out your terminal +type from an on-line list. +.NH 1 +Normal Commands +.LP +\fBVi\fR is a visual editor with a window on the file. What +you see on the screen is \fBvi\fR's current notion of +what your file will contain, +(at this point in the file), +when it is written out. +Most commands do not cause any change in the screen until the +complete command is typed. Should you get confused while +typing a command, you can abort the command by typing an +<del> character. You will know you are back to command level +when you hear a <bell>. Usually typing an <esc> will produce the +same result. When \fBvi\fR gets an improperly formatted command +it rings the <bell>. +Following are the \fBvi\fR commands broken down by function. +.NH 2 +Entry and Exit +.LP +To enter +.B vi +on a particular +.I file , +type +.DS +\fBvi\fP \fIfile\fP +.DE +The file will be read in and the cursor will be placed at the beginning +of the first line. +The first screenfull of the file will be displayed on the terminal. +.PP +To get out of the editor, type +.DS +ZZ +.DE +If you are in some special mode, such as input mode +or the middle of a multi-keystroke command, it may +be necessary to type <esc> first. +.NH 2 +Cursor and Page Motion +.LP +.VL 16 +.B NOTE: +The arrow keys (see the next four commands) +on certain kinds of terminals will not work with the +PDP-11 version of vi. The control versions or the hjkl versions will +work on any terminal. Experienced users prefer the hjkl keys because +they are always right under their fingers. Beginners often prefer +the arrow keys, since they do not require memorization of which hjkl +key is which. +The mnemonic value of hjkl is clear from looking at the keyboard of an adm3a. +.sp +.IP "[cnt]<bs> or [cnt]h or [cnt]\(<-" 16 +.br +Move the cursor to the left one character. Cursor stops at the left +margin of the page. +If cnt is given, these commands move that many spaces. +.IP "[cnt]^N or [cnt]j or [cnt]\(da or [cnt]<lf>" 16 +.br +Move down one line. +Moving off the screen scrolls the window to force a new line +onto the screen. +Mnemonic: \fBN\fRext +.IP "[cnt]^P or [cnt]k or [cnt]\(ua" 16 +.br +Move up one line. +Moving off the top of the screen forces new text onto the screen. +Mnemonic: \fBP\fRrevious +.IP "[cnt]<sp> or [cnt]l or [cnt]\(->" 16 +.br +Move to the right one character. +Cursor will not go beyond the end of the line. +.IP [cnt]- 16 +Move the cursor up the screen to the beginning of the next line. +Scroll if necessary. +.IP "[cnt]+ or [cnt]<cr>" 16 +.sp 1 +Move the cursor down the screen to the beginning of the next line. +Scroll up if necessary. +.IP "[cnt]$" 16 +Move the cursor to the end of the line. +If there is a count, move to the end of the line "cnt" lines +forward in the file. +.IP "^" 16 +Move the cursor to the beginning of the first word on the line. +.IP "0" 16 +Move the cursor to the left margin of the current line. +.IP "[cnt]|" 16 +Move the cursor to the column specified by the count. The default is +column zero. +.IP "[cnt]w" 16 +Move the cursor to the beginning of the next word. If there +is a count, then move forward that many words and +position the cursor at the beginning of the word. +Mnemonic: next-\fBw\fRord +.IP "[cnt]W" 16 +Move the cursor to the beginning of the next word which follows +a "white space" (<sp>,<tab>, or <nl>). Ignore other punctuation. +.IP "[cnt]b" 16 +Move the cursor to the preceding word. Mnemonic: \fBb\fRackup-word +.IP "[cnt]B" 16 +Move the cursor to the preceding word that is separated from the +current word by a "white space" (<sp>,<tab>, or <nl>). +.IP "[cnt]e" 16 +Move the cursor to the end of the current word or the end of the +"cnt"'th word hence. Mnemonic: \fBe\fRnd-of-word +.IP "[cnt]E" 16 +Move the cursor to the end of the current word which is delimited by +"white space" (<sp>,<tab>, or <nl>). +.IP "[line number]G" 16 +.br +Move the cursor to the line specified. Of particular use are the +sequences "1G" and "G", which move the cursor to the beginning and +the end of the file respectively. Mnemonic: \fBG\fRo-to +.LP +.B NOTE: +The next four commands (^D, ^U, ^F, ^B) +are not true motion commands, in that they +cannot be used as the object of commands such as delete or change. +.IP "[cnt]^D" 16 +Move the cursor down in the file by "cnt" lines (or the last "cnt" +if a new count isn't given. The initial default is half a page.) The +screen is simultaneously scrolled up. Mnemonic: \fBD\fRown +.IP "[cnt]^U" 16 +Move the cursor up in the file by "cnt" lines. The screen is simultaneously +scrolled down. Mnemonic: \fBU\fRp +.IP "[cnt]^F" 16 +Move the cursor to the next page. A count moves that many pages. +Two lines of the previous page are kept on the screen for continuity if +possible. Mnemonic: \fBF\fRorward-a-page +.IP "[cnt]^B" 16 +Move the cursor to the previous page. Two lines of the current page +are kept if possible. Mnemonic: \fBB\fRackup-a-page +.IP "[cnt](" 16 +Move the cursor to the beginning of the next sentence. +A sentence is defined as ending with a ".", "!", or "?" +followed by two spaces or a <nl>. +.IP "[cnt])" 16 +Move the cursor backwards to the beginning of a sentence. +.IP "[cnt]}" 16 +Move the cursor to the beginning of the next paragraph. This command +works best inside \fBnroff\fR documents. It understands two sets of +\fBnroff\fR macros, \fB\-ms\fR and \fB\-mm\fR, for which the +commands ".IP", ".LP", ".PP", ".QP", "P", as well as the nroff command ".bp" +are considered to be paragraph delimiters. +A blank line also delimits a paragraph. +The \fBnroff\fR macros that it accepts as paragraph delimiters is +adjustable. See \fBparagraphs\fR under the \fBSet Commands\fR section. +.IP "[cnt]{" 16 +Move the cursor backwards to the beginning of a paragraph. +.IP "]]" 16 +Move the cursor to the next "section", where a section is defined by +two sets of \fBnroff\fR macros, \fB\-ms\fR and \fB\-mm\fR, in which +".NH", ".SH", and ".H" delimit a section. A line beginning with a <ff><nl> +sequence, or a line beginning with a "{" are also considered to +be section delimiters. The last option makes it +useful for finding the beginnings of C functions. +The \fBnroff\fR macros that are used for section delimiters can be adjusted. +See \fBsections\fR under the \fBSet Commands\fR section. +.IP "[[" 16 +Move the cursor backwards to the beginning of a section. +.IP "%" 16 +Move the cursor to the matching parenthesis +or brace. This is very useful in C or lisp code. If the +cursor is sitting on a \fB( ) {\fR or \fB}\fR the cursor +is moved to the matching character at the other end of the +section. If the cursor is not sitting on a brace or a +parenthesis, \fBvi\fR searches forward until it finds one +and then jumps to the match mate. +.IP "[cnt]H" 16 +If there is no count move the cursor to the top left position on the screen. +If there is a count, then move the cursor to the beginning of the line +"cnt" lines from the top of the screen. Mnemonic: \fBH\fRome +.IP "[cnt]L" 16 +If there is no count move the cursor to the beginning +of the last line on the screen. +If there is a count, then move the cursor to the beginning of the line +"cnt" lines from the bottom of the screen. Mnemonic: \fBL\fRast +.IP "M" 16 +Move the cursor to the beginning of the middle line on the screen. +Mnemonic: \fBM\fRiddle +.IP "m<a-z>" 16 +This command does not move the cursor, but it \fBmarks\fR the place +in the file and the character "<a-z>" becomes the label for referring +to this location in the file. See the next two commands. Mnemonic: +\fBm\fRark +.B NOTE: +The mark command is not a motion, and cannot be used as the target +of commands such as delete. +.IP "\(aa<a-z>" 16 +Move the cursor to the beginning of the line that is marked with the label +"<a-z>". +.IP "\(ga<a-z>" 16 +Move the cursor to the exact position on the line that was marked with +with the label "<a-z>". +.IP "\(aa\(aa" 16 +Move the cursor back to the beginning of the line where it was before the +last "non-relative" move. A "non-relative" move is something such as a +search or a jump to a specific line in the file, rather than moving the +cursor or scrolling the screen. +.IP "\(ga\(ga" 16 +Move the cursor back to the exact spot on the line where it was located +before the last "non-relative" move. +.LE +.NH 2 +Searches +.LP +The following commands allow you to search for items in a file. +.VL 16 +.IP [cnt]f{chr} 16 +.sp 1 +Search forward on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBat\fR the character +of interest. Mnemonic: \fBf\fRind character +.IP [cnt]F{chr} 16 +.sp 1 +Search backwards on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBat\fR the character +of interest. +.IP [cnt]t{chr} 16 +.sp 1 +Search forward on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBjust preceding\fR +the character of interest. Mnemonic: move cursor up \fBt\fRo character +.IP [cnt]T{chr} 16 +.sp 1 +Search backwards on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBjust preceding\fR +the character of interest. +.IP "[cnt];" 16 +Repeat the last "f", "F", "t" or "T" command. +.IP "[cnt]," 16 +Repeat the last "f", "F", "t" or "T" command, but in the opposite +search direction. This is useful if you overshoot. +.IP "[cnt]/[string]/<nl>" 16 +.br +Search forward for the next occurrence of "string". +Wrap around at the end of the file +does occur. +The final \fB</>\fR is not required. +.IP "[cnt]?[string]?<nl>" 16 +.br +Search backwards for the next occurrence of "string". If a count is +specified, the count becomes the new window size. Wrap around at the beginning +of the file does occur. +The final \fB<?>\fR is not required. +.IP n 16 +Repeat the last /[string]/ or ?[string]? search. Mnemonic: \fBn\fRext +occurrence. +.IP N 16 +Repeat the last /[string]/ or ?[string]? search, but in the reverse +direction. +.IP ":g/[string]/[editor command]<nl>" 16 +.sp 1 +Using the \fB:\fR syntax it is possible to do global searches ala the +standard UNIX "ed" editor. +.LE +.NH 2 +Text Insertion +.LP +The following commands allow for the insertion of text. All multicharacter +text insertions are terminated with an <esc> character. +The last change +can always be \fBundone\fR by typing a \fBu\fR. +The text insert in insertion mode can contain newlines. +.VL 16 +.IP a{text}<esc> 16 +Insert text immediately following the cursor position. +Mnemonic: \fBa\fRppend +.IP A{text}<esc> 16 +Insert text at the end of the current line. +Mnemonic: \fBA\fRppend +.IP i{text}<esc> 16 +Insert text immediately preceding the cursor position. +Mnemonic: \fBi\fRnsert +.IP I{text}<esc> 16 +Insert text at the beginning of the current line. +.IP o{text}<esc> 16 +Insert a new line after the line on which the cursor appears and +insert text there. Mnemonic: \fBo\fRpen new line +.IP O{text}<esc> 16 +Insert a new line preceding the line on which the cursor appears +and insert text there. +.LE +.NH 2 +Text Deletion +.LP +The following commands allow the user to delete text in various ways. +All changes can always be \fBundone\fR by typing the \fBu\fR command. +.VL 16 +.IP "[cnt]x" 16 +Delete the character or characters starting at the cursor position. +.IP "[cnt]X" 16 +Delete the character or characters starting at the character preceding +the cursor position. +.IP "D" 16 +Deletes the remainder of the line starting at the cursor. +Mnemonic: \fBD\fRelete the rest of line +.IP "[cnt]d{motion}" 16 +.br +Deletes one or more occurrences of the specified motion. +Any motion from sections 4.1 and 4.2 can be used here. +The d can be stuttered (e.g. [cnt]dd) to delete cnt lines. +.LE +.NH 2 +Text Replacement +.LP +The following commands allow the user to simultaneously delete and +insert new text. All such actions can be \fBundone\fR by typing +\fBu\fR following the command. +.VL 16 +.IP "r<chr>" 16 +Replaces the character at the current cursor position with <chr>. This +is a one character replacement. No <esc> is required for termination. +Mnemonic: \fBr\fReplace character +.IP "R{text}<esc>" 16 +Starts overlaying the characters on the screen with whatever you type. +It does not stop until an <esc> is typed. +.IP "[cnt]s{text}<esc>" 16 +Substitute for "cnt" characters beginning at the current cursor +position. A "$" will appear at the position in the text where the +"cnt"'th character appears so you will know how much you are erasing. +Mnemonic: \fBs\fRubstitute +.IP "[cnt]S{text}<esc>" 16 +Substitute for the entire current line (or lines). If no count is given, +a "$" appears at the end of the current line. If a count of more than +1 is given, all the lines to be replaced are deleted before the insertion +begins. +.IP "[cnt]c{motion}{text}<esc>" 16 +.br +Change the specified "motion" by replacing it with the +insertion text. A "$" will appear at the end of the last item +that is being deleted unless the deletion involves whole lines. +Motion's can be any motion from sections 4.1 or 4.2. +Stuttering the c (e.g. [cnt]cc) changes cnt lines. +.LE +.NH 2 +Moving Text +.LP +\fBVi\fR provides a number of ways of moving chunks of text around. +There are nine buffers into which each piece of text which is deleted +or "yanked" is put in addition to the "undo" buffer. +The most recent deletion or yank is in the "undo" buffer and also +usually in buffer +1, the next most recent in buffer 2, and so forth. Each new deletion +pushes down all the older deletions. Deletions older than 9 +disappear. There is also +a set of named registers, a-z, into which text can optionally +be placed. If any delete or replacement type command is preceded +by \fB"<a-z>\fR, that named buffer will contain the text deleted +after the command is executed. For example, \fB"a3dd\fR will delete +three lines starting at the current line and put them in buffer \fB"a\fR.* +.FS +* Referring to an upper case letter as a buffer name (A-Z) is the +same as referring to the lower case letter, except that text placed +in such a buffer is appended to it instead of replacing it. +.FE +There are two more basic commands and +some variations useful in getting and putting text into a file. +.VL 16 +.IP ["<a-z>][cnt]y{motion} 16 +.sp 1 +Yank the specified item or "cnt" items and put in the "undo" buffer or +the specified buffer. The variety of "items" that can be yanked +is the same as those that can be deleted with the "d" command or +changed with the "c" command. In the same way that "dd" means +delete the current line and "cc" means replace the current line, +"yy" means yank the current line. +.IP ["<a-z>][cnt]Y 16 +Yank the current line or the "cnt" lines starting from the current +line. If no buffer is specified, they will go into the "undo" buffer, +like any delete would. It is equivalent to "yy". +Mnemonic: \fBY\fRank +.IP ["<a-z>]p 16 +Put "undo" buffer or the specified buffer down \fBafter\fR the cursor. +If whole lines were yanked or deleted into the buffer, then they will be +put down on the line following the line the cursor is on. If +something else was deleted, like a word or sentence, then it will +be inserted immediately following the cursor. +Mnemonic: \fBp\fRut buffer +.IP +It should be noted that text in the named buffers remains there when you +start editing a new file with the \fB:e file<esc>\fR command. Since +this is so, it is possible to copy or delete text from one file and +carry it over to another file in the buffers. +However, the undo buffer and the ability to undo are lost when +changing files. +.IP ["<a-z>]P 16 +Put "undo" buffer or the specified buffer down \fBbefore\fR the cursor. +If whole lines where yanked or deleted into the buffer, then they will be +put down on the line preceding the line the cursor is on. If +something else was deleted, like a word or sentence, then it will +be inserted immediately preceding the cursor. +.IP [cnt]>{motion} 16 +The shift operator will right shift all the text from the line on which +the cursor is located to the line where the \fBmotion\fR is located. +The text is shifted by one \fBshiftwidth\fR. (See section 6.) +\fB>>\fR means right shift the current line or lines. +.IP [cnt]<{motion} 16 +The shift operator will left shift all the text from the line on which +the cursor is located to the line where the \fBitem\fR is located. +The text is shifted by one \fBshiftwidth\fR. (See section 6.) +\fB<<\fR means left shift the current line or lines. +Once the line has reached the left margin it is not further affected. +.IP [cnt]={motion} 16 +Prettyprints the indicated area according to +.B lisp +conventions. +The area should be a lisp s-expression. +.LE +.NH 2 +Miscellaneous Commands +.LP +\fBVi\fR has a number of miscellaneous commands that are very +useful. They are: +.VL 16 +.IP ZZ 16 +This is the normal way to exit from vi. +If any changes have been made, the file is written out. +Then you are returned to the shell. +.IP ^L 16 +Redraw the current screen. This is useful if someone "write"s you +while you are in "vi" or if for any reason garbage gets onto the +screen. +.IP ^R 16 +On dumb terminals, those not having the "delete line" function +(the vt100 is such a terminal), \fBvi\fR saves redrawing the +screen when you delete a line by just marking the line with an +"@" at the beginning and blanking the line. If you want to +actually get rid of the lines marked with "@" and see what the +page looks like, typing a ^R will do this. +.IP \s+4.\s0 16 +"Dot" is a particularly useful command. It repeats the last +text modifying command. Therefore you can type a command once and +then to another place and repeat it by just typing ".". +.IP u 16 +Perhaps the most important command in the editor, +u undoes the last command that changed the buffer. +Mnemonic: \fBu\fRndo +.IP U 16 +Undo all the text modifying commands performed on the current line +since the last time you moved onto it. +.IP [cnt]J 16 +Join the current line and the following line. The <nl> is deleted +and the two lines joined, usually with a space between the +end of the first line and the beginning of what was the second +line. If the first line ended with a "period", then two spaces +are inserted. +A count joins the next cnt lines. +Mnemonic: \fBJ\fRoin lines +.IP Q 16 +Switch to \fBex\fR editing mode. +In this mode \fBvi\fR will behave very much like \fBed\fR. +The editor in this mode will operate on single lines normally and +will not attempt to keep the "window" up to date. +Once in this mode it is also possible to switch to the \fBopen\fR +mode of editing. By entering the command \fB[line number]open<nl>\fR +you enter this mode. It is similar to the normal visual mode +except the window is only \fBone\fR line long. +Mnemonic: \fBQ\fRuit visual mode +.IP ^] 16 +An abbreviation for a tag command. +The cursor should be positioned at the beginning of a word. +That word is taken as a tag name, and the tag with that +name is found as if it had been typed in a :tag command. +.IP [cnt]!{motion}{UNIX\ cmd}<nl> 16 +.br +Any UNIX filter +(e.g. command that reads the standard input and outputs something +to the standard output) can be sent a section of the current file and +have the output of the command replace the original text. Useful +examples are programs like \fBcb\fR, \fBsort\fR, and +\fBnroff\fR. For instance, using \fBsort\fR it would be possible to +sort a section of the current file into a new list. +Using \fB!!\fR means take a line or lines starting at the line the +cursor is currently on and pass them to the UNIX command. +.B NOTE: +To just escape to the shell for one command, +use :!{cmd}<nl>, see section 5. +.IP z{cnt}<nl> 16 +This resets the current window size to "cnt" lines and redraws the screen. +.LE +.NH 2 +Special Insert Characters +.LP +There are some characters that have special meanings during +insert modes. They are: +.VL 16 +.IP ^V 16 +During inserts, typing a ^V allows you to quote control characters +into the file. Any character typed after the ^V will be inserted +into the file. +.IP [^]^D\ or\ [0]^D 16 +<^D> without any argument backs up one \fBshiftwidth\fR. This is necessary +to remove indentation that was inserted by the \fBautoindent\fR feature. +^<^D> temporarily removes all the autoindentation, thus placing the cursor +at the left margin. On the next line, the previous indent level will be +restored. This is useful for putting "labels" at the left margin. +0<^D> says remove all autoindents and stay that way. Thus the cursor +moves to the left margin and stays there on successive lines until +<tab>'s are typed. As with the <tab>, the <^D> is only effective before +any other "non-autoindent" controlling characters are typed. +Mnemonic: \fBD\fRelete a shiftwidth +.IP ^W 16 +If the cursor is sitting on a word, <^W> moves the cursor back to the beginning +of the word, thus erasing the word from the insert. +Mnemonic: erase \fBW\fRord +.IP <bs> 16 +The backspace always serves as an erase during insert modes in addition +to your normal "erase" character. To insert a <bs> into your file, use +the <^V> to quote it. +.LE +.NH 1 +\fB:\fR Commands +.LP +Typing a ":" during command mode causes \fBvi\fR to put the cursor at +the bottom on the screen in preparation for a command. In the +":" mode, \fBvi\fR can be given most \fBed\fR commands. It is +also from this mode that you exit from \fBvi\fR or switch to different +files. All commands of this variety are terminated by a <nl>, <cr>, +or <esc>. +.VL 16 +.IP ":w[!] [file]" 16 +Causes \fBvi\fR to write out the current text to the disk. It is +written to the file you are editing unless "file" is supplied. If +"file" is supplied, the write is directed to that file instead. If +that file already exists, \fBvi\fR will not perform the write unless +the "!" is supplied indicating you +.I really +want to destroy the older copy of the file. +.IP :q[!] 16 +Causes \fBvi\fR to exit. If you have modified the file you are +looking at currently and haven't written it out, \fBvi\fR will +refuse to exit unless the "!" is supplied. +.IP ":e[!] [+[cmd]] [file]" 16 +.sp 1 +Start editing a new file called "file" or start editing the current +file over again. The command ":e!" says "ignore the changes I've made +to this file and start over from the beginning". It is useful if +you really mess up the file. The optional "+" says instead of starting +at the beginning, start at the "end", or, +if "cmd" is supplied, execute "cmd" first. +Useful cases of this are where cmd is "n" (any integer) which starts +at line number n, +and "/text", which searches for "text" and starts at the line where +it is found. +.IP "^^" 16 +Switch back to the place you were before your last tag command. +If your last tag command stayed within the file, ^^ returns to that tag. +If you have no recent tag command, it will return to the +same place in the previous file that it was showing when you switched +to the current file. +.IP ":n[!]" 16 +Start editing the next file in the argument list. Since \fBvi\fR +can be called with multiple file names, the ":n" command tells it to +stop work on the current file and switch to the next file. If the +current file was modifies, it has to be written out before the ":n" +will work or else the "!" must be supplied, which says discard the +changes I made to the current file. +.IP ":n[!] file [file file ...]" 16 +.sp +Replace the current argument list with a new list of files and start +editing the first file in this new list. +.IP ":r file" 16 +Read in a copy of "file" on the line after the cursor. +.IP ":r !cmd" 16 +Execute the "cmd" and take its output and put it into the file after +the current line. +.IP ":!cmd" 16 +Execute any UNIX shell command. +.IP ":ta[!] tag" 16 +.B Vi +looks in the file named +.B tags +in the current directory. +.B Tags +is a file of lines in the format: +.sp 1 +.ti +8 +tag filename \fBvi\fR-search-command +.sp 1 +If \fBvi\fR finds the tag you specified in the \fB:ta\fR command, +it stops editing the current file if necessary and if the current file is +up to date on the disk and switches to the file specified and uses the +search pattern specified to find the "tagged" item of interest. This +is particularly useful when editing multi-file C programs such as the +operating system. There is a program called \fBctags\fR which will +generate an appropriate \fBtags\fR file for C and f77 +programs so that by saying +\fB:ta function<nl>\fR you will be switched to that function. +It could also be useful when editing multi-file documents, though the +\fBtags\fR file would have to be generated manually. +.LE +.NH 1 +Special Arrangements for Startup +.PP +\fBVi\fR takes the value of \fB$TERM\fR and looks up the characteristics +of that terminal in the file \fB/etc/termcap\fR. +If you don't know \fBvi\fR's name for the terminal you are working +on, look in \fB/etc/termcap\fR. +.PP +When \fBvi\fR starts, it attempts to read the variable EXINIT +from your environment.* +If that exists, it takes the values in it as the default values +for certain of its internal constants. See the section on "Set Values" +for further details. +If EXINIT doesn't exist you will get all the normal defaults. +.FS +* On version 6 systems +Instead of EXINIT, put the startup commands in the file .exrc +in your home directory. +.FE +.PP +Should you inadvertently hang up the phone while inside +.B vi , +or should the computer crash, +all may not be lost. +Upon returning to the system, type: +.DS +vi \-r file +.DE +This will normally recover the file. If there is more than one +temporary file for a specific file name, \fBvi\fR recovers the +newest one. You can get an older version by recovering the +file more than once. +The command "vi -r" without a file name gives you the list of files +that were saved in the last system crash +(but +.I not +the file just saved when the phone was hung up). +.NH 1 +Set Commands +.LP +\fBVi\fR has a number of internal variables and switches which can be +set to achieve special affects. +These options come in three forms, those that are switches, which toggle +from off to on and back, those that require a numeric value, and those +that require an alphanumeric string value. +The toggle options are set by a command of the form: +.DS +:set option<nl> +.DE +and turned off with the command: +.DS +:set nooption<nl> +.DE +Commands requiring a value are set with a command of the form: +.DS +:set option=value<nl> +.DE +To display the value of a specific option type: +.DS +:set option?<nl> +.DE +To display only those that you have changed type: +.DS +:set<nl> +.DE +and to display the long table of all the settable parameters and +their current values type: +.DS +:set all<nl> +.DE +.PP +Most of the options have a long form and an abbreviation. Both are +listed in the following table as well as the normal default value. +.PP +To arrange to have values other than the default used every time you +enter +.B vi , +place the appropriate +.B set +command in EXINIT in your environment, e.g. +.DS +EXINIT='set ai aw terse sh=/bin/csh' +export EXINIT +.DE +or +.DS +setenv EXINIT 'set ai aw terse sh=/bin/csh' +.DE +for +.B sh +and +.B csh , +respectively. +These are usually placed in your .profile or .login. +If you are running a system without environments (such as version 6) +you can place the set command in the file .exrc in your home +directory. +.VL 16 +.IP autoindent\ ai 16 +Default: noai Type: toggle +.br +When in autoindent mode, vi helps you indent code by starting each +line in the same column as the preceding line. +Tabbing to the right with <tab> or <^T> will move this boundary to +the right, and it can be moved to the left with <^D>. +.IP autoprint\ ap 16 +Default: ap Type: toggle +.br +Causes the current line to be printed after each ex text modifying command. +This is not of much interest in the normal \fBvi\fR visual mode. +.IP autowrite\ aw 16 +Default: noaw type: toggle +.br +Autowrite causes an automatic write to be done if there are unsaved +changes before certain commands which change files or otherwise +interact with the outside world. +These commands are :!, :tag, :next, :rewind, ^^, and ^]. +.IP beautify\ bf 16 +Default: nobf Type: toggle +.br +Causes all control characters except <tab>, <nl>, and <ff> to be discarded. +.IP directory\ dir 16 +Default: dir=/tmp Type: string +.br +This is the directory in which \fBvi\fR puts its temporary file. +.IP errorbells\ eb 16 +Default: noeb Type: toggle +.br +Error messages are preceded by a <bell>. +.IP hardtabs\ ht 16 +Default: hardtabs=8 Type: numeric +.br +This option contains the value of hardware tabs in your terminal, or +of software tabs expanded by the Unix system. +.IP ignorecase\ ic 16 +Default: noic Type: toggle +.br +All upper case characters are mapped to lower case in regular expression +matching. +.IP lisp 16 +Default: nolisp Type: toggle +.br +Autoindent for \fBlisp\fR code. The commands \fB( ) [[\fR and \fB]]\fR +are modified appropriately to affect s-expressions and functions. +.IP list 16 +Default: nolist Type: toggle +.br +All printed lines have the <tab> and <nl> characters displayed visually. +.IP magic 16 +Default: magic Type: toggle +.br +Enable the metacharacters for matching. These include \fB. * < > [string] +[^string]\fR and \fB[<chr>-<chr>]\fR. +.IP number\ nu 16 +Default: nonu Type: toggle +.br +Each line is displayed with its line number. +.IP open 16 +Default: open Type: toggle +.br +When set, prevents entering open or visual modes from ex or edit. +Not of interest from vi. +.IP optimize\ opt 16 +Default: opt Type: toggle +.br +Basically of use only when using the \fBex\fR capabilities. This +option prevents automatic <cr>s from taking place, +and speeds up output of indented lines, +at the expense of losing typeahead on some versions of UNIX. +.IP paragraphs\ para 16 +Default: para=IPLPPPQPP\ bp Type: string +.br +Each pair of characters in the string indicate \fBnroff\fR macros +which are to be treated as the beginning of a paragraph for the +\fB{\fR and \fB}\fR commands. The default string is for the \fB-ms\fR +and \fB-mm\fR macros. +To indicate one letter \fBnroff\fR macros, such as \fB.P\fR or \fB.H\fR, +quote a space in for the second character position. For example: +.sp 1 +.ti +8 +:set paragraphs=P\e bp<nl> +.sp 1 +would cause \fBvi\fR to consider \fB.P\fR and \fB.bp\fR as paragraph +delimiters. +.IP prompt 16 +Default: prompt Type: toggle +.br +In +.B ex +command mode the prompt character \fB:\fR will be printed when +\fBex\fR is waiting for a command. This is not of interest from vi. +.IP redraw 16 +Default: noredraw Type: toggle +.br +On dumb terminals, force the screen to always be up to date, +by sending great amounts of output. Useful only at high speeds. +.IP report 16 +Default: report=5 Type: numeric +.br +This sets the threshold for the number of lines modified. When +more than this number of lines are modified, removed, or yanked, +\fBvi\fR will report the number of lines changed at the bottom of +the screen. +.IP scroll 16 +Default: scroll={1/2 window} Type: numeric +.br +This is the number of lines that the screen scrolls up or down when +using the <^U> and <^D> commands. +.IP sections 16 +Default: sections=SHNHH HU Type: string +.br +Each two character pair of this string specify \fBnroff\fR macro names +which are to be treated as the beginning of a section by the +\fB]]\fR and \fB[[\fR commands. The default string is for the \fB-ms\fR +and \fB-mm\fR macros. +To enter one letter \fBnroff\fR macros, use a quoted space as the +second character. +See \fBparagraphs\fR for a fuller explanation. +.IP shell\ sh 16 +Default: sh=from environment SHELL or /bin/sh Type: string +.br +This is the name of the \fBsh\fR to be used for "escaped" commands. +.IP shiftwidth\ sw 16 +Default: sw=8 Type: numeric +.br +This is the number of spaces that a <^T> or <^D> will move over for +indenting, and the amount < and > shift by. +.IP showmatch\ sm 16 +Default: nosm Type: toggle +.br +When a \fB)\fR or \fB}\fR is typed, show the matching \fB(\fR or \fB{\fR +by moving the cursor to it for one second if it is on the current screen. +.IP slowopen\ slow 16 +Default: terminal dependent Type: toggle +.br +On terminals that are slow and unintelligent, this option prevents the +updating of the screen some of the time to improve speed. +.IP tabstop\ ts 16 +Default: ts=8 Type: numeric +.br +<tab>s are expanded to boundaries that are multiples of this value. +.IP taglength\ tl 16 +Default: tl=0 Type: numeric +.br +If nonzero, tag names are only significant to this many characters. +.IP term 16 +Default: (from environment \fBTERM\fP, else dumb) Type: string +.br +This is the terminal and controls the visual displays. It cannot be +changed when in "visual" mode, +you have to Q to command mode, type a +set term command, and do ``vi.'' to get back into visual. +Or exit vi, fix $TERM, and reenter. +The definitions that drive a particular +terminal type are found in the file \fB/etc/termcap\fR. +.IP terse 16 +Default: terse Type: toggle +.br +When set, the error diagnostics are short. +.IP warn 16 +Default: warn Type: toggle +.br +The user is warned if she/he tries to escape to +the shell without writing out the current changes. +.IP window 16 +Default: window={8 at 600 baud or less, 16 at 1200 baud, and screen +size \- 1 at 2400 baud or more} Type: numeric +.br +This is the number of lines in the window whenever \fBvi\fR must redraw +an entire screen. It is useful to make this size smaller if you are +on a slow line. +.IP w300,\ w1200,\ w9600 +.br +These set window, but only within the corresponding speed ranges. +They are useful in an EXINIT to fine tune window sizes. +For example, +.DS +set w300=4 w1200=12 +.DE +causes a 4 lines window at speed up to 600 baud, a 12 line window at 1200 +baud, and a full screen (the default) at over 1200 baud. +.IP wrapscan\ ws 16 +Default: ws Type: toggle +.br +Searches will wrap around the end of the file when is option is set. When +it is off, the search will terminate when it reaches the end or the +beginning of the file. +.IP wrapmargin\ wm 16 +Default: wm=0 Type: numeric +.br +\fBVi\fR will automatically insert a <nl> when it finds a natural +break point (usually a <sp> between words) that occurs within +"wm" spaces of the right margin. +Therefore with "wm=0" the option is off. Setting it to 10 would +mean that any time you are within 10 spaces of the right margin +\fBvi\fR would be looking for a <sp> or <tab> which it could +replace with a <nl>. This is convenient for people who forget +to look at the screen while they type. +(In version 3, wrapmargin behaves more like nroff, in that the +boundary specified by the distance from the right edge of the screen +is taken as the rightmost edge of the area where a break is allowed, +instead of the leftmost edge.) +.IP writeany\ wa 16 +Default: nowa Type: toggle +.br +\fBVi\fR normally makes a number of checks before it writes out a file. +This prevents the user from inadvertently destroying a file. When the +"writeany" option is enabled, \fBvi\fR no longer makes these checks. +.LE diff --git a/share/doc/usd/13.viref/Makefile b/share/doc/usd/13.viref/Makefile new file mode 100644 index 000000000000..c7a03af2c7aa --- /dev/null +++ b/share/doc/usd/13.viref/Makefile @@ -0,0 +1,34 @@ +VOLUME= usd/13.viref +EXTRA= ex.cmd.roff ref.so set.opt.roff vi.cmd.roff +MACROS= -me +CLEANFILES= vi.ref-patched index +TRFLAGS= -U # this is to hide warnings only +USE_SOELIM= +USE_TBL= + +vi.ref-patched: vi.ref + sed -e 's:^\.so index.so$$:&.\\*[.T]:' ${.ALLSRC} > ${.TARGET} + +PRINTERDEVICE?= ascii +.for _dev in ${PRINTERDEVICE} +SRCS+= vi.ref-${_dev} +EXTRA+= index.so.${_dev} +CLEANFILES+= index.so.${_dev} vi.ref-${_dev} + +vi.ref-${_dev}: index.so.${_dev} + sed -e 's:^\.so index\.so\.\\\*\[\.T\]$$:${_dev}:' vi.ref-patched > ${.TARGET} + +# Build index.so as a side-effect of building the paper. +index.so.${_dev}: vi.ref-patched ${EXTRA:Nindex.so.${_dev}} + sed -e 's:^\.so index\.so\.\\\*\[\.T\]$$::' vi.ref-patched | \ + ${ROFF.${_dev}} -U -z + sed -e 's/MINUSSIGN/-/' \ + -e 's/DOUBLEQUOTE/""/' \ + -e "s/SQUOTE/'/" \ + -e 's/ /__SPACE/g' < index | \ + sort -u '-t ' -k 1,1 -k 2n | awk -f ${.CURDIR}/merge.awk | \ + sed -e 's/__SPACE/ /g' \ + -e "s/^\\(['\\.]\\)/\\\\\&\\1/" > ${.TARGET} +.endfor + +.include <bsd.doc.mk> diff --git a/share/doc/usd/13.viref/ex.cmd.roff b/share/doc/usd/13.viref/ex.cmd.roff new file mode 100644 index 000000000000..73531eaa7e6f --- /dev/null +++ b/share/doc/usd/13.viref/ex.cmd.roff @@ -0,0 +1,1922 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.SH 1 "Ex Description" +.pp +The following words have special meanings for +.CO ex +commands. +.KY "<end-of-file>" +.IP "<end-of-file>" +The end-of-file character is used to scroll the screen in the +.CO ex +editor. +This character is normally +.LI <control-D> . +However, whatever character is set for the current terminal is supported +as well as +.LI <control-D> . +.KY "line" +.IP "line" +A single-line address, given in any of the forms described in the +section entitled +.QB "Ex Addressing" . +The default for +.LI line +is the current line. +.KY "range" +.IP "range" +A line, or a pair of line addresses, separated by a comma or semicolon. +(See the section entitled +.QB "Ex Addressing" +for more information.) +The default for range is the current line +.i only , +i.e. +.QT \&.,. . +A percent sign +.PQ % +stands for the range +.QT 1,$ . +The starting address must be less than, or equal to, the ending address. +.KY "count" +.IP "count" +A positive integer, specifying the number of lines to be affected by +the command; the default is 1. +Generally, a count past the end-of-file may be specified, e.g. the +command +.QT "p 3000" +in a 10 line file is acceptable, and will print from the current line +through the last line in the file. +.KY "flags" +.IP "flags" +One or more of the characters +.QQ # , +.QQ p , +and +.QQ l . +When a command that accepts these flags completes, the addressed line(s) +are written out as if by the corresponding +.CO # , +.CO l +or +.CO p +commands. +In addition, any number of +.QT + +or +.QT \- +characters can be specified before, after, or during the flags, in which +case the line written is not necessarily the one affected by the command, +but rather the line addressed by the offset address specified. +The default for +.LI flags +is none. +.KY "file" +.IP "file" +A pattern used to derive a pathname; the default is the current file. +File names are subjected to normal +.XR sh 1 +word expansions. +.pp +Anywhere a file name is specified, it is also possible to use +the special string +.QT /tmp . +This will be replaced with a temporary file name which can be used +for temporary work, e.g. +.QT ":e /tmp" +creates and edits a new file. +.pp +If both a count and a range are specified for commands that use either, +the starting line for the command is the +.i last +line addressed by the range, and +.LI count - 1 +subsequent lines are affected by the command, e.g. the command +.QT 2,3p4 +prints out lines 3, 4, 5 and 6. +.pp +When only a line or range is specified, with no command, the implied +command is either a +.CO list , +.CO number +or +.CO print +command. +The command used is the most recent of the three commands to have been +used (including any use as a flag). +If none of these commands have been used before, the +.CO print +command is the implied command. +When no range or count is specified and the command line is a blank line, +the current line is incremented by 1 and then the current line is displayed. +.pp +Zero or more whitespace characters may precede or follow the addresses, +count, flags, or command name. +Any object following a command name (such as buffer, file, etc.), +that begins with an alphabetic character, +should be separated from the command name by at least one whitespace +character. +.pp +Any character, including +.LI <carriage-return> , +.QT % +and +.QT # +retain their literal value when preceded by a backslash. +.SH 1 "Ex Commands" +.pp +The following section describes the commands available in the +.CO ex +editor. +In each entry below, the tag line is a usage synopsis for the command. +.pp +Each command can be entered as the abbreviation +(those characters in the synopsis command word preceding the +.QQ [ +character), +the full command (all characters shown for the command word, +omitting the +.QQ [ +and +.QQ ] +characters), +or any leading subset of the full command down to the abbreviation. +For example, the args command (shown as +.QT ar[gs] +in the synopsis) +can be entered as +.QT ar , +.QT arg +or +.QT args . +.pp +Each +.CO ex +command described below notes the new current line after it +is executed, as well as any options that affect the command. +.\" I cannot get a double quote to print to save my life. The ONLY way +.\" I've been able to get this to work is with the .tr command. +.tr Q" +.ds ms Q +.KY DOUBLEQUOTE +.IP "\*(ms" +.tr QQ +A comment. +Command lines beginning with the double-quote character +.PQ """" +are ignored. +This permits comments in editor scripts and startup files. +.KY "<control-D>" +.KY "<end-of-file>" +.IP "<control-D>" +.IP "<end-of-file>" +Scroll the screen. +Write the next N lines, where N is the value of the +.OP scroll +option. +The command is the end-of-file terminal character, which may be +different on different terminals. +Traditionally, it is the +.LI <control-D> +key. +.sp +Historically, the +.CO eof +command ignored any preceding count, and the +.LI <end-of-file> +character was ignored unless it was entered as the first character +of the command. +This implementation treats it as a command +.i only +if entered as the first character of the command line, and otherwise +treats it as any other character. +.SS +.SP Line: +Set to the last line written. +.SP Options: +Affected by the +.OP scroll +option. +.SE +.KY "!" +.IP "! argument(s)" +.Ip "[range]! argument(s)" +Execute a shell command, or filter lines through a shell command. +In the first synopsis, the remainder of the line after the +.QT ! +character is passed to the program named by the +.OP shell +option, as a single argument. +.sp +Within the rest of the line, +.QT % +and +.QT # +are expanded into the current and alternate pathnames, respectively. +The character +.QT ! +is expanded with the command text of the previous +.CO ! +command. +(Therefore, the command +.CO !! +repeats the previous +.CO ! +command.) +The special meanings of +.QT % , +.QT # , +and +.QT ! +can be overridden by escaping them with a backslash. +If no +.CO ! +or +.CO :! +command has yet been executed, it is an error to use an unescaped +.QT ! +character. +The +.CO ! +command does +.i not +do shell expansion on the strings provided as arguments. +If any of the above expansions change the command the user entered, +the command is redisplayed at the bottom of the screen. +.sp +.CO Ex +then executes the program named by the +.OP shell +option, with a +.b \-c +flag followed by the arguments (which are bundled into a single argument). +.sp +The +.CO ! +command is permitted in an empty file. +.sp +If the file has been modified since it was last completely written, +the +.Co ! +command will warn you. +.sp +A single +.QT ! +character is displayed when the command completes. +.sp +In the second form of the +.CO ! +command, the remainder of the line after the +.QT ! +is passed to the program named by the +.OP shell +option, as described above. +The specified lines are passed to the program as standard input, +and the standard and standard error output of the program replace +the original lines. +.SS +.SP Line: +Unchanged if no range was specified, otherwise set to the first +line of the range. +.SP Options: +Affected by the +.OP shell +and +.OP warn +options. +.SE +.KY "#" +.IP "[range] # [count] [flags]" +.KY "number" +.Ip "[range] nu[mber] [count] [flags]" +Display the selected lines, each preceded with its line number. +.sp +The line number format is +.QQ %6d , +followed by two spaces. +.SS +.SP Line: +Set to the last line displayed. +.SP Options: +Affected by the +.OP list +option. +.SE +.KY "@" +.IP "@ buffer" +.KY "*" +.Ip "* buffer" +Execute a buffer. +Each line in the named buffer is executed as an +.CO ex +command. +If no buffer is specified, or if the specified buffer is +.QT @ +or +.QT * , +the last buffer executed is used. +.KY < +.IP "[range] <[< ...] [count] [flags]" +Shift lines left or right. +The specified lines are shifted to the left (for the +.CO < +command) or right (for the +.CO > +command), by the number of columns specified by the +.OP shiftwidth +option. +Only leading whitespace characters are deleted when shifting left; +once the first column of the line contains a nonblank character, +the +.CO shift +command will succeed, but the line will not be modified. +.sp +If the command character +.CO < +or +.CO > +is repeated more than once, the command is repeated once for each +additional command character. +.SS +.SP Line: +If the current line is set to one of the lines that are affected +by the command, it is unchanged. +Otherwise, it is set to the first nonblank character of the lowest +numbered line shifted. +.SP Options: +Affected by the +.OP shiftwidth +option. +.SE +.KY = +.IP "[line] = [flags]" +Display the line number of +.LI line +(which defaults to the last line in the file). +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY > +.IP "[range] >[> ...] [count] [flags]" +Shift right. +The specified lines are shifted to the right by the number of columns +specified by the +.OP shiftwidth +option, by inserting tab and space characters. +Empty lines are not changed. +.sp +If the command character +.QT > +is repeated more than once, the command is repeated once for each +additional command character. +.SS +.SP Line: +Set to the last line modified by the command. +.SP Options: +Affected by the +.OP shiftwidth +option. +.SE +.KY abbrev +.IP "ab[brev] lhs rhs" +Add an abbreviation to the current abbreviation list. +When inserting text in +.CO vi , +each time a non-word character is entered after a word character, +a set of characters ending at the word character are checked for +a match with +.LI lhs . +If a match is found, they are replaced with +.LI rhs . +The set of characters that are checked for a match are defined as follows, +for inexplicable historical reasons. +If only one or two characters were entered before the non-word character +that triggered the check, +and after the beginning of the insertion, +or the beginning of the line or the file, +or the last +.LI <blank> +character that was entered, +then the one or the both characters are checked for a match. +Otherwise, the set includes both characters, +as well as the characters that precede them that are the same word +class (i.e. word or non-word) as the +.b second +to last character entered before the non-word character that triggered +the check, +back to the first +.LI <blank> character, +the beginning of the insertion, +or the beginning of the line or the file. +.sp +For example, the abbreviations: +.sp +.ne 3v +.ft C +.TS +r l l. +:abbreviate abc ABC +:abbreviate #i #include +:abbreviate /*#i /*#include +.TE +.ft R +will all work, while the abbreviations: +.sp +.ne 2v +.ft C +.TS +r l l. +:abbreviate a#i A#include +:abbreviate /* /******************** +.TE +.ft R +will not work, and are not permitted by +.CO nvi . +.sp +To keep the abbreviation expansion from happening, +the character immediately following the +.LI lhs +characters should be quoted with a +.LI <literal-next> +character. +.sp +The replacement +.LI rhs +is itself subject to both further abbreviation expansion and further +map expansion. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY append +.IP "[line] a[ppend][!]" +The input text is appended to the specified line. +If line 0 is specified, the text is inserted at the beginning of the file. +Set to the last line input. +If no lines are input, then set to +.LI line , +or to the first line of the file if a +.LI line +of 0 was specified. +Following the command name with a +.QT ! +character causes the +.OP autoindent +option to be toggled for the duration of the command. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP autoindent +and +.OP number +options. +.SE +.KY args +.IP "ar[gs]" +Display the argument list. +The current argument is displayed inside of +.QT [ +and +.QT ] +characters. +The argument list is the list of operands specified on startup, +which can be replaced using the +.CO next +command. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY bg +.IP bg +.CO Vi +mode only. +Background the current screen. +The screen is unchanged, +but is no longer accessible and disappears from the display. +Use the +.CO fg +command to bring the screen back to the display foreground. +.SS +.SP Line: +Set to the current line when the screen was last edited. +.SP Options: +None. +.SE +.KY change +.IP "[range] c[hange][!] [count]" +Replace the lines with input text. +Following the command name with a +.QT ! +character causes the +.OP autoindent +option to be toggled for the duration of the command. +.SS +.SP Line: +Set to the last line input, or, if no lines were input, +set to the line before the target line, or to the first +line of the file if there are no lines preceding the target line. +.SP Options: +Affected by the +.OP autoindent +and +.OP number +options. +.SE +.KY cd +.KY chdir +.IP "chd[ir][!] [directory]" +.Ip "cd[!] [directory]" +Change the current working directory. +The +.LI directory +argument is subjected to +.XR sh 1 +word expansions. +When invoked with no directory argument and the +.LI HOME +environment variable is set, the directory named by the +.LI HOME +environment variable becomes the new current directory. +Otherwise, the new current directory becomes the directory returned +by the +.XR getpwent 3 +routine. +.sp +The +.CO chdir +command will fail if the file has been modified since the last complete +write of the file. +You can override this check by appending a +.QT ! +character to the command. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP cdpath +option. +.SE +.KY copy +.KY t +.IP "[range] co[py] line [flags]" +.Ip "[range] t line [flags]" +Copy the specified lines (range) after the destination line. +Line 0 may be specified to insert the lines at the beginning of +the file. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY cscope +.IP "cs[cope] command [args]" +Execute a +.CO cscope +command. +For more information, see the section of the reference manual entitled +.QB "Tags, Tag Stacks, and Cscope" . +.KY delete +.IP "[range] d[elete] [buffer] [count] [flags]" +Delete the lines from the file. +The deleted text is saved in the specified buffer, or, if no buffer +is specified, in the unnamed buffer. +If the command name is followed by a letter that could be interpreted +as either a buffer name or a flag value (because neither a +.LI count +or +.LI flags +values were given), +.CO ex +treats the letter as a +.LI flags +value if the letter immediately follows the command name, +without any whitespace separation. +If the letter is preceded by whitespace characters, +it treats it as a buffer name. +.SS +.SP Line: +Set to the line following the deleted lines, +or to the last line if the deleted lines were at the end. +.SP Options: +None. +.SE +.KY display +.IP "di[splay] b[uffers] | c[onnections] | s[creens] | t[ags]" +Display buffers, +.CO cscope +connections, screens or tags. +The +.CO display +command takes one of three additional arguments, which are as follows: +.SS +.SP b[uffers] +Display all buffers (including named, unnamed, and numeric) +that contain text. +.SP c[onnections] +Display the source directories for all attached +.CO cscope +databases. +.SP s[creens] +Display the file names of all background screens. +.SP t[ags] +Display the tags stack. +.SE +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY edit +.IP "e[dit][!] [+cmd] [file]" +.Ip "ex[!] [+cmd] [file]" +Edit a different file. +If the current buffer has been modified since the last complete write, +the command will fail. +You can override this by appending a +.QT ! +character to the command name. +.sp +If the +.QT +cmd +option is specified, that +.CO ex +command will be executed in the new file. +Any +.CO ex +command may be used, although the most common use of this feature is +to specify a line number or search pattern to set the initial location +in the new file. +.sp +Capitalizing the first letter of the command, i.e. +.CO Edit +or +.CO Ex , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +If you have previously edited the file, the current line will be set +to your last position in the file. +If that position does not exist, or you have not previously edited the +file, the current line will be set to the first line of the file if +you are in +.CO vi +mode, and the last line of the file if you are in +.CO ex . +.SP Options: +None. +.SE +.KY exusage +.IP "exu[sage] [command]" +Display usage for an +.CO ex +command. +If +.LI command +is specified, a usage statement for that command is displayed. +Otherwise, usage statements for all +.CO ex +commands are displayed. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY file +.IP "f[ile] [file]" +Display and optionally change the file name. +If a file name is specified, the current pathname is changed to the +specified name. +The current pathname, the number of lines, and the current position +in the file are displayed. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY fg +.IP "fg [name]" +.CO Vi +mode only. +Foreground the specified screen. +If the argument name doesn't exactly match the name of a file displayed +by a background screen, +it is compared against the last component of each of the file names. +If no background screen is specified, +the first background screen is foregrounded. +.sp +By default, +foregrounding causes the current screen to be swapped with the backgrounded +screen. +Capitalizing the first letter of the command, i.e. +.CO Fg , +will foreground the backgrounded screen in a new screen instead of +swapping it with the current screen. +.SS +.SP Line: +Set to the current line when the screen was last edited. +.SP Options: +None. +.SE +.KY global +.IP "[range] g[lobal] /pattern/ [commands]" +.KY v +.Ip "[range] v /pattern/ [commands]" +Apply commands to lines matching (or not matching) a pattern. +The lines within the given range that match +.PQ g[lobal] , +or do not match +.PQ v +the given pattern are selected. +Then, the specified +.CO ex +command(s) are executed with the current line +.PQ \&. +set to each selected line. +If no range is specified, the entire file is searched for matching, +or not matching, lines. +.sp +Multiple commands can be specified, one per line, by escaping each +.LI <newline> +character with a backslash, or by separating commands with a +.QT | +character. +If no commands are specified, the command defaults to the +.CO print +command. +.sp +For the +.CO append , +.CO change +and +.CO insert +commands, the input text must be part of the global command line. +In this case, the terminating period can be omitted if it ends the commands. +.sp +The +.CO visual +command may also be specified as one of the +.CO ex +commands. +In this mode, input is taken from the terminal. +Entering a +.CO Q +command in +.CO vi +mode causes the next line matching the pattern to be selected and +.CO vi +to be reentered, until the list is exhausted. +.sp +The +.CO global , +.CO v +and +.CO undo +commands cannot be used as part of these commands. +.sp +The editor options +.OP autoindent , +.OP autoprint +and +.OP report +are turned off for the duration of the +.CO global +and +.CO v +commands. +.SS +.SP Line: +The last line modified. +.SP Options: +Affected by the +.OP ignorecase +and +.OP magic +options. +Turns off the +.OP autoindent , +.OP autoprint +and +.OP report +options. +.SE +.KY help +.IP "he[lp]" +Display a help message. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY insert +.IP "[line] i[nsert][!]" +The input text is inserted before the specified line. +Following the command name with a +.QT ! +character causes the +.OP autoindent +option setting to be toggled for the duration of this command. +.SS +.SP Line: +Set to the last line input; if no lines were input, +set to the line before the target line, or to the first line +of the file if there are no lines preceding the target line. +Affected by the +.OP autoindent +and +.OP number +options. +.SE +.KY join +.IP "[range] j[oin][!] [count] [flags]" +Join lines of text together. +.sp +A +.LI count +specified to the +.Sy join +command specifies that the last line of the +.LI range +plus +.LI count +subsequent lines will be joined. +(Note, this differs by one from the general rule where only +.LI count - 1 +subsequent lines are affected.) +.sp +If the current line ends with a whitespace character, all whitespace +is stripped from the next line. +Otherwise, if the next line starts with a open parenthesis +.PQ ( , +do nothing. +Otherwise, if the current line ends with a question mark +.PQ ? , +period +.PQ \&. +or exclamation point +.PQ ! , +insert two spaces. +Otherwise, insert a single space. +.sp +Appending a +.QT ! +character to the command name causes a simpler join with no +white-space processing. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY list +.IP "[range] l[ist] [count] [flags]" +Display the lines unambiguously. +Tabs are displayed as +.QT ^I , +and the end of the line is marked with a +.QT $ +character. +.SS +.SP Line: +Set to the last line displayed. +.SP Options: +Affected by the +.OP number +option. +.SE +.KY map +.IP "map[!] [lhs rhs]" +Define or display maps (for +.CO vi +only). +.sp +If +.QT lhs +and +.QT rhs +are not specified, the current set of command mode maps are displayed. +If a +.QT ! +character is appended to to the command, +the text input mode maps are displayed. +.sp +Otherwise, when the +.QT lhs +character sequence is entered in +.CO vi , +the action is as if the corresponding +.QT rhs +had been entered. +If a +.QT ! +character is appended to the command name, +the mapping is effective during text input mode, +otherwise, it is effective during command mode. +This allows +.QT lhs +to have two different macro definitions at the same time: one for command +mode and one for input mode. +.sp +Whitespace characters require escaping with a +.LI <literal-next> +character to be entered in the +.LI lhs +string in visual mode. +.sp +Normally, keys in the +.LI rhs +string are remapped (see the +.OP remap +option), +and it is possible to create infinite loops. +However, keys which map to themselves are not further remapped, +regardless of the setting of the +.OP remap +option. +For example, the command +.QT ":map n nz." +maps the +.QT n +key to the +.CO n +and +.CO z +commands. +.sp +To exit an infinitely looping map, use the terminal +.LI <interrupt> +character. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP remap +option. +.SE +.KY mark +.KY k +.IP "[line] ma[rk] <character>" +.Ip "[line] k <character>" +Mark the line with the mark +.LI <character> . +The expressions +.QT '<character> +and +.QT `<character> +can then be used as an address in any command that uses one. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY move +.IP "[range] m[ove] line" +Move the specified lines after the target line. +A target line of 0 places the lines at the beginning of the file. +.SS +.SP Line: +Set to the first of the moved lines. +.SP Options: +None. +.SE +.KY mkexrc +.IP "mk[exrc][!] file" +Write the abbreviations, editor options and maps to the specified +file. +Information is written in a form which can later be read back in +using the +.CO ex +.CO source +command. +If +.LI file +already exists, the +.CO mkexrc +command will fail. +This check can be overridden by appending a +.QT ! +character to the command. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY next +.IP "n[ext][!] [file ...]" +Edit the next file from the argument list. +The +.CO next +command will fail if the file has been modified since the last complete +write. +This check can be overridden by appending the +.QT ! +character to the command name. +The argument list can optionally be replaced by specifying a new one +as arguments to this command. +In this case, editing starts with the first file on the new list. +.sp +Capitalizing the first letter of the command, i.e. +.CO Next , +while in +.CO vi +mode, will set the argument list and edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +Affected by the options +.OP autowrite +and +.OP writeany . +.SE +.KY open +.IP "[line] o[pen] /pattern/ [flags]" +Enter open mode. +Open mode is the same as being in +.CO vi , +but with a one-line window. +All the standard +.CO vi +commands are available. +If a match is found for the optional RE argument, +the cursor is set to the start of the matching pattern. +.sp +.i "This command is not yet implemented." +.SS +.SP Line: +Unchanged, unless the optional RE is specified, in which case it is +set to the line where the matching pattern is found. +.SP Options: +Affected by the +.OP open +option. +.SE +.KY preserve +.IP "pre[serve]" +Save the file in a form that can later be recovered using the +.CO ex +.b \-r +option. +When the file is preserved, an email message is sent to the user. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY previous +.IP "prev[ious][!]" +Edit the previous file from the argument list. +The +.CO previous +command will fail if the file has been modified since the last complete +write. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +Capitalizing the first letter of the command, i.e. +.CO Previous , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +Affected by the options +.OP autowrite +and +.OP writeany . +None. +.SE +.KY print +.IP "[range] p[rint] [count] [flags]" +Display the specified lines. +.SS +.SP Line: +Set to the last line displayed. +.SP Options: +Affected by the +.OP list +and +.OP number +option. +.SE +.KY put +.IP "[line] pu[t] [buffer]" +Append buffer contents to the current line. +If a buffer is specified, its contents are appended to the line, +otherwise, the contents of the unnamed buffer are used. +.SS +.SP Line: +Set to the line after the current line. +.SP Options: +None. +.SE +.KY quit +.IP "q[uit][!]" +End the editing session. +If the file has been modified since the last complete write, the +.CO quit +command will fail. +This check may be overridden by appending a +.QT ! +character to the command. +.sp +If there are more files to edit, the +.CO quit +command will fail. +Appending a +.QT ! +character to the command name or entering two +.CO quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row) will override this check and the editor will exit. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY read +.IP "[line] r[ead][!] [file]" +Read a file. +A copy of the specified file is appended to the line. +If +.LI line +is 0, the copy is inserted at the beginning of the file. +If no file is specified, the current file is read; if there is no +current file, then +.LI file +becomes the current file. +If there is no current file and no +.LI file +is specified, then the +.CO read +command will fail. +.sp +If +.LI file +is preceded by a +.QT ! +character, +.LI file +is treated as if it were a shell command, and passed to the program +named by the +.OP shell +edit option. +The standard and standard error outputs of that command are read into +the file after the specified line. +The special meaning of the +.QT ! +character can be overridden by escaping it with a backslash +.PQ \e +character. +.SS +.SP Line: +When executed from +.CO ex , +the current line is set to the last line read. +When executed from +.CO vi , +the current line is set to the first line read. +.SP Options: +None. +.SE +.KY recover +.IP "rec[over] file" +Recover +.LI file +if it was previously saved. +If no saved file by that name exists, the +.CO recover +command behaves equivalently to the +.CO edit +command. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +None. +.SE +.KY resize +.IP "res[ize] [+|-]size" +.CO Vi +mode only. +Grow or shrink the current screen. +If +.LI size +is a positive, signed number, the current screen is grown by that many lines. +If +.LI size +is a negative, signed number, the current screen is shrunk by that many lines. +If +.LI size +is not signed, the current screen is set to the specified +.LI size . +Applicable only to split screens. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY rewind +.IP "rew[ind][!]" +Rewind the argument list. +If the current file has been modified since the last complete write, +the +.CO rewind +command will fail. +This check may be overridden by appending the +.QT ! +character to the command. +.sp +Otherwise, the current file is set to the first file in the argument +list. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY set +.IP "se[t] [option[=[value]] ...] [nooption ...] [option? ...] [all]" +Display or set editor options. +When no arguments are specified, the editor option +.OP term , +and any editor options whose values have been changed from the +default settings are displayed. +If the argument +.LI all +is specified, the values of all of editor options are displayed. +.sp +Specifying an option name followed by the character +.QT ? +causes the current value of that option to be displayed. +The +.QT ? +can be separated from the option name by whitespace characters. +The +.QT ? +is necessary only for Boolean valued options. +Boolean options can be given values by the form +.QT "set option" +to turn them on, or +.QT "set nooption" +to turn them off. +String and numeric options can be assigned by the form +.QT "set option=value" . +Any whitespace characters in strings can be included literally by preceding +each with a backslash. +More than one option can be set or listed by a single set command, +by specifying multiple arguments, each separated from the next by +whitespace characters. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY shell +.IP "sh[ell]" +Run the shell program. +The program named by the +.OP shell +option is run with a +.b \-i +(for interactive) flag. +Editing is resumed when that program exits. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP shell +option. +.SE +.KY source +.IP "so[urce] file" +Read and execute +.CO ex +commands from a file. +.CO Source +commands may be nested. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY substitute +.IP "[range] s[ubstitute] [/pattern/replace/] [options] [count] [flags]" +.KY & +.Ip "[range] & [options] [count] [flags]" +.KY ~ +.Ip "[range] ~ [options] [count] [flags]" +Make substitutions. +Replace the first instance of +.LI pattern +with the string +.LI replace +on the specified line(s). +If the +.QT /pattern/repl/ +argument is not specified, the +.QT /pattern/repl/ +from the previous +.CO substitute +command is used. +Any character other than an alphabetic, numeric, <blank> or backslash +character may be used as the delimiter. +.sp +If +.LI options +includes the letter +.QT c +(confirm), you will be prompted for confirmation before each replacement +is done. +An affirmative response (in English, a +.QT y +character) causes the replacement to be made. +A quit response (in English, a +.QT q +character) causes the +.CO substitute +command to be terminated. +Any other response causes the replacement not to be made, and the +.CO substitute +command continues. +If +.LI options +includes the letter +.QT g +(global), all nonoverlapping instances of +.LI pattern +in the line are replaced. +.sp +The +.CO & +version of the command is the same as not specifying a pattern +or replacement string to the +.CO substitute +command, and the +.QT & +is replaced by the pattern and replacement information from the +previous substitute command. +.sp +The +.CO ~ +version of the command is the same as +.CO & +and +.CO s , +except that the search pattern used is the last RE used in +.i any +command, not necessarily the one used in the last +.CO substitute +command. +.sp +For example, in the sequence +.ft C +.(b +s/red/blue/ +/green +~ +.)b +.ft R +the +.QT ~ +is equivalent to +.QT s/green/blue/ . +.sp +The +.CO substitute +command may be interrupted, using the terminal interrupt character. +All substitutions completed before the interrupt are retained. +.SS +.SP Line: +Set to the last line upon which a substitution was made. +.SP Options: +Affected by the +.OP ignorecase +and +.OP magic +option. +.SE +.KY suspend +.IP "su[spend][!]" +.KY stop +.Ip "st[op][!]" +.KY <control-Z> +.Ip <control-Z> +Suspend the edit session. +Appending a +.QT ! +character to these commands turns off the +.OP autowrite +option for the command. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tag +.IP "ta[g][!] tagstring" +Edit the file containing the specified tag. +If the tag is in a different file, then the new file is edited. +If the current file has been modified since the last complete write, +the +.CO tag +command will fail. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +The +.CO tag +command searches for +.LI tagstring +in the tags file(s) specified by the +.Op tags +option. +(See +.XR ctags 1 +for more information on tags files.) +.sp +Capitalizing the first letter of the command, i.e. +.CO Tag , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite , +.OP taglength , +.OP tags +and +.OP writeany +options. +.SE +.KY tagnext +.IP "tagn[ext][!]" +Edit the file containing the next context for the current tag. +If the context is in a different file, then the new file is edited. +If the current file has been modified since the last complete write, +the +.CO tagnext +command will fail. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +Capitalizing the first letter of the command, i.e. +.CO Tagnext , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tagpop +.IP "tagp[op][!] [file | number]" +Pop to the specified tag in the tags stack. +If neither +.LI file +or +.LI number +is specified, the +.CO tagpop +command pops to the most recent entry on the tags stack. +If +.LI file +or +.LI number +is specified, the +.CO tagpop +command pops to the most recent entry in the tags stack for that file, +or numbered entry in the tags stack, respectively. +(See the +.CO display +command for information on displaying the tags stack.) +.sp +If the file has been modified since the last complete write, the +.CO tagpop +command will fail. +This check may be overridden by appending a +.QT ! +character to the command name. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tagprev +.IP "tagp[rev][!]" +Edit the file containing the previous context for the current tag. +If the context is in a different file, then the new file is edited. +If the current file has been modified since the last complete write, +the +.CO tagprev +command will fail. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +Capitalizing the first letter of the command, i.e. +.CO Tagprev , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tagtop +.IP "tagt[op][!]" +Pop to the least recent tag on the tags stack, clearing the tags stack. +.sp +If the file has been modified since the last complete write, the +.CO tagtop +command will fail. +This check may be overridden by appending a +.QT ! +character to the command name. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY unabbrev +.IP "una[bbrev] lhs" +Delete an abbreviation. +Delete +.LI lhs +from the current list of abbreviations. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY undo +.IP "u[ndo]" +Undo the last change made to the file. +Changes made by +.CO global , +.CO v , +.CO visual +and map sequences are considered a single command. +If repeated, the +.CO u +command alternates between these two states, and is its own inverse. +.SS +.SP Line: +Set to the last line modified by the command. +.SP Options: +None. +.SE +.KY unmap +.IP "unm[ap][!] lhs" +Unmap a mapped string. +Delete the command mode map definition for +.LI lhs . +If a +.QT ! +character is appended to the command name, delete the text input mode +map definition instead. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY version +.IP "ve[rsion]" +Display the version of the +.CO ex/vi +editor. +.KY visual +.IP "[line] vi[sual] [type] [count] [flags]" +.CO Ex +mode only. +Enter +.CO vi . +The +.LI type +is optional, and can be +.QT \- , +.QT + +or +.QT ^ , +as in the +.CO ex +.CO z +command, to specify the position of the specified line in the screen +window. +(The default is to place the line at the top of the screen window.) +A +.LI count +specifies the number of lines that will initially be displayed. +(The default is the value of the +.OP window +editor option.) +.SS +.SP Line: +Unchanged unless +.LI line +is specified, in which case it is set to that line. +.SP Options: +None. +.SE +.KY visual +.IP "vi[sual][!] [+cmd] [file]" +.CO Vi +mode only. +Edit a new file. +Identical to the +.QT "edit[!] [+cmd] [file]" +command. +.sp +Capitalizing the first letter of the command, i.e. +.CO Visual , +will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.KY viusage +.IP "viu[sage] [command]" +Display usage for a +.CO vi +command. +If +.LI command +is specified, a usage statement for that command is displayed. +Otherwise, usage statements for all +.CO vi +commands are displayed. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY write +.IP "[range] w[rite][!] [>>] [file]" +.Ip "[range] w[rite] [!] [file]" +.KY wn +.Ip "[range] wn[!] [>>] [file]" +.KY wq +.Ip "[range] wq[!] [>>] [file]" +Write the file. +The specified lines (the entire file, if no range is given) is written +to +.LI file . +If +.LI file +is not specified, the current pathname is used. +If +.LI file +is specified, and it exists, or if the current pathname was set using the +.CO file +command, and the file already exists, these commands will fail. +Appending a +.QT ! +character to the command name will override this check and the write +will be attempted, regardless. +.sp +Specifying the optional +.QT >> +string will cause the write to be appended to the file, in which case +no tests are made for the file already existing. +.sp +If the file is preceded by a +.QT ! +character, the program named by the shell edit option is +invoked with file as its second argument, and the specified +lines are passed as standard input to that command. +The +.QT ! +in this usage must be separated from command name by at least one +whitespace character. +The special meaning of the +.QT ! +may be overridden by escaping it with a backslash +.PQ \e +character. +.sp +The +.CO wq +version of the write command will exit the editor after writing the file, +if there are no further files to edit. +Appending a +.QT ! +character to the command name or entering two +.QQ quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row) will override this check and the editor will exit, +ignoring any files that have not yet been edited. +.sp +The +.CO wn +version of the write command will move to the next file after writing +the file, unless the write fails. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP readonly +and +.OP writeany +options. +.SE +.KY xit +.IP "[range] x[it][!] [file]" +Write the file if it has been modified. +The specified lines are written to +.LI file , +if the file has been modified since the last complete write to any +file. +If no +.LI range +is specified, the entire file is written. +.sp +The +.CO xit +command will exit the editor after writing the file, +if there are no further files to edit. +Appending a +.QT ! +character to the command name or entering two +.QQ quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row) will override this check and the editor will exit, +ignoring any files that have not yet been edited. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP readonly +and +.OP writeany +options. +.SE +.KY yank +.IP "[range] ya[nk] [buffer] [count]" +Copy the specified lines to a buffer. +If no buffer is specified, the unnamed buffer is used. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY z +.IP "[line] z [type] [count] [flags]" +Adjust the window. +If no +.LI type +is specified, then +.LI count +lines following the specified line are displayed. +The default +.LI count +is the value of the +.OP window +option. +The +.LI type +argument changes the position at which +.LI line +is displayed on the screen by changing the number of lines +displayed before and after +.LI line . +The following +.LI type +characters may be used: +.SS +.SP \- +Place the line at the bottom of the screen. +.SP + +Place the line at the top of the screen. +.SP \&. +Place the line in the middle of the screen. +.SP ^ +Write out count lines starting +.LI "count * 2" +lines before +.LI line ; +the net effect of this is that a +.QT z^ +command following a +.CO z +command writes the previous page. +.SP = +Center +.LI line +on the screen with a line of hyphens displayed immediately before and +after it. +The number of preceding and following lines of text displayed are +reduced to account for those lines. +.SE +.SS +.SP Line: +Set to the last line displayed, with the exception of the +.Dq Li \&= +.LI type , +where the current line is set to the line specified by the command. +.SP Options: +Affected by the +.OP scroll +option. +.SE diff --git a/share/doc/usd/13.viref/merge.awk b/share/doc/usd/13.viref/merge.awk new file mode 100644 index 000000000000..2ff1c0997a12 --- /dev/null +++ b/share/doc/usd/13.viref/merge.awk @@ -0,0 +1,14 @@ +# merge index entries into one line per label +$1 == prev { + printf ", %s", $2; + next; +} +{ + if (NR != 1) + printf "\n"; + printf "%s \t%s", $1, $2; + prev = $1; +} +END { + printf "\n" +} diff --git a/share/doc/usd/13.viref/ref.so b/share/doc/usd/13.viref/ref.so new file mode 100644 index 000000000000..d1168c778872 --- /dev/null +++ b/share/doc/usd/13.viref/ref.so @@ -0,0 +1,101 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" +.\" indented paragraph, with spaces between the items, bold font +.de IP +.\".tm arg 1 \\$1 arg 2 \\$2 arg 3 \\$3 +.sp 1 +.nr PS \\n(ps +.nr ps 0 +.ip "\fB\\$1\fP" \\$2 +.nr ps \\n(PS +.br +.. +.\" indented paragraph, no spaces between the items, bold font +.de Ip +.\".tm arg 1 \\$1 arg 2 \\$2 arg 3 \\$3 +.nr PS \\n(ps +.nr ps 0 +.ns +.ip "\fB\\$1\fP" \\$2 +.nr ps \\n(PS +.br +.. +.\" start nested .IP +.de SS +.sp +.ba +5n +.. +.\" end nested .IP +.de SE +.ba -5n +.. +.\" nested .IP, no spaces, normal font +.de SP +.\".tm arg 1 \\$1 arg 2 \\$2 arg 3 \\$3 +.nr PS \\n(ps +.nr ps 0 +.ns +.ip "\\$1" 9n +.nr ps \\n(PS +.. +.\" typewriter font +.de LI +\&\fC\\$1\fP\\$2 +.. +.\" ex/vi names in command font +.de EV +\&\fB\\$1\fP/\fB\\$2\fP\\$3 +.. +.\" command names +.de CO +\&\fB\\$1\fP\\$2 +.. +.\" key words for index +.de KY +.sy echo >>index '\\$1 \\n%' +.. +.\" option names +.de OP +\&\fB\\$1\fP\\$2 +.. +.\" paren quoted (typewriter font) +.de PQ +(\*(lq\fC\\$1\fP\*(rq)\\$2 +.. +.\" quoted bold +.de QB +\*(lq\fB\\$1\fP\*(rq\\$2 +.. +.\" quoted command +.de QC +\*(lq\fB\\$1\fP\*(rq\\$2 +.. +.\" quoted option +.de QO +\*(lq\fB\\$1\fP\*(rq\\$2 +.. +.\" quoted (no font change) +.de QQ +\*(lq\\$1\*(rq\\$2 +.. +.\" quoted (typewriter font) +.de QT +\*(lq\fC\\$1\fP\*(rq\\$2 +.. +.\" section macro to build TOC +.de SH +.(x +\\$2 +.)x +.sh \\$1 "\\$2" +.. +.\" manual section +.de XR +\&\fI\\$1\fP(\\$2)\\$3 +.. diff --git a/share/doc/usd/13.viref/set.opt.roff b/share/doc/usd/13.viref/set.opt.roff new file mode 100644 index 000000000000..cdee5290ed48 --- /dev/null +++ b/share/doc/usd/13.viref/set.opt.roff @@ -0,0 +1,1301 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.SH 1 "Set Options" +.pp +There are a large number of options that may be set (or unset) to +change the editor's behavior. +This section describes the options, their abbreviations and their +default values. +.pp +In each entry below, the first part of the tag line is the full name +of the option, followed by any equivalent abbreviations. +(Regardless of the abbreviations, it is only necessary to use the +minimum number of characters necessary to distinguish an abbreviation +from all other commands for it to be accepted, in +.EV nex nvi . +Historically, only the full name and the official abbreviations +were accepted by +.EV ex vi . +Using full names in your startup files and environmental variables will +probably make them more portable.) +The part in square brackets is the default value of the option. +Most of the options are boolean, i.e. they are either on or off, +and do not have an associated value. +.pp +Options apply to both +.CO ex +and +.CO vi +modes, unless otherwise specified. +.pp +With a few exceptions, +all options are settable per screen, i.e. the +.OP tags +option can be set differently in each screen. +The exceptions are the +.OP columns , +.OP lines , +.OP secure +and +.OP term +options. +Changing these options modifies the respective information for all screens. +.pp +For information on modifying the options or to display the options and +their current values, see the +.QQ set +command in the section entitled +.QB "Ex Commands" . +.KY altwerase +.IP "altwerase [off]" +.CO Vi +only. +Change how +.CO vi +does word erase during text input. +When this option is set, text is broken up into three classes: +alphabetic, numeric and underscore characters, other nonblank +characters, and blank characters. +Changing from one class to another marks the end of a word. +In addition, the class of the first character erased is ignored +(which is exactly what you want when erasing pathname components). +.KY autoindent +.IP "autoindent, ai [off]" +If this option is set, whenever you create a new line (using the +.CO vi +.CO A , +.CO a , +.CO C , +.CO c , +.CO I , +.CO i , +.CO O , +.CO o , +.CO R , +.CO r , +.CO S , +and +.CO s +commands, or the +.CO ex +.CO append , +.CO change , +and +.CO insert +commands) the new line is automatically indented to align the cursor with +the first nonblank character of the line from which you created it. +Lines are indented using tab characters to the extent possible (based on +the value of the +.OP tabstop +option) and then using space characters as necessary. +For commands inserting text into the middle of a line, any blank characters +to the right of the cursor are discarded, and the first nonblank character +to the right of the cursor is aligned as described above. +.sp +The indent characters are themselves somewhat special. +If you do not enter more characters on the new line before moving to +another line, or entering +.LI <escape> , +the indent character will be deleted and the line will be empty. +For example, if you enter +.LI <carriage-return> +twice in succession, +the line created by the first +.LI <carriage-return> +will not have any characters in it, +regardless of the indentation of the previous or subsequent line. +.sp +Indent characters also require that you enter additional erase characters +to delete them. +For example, +if you have an indented line, containing only blanks, the first +.LI <word-erase> +character you enter will erase up to end of the indent characters, +and the second will erase back to the beginning of the line. +(Historically, only the +.LI <control-D> +key would erase the indent characters. +Both the +.LI <control-D> +key and the usual erase keys work in +.CO nvi .) +In addition, if the cursor is positioned at the end of the indent +characters, the keys +.QT 0<control-D> +will erase all of the indent characters for the current line, +resetting the indentation level to 0. +Similarly, the keys +.QT ^<control-D> +will erase all of the indent characters for the current line, +leaving the indentation level for future created lines unaffected. +.sp +Finally, if the +.OP autoindent +option is set, the +.CO S +and +.CO cc +commands change from the first nonblank of the line to the end of the +line, instead of from the beginning of the line to the end of the line. +.KY autoprint +.IP "autoprint, ap [off]" +.CO Ex +only. +Cause the current line to be automatically displayed after the +.CO ex +commands +.CO < , +.CO > , +.CO copy , +.CO delete , +.CO join , +.CO move , +.CO put , +.CO t , +.CO Undo , +and +.CO undo . +This automatic display is suppressed during +.CO global +and +.CO v +commands, and for any command where optional flags are used to explicitly +display the line. +.KY autowrite +.IP "autowrite, aw [off]" +If this option is set, the +.CO vi +.CO ! , +.CO ^^ , +.CO ^] +and +.CO <control-Z> +commands, and the +.CO ex +.CO edit , +.CO next , +.CO rewind , +.CO stop , +.CO suspend , +.CO tag , +.CO tagpop , +and +.CO tagtop +commands automatically write the current file back to the current file name +if it has been modified since it was last written. +If the write fails, the command fails and goes no further. +.sp +Appending the optional force flag character +.QT ! +to the +.CO ex +commands +.CO next , +.CO rewind , +.CO stop , +.CO suspend , +.CO tag , +.CO tagpop , +and +.CO tagtop +stops the automatic write from being attempted. +.sp +(Historically, the +.CO next +command ignored the optional force flag.) +Note, the +.CO ex +commands +.CO edit , +.CO quit , +.CO shell , +and +.CO xit +are +.i not +affected by the +.OP autowrite +option. +.sp +The +.OP autowrite +option is ignored if the file is considered read-only for any reason. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms backup [QQ] +.KY backup +.IP "\*(ms" +.tr QQ +If this option is set, it specifies a pathname used as a backup file, +and, whenever a file is written, the file's current contents are copied +to it. +The pathname is +.QT \&# , +.QT \&% +and +.QT \&! +expanded. +.sp +If the first character of the pathname is +.QT \&N , +a version number is appended to the pathname (and the +.QT \&N +character is then discarded). +Version numbers are always incremented, and each backup file will have +a version number one greater than the highest version number currently +found in the directory. +.sp +Backup files must be regular files, owned by the real user ID of the +user running the editor, and not accessible by any other user. +.KY beautify +.IP "beautify, bf [off]" +If this option is set, all control characters that are not currently being +specially interpreted, other than +.LI <tab> , +.LI <newline> , +and +.LI <form-feed> , +are +discarded from commands read in by +.CO ex +from command files, and from input text entered to +.CO vi +(either into the file or to the colon command line). +Text files read by +.EV ex vi +are +.i not +affected by the +.OP beautify +option. +.KY cdpath +.IP "cdpath [environment variable CDPATH, or current directory]" +This option is used to specify a colon separated list of directories +which are used as path prefixes for any relative path names used as +arguments for the +.CO cd +command. +The value of this option defaults to the value of the environmental +variable +.LI CDPATH +if it is set, otherwise to the current directory. +For compatibility with the POSIX 1003.2 shell, the +.CO cd +command does +.i not +check the current directory as a path prefix for relative path names +unless it is explicitly specified. +It may be so specified by entering an empty string or a +.QT \&. +character into the +.LI CDPATH +variable or the option value. +.KY cedit +.IP "cedit [no default]" +This option adds the ability to edit the colon command-line history. +This option is set to a string. +Whenever the first character of that string is entered on the colon +command line, +you will enter a normal editing window on the collected commands that +you've entered on the +.CO vi +colon command-line. +You may then modify and/or execute the commands. +All normal text editing is available, +except that you cannot use +.CO <control-W> +to switch to an alternate screen. +Entering a +.CO <carriage-return> +will execute the current line of the screen window as an ex command in +the context of the screen from which you created the colon command-line +screen, +and you will then return to that screen. +.sp +Because of +.CO vi \&'s +parsing rules, it can be difficult to set the colon command-line edit +character to the +.LI <escape> +character. +To set it to +.LI <escape> , +use +.QT "set cedit=<literal-next><escape>" . +.sp +If the +.OP cedit +edit option is set to the same character as the +.OP filec +edit option, +.CO vi +will perform colon command-line editing if the character is entered as +the first character of the line, +otherwise, +.CO vi +will perform file name expansion. +.KY columns +.IP "columns, co [80]" +The number of columns in the screen. +Setting this option causes +.EV ex vi +to set (or reset) the environmental variable +.LI COLUMNS . +See the section entitled +.QB "Sizing the Screen" +more information. +.KY comment +.IP "comment [off]" +.CO Vi +only. +If the first non-empty line of the file begins with the string +.QT # , +.QT /\&* +or +.QT // , +this option causes +.CO vi +to skip to the end of that shell, C or C++ comment (probably a +terribly boring legal notice) before displaying the file. +.KY directory +.IP "directory, dir [environment variable TMPDIR, or /tmp]" +The directory where temporary files are created. +The environmental variable +.LI TMPDIR +is used as the default value if it exists, otherwise +.LI /tmp +is used. +.KY edcompatible +.IP "edcompatible, ed [off]" +Remember the values of the +.QQ c +and +.QQ g +suffixes to the +.CO substitute +commands, instead of initializing them as unset for each new +command. +Specifying pattern and replacement strings to the +.CO substitute +command unsets the +.QQ c +and +.QQ g +suffixes as well. +.KY escapetime +.IP "escapetime [1]" +The 10th's of a second +.EV ex vi +waits for a subsequent key to complete an +.LI <escape> +key mapping. +.KY errorbells +.IP "errorbells, eb [off]" +.CO Ex +only. +.CO Ex +error messages are normally presented in inverse video. +If that is not possible for the terminal, setting this option causes +error messages to be announced by ringing the terminal bell. +.KY exrc +.IP "exrc, ex [off]" +If this option is turned on in the EXINIT environment variables, +or the system or $HOME startup files, +the local startup files are read, +unless they are the same as the system or $HOME startup files or +fail to pass the standard permission checks. +See the section entitled +.QB "Startup Information" +for more information. +.KY extended +.IP "extended [off]" +This option causes all regular expressions to be treated as POSIX +1003.2 Extended Regular Expressions (which are similar to historic +.XR egrep 1 +style expressions). +.KY filec +.IP "filec [no default]" +This option adds the ability to do shell expansion when entering input +on the colon command line. +This option is set to a string. +Whenever the first character of that string is entered on the colon +command line, +the <blank> delimited string immediately before the cursor is expanded +as if it were followed by a +.LI \&* +character, and file name expansion for the +.CO ex +edit command was done. +If no match is found, the screen is flashed and text input resumed. +If a single match results, that match replaces the expanded text. +In addition, if the single match is for a directory, a +.LI \&/ +character is appended and file completion is repeated. +If more than a single match results, +any unique prefix shared by the matches replaces the expanded text, +the matches are displayed, +and text input resumed. +.sp +Because of +.CO vi \&'s +parsing rules, it can be difficult to set the path completion character +to two command values, +.LI <escape> +and +.LI <tab> . +To set it to +.LI <escape> , +use +.QT "set filec=<literal-next><escape>" . +To set it to +.LI <tab> , +use +.QT "set filec=\e<tab>" . +.sp +If the +.OP cedit +edit option is set to the same character as the +.OP filec +edit option, +.CO vi +will perform colon command-line editing if the character is entered as +the first character of the line, +otherwise, +.CO vi +will perform file name expansion. +.KY flash +.IP "flash [on]" +This option causes the screen to flash instead of beeping the keyboard, +on error, if the terminal has the capability. +.KY hardtabs +.IP "hardtabs, ht [8]" +This option defines the spacing between hardware tab settings, i.e. +the tab expansion done by the operating system and/or the terminal +itself. +As +.EV nex nvi +never writes +.LI <tab> +characters to the terminal, unlike historic versions of +.EV ex vi , +this option does not currently have any affect. +.KY iclower +.IP "iclower [off]" +The +.OP iclower +edit option makes all Regular Expressions case-insensitive, +as long as an upper-case letter does not appear in the search string. +.KY ignorecase +.IP "ignorecase, ic [off]" +This option causes regular expressions, both in +.CO ex +commands and in searches, +to be evaluated in a case-insensitive manner. +.KY keytime +.IP "keytime [6]" +The 10th's of a second +.EV ex vi +waits for a subsequent key to complete a key mapping. +.KY leftright +.IP "leftright [off]" +.CO Vi +only. +This option causes the screen to be scrolled left-right to view +lines longer than the screen, instead of the traditional +.CO vi +screen interface which folds long lines at the right-hand margin +of the terminal. +.KY lines +.IP "lines, li [24]" +.CO Vi +only. +The number of lines in the screen. +Setting this option causes +.EV ex vi +to set (or reset) the environmental variable +.LI LINES . +See the section entitled +.QB "Sizing the Screen" +for more information. +.KY lisp +.IP "lisp [off]" +.CO Vi +only. +This option changes the behavior of the +.CO vi +.CO ( , +.CO ) , +.CO { , +.CO } , +.CO [[ +and +.CO ]] +commands to match the Lisp language. +Also, the +.OP autoindent +option's behavior is changed to be appropriate for Lisp. +.sp +.i "This option is not yet implemented." +.KY list +.IP "list [off]" +This option causes lines to be displayed in an unambiguous fashion. +Specifically, tabs are displayed as control characters, i.e. +.QT ^I , +and the ends of lines are marked with a +.QT $ +character. +.KY lock +.IP "lock [on]" +This option causes the editor to attempt to get an exclusive lock on +any file being edited, read or written. +Reading or writing a file that cannot be locked produces a warning +message, but no other effect. +Editing a file that cannot be locked results in a read only edit session, +as if the +.OP readonly +edit option were set. +.KY magic +.IP "magic [on]" +This option is on by default. +Turning the +.OP magic +option off causes all regular expression characters except for +.QT ^ +and +.QT $ , +to be treated as ordinary characters. +To re-enable characters individually, when the +.OP magic +option is off, +precede them with a backslash +.QT \e +character. +See the section entitled +.QB "Regular Expressions and Replacement Strings" +for more information. +.KY matchtime +.IP "matchtime [7]" +.CO Vi +only. +The 10th's of a second +.CO vi +pauses on the matching character when the +.OP showmatch +option is set. +.KY mesg +.IP "mesg [on]" +This option allows other users to contact you using the +.XR talk 1 +and +.XR write 1 +utilities, while you are editing. +.EV Ex vi +does not turn message on, i.e. if messages were turned off when the +editor was invoked, they will stay turned off. +This option only permits you to disallow messages for the edit session. +See the +.XR mesg 1 +utility for more information. +.KY msgcat +.IP "msgcat [./]" +This option selects a message catalog to be used to display error and +informational messages in a specified language. +If the value of this option ends with a '/', it is treated as the name +of a directory that contains a message catalog +.QT "vi_XXXX" , +where +.QT XXXX +is the value of the +.LI LANG +environmental variable, if it's set, or the value of the +.LI LC_MESSAGES +environmental variable if it's not. +If neither of those environmental variables are set, +or if the option doesn't end in a '/', +the option is treated as the full path name of the message catalog to use. +.sp +If any messages are missing from the catalog, +the backup text (English) is used instead. +.sp +See the distribution file +.LI catalog/README +for additional information on building and installing message catalogs. +.KY modelines +.IP "modelines, modeline [off]" +If the +.OP modelines +option is set, +.EV ex vi +has historically scanned the first and last five lines of each file as +it is read for editing, looking for any +.CO ex +commands that have been placed in those lines. +After the startup information has been processed, and before the user +starts editing the file, any commands embedded in the file are executed. +.sp +Commands were recognized by the letters +.QQ e +or +.QQ v +followed by +.QQ x +or +.QQ i , +at the beginning of a line or following a tab or space character, +and followed by a +.QQ : , +an +.CO ex +command, and another +.QQ : . +.sp +This option is a security problem of immense proportions, +and should not be used under any circumstances. +.sp +.i "This option will never be implemented." +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms noprint [QQ] +.KY noprint +.IP "\*(ms" +.tr QQ +Characters that are never handled as printable characters. +By default, the C library function +.XR isprint 3 +is used to determine if a character is printable or not. +This edit option overrides that decision. +.KY number +.IP "number, nu [off]" +Precede each line displayed with its current line number. +.KY octal +.IP "octal [off]" +Display unknown characters as octal numbers +.PQ "\e###" , +instead of the default +hexadecimal +.PQ "\ex##" . +.KY open +.IP "open [on]" +.CO Ex +only. +If this option is not set, the +.CO open +and +.CO visual +commands are disallowed. +.KY optimize +.IP "optimize, opt [on]" +.CO Vi +only. +Throughput of text is expedited by setting the terminal not to do automatic +carriage returns when printing more than one (logical) line of output, +greatly speeding output on terminals without addressable cursors when text +with leading white space is printed. +.sp +.i "This option is not yet implemented." +.KY paragraphs +.IP "paragraphs, para [IPLPPPQPP LIpplpipbp]" +.CO Vi +only. +Define additional paragraph boundaries for the +.CO { +and +.CO } +commands. +The value of this option must be a character string consisting +of zero or more character pairs. +.sp +In the text to be edited, the character string +.LI "<newline>.<char-pair>" , +(where +.LI <char-pair> +is one of the character pairs in the option's value) +defines a paragraph boundary. +For example, if the option were set to +.LI "LaA<space>##" , +then all of the following additional paragraph boundaries would be +recognized: +.sp +.(l +<newline>.La +<newline>.A<space> +<newline>.## +.)l +.KY path +.IP "path []" +The path option can be used to specify a <colon>-separated list of +paths, similar to the +.LI PATH +environment variable in the shells. +If this option is set, +the name of the file to be edited is not an absolute pathname, +the first component of the filename is not +.QT \&. +or +.QT \&.. , +and the file to be edited doesn't exist in the current directory, +the elements of the +.OP path +option are sequentially searched for a file of the specified name. +If such a file is found, it is edited. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms print [QQ] +.KY print +.IP "\*(ms" +.tr QQ +Characters that are always handled as printable characters. +By default, the C library function +.XR isprint 3 +is used to determine if a character is printable or not. +This edit option overrides that decision. +.KY prompt +.IP "prompt [on]" +.CO Ex +only. +This option causes +.CO ex +to prompt for command input with a +.QT : +character; when it is not set, no prompt is displayed. +.KY readonly +.IP "readonly, ro [off]" +This option causes a force flag to be required to attempt to write the file. +Setting this option is equivalent to using the +.b \-R +command line option, +or executing the +.CO vi +program using the name +.CO view . +.sp +The +.OP readonly +edit option is not usually persistent, like other edit options. +If the +.b \-R +command line option is set, +.CO vi +is executed as +.CO view , +or the +.OP readonly +edit option is explicitly set, +all files edited in the screen will be marked readonly, +and the force flag will be required to write them. +However, if none of these conditions are true, +or the +.OP readonly +edit option is explicitly unset, +then the +.OP readonly +edit option will toggle based on the write permissions of the file currently +being edited as of when it is loaded into the edit buffer. +In other words, the +.OP readonly +edit option will be set if the current file lacks write permissions, +and will not be set if the user has write permissions for the file. +.KY recdir +.IP "recdir [/var/tmp/vi.recover]" +The directory where recovery files are stored. +.sp +If you change the value of +.OP recdir , +be careful to choose a directory whose contents are not regularly +deleted. +Bad choices include directories in memory based filesystems, +or +.LI /tmp , +on most systems, +as their contents are removed when the machine is rebooted. +.sp +Public directories like +.LI /usr/tmp +and +.LI /var/tmp +are usually safe, although some sites periodically prune old files +from them. +There is no requirement that you use a public directory, +e.g. a sub-directory of your home directory will work fine. +.sp +Finally, if you change the value of +.OP recdir , +you must modify the recovery script to operate in your chosen recovery +area. +.sp +See the section entitled +.QB "Recovery" +for further information. +.KY redraw +.IP "redraw, re [off]" +.CO Vi +only. +The editor simulates (using great amounts of output), an intelligent +terminal on a dumb terminal (e.g. during insertions in +.CO vi +the characters to the right of the cursor are refreshed as each input +character is typed). +.sp +.i "This option is not yet implemented." +.KY remap +.IP "remap [on]" +If this option is set, +it is possible to define macros in terms of other macros. +Otherwise, each key is only remapped up to one time. +For example, if +.QT A +is mapped to +.QT B , +and +.QT B +is mapped to +.QT C , +The keystroke +.QT A +will be mapped to +.QT C +if the +.OP remap +option is set, and to +.QT B +if it is not set. +.KY report +.IP "report [5]" +Set the threshold of the number of lines that need to be changed or +yanked before a message will be displayed to the user. +For everything but the yank command, the value is the largest value +about which the editor is silent, i.e. by default, 6 lines must be +deleted before the user is notified. +However, if the number of lines yanked is greater than +.i "or equal to" +the set value, it is reported to the user. +.KY ruler +.IP "ruler [off]" +.CO Vi +only. +Display a row/column ruler on the colon command line. +.KY scroll +.IP "scroll, scr [(environment variable LINES - 1) / 2]" +Set the number of lines scrolled by the +.CO ex +.CO <control-D> +and +.CO <end-of-file> +commands. +.sp +Historically, the +.CO ex +.CO z +command, when specified without a count, used two times the size of the +scroll value; the POSIX 1003.2 standard specified the window size, which +is a better choice. +.KY searchincr +.IP "searchincr [off]" +The +.OP searchincr +edit option makes the search commands +.CO \&/ +and +.CO \&? +incremental, i.e. the screen is updated and the cursor moves to the matching +text as the search pattern is entered. +If the search pattern is not found, +the screen is beeped and the cursor remains on the colon-command line. +Erasing characters from the search pattern backs the cursor up to the +previous matching text. +.KY sections +.IP "sections, sect [NHSHH HUnhsh]" +.CO Vi +only. +Define additional section boundaries for the +.CO [[ +and +.CO ]] +commands. +The +.OP sections +option should be set to a character string consisting of zero or +more character pairs. +In the text to be edited, the character string +.LI "<newline>.<char-pair>" , +(where +.LI <char-pair> +is one of the character pairs in the option's value), +defines a section boundary in the same manner that +.OP paragraphs +option boundaries are defined. +.KY secure +.IP "secure [off]" +The +.OP secure +edit option turns off all access to external programs. +This means that the versions of the +.CO read +and +.CO write +commands that filter text through other programs, +the +.CO vi +.CO \&! +and +.CO <control-Z> +commands, +the +.CO ex +.CO \&! , +.CO script , +.CO shell , +.CO stop +and +.CO suspend +commands and file name expansion will not be permitted. +Once set, +the +.OP secure +edit option may not be unset. +.KY shell +.IP "shell, sh [environment variable SHELL, or /bin/sh]" +Select the shell used by the editor. +The specified path is the pathname of the shell invoked by the +.CO vi +.CO ! +shell escape command and by the +.CO ex +.CO shell +command. +This program is also used to resolve any shell meta-characters in +.CO ex +commands. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms shellmeta [~{[*?$`'Q\e] +.KY shellmeta +.IP "\*(ms" +.tr QQ +The set of characters that +.CO ex +checks for when doing file name expansion. +If any of the specified characters are found in the file name arguments +to the +.CO ex +commands, +the arguments are expanded using the program defined by the +.OP shell +option. +The default set of characters is a union of meta characters +from the Version 7 and the Berkeley C shell. +.KY shiftwidth +.IP "shiftwidth, sw [8]" +Set the autoindent and shift command indentation width. +This width is used by the +.OP autoindent +option and by the +.CO < , +.CO > , +and +.CO shift +commands. +.KY showmatch +.IP "showmatch, sm [off]" +.CO Vi +only. +This option causes +.CO vi , +when a +.QT } +or +.QT ) +is entered, to briefly move the cursor the matching +.QT { +or +.QT ( . +See the +.OP matchtime +option for more information. +.KY showmode +.IP "showmode, smd [off]" +.CO Vi +only. +This option causes +.CO vi +to display a string identifying the current editor mode on the colon +command line. +The string is preceded by an asterisk (``*'') if the file has been +modified since it was last completely written, +.KY sidescroll +.IP "sidescroll [16]" +.CO Vi +only. +Sets the number of columns that are shifted to the left or right, +when +.CO vi +is doing left-right scrolling and the left or right margin is +crossed. +See the +.OP leftright +option for more information. +.KY slowopen +.IP "slowopen, slow [off]" +This option affects the display algorithm used by +.CO vi , +holding off display updating during input of new text to improve +throughput when the terminal in use is slow and unintelligent. +.sp +.i "This option is not yet implemented." +.KY sourceany +.IP "sourceany [off]" +If this option is turned on, +.CO vi +historically read startup files that were owned by someone other than +the editor user. +See the section entitled +.QB "Startup Information" +for more information. +This option is a security problem of immense proportions, +and should not be used under any circumstances. +.sp +.i "This option will never be implemented." +.KY tabstop +.IP "tabstop, ts [8]" +This option sets tab widths for the editor display. +.KY taglength +.IP "taglength, tl [0]" +This option sets the maximum number of characters that are considered +significant in a tag name. +Setting the value to 0 makes all of the characters in the tag name +significant. +.KY tags +.IP "tags, tag [tags /var/db/libc.tags /sys/kern/tags]" +Sets the list of tags files, in search order, +which are used when the editor searches for a tag. +.KY term +.IP "term, ttytype, tty [environment variable TERM]" +Set the terminal type. +Setting this option causes +.EV ex vi +to set (or reset) the environmental variable +.LI TERM . +.KY terse +.IP "terse [off]" +This option has historically made editor messages less verbose. +It has no effect in this implementation. +See the +.OP verbose +option for more information. +.KY tildeop +.IP "tildeop [off]" +Modify the +.CO ~ +command to take an associated motion. +.KY timeout +.IP "timeout, to [on]" +If this option is set, +.EV ex vi +waits for a specific period for a subsequent key to complete a key +mapping (see the +.OP keytime +option). +If the option is not set, the editor waits until enough keys are +entered to resolve the ambiguity, regardless of how long it takes. +.KY ttywerase +.IP "ttywerase [off]" +.CO Vi +only. +This option changes how +.CO vi +does word erase during text input. +If this option is set, text is broken up into two classes, +blank characters and nonblank characters. +Changing from one class to another marks the end of a word. +.KY verbose +.IP "verbose [off]" +.CO Vi +only. +.CO Vi +historically bells the terminal for many obvious mistakes, e.g. trying +to move past the left-hand margin, or past the end of the file. +If this option is set, an error message is displayed for all errors. +.KY w300 +.IP "w300 [no default]" +.CO Vi +only. +Set the window size if the baud rate is less than 1200 baud. +See the +.OP window +option for more information. +.KY w1200 +.IP "w1200 [no default]" +.CO Vi +only. +Set the window size if the baud rate is equal to 1200 baud. +See the +.OP window +option for more information. +.KY w9600 +.IP "w9600 [no default]" +.CO Vi +only. +Set the window size if the baud rate is greater than 1200 baud. +See the +.OP window +option for more information. +.KY warn +.IP "warn [on]" +.CO Ex +only. +This option causes a warning message to the terminal if the file has +been modified, since it was last written, before a +.CO ! +command. +.KY window +.IP "window, w, wi [environment variable LINES - 1]" +This option determines the default number of lines in a screenful, +as displayed by the +.CO z +command. +It also determines the number of lines scrolled by the +.CO vi +commands +.CO <control-B> +and +.CO <control-F> , +and the default number of lines scrolled by the +.CO vi +commands +.CO <control-D> +and +.CO <control-U> . +The value of window can be unrelated to the real screen size, +although it starts out as the number of lines on the screen. +See the section entitled +.QB "Sizing the Screen" +for more information. +Setting the value of the +.OP window +option is the same as using the +.b \-w +command line option. +.sp +If the value of the +.OP window +option (as set by the +.OP window , +.OP w300 , +.OP w1200 +or +.OP w9600 +options) is smaller than the actual size of the screen, +large screen movements will result in displaying only that smaller +number of lines on the screen. +(Further movements in that same area will result in the screen being +filled.) +This can provide a performance improvement when viewing different +places in one or more files over a slow link. +.sp +Resetting the window size does not reset the default number of lines +scrolled by the +.CO <control-D> +and +.CO <control-U> +commands. +.KY windowname +.IP "windowname [off]" +.CO Vi +changes the name of the editor's icon/window to the current file name +when it's possible and not destructive, i.e., +when the editor can restore it to its original value on exit or when +the icon/window will be discarded as the editor exits. +If the +.OP windowname +edit option is set, +.CO vi +will change the icon/window name even when it's destructive and the +icon/window name will remain after the editor exits. +(This is the case for +.XR xterm 1 ). +.KY wraplen +.IP "wraplen, wl [0]" +This option is identical to the +.OP wrapmargin +option, with the exception that it specifies the number of columns +from the +.i left +margin before the line splits, not the right margin. +.sp +If both +.OP wraplen +and +.OP wrapmargin +are set, the +.OP wrapmargin +value is used. +.KY wrapmargin +.IP "wrapmargin, wm [0]" +.CO Vi +only. +If the value of the +.OP wrapmargin +option is non-zero, +.CO vi +will split lines so that they end at least that number of columns +before the right-hand margin of the screen. +(Note, the value of +.OP wrapmargin +is +.i not +a text length. +In a screen that is 80 columns wide, the command +.QT ":set wrapmargin=8" +attempts to keep the lines less than or equal to 72 columns wide.) +.sp +Lines are split at the previous whitespace character closest to the +number. +Any trailing whitespace characters before that character are deleted. +If the line is split because of an inserted +.LI <space> +or +.LI <tab> +character, and you then enter another +.LI <space> +character, it is discarded. +.sp +If wrapmargin is set to 0, +or if there is no blank character upon which to split the line, +the line is not broken. +.sp +If both +.OP wraplen +and +.OP wrapmargin +are set, the +.OP wrapmargin +value is used. +.KY wrapscan +.IP "wrapscan, ws [on]" +This option causes searches to wrap around the end or the beginning +of the file, and back to the starting point. +Otherwise, the end or beginning of the file terminates the search. +.KY writeany +.IP "writeany, wa [off]" +If this option is set, file-overwriting checks that would usually be +made before the +.CO write +and +.CO xit +commands, or before an automatic write (see the +.OP autowrite +option), are not made. +This allows a write to any file, provided the file permissions allow it. diff --git a/share/doc/usd/13.viref/vi.cmd.roff b/share/doc/usd/13.viref/vi.cmd.roff new file mode 100644 index 000000000000..9f2970f0b0a1 --- /dev/null +++ b/share/doc/usd/13.viref/vi.cmd.roff @@ -0,0 +1,3083 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.SH 1 "Vi Description" +.pp +.CO Vi +takes up the entire screen to display the edited file, +except for the bottom line of the screen. +The bottom line of the screen is used to enter +.CO ex +commands, and for +.CO vi +error and informational messages. +If no other information is being displayed, +the default display can show the current cursor row and cursor column, +an indication of whether the file has been modified, +and the current mode of the editor. +See the +.OP ruler +and +.OP showmode +options for more information. +.pp +Empty lines do not have any special representation on the screen, +but lines on the screen that would logically come after the end of +the file are displayed as a single tilde +.PQ ~ +character. +To differentiate between empty lines and lines consisting of only +whitespace characters, use the +.OP list +option. +Historically, implementations of +.CO vi +have also displayed some lines as single asterisk +.PQ @ +characters. +These were lines that were not correctly displayed, i.e. lines on the +screen that did not correspond to lines in the file, or lines that did +not fit on the current screen. +.CO Nvi +never displays lines in this fashion. +.pp +.CO Vi +is a modeful editor, i.e. it has two modes, +.QQ command +mode and +.QQ "text input" +mode. +When +.CO vi +first starts, it is in command mode. +There are several commands that change +.CO vi +into text input mode. +The +.LI <escape> +character is used to resolve the text input into the file, +and exit back into command mode. +In +.CO vi +command mode, the cursor is always positioned on the last column of +characters which take up more than one column on the screen. +In +.CO vi +text insert mode, the cursor is positioned on the first column of +characters which take up more than one column on the screen. +.pp +When positioning the cursor to a new line and column, +the type of movement is defined by the distance to the new cursor position. +If the new position is close, +the screen is scrolled to the new location. +If the new position is far away, +the screen is repainted so that the new position is on the screen. +If the screen is scrolled, +it is moved a minimal amount, +and the cursor line will usually appear at the top or bottom of the screen. +If the screen is repainted, +the cursor line will appear in the center of the screen, +unless the cursor is sufficiently close to the beginning or end of the file +that this isn't possible. +If the +.OP leftright +option is set, the screen may be scrolled or repainted in a horizontal +direction as well as in a vertical one. +.pp +A major difference between the historical +.CO vi +presentation and +.CO nvi +is in the scrolling and screen oriented position commands, +.CO <control-B> , +.CO <control-D> , +.CO <control-E> , +.CO <control-F> , +.CO <control-U> , +.CO <control-Y> , +.CO H , +.CO L +and +.CO M . +In historical implementations of +.CO vi , +these commands acted on physical (as opposed to logical, or screen) +lines. +For lines that were sufficiently long in relation to the size of the +screen, this meant that single line scroll commands might repaint the +entire screen, scrolling or screen positioning commands might not change +the screen or move the cursor at all, and some lines simply could not +be displayed, even though +.CO vi +would edit the file that contained them. +In +.CO nvi , +these commands act on logical, i.e. screen lines. +You are unlikely to notice any difference unless you are editing files +with lines significantly longer than a screen width. +.pp +.CO Vi +keeps track of the currently +.QQ "most attractive" +cursor position. +Each command description (for commands that alter the current cursor +position), +specifies if the cursor is set to a specific location in the line, +or if it is moved to the +.QQ "most attractive cursor position" . +The latter means that the cursor is moved to the cursor position that +is horizontally as close as possible to the current cursor position. +If the current line is shorter than the cursor position +.CO vi +would select, the cursor is positioned on the last character in the line. +(If the line is empty, the cursor is positioned on the first column +of the line.) +If a command moves the cursor to the most attractive position, +it does not alter the current cursor position, and a subsequent +movement will again attempt to move the cursor to that position. +Therefore, although a movement to a line shorter than the currently +most attractive position will cause the cursor to move to the end of +that line, a subsequent movement to a longer line will cause the +cursor to move back to the most attractive position. +.pp +In addition, the +.CO $ +command makes the end of each line the most attractive cursor position +rather than a specific column. +.pp +Each +.CO vi +command described below notes where the cursor ends up after it is +executed. +This position is described in terms of characters on the line, i.e. +.QQ "the previous character" , +or, +.QQ "the last character in the line" . +This is to avoid needing to continually refer to on what part of the +character the cursor rests. +.pp +The following words have special meaning for +.CO vi +commands. +.KY "previous context" +.IP "previous context" +The position of the cursor before the command which caused the +last absolute movement was executed. +Each +.CO vi +command described in the next section that is considered an +absolute movement is so noted. +In addition, specifying +.i any +address to an +.CO ex +command is considered an absolute movement. +.KY "motion" +.IP "motion" +A second +.CO vi +command can be used as an optional trailing argument to the +.CO vi +.CO \&< , +.CO \&> , +.CO \&! , +.CO \&c , +.CO \&d , +.CO \&y , +and (depending on the +.OP tildeop +option) +.CO \&~ +commands. +This command indicates the end of the region of text that's affected by +the command. +The motion command may be either the command character repeated (in +which case it means the current line) or a cursor movement command. +In the latter case, the region affected by the command is from the +starting or stopping cursor position which comes first in the file, +to immediately before the starting or stopping cursor position which +comes later in the file. +Commands that operate on lines instead of using beginning and ending +cursor positions operate on all of the lines that are wholly or +partially in the region. +In addition, some other commands become line oriented depending on +where in the text they are used. +The command descriptions below note these special cases. +.sp +The following commands may all be used as motion components for +.CO vi +commands: +.sp +.ne 12v +.ft C +.TS +r r r r. +<control-A> <control-H> <control-J> <control-M> +<control-N> <control-P> <space> $ +% '<character> ( ) ++ , - / +0 ; ? B +E F G H +L M N T +W [[ ]] ^ +\&_ `<character> b e +f h j k +l n t w +{ | } +.TE +.ft R +.sp +The optional count prefix available for some of the +.CO vi +commands that take motion commands, +or the count prefix available for the +.CO vi +commands that are used as motion components, +may be included and is +.i always +considered part of the motion argument. +For example, the commands +.QT c2w +and +.QT 2cw +are equivalent, and the region affected by the +.CO c +command is two words of text. +In addition, +if the optional count prefix is specified for both the +.CO vi +command and its motion component, +the effect is multiplicative and is considered part of the motion argument. +For example, the commands +.QT 4cw +and +.QT 2c2w +are equivalent, and the region affected by the +.CO c +command is four words of text. +.KY "count" +.IP "count" +A positive number used as an optional argument to most commands, +either to give a size or a position (for display or movement commands), +or as a repeat count (for commands that modify text). +The count argument is always optional and defaults to 1 unless otherwise +noted in the command description. +.sp +When a +.CO vi +command synopsis shows both a +.LI [buffer] +and +.LI [count] , +they may be presented in any order. +.KY word +.IP word +Generally, in languages where it is applicable, +.CO vi +recognizes two kinds of words. +First, a sequence of letters, digits and underscores, +delimited at both ends by: +characters other than letters, digits, or underscores, +the beginning or end of a line, and the beginning or end of the file. +Second, a sequence of characters other than letters, digits, underscores, +or whitespace characters, delimited at both ends by: a letter, digit, +underscore, or whitespace character, +the beginning or end of a line, and the beginning or end of the file. +For example, the characters +.QT " !@#abc$%^ " +contain three words: +.QT "!@#" , +.QT "abc" +and +.QT "$%^" . +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single word. +.KY "bigword" +.IP "bigword" +A set of non-whitespace characters preceded and followed by whitespace +characters or the beginning or end of the file or line. +For example, the characters +.QT " !@#abc$%^ " +contain one bigword: +.QT "!@#abc$%^" . +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single bigword. +.KY "paragraph" +.IP "paragraph" +An area of text that begins with either the beginning of a file, +an empty line, or a section boundary, and continues until either +an empty line, section boundary, or the end of the file. +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single paragraph. +.sp +Additional paragraph boundaries can be defined using the +.OP paragraphs +option. +.KY "section" +.IP "section" +An area of text that starts with the beginning of the file or a line +whose first character is an open brace +.PQ { +and continues until the next section or the end of the file. +.sp +Additional section boundaries can be defined using the +.OP sections +option. +.KY "sentence" +.IP "sentence" +An area of text that begins with either the beginning of the file or the +first nonblank character following the previous sentence, paragraph, or +section boundary and continues until the end of the file or a period +.PQ \&. +exclamation point +.PQ ! +or question mark +.PQ ? +character, +followed by either an end-of-line or two whitespace characters. +Any number of closing parentheses +.PQ ) , +brackets +.PQ ] , +double-quote +.PQ """" +or single quote +.PQ ' +characters can appear between the period, exclamation point, +or question mark and the whitespace characters or end-of-line. +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single sentence. +.SH 1 "Vi Commands" +.pp +The following section describes the commands available in the command +mode of the +.CO vi +editor. +In each entry below, the tag line is a usage synopsis for the command +character. +In addition, the final line and column the cursor rests upon, +and any options which affect the command are noted. +.KY <control-A> +.IP "[count] <control-A>" +Search forward +.LI count +times for the current word. +The current word begins at the first non-whitespace character on or +after the current cursor position, +and extends up to the next non-word character or the end of the line. +The search is literal, i.e. no characters in the word have any special +meaning in terms of Regular Expressions. +It is an error if no matching pattern is found between the starting position +and the end of the file. +.sp +The +.CO <control-A> +command is an absolute movement. +The +.CO <control-A> +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line where the word is found. +.SP Column: +Set to the first character of the word. +.SP Options: +Affected by the +.OP ignorecase +and +.OP wrapscan +options. +.SE +.KY <control-B> +.IP "[count] <control-B>" +Page backward +.LI count +screens. +Two lines of overlap are maintained, if possible, +by displaying the window starting at line +.LI "(top_line - count * window_size) + 2" , +where +.LI window_size +is the value of the +.OP window +option. +(In the case of split screens, this size is corrected to the +current screen size.) +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Set to the last line of text displayed on the screen. +.SP Column: +Set to the first nonblank character of the line. +.SP Options: +Affected by the +.OP window +option. +.SE +.KY <control-D> +.IP "[count] <control-D>" +Scroll forward +.LI count +lines. +If +.LI count +is not specified, scroll forward the number of lines specified by the last +.CO <control-D> +or +.CO <control-U> +command. +If this is the first +.CO <control-D> +or +.CO <control-U> +command, +scroll forward half the number of lines in the screen. +(In the case of split screens, the default scrolling distance is +corrected to half the current screen size.) +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Set to the current line plus the number of lines scrolled. +.SP Column: +Set to the first nonblank character of the line. +.SP Options: +None. +.SE +.KY <control-E> +.IP "[count] <control-E>" +Scroll forward +.LI count +lines, leaving the cursor on the current line and column, if possible. +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Unchanged unless the current line scrolls off the screen, +in which case it is set to the first line on the screen. +.SP Column: +Unchanged unless the current line scrolls off the screen, +in which case it is set to the most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-F> +.IP "[count] <control-F>" +Page forward +.LI count +screens. +Two lines of overlap are maintained, if possible, +by displaying the window starting at line +.LI "top_line + count * window_size - 2" , +where +.LI window_size +is the value of the +.OP window +option. +(In the case of split screens, this size is corrected to the +current screen size.) +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Set to the first line on the screen. +.SP Column: +Set to the first nonblank character of the current line. +.SP Options: +Affected by the +.OP window +option. +.SE +.KY <control-G> +.IP "<control-G>" +Display the file information. +The information includes the current pathname, the current line, +the number of total lines in the file, the current line as a percentage +of the total lines in the file, if the file has been modified, +was able to be locked, if the file's name has been changed, +and if the edit session is read-only. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY <control-H> +.IP "[count] <control-H>" +.Ip "[count] h" +Move the cursor back +.LI count +characters in the current line. +It is an error if the cursor is on the first character in the line. +.sp +The +.CO <control-H> +and +.CO h +commands may be used as the motion component of other +.CO vi +commands, +in which case any text copied into a buffer is character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the +.LI "current - count" +character, or, the first character in the line if +.LI count +is greater than or equal to the number of characters in the line +before the cursor. +.SP Options: +None. +.SE +.KY <control-J> +.IP "[count] <control-J>" +.KY <control-N> +.Ip "[count] <control-N>" +.KY j +.Ip "[count] j" +Move the cursor down +.LI count +lines without changing the current column. +It is an error if the movement is past the end of the file. +.sp +The +.CO <control-J> , +.CO <control-N> +and +.CO j +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line plus +.LI count . +.SP Column: +The most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-L> +.IP "<control-L>" +.KY <control-R> +.Ip "<control-R>" +Repaint the screen. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY <control-M> +.IP "[count] <control-M>" +.KY + +.Ip "[count] +" +Move the cursor down +.LI count +lines to the first nonblank character of that line. +It is an error if the movement is past the end of the file. +.sp +The +.CO <control-M> +and +.CO + +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line plus +.LI count . +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY <control-P> +.IP "[count] <control-P>" +.KY k +.Ip "[count] k" +Move the cursor up +.LI count +lines, without changing the current column. +It is an error if the movement is past the beginning of the file. +.sp +The +.CO <control-P> +and +.CO k +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line minus +.LI count . +.SP Column: +The most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-T> +.IP "<control-T>" +Return to the most recent tag context. +The +.CO <control-T> +command is an absolute movement. +.SS +.SP Line: +Set to the context of the previous tag command. +.SP Column: +Set to the context of the previous tag command. +.SP Options: +None. +.SE +.KY <control-U> +.IP "[count] <control-U>" +Scroll backward +.LI count +lines. +If +.LI count +is not specified, scroll backward the number of lines specified by the +last +.CO <control-D> +or +.CO <control-U> +command. +If this is the first +.CO <control-D> +or +.CO <control-U> +command, +scroll backward half the number of lines in the screen. +(In the case of split screens, the default scrolling distance is +corrected to half the current screen size.) +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Set to the current line minus the amount scrolled. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY <control-W> +.IP "<control-W>" +Switch to the next lower screen in the window, or, to the first +screen if there are no lower screens in the window. +.SS +.SP Line: +Set to the previous cursor position in the window. +.SP Column: +Set to the previous cursor position in the window. +.SP Options: +None. +.SE +.KY <control-Y> +.IP "[count] <control-Y>" +Scroll backward +.LI count +lines, leaving the current line and column as is, if possible. +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Unchanged unless the current line scrolls off the screen, +in which case it is set to the last line of text displayed +on the screen. +.SP Column: +Unchanged unless the current line scrolls off the screen, +in which case it is the most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-Z> +.IP "<control-Z>" +Suspend the current editor session. +If the file has been modified since it was last completely written, +and the +.OP autowrite +option is set, the file is written before the editor session is +suspended. +If this write fails, the editor session is not suspended. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +Affected by the +.OP autowrite +option. +.SE +.KY <escape> +.IP "<escape>" +Execute +.CO ex +commands or cancel partial commands. +If an +.CO ex +command is being entered (e.g. +.CO / , +.CO ? , +.CO : +or +.CO ! ), +the command is executed. +If a partial command has been entered, e.g. +.QT "[0-9]*" , +or +.QT "[0-9]*[!<>cdy]" , +the command is cancelled. +Otherwise, it is an error. +.SS +.SP Line: +When an +.CO ex +command is being executed, the current line is set as described for +that command. +Otherwise, unchanged. +.SP Column: +When an +.CO ex +command is being executed, the current column is set as described for +that command. +Otherwise, unchanged. +.SP Options: +None. +.SE +.KY <control-]> +.IP "<control-]>" +Push a tag reference onto the tag stack. +The tags files (see the +.OP tags +option for more information) are searched for a tag matching the +current word. +The current word begins at the first non-whitespace character on or +after the current cursor position, +and extends up to the next non-word character or the end of the line. +If a matching tag is found, the current file is discarded and the +file containing the tag reference is edited. +.sp +If the current file has been modified since it was last completely +written, the command will fail. +The +.CO <control-]> +command is an absolute movement. +.SS +.SP Line: +Set to the line containing the matching tag string. +.SP Column: +Set to the start of the matching tag string. +.SP Options: +Affected by the +.OP tags +and +.OP taglength +options. +.SE +.KY <control-^> +.IP "<control-^>" +Switch to the most recently edited file. +.sp +If the file has been modified since it was last completely written, +and the +.OP autowrite +option is set, the file is written out. +If this write fails, the command will fail. +Otherwise, if the current file has been modified since it was last +completely written, the command will fail. +.SS +.SP Line: +Set to the line the cursor was on when the file was last edited. +.SP Column: +Set to the column the cursor was on when the file was last edited. +.SP Options: +Affected by the +.OP autowrite +option. +.SE +.KY <space> +.IP "[count] <space>" +.KY l +.Ip "[count] l" +Move the cursor forward +.LI count +characters without changing the current line. +It is an error if the cursor is on the last character in the line. +.sp +The +.CO <space> +and +.CO \&l +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +In addition, these commands may be used as the motion components +of other commands when the cursor is on the last character in the +line, without error. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the current character plus the next +.LI count +characters, or to the last character on the line if +.LI count +is greater than the number of characters in the line after the +current character. +.SP Options: +None. +.SE +.KY ! +.IP "[count] ! motion shell-argument(s)<carriage-return>" +Replace text with results from a shell command. +Pass the lines specified by the +.LI count +and +.LI motion +arguments as standard input to the program named by the +.OP shell +option, and replace those lines with the output (both +standard error and standard output) of that command. +.sp +After the motion is entered, +.CO vi +prompts for arguments to the shell command. +.sp +Within those arguments, +.QT % +and +.QT # +characters are expanded to the current and alternate pathnames, +respectively. +The +.QT ! +character is expanded with the command text of the previous +.CO ! +or +.CO :! +commands. +(Therefore, the command +.CO !<motion>! +repeats the previous +.CO ! +command.) +The special meanings of +.QT % , +.QT # +and +.QT ! +can be overridden by escaping them with a backslash. +If no +.CO ! +or +.CO :! +command has yet been executed, +it is an error to use an unescaped +.QT ! +character as a shell argument. +The +.CO ! +command does +.i not +do shell expansion on the strings provided as arguments. +If any of the above expansions change the arguments the user entered, +the command is redisplayed at the bottom of the screen. +.sp +.CO Vi +then executes the program named by the +.OP shell +option, with a +.b \-c +flag followed by the arguments (which are bundled into a single argument). +.sp +The +.CO ! +command is permitted in an empty file. +.sp +If the file has been modified since it was last completely written, +the +.CO ! +command will warn you. +.SS +.SP Line: +The first line of the replaced text. +.SP Column: +The first column of the replaced text. +.SP Options: +Affected by the +.OP shell +option. +.SE +.KY # +.IP "[count] # #|+|-" +Increment or decrement the number referenced by the cursor. +If the trailing character is a +.LI \&+ +or +.LI \&# , +the number is incremented by +.LI count . +If the trailing character is a +.LI \&- , +the number is decremented by +.LI count . +.sp +A leading +.QT \&0X +or +.QT \&0x +causes the number to be interpreted as a hexadecimal number. +Otherwise, a leading +.QT \&0 +causes the number to be interpreted as an octal number, unless a non-octal +digit is found as part of the number. +Otherwise, the number is interpreted as a decimal number, and may +have a leading +.LI \&+ +or +.LI \&- +sign. +The current number begins at the first non-blank character at or after +the current cursor position, and extends up to the end of the line or +the first character that isn't a possible character for the numeric type. +The format of the number (e.g. leading 0's, signs) is retained unless +the new value cannot be represented in the previous format. +.sp +Octal and hexadecimal numbers, and the result of the operation, must fit +into an +.QT "unsigned long" . +Similarly, decimal numbers and their result must fit into a +.QT "signed long" . +It is an error to use this command when the cursor is not positioned at +a number. +.sp +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first character in the cursor number. +.SP Options: +None. +.SE +.KY $ +.IP "[count] $" +Move the cursor to the end of a line. +If +.LI count +is specified, the cursor moves down +.LI "count - 1" +lines. +.sp +It is not an error to use the +.CO $ +command when the cursor is on the last character in the line or +when the line is empty. +.sp +The +.CO $ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the cursor is at, or before the first +nonblank character in the line, in which case it is line oriented. +It is not an error to use the +.CO $ +command as a motion component when the cursor is on the last character +in the line, although it is an error when the line is empty. +.SS +.SP Line: +Set to the current line plus +.LI count +minus 1. +.SP Column: +Set to the last character in the line. +.SP Options: +None. +.SE +.KY % +.IP % +Move to the matching character. +The cursor moves to the parenthesis or curly brace which +.i matches +the parenthesis or curly brace found at the current cursor position +or which is the closest one to the right of the cursor on the line. +It is an error to execute the +.CO % +command on a line without a parenthesis or curly brace. +Historically, any +.LI count +specified to the +.CO % +command was ignored. +.sp +The +.CO % +command is an absolute movement. +The +.CO % +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting point of the region is at +or before the first nonblank character on its line, and the ending +point is at or after the last nonblank character on its line, in +which case it is line oriented. +.SS +.SP Line: +Set to the line containing the matching character. +.SP Column: +Set to the matching character. +.SP Options: +None. +.SE +.KY & +.IP "&" +Repeat the previous substitution command on the current line. +.sp +Historically, any +.LI count +specified to the +.CO & +command was ignored. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged if the cursor was on the last character in the line, +otherwise, set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP edcompatible , +.OP extended , +.OP ignorecase +and +.OP magic +options. +.SE +.KY SQUOTE<character> +.IP \'<character> +.KY `<character> +.Ip `<character> +Return to a context marked by the character +.LI <character> . +If +.LI <character> +is the +.QT ' +or +.QT ` +character, return to the previous context. +If +.LI <character> +is any other character, +return to the context marked by that character (see the +.CO m +command for more information). +If the command is the +.CO \' +command, only the line value is restored, +and the cursor is placed on the first nonblank character of that line. +If the command is the +.CO ` +command, both the line and column values are restored. +.sp +It is an error if the context no longer exists because of +line deletion. +(Contexts follow lines that are moved, or which are deleted +and then restored.) +.sp +The +.CO \' +and +.CO ` +commands are both absolute movements. +They may be used as a motion component for other +.CO vi +commands. +For the +.CO \' +command, any text copied into a buffer is line oriented. +For the +.CO ` +command, +any text copied into a buffer is character oriented, +unless it both starts and stops at the first character in the line, +in which case it is line oriented. +In addition, when using the +.CO ` +command as a motion component, +commands which move backward and started at the first character in the line, +or move forward and ended at the first character in the line, +are corrected to the last character of the line preceding the starting and +ending lines, respectively. +.SS +.SP Line: +Set to the line from the context. +.SP Column: +Set to the first nonblank character in the line, for the +.CO \' +command, and set to the context's column for the +.CO ` +command. +.SP Options: +None. +.SE +.KY ( +.IP "[count] (" +Back up +.LI count +sentences. +.sp +The +.CO ( +command is an absolute movement. +The +.CO ( +command may be used as the motion component of other +.CO vi +commands, +in which case any text copied into a buffer is character oriented, +unless the starting and stopping points of the region are the first +character in the line, +in which case it is line oriented. +If it is line oriented, +the starting point of the region is adjusted to be the end of the line +immediately before the starting cursor position. +.SS +.SP Line: +Set to the line containing the beginning of the sentence. +.SP Column: +Set to the first nonblank character of the sentence. +.SP Options: +Affected by the +.OP lisp +option. +.SE +.KY ) +.IP "[count] )" +Move forward +.LI count +sentences. +.sp +The +.CO ) +command is an absolute movement. +The +.CO ) +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting point of the region is the +first character in the line, in which case it is line oriented. +In the latter case, if the stopping point of the region is also +the first character in the line, it is adjusted to be the end of the +line immediately before it. +.SS +.SP Line: +Set to the line containing the beginning of the sentence. +.SP Column: +Set to the first nonblank character of the sentence. +.SP Options: +Affected by the +.OP lisp +option. +.SE +.KY , +.IP "[count] ," +Reverse find character +.LI count +times. +Reverse the last +.CO F , +.CO f , +.CO T +or +.CO t +command, searching the other way in the line, +.LI count +times. +It is an error if a +.CO F , +.CO f , +.CO T +or +.CO t +command has not been performed yet. +.sp +The +.CO , +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character for the +.CO F +and +.CO f +commands, +before the character for the +.CO t +command +and after the character for the +.CO T +command. +.SP Options: +None. +.SE +.KY MINUSSIGN +.IP "[count] \-" +Move to the first nonblank of the previous line, +.LI count +times. +.sp +It is an error if the movement is past the beginning of the file. +.sp +The +.CO - +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line minus +.LI count . +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY \&. +.IP "[count] \&." +Repeat the last +.CO vi +command that modified text. +The repeated command may be a command and motion component combination. +If +.LI count +is specified, it replaces +.i both +the count specified for the repeated command, and, if applicable, for +the repeated motion component. +If +.LI count +is not specified, the counts originally specified to the command being +repeated are used again. +.sp +As a special case, if the +.CO \. +command is executed immediately after the +.CO u +command, the change log is rolled forward or backward, depending on +the action of the +.CO u +command. +.SS +.SP Line: +Set as described for the repeated command. +.SP Column: +Set as described for the repeated command. +.SP Options: +None. +.SE +.KY /RE/ +.IP "/RE<carriage-return>" +.Ip "/RE/ [offset]<carriage-return>" +.KY ?RE? +.Ip "?RE<carriage-return>" +.Ip "?RE? [offset]<carriage-return>" +.KY N +.Ip "N" +.KY n +.Ip "n" +Search forward or backward for a regular expression. +The commands beginning with a slash +.PQ / +character are forward searches, the commands beginning with a +question mark +.PQ ? +are backward searches. +.CO Vi +prompts with the leading character on the last line of the screen +for a string. +It then searches forward or backward in the file for the next +occurrence of the string, which is interpreted as a Basic Regular +Expression. +.sp +The +.CO / +and +.CO ? +commands are absolute movements. +They may be used as the motion components of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the search started and ended on +the first column of a line, in which case it is line oriented. +In addition, forward searches ending at the first character of a line, +and backward searches beginning at the first character in the line, +are corrected to begin or end at the last character of the previous line. +(Note, forward and backward searches can occur for both +.CO / +and +.CO ? +commands, if the +.OP wrapscan +option is set.) +.sp +If an offset from the matched line is specified (i.e. a trailing +.QT / +or +.QT ? +character is followed by a signed offset), the buffer will always +be line oriented (e.g. +.QT /string/+0 +will always guarantee a line orientation). +.sp +The +.CO N +command repeats the previous search, but in the reverse direction. +The +.CO n +command repeats the previous search. +If either the +.CO N +or +.CO n +commands are used as motion components for the +.CO ! +command, you will not be prompted for the text of the bang command, +instead the previous bang command will be executed. +.sp +Missing RE's (e.g. +.QT //<carriage-return> , +.QT /<carriage-return> , +.QT ??<carriage-return> , +or +.QT ?<carriage-return> +search for the last search RE, in the indicated direction. +.sp +Searches may be interrupted using the +.LI <interrupt> +character. +.sp +Multiple search patterns may be grouped together by delimiting +them with semicolons and zero or more whitespace characters, e.g. +.LI "/foo/ ; ?bar?" +searches forward for +.LI foo +and then, from that location, backwards for +.LI bar . +When search patterns are grouped together in this manner, +the search patterns are evaluated left to right with the +final cursor position determined by the last search pattern. +.sp +It is also permissible to append a +.CO z +command to the search strings, e.g. +.LI "/foo/ z." +searches forward for the next occurrence of +.LI foo , +and then positions that line in the middle of screen. +.SS +.SP Line: +Set to the line in which the match occurred. +.SP Column: +Set to the first character of the matched string. +.SP Options: +Affected by the +.OP edcompatible , +.OP extended , +.OP ignorecase , +.OP magic , +and +.OP wrapscan +options. +.SE +.KY 0 +.IP "0" +Move to the first character in the current line. +It is not an error to use the +.CO 0 +command when the cursor is on the first character in the line, +.sp +The +.CO 0 +command may be used as the motion component of other +.CO vi +commands, +in which case it is an error if the cursor is on the first character +in the line, +and any text copied into a buffer is character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first character in the line. +.SP Options: +None. +.SE +.KY : +.IP ":" +Execute an +.CO ex +command. +.CO Vi +prompts for an +.CO ex +command on the last line of the screen, using a colon +.PQ : +character. +The command is terminated by a +.LI <carriage-return> , +.LI <newline> +or +.LI <escape> +character; all of these characters may be escaped by using a +.LI "<literal-next>" +character. +The command is then executed. +.sp +If the +.CO ex +command writes to the screen, +.CO vi +will prompt the user for a +.LI <carriage-return> +before continuing +when the +.CO ex +command finishes. +Large amounts of output from the +.CO ex +command will be paged for the user, and the user prompted for a +.LI <carriage-return> +or +.LI <space> +key to continue. +In some cases, a quit (normally a +.QQ q +character) or +.LI <interrupt> +may be entered to interrupt the +.CO ex +command. +.sp +When the +.CO ex +command finishes, and the user is prompted to resume visual mode, +it is also possible to enter another +.QT : +character followed by another +.CO ex +command. +.SS +.SP Line: +The current line is set as described for the +.CO ex +command. +.SP Column: +The current column is set as described for the +.CO ex +command. +.SP Options: +Affected as described for the +.CO ex +command. +.SE +.KY ; +.IP "[count] ;" +Repeat the last character find +.LI count +times. +The last character find is one of the +.CO F , +.CO f , +.CO T +or +.CO t +commands. +It is an error if a +.CO F , +.CO f , +.CO T +or +.CO t +command has not been performed yet. +.sp +The +.CO ; +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character for the +.CO F +and +.CO f +commands, +before the character for the +.CO t +command +and after the character for the +.CO T +command. +.SP Options: +None. +.SE +.KY < +.IP "[count] < motion" +.KY > +.Ip "[count] > motion" +Shift lines left or right. +Shift the number of lines in the region specified by the +.LI count +and +.LI motion +left (for the +.CO < +command) or right (for the +.CO > +command) by the number of columns specified by the +.OP shiftwidth +option. +Only whitespace characters are deleted when shifting left. +Once the first character in the line no longer contains a whitespace +character, the command will succeed, +but the line will not be modified. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP shiftwidth +option. +.SE +.KY @ +.IP "@ buffer" +Execute a named buffer. +Execute the named buffer as +.CO vi +commands. +The buffer may include +.CO ex +commands, too, but they must be expressed as a +.CO : +command. +If the buffer is line oriented, +.LI <newline> +characters are logically appended to each line of the buffer. +If the buffer is character oriented, +.LI <newline> +characters are logically appended to all but the last line in the buffer. +.sp +If the buffer name is +.QT @ , +or +.QT * , +then the last buffer executed shall be used. +It is an error to specify +.QT @@ +or +.QT @* +if there were no previous buffer executions. +The text of a buffer may contain a +.CO @ +command, +and it is possible to create infinite loops in this manner. +(The +.LI <interrupt> +character may be used to interrupt the loop.) +.SS +.SP Line: +The current line is set as described for the command(s). +.SP Column: +The current column is set as described for the command(s). +.SP Options: +None. +.SE +.KY A +.IP "[count] A" +Enter input mode, appending the text after the end of the line. +If +.LI count +is specified, the text is repeatedly input +.LI "count - 1" +more times after input mode is exited. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY B +.IP "[count] B" +Move backward +.LI count +bigwords. +Move the cursor backward to the beginning of a bigword by repeating the +following algorithm: if the current position is at the beginning of a +bigword or the character at the current position cannot be part of a bigword, +move to the first character of the preceding bigword. +Otherwise, move to the first character of the bigword at the current position. +If no preceding bigword exists on the current line, move to the first +character of the last bigword on the first preceding line that contains a +bigword. +.sp +The +.CO B +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the first character of the word selected. +.SP Options: +None. +.SE +.KY C +.IP "[buffer] [count] C" +Change text from the current position to the end-of-line. +If +.LI count +is specified, the input text replaces from the current position to +the end-of-line, plus +.LI "count - 1" +subsequent lines. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY D +.IP "[buffer] D" +Delete text from the current position to the end-of-line. +.sp +It is not an error to execute the +.CO D +command on an empty line. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character before the current character, or, column 1 if +the cursor was on column 1. +.SP Options: +None. +.SE +.KY E +.IP "[count] E" +Move forward +.LI count +end-of-bigwords. +Move the cursor forward to the end of a bigword by repeating the +following algorithm: if the current position is the end of a +bigword or the character at that position cannot be part of a bigword, +move to the last character of the following bigword. +Otherwise, move to the last character of the bigword at the current +position. +If no succeeding bigword exists on the current line, +move to the last character of the first bigword on the next following +line that contains a bigword. +.sp +The +.CO E +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the last character of the word selected. +.SP Options: +None. +.SE +.KY F +.IP "[count] F <character>" +Search +.LI count +times backward through the current line for +.LI <character> . +.sp +The +.CO F +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character. +.SP Options: +None. +.SE +.KY G +.IP "[count] G" +Move to line +.LI count , +or the last line of the file if +.LI count +not specified. +.sp +The +.CO G +command is an absolute movement. +The +.CO \&G +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to +.LI count , +if specified, otherwise, the last line. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY H +.IP "[count] H" +Move to the screen line +.LI "count - 1" +lines below the top of the screen. +.sp +The +.CO H +command is an absolute movement. +The +.CO H +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the line +.LI "count - 1" +lines below the top of the screen. +.SP Column: +Set to the first nonblank character of the +.i screen +line. +.SP Options: +None. +.SE +.KY I +.IP "[count] I" +Enter input mode, inserting the text at the beginning of the line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +None. +.SE +.KY J +.IP "[count] J" +Join lines. +If +.LI count +is specified, +.LI count +lines are joined; a minimum of two lines are always joined, +regardless of the value of +.LI count . +.sp +If the current line ends with a whitespace character, all whitespace +is stripped from the next line. +Otherwise, if the next line starts with a open parenthesis +.PQ ( +do nothing. +Otherwise, if the current line ends with a question mark +.PQ ? , +period +.PQ \&. +or exclamation point +.PQ ! , +insert two spaces. +Otherwise, insert a single space. +.sp +It is not an error to join lines past the end of the file, +i.e. lines that do not exist. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character after the last character of the next-to-last +joined line. +.SP Options: +None. +.SE +.KY L +.IP "[count] L" +Move to the screen line +.LI "count - 1" +lines above the bottom of the screen. +.sp +The +.CO L +command is an absolute movement. +The +.CO L +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the line +.LI "count - 1" +lines above the bottom of the screen. +.SP Column: +Set to the first nonblank character of the +.i screen +line. +.SP Options: +None. +.SE +.KY M +.IP " M" +Move to the screen line in the middle of the screen. +.sp +The +.CO M +command is an absolute movement. +The +.CO M +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.sp +Historically, any +.LI count +specified to the +.CO M +command was ignored. +.SS +.SP Line: +Set to the line in the middle of the screen. +.SP Column: +Set to the first nonblank character of the +.i screen +line. +.SP Options: +None. +.SE +.KY O +.IP "[count] O" +Enter input mode, appending text in a new line above the current line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.sp +Historically, any +.LI count +specified to the +.CO O +command was ignored. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY P +.IP "[buffer] P" +Insert text from a buffer. +Text from the buffer (the unnamed buffer by default) is inserted +before the current column or, if the buffer is line oriented, +before the current line. +.SS +.SP Line: +Set to the lowest numbered line insert, +if the buffer is line oriented, otherwise unchanged. +.SP Column: +Set to the first nonblank character of the appended text, +if the buffer is line oriented, otherwise, the last character +of the appended text. +.SP Options: +None. +.SE +.KY Q +.IP "Q" +Exit +.CO vi +(or visual) mode and switch to +.CO ex +mode. +.SS +.SP Line: +Unchanged. +.SP Column: +No longer relevant. +.SP Options: +None. +.SE +.KY R +.IP "[count] R" +Enter input mode, replacing the characters in the current line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.sp +If the end of the current line is reached, no more characters are +replaced and any further characters input are appended to the line. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY S +.IP "[buffer] [count] S" +Substitute +.LI count +lines. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY T +.IP "[count] T <character>" +Search backward, +.LI count +times, +through the current line for the character +.i after +the specified +.LI <character> . +.sp +The +.CO T +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character +.i after +the searched-for character. +.SP Options: +None. +.SE +.KY U +.IP "U" +Restore the current line to its state before the cursor last +moved to it. +.SS +.SP Line: +Unchanged. +.SP Column: +The first character in the line. +.SP Options: +None. +.SE +.KY W +.IP "[count] W" +Move forward +.LI count +bigwords. +Move the cursor forward to the beginning of a bigword by repeating the +following algorithm: if the current position is within a bigword or the +character at that position cannot be part of a bigword, move to the first +character of the next bigword. +If no subsequent bigword exists on the current line, +move to the first character of the first bigword on the first following +line that contains a bigword. +.sp +The +.CO W +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +The line containing the word selected. +.SP Column: +The first character of the word selected. +.SP Options: +None. +.SE +.KY X +.IP "[buffer] [count] X" +Delete +.LI count +characters before the cursor. +If the number of characters to be deleted is greater than or equal to +the number of characters to the beginning of the line, all of the +characters before the current cursor position, to the beginning of the +line, are deleted. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the current character minus +.LI count , +or the first character if count is greater than the number of +characters in the line before the cursor. +.SP Options: +None. +.SE +.KY Y +.IP "[buffer] [count] Y" +Copy (or +.QQ yank ) +.LI count +lines into the specified buffer. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY ZZ +.IP "ZZ" +Write the file and exit +.CO vi . +The file is only written if it has been modified since the last +complete write of the file to any file. +.sp +The +.CO ZZ +command will exit the editor after writing the file, +if there are no further files to edit. +Entering two +.QQ quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row will override this check and the editor will exit, +ignoring any files that have not yet been edited. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY [[ +.IP "[count] [[" +Back up +.LI count +section boundaries. +.sp +The +.CO [[ +command is an absolute movement. +The +.CO [[ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting position is column 0, +in which case it is line oriented. +.sp +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Set to the previous line that is +.LI count +section boundaries back, +or the first line of the file if no more section boundaries exist +preceding the current line. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP sections +option. +.SE +.KY ]] +.IP "[count] ]]" +Move forward +.LI count +section boundaries. +.sp +The +.CO ]] +command is an absolute movement. +The +.CO ]] +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting position is column 0, +in which case it is line oriented. +.sp +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Set to the line that is +.LI count +section boundaries forward, +or to the last line of the file if no more section +boundaries exist following the current line. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP sections +option. +.SE +.KY ^ +.IP "\&^" +Move to first nonblank character on the current line. +.sp +The +.CO ^ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first nonblank character of the current line. +.SP Options: +None. +.SE +.KY _ +.IP "[count] _" +Move down +.LI "count - 1" +lines, to the first nonblank character. +The +.CO _ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.sp +It is not an error to execute the +.CO _ +command when the cursor is on the first character in the line. +.SS +.SP Line: +The current line plus +.LI "count - 1" . +.SP Column: +The first nonblank character in the line. +.SP Options: +None. +.SE +.KY a +.IP "[count] a" +Enter input mode, appending the text after the cursor. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY b +.IP "[count] b" +Move backward +.LI count +words. +Move the cursor backward to the beginning of a word by repeating the +following algorithm: if the current position is at the beginning of a word, +move to the first character of the preceding word. +Otherwise, the current position moves to the first character of the word +at the current position. +If no preceding word exists on the current line, move to the first +character of the last word on the first preceding line that contains +a word. +.sp +The +.CO b +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the first character of the word selected. +.SP Options: +None. +.SE +.KY c +.IP "[buffer] [count] c motion" +Change the region of text specified by the +.LI count +and +.LI motion . +If only part of a single line is affected, then the last character +being changed is marked with a +.QT $ . +Otherwise, the region of text is deleted, and input mode is entered. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY d +.IP "[buffer] [count] d motion" +Delete the region of text specified by the +.LI count +and +.LI motion . +.SS +.SP Line: +Set to the line where the region starts. +.SP Column: +Set to the first character in the line after the last character in the +region. +If no such character exists, set to the last character before the region. +.SP Options: +None. +.SE +.KY e +.IP "[count] e" +Move forward +.LI count +end-of-words. +Move the cursor forward to the end of a word by repeating the following +algorithm: if the current position is the end of a word, +move to the last character of the following word. +Otherwise, move to the last character of the word at the current position. +If no succeeding word exists on the current line, move to the last character +of the first word on the next following line that contains a word. +.sp +The +.CO e +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the last character of the word selected. +.SP Options: +None. +.SE +.KY f +.IP "[count] f <character>" +Search forward, +.LI count +times, through the rest of the current line for +.LI <character> . +.sp +The +.CO f +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character. +.SP Options: +None. +.SE +.KY i +.IP "[count] i" +Enter input mode, inserting the text before the cursor. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY m +.IP "m <character>" +Save the current context (line and column) as +.LI <character> . +The exact position is referred to by +.QT `<character> . +The line is referred to by +.QT '<character> . +.sp +Historically, +.LI <character> +was restricted to lower-case letters. +.CO Nvi +permits the use of any character. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY o +.IP "[count] o" +Enter input mode, appending text in a new line under the current line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.sp +Historically, any +.LI count +specified to the +.CO o +command was ignored. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY p +.IP "[buffer] p" +Append text from a buffer. +Text from the buffer (the unnamed buffer by default) is appended +after the current column or, if the buffer is line oriented, +after the current line. +.SS +.SP Line: +Set to the first line appended, if the buffer is line oriented, +otherwise unchanged. +.SP Column: +Set to the first nonblank character of the appended text if the buffer +is line oriented, otherwise, the last character of the appended text. +.SP Options: +None. +.SE +.KY r +.IP "[count] r <character>" +Replace characters. +The next +.LI count +characters in the line are replaced with +.LI <character> . +Replacing characters with +.LI <newline> +characters results in creating new, empty lines into the file. +.sp +If +.LI <character> +is +.LI <escape> , +the command is cancelled. +.SS +.SP Line: +Unchanged unless the replacement character is a +.LI <newline> , +in which case it is set to the current line plus +.LI "count - 1" . +.SP Column: +Set to the last character replaced, +unless the replacement character is a +.LI <newline> , +in which case the cursor is in column 1 of the last line inserted. +.SP Options: +None. +.SE +.KY s +.IP "[buffer] [count] s" +Substitute +.LI count +characters in the current line starting with the current character. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY t +.IP "[count] t <character>" +Search forward, +.LI count +times, through the current line for the character immediately +.i before +.LI <character> . +.sp +The +.CO t +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character +.i before +the searched-for character. +.SP Options: +None. +.SE +.KY u +.IP "u" +Undo the last change made to the file. +If repeated, the +.CO u +command alternates between these two states, and is its own inverse. +When used after an insert that inserted text on more than one line, +the lines are saved in the numeric buffers. +.sp +The +.CO \&. +command, when used immediately after the +.CO u +command, causes the change log to be rolled forward or backward, +depending on the action of the +.CO u +command. +.SS +.SP Line: +Set to the position of the first line changed, if the reversal affects +only one line or represents an addition or change; otherwise, the line +preceding the deleted text. +.SP Column: +Set to the cursor position before the change was made. +.SP Options: +None. +.SE +.KY w +.IP "[count] w" +Move forward +.LI count +words. +Move the cursor forward to the beginning of a word by repeating the +following algorithm: if the current position is at the +beginning of a word, move to the first character of the next word. +If no subsequent word exists on the current line, move to the first +character of the first word on the first following line that contains +a word. +.sp +The +.CO w +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the first character of the word selected. +.SP Options: +None. +.SE +.KY x +.IP "[buffer] [count] x" +Delete +.LI count +characters. +The deletion is at the current character position. +If the number of characters to be deleted is greater than or equal to +the number of characters to the end of the line, all of the characters +from the current cursor position to the end of the line are deleted. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged unless the last character in the line is deleted and the cursor +is not already on the first character in the line, in which case it is +set to the previous character. +.SP Options: +None. +.SE +.KY y +.IP "[buffer] [count] y motion" +Copy (or +.QQ yank ) +the text region specified by the +.LI count +and +.LI motion , +into a buffer. +.SS +.SP Line: +Unchanged, unless the region covers more than a single line, +in which case it is set to the line where the region starts. +.SP Column: +Unchanged, unless the region covers more than a single line, +in which case it is set to the character were the region starts. +.SP Options: +None. +.SE +.KY z +.IP "[count1] z [count2] type" +Redraw the screen with a window +.LI count2 +lines long, with line +.LI count1 +placed as specified by the +.LI type +character. +If +.LI count1 +is not specified, it defaults to the current line. +If +.LI count2 +is not specified, it defaults to the current window size. +.sp +The following +.LI type +characters may be used: +.SS +.SP + +If +.LI count1 +is specified, place the line +.LI count1 +at the top of the screen. +Otherwise, display the screen after the current screen, similarly to the +.CO <control-F> +command. +.SP <carriage-return> +Place the line +.LI count1 +at the top of the screen. +.SP \&. +Place the line +.LI count1 +in the center of the screen. +.SP \- +Place the line +.LI count1 +at the bottom of the screen. +.SP ^ +If +.LI count1 +is specified, place the line that is at the top of the screen +when +.LI count1 +is at the bottom of the screen, at the bottom of the screen, +i.e. display the screen before the screen before +.LI count1 . +Otherwise, display the screen before the current screen, similarly to the +.CO <control-B> +command. +.SE +.SS +.SP Line: +Set to +.LI count1 +unless +.LI count1 +is not specified and the +.LI type +character was either +.QT ^ +or +.QT + , +in which case it is set to the line before the first line on the +previous screen or the line after the last line on the previous +screen, respectively. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY { +.IP "[count] {" +Move backward +.LI count +paragraphs. +.sp +The +.CO { +command is an absolute movement. +The +.CO { +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting character is the first +character on its line, in which case it is line oriented. +.SS +.SP Line: +Set to the line containing the beginning of the previous paragraph. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP paragraph +option. +.SE +.KY | +.IP "[count] |" +Move to a specific +.i column +position on the current line. +.sp +The +.CO | +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +It is an error to use the +.CO | +command as a motion component and for the cursor not to move. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character occupying the column position identified by +.LI count , +if the position exists in the line. +If the column length of the current line is less than +.LI count , +the cursor is moved to the last character in the line. +.SP Options: +None. +.SE +.KY } +.IP "[count] }" +Move forward +.LI count +paragraphs. +.sp +The +.CO } +command is an absolute movement. +The +.CO } +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting character is at or +before any nonblank characters in its line, +in which case it is line oriented. +.SS +.SP Line: +Set to the line containing the beginning of the next paragraph. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP paragraph +option. +.SE +.KY ~ +.IP "[count] ~" +Reverse the case of the next +.LI count +character(s). +This is the historic semantic for the +.CO ~ +command and it is only in effect if the +.OP tildeop +option is not set. +.sp +Lowercase alphabetic characters are changed to uppercase, +and uppercase characters are changed to lowercase. +No other characters are affected. +.sp +Historically, the +.CO ~ +command did not take an associated count, nor did it move past the +end of the current line. +As it had no associated motion it was difficult to change the case +of large blocks of text. +In +.CO nvi , +if the cursor is on the last character of a line, and there are +more lines in the file, the cursor moves to the next line. +.sp +It is not an error to specify a count larger than the number of +characters between the cursor and the end of the file. +.SS +.SP Line: +Set to the line of the character after +.LI count +characters, or, end of file. +.SP Column: +Set to the character after +.LI count +characters, or, end-of-file. +.SP Options: +Affected by the +.OP tildeop +option. +.SE +.KY ~ +.IP "[count] ~ motion" +Reverse the case of the characters in a text region specified by the +.LI count +and +.LI motion . +Only in effect if the +.OP tildeop +option is set. +.sp +Lowercase characters are changed to uppercase, +and uppercase characters are changed to lowercase. +No other characters are affected. +.SS +.SP Line: +Set to the line of the character after the last character in the region. +.SP Column: +Set to the character after the last character in the region. +.SP Options: +Affected by the +.OP tildeop +option. +.SE +.KY <interrupt> +.IP "<interrupt>" +Interrupt the current operation. +Many of the potentially long-running +.CO vi +commands may be interrupted using the terminal interrupt character. +These operations include searches, file reading and writing, filter +operations and map character expansion. +Interrupts are also enabled when running commands outside of +.CO vi . +.sp +If the +.LI <interrupt> +character is used to interrupt while entering an +.CO ex +command, the command is aborted, the cursor returns to its previous +position, and +.CO vi +remains in command mode. +.sp +Generally, if the +.LI <interrupt> +character is used to interrupt any +operation, any changes made before the interrupt are left in place. +.SS +.SP Line: +Dependent on the operation being interrupted. +.SP Column: +Dependent on the operation being interrupted. +.SP Options: +None. +.SH 1 "Vi Text Input Commands" +.pp +The following section describes the commands available in the text +input mode of the +.CO vi +editor. +.pp +Historically, +.CO vi +implementations only permitted the characters inserted on the current +line to be erased. +In addition, only the +.LI <control-D> +erase character and the +.QT 0<control-D> +and +.QT ^<control-D> +erase strings could erase autoindent characters. +(Autoindent characters include both the characters inserted automatically +at the beginning of an input line as well as characters inserted using the +.LI <control-T> +command.) +This implementation permits erasure to continue past the beginning +of the current line, and back to where text input mode was entered. +In addition, autoindent characters may be erased using the standard +erase characters. +For the line and word erase characters, reaching the autoindent +characters forms a +.QQ soft +boundary, denoting the end of the current word or line erase. +Repeating the word or line erase key will erase the autoindent characters. +.pp +Historically, +.CO vi +always used +.LI <control-H> +and +.LI <control-W> +as character and word erase characters, respectively, regardless of +the current terminal settings. +This implementation accepts, in addition to these two characters, +the current terminal characters for those operations. +.KY <nul> +.IP "<nul>" +If the first character of the input is a +.LI <nul> , +the previous input is replayed, as if just entered. +.KY <control-D> +.IP "<control-D>" +If the previous character on the line was an autoindent character, +erase characters to move the cursor back to the column immediately +after the previous (1-based) column which is a multiple of the +.OP shiftwidth +edit option. +This may result in any number of +.LI <tab> +and +.LI <space> +characters preceding the cursor being changed. +.sp +Otherwise, if the +.OP autoindent +option is set and the user is entering the first character in the line, +.LI <control-D> +is ignored. +Otherwise, a literal +.LI <control-D> +character is entered. +.KY ^<control-D> +.IP "^<control-D>" +If the previous character on the line was an autoindent character, +erase all of the autoindent characters on the line. +In addition, the autoindent level is reset to 0. +.KY 0<control-D> +.IP "0<control-D>" +If the previous character on the line was an autoindent character, +erase all of the autoindent characters on the line. +The autoindent level is not altered. +.KY <control-T> +.IP "<control-T>" +Insert sufficient +.LI <tab> +and +.LI <space> +characters to move the cursor forward to the column immediately +after the next (1-based) column which is a multiple of the +.OP shiftwidth +edit option. +This may result in any number of +.LI <tab> +and +.LI <space> +characters preceding the cursor being changed. +.sp +Historically, +.CO vi +did not permit the +.LI <control-T> +command to be used unless the cursor was at the first column of a new +line or it was preceded only by autoindent characters. +.CO Nvi +permits it to be used at any time during insert mode. +.KY <erase> +.IP <erase> +.KY <control-H> +.Ip <control-H> +Erase the last character. +.KY "<literal-next>" +.IP "<literal-next>" +Quote the next character. +The next character will not be mapped (see the +.CO map +command for more information) +or interpreted specially. +A carat +.PQ ^ +character will be displayed immediately as a placeholder, +but will be replaced by the next character. +.KY <escape> +.IP <escape> +If on the colon command line, and the +.OP filec +edit option is set, behave as described for that option. +Otherwise, if on the colon command line, +execute the command. +Otherwise, if not on the colon command line, +resolve all text input into the file, and return to command mode. +.KY "<line erase>" +.IP "<line erase>" +Erase the current line. +.KY "<control-W>" +.IP "<control-W>" +.KY "<word erase>" +.Ip "<word erase>" +Erase the last word. +The definition of word is dependent on the +.OP altwerase +and +.OP ttywerase +options. +.KY "<control-X>" +.IP "<control-X>[0-9A-Fa-f]+" +Insert a character with the specified hexadecimal value into the text. +The value is delimited by any non-hexadecimal character or the input +of the maximum number of characters that can be translated into a single +character value. +.KY <interrupt> +.IP "<interrupt>" +Interrupt text input mode, returning to command mode. +If the +.LI <interrupt> +character is used to interrupt inserting text into the file, +it is as if the +.LI <escape> +character was used; all text input up to the interruption is +resolved into the file. diff --git a/share/doc/usd/13.viref/vi.ref b/share/doc/usd/13.viref/vi.ref new file mode 100644 index 000000000000..91a7332ba81f --- /dev/null +++ b/share/doc/usd/13.viref/vi.ref @@ -0,0 +1,1836 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" This document may not be republished without written permission from +.\" Keith Bostic. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.so ref.so +.tp +.(l C +.ps 12 +.ft B +Vi/Ex Reference Manual +.ft +.ps +.sp +.i "Keith Bostic" +.sp +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, California 94720 +.sp 1 +.)l +.sp 3 +.(l C +.i Abstract +.)l +.(q +.pp +This document is the reference guide for the 4.4BSD +implementations of +.EV nex nvi , +which are implementations of the historic Berkeley +.EV ex vi +editors. +.)q +.sp 3 +.(l C +.i Licensing +.)l +.sp +.lp +Copyright (c) 1991, 1992, 1993, 1994 +.ti +5 +The Regents of the University of California. All Rights Reserved. +.lp +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996 +.ti +5 +Keith Bostic. All Rights Reserved. +.sp +.pp +The vi program is freely redistributable. You are welcome to copy, +modify and share it with others under the conditions listed in the +LICENSE file. If any company (not individual!) finds vi sufficiently +useful that you would have purchased it, or if any company wishes to +redistribute it, contributions to the authors would be appreciated. +.bp 2 +.(l C +.i Acknowledgements +.)l +.sp +.(q +.pp +Bruce Englar encouraged the early development of the historic +.EV ex vi +editor. +Peter Kessler helped bring sanity to version 2's command layout. +Bill Joy wrote versions 1 and 2.0 through 2.7, +and created the framework that users see in the present editor. +Mark Horton added macros and other features and made +.EV ex vi +work on a large number of terminals and Unix systems. +.pp +.CO Nvi +is originally derived from software contributed to the University of +California, Berkeley by Steve Kirkendall, the author of the +.CO vi +clone +.CO elvis . +.pp +IEEE Standard Portable Operating System Interface for Computer +Environments (POSIX) 1003.2 style Regular Expression support was +done by Henry Spencer. +.pp +The curses library was originally done by Ken Arnold. +Scrolling and reworking for +.CO nvi +was done by Elan Amir. +.pp +George Neville-Neil added the Tcl interpreter, +and Sven Verdoolaege added the Perl interpreter. +.pp +Rob Mayoff added Cscope support. +.pp +The Institute of Electrical and Electronics Engineers has +given us permission to reprint portions of their documentation. +Portions of this document are reprinted and reproduced from +IEEE Std 1003.2-1992, IEEE Standard Portable Operating +System Interface for Computer Environments (POSIX), +copyright 1992 by the Institute of Electrical and Electronics +Engineers, Inc. +.pp +The financial support of UUNET Communications Services is gratefully +acknowledged. +.)q +.sy echo -n >index +.oh 'Vi/Ex Reference''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference' +.bp 4 +.SH 1 Description +.pp +.CO Vi +is a screen oriented text editor. +.CO Ex +is a line-oriented text editor. +.CO Ex +and +.CO vi +are different interfaces to the same program, +and it is possible to switch back and forth during an edit session. +.CO View +is the equivalent of using the +.b \-R +(read-only) option of +.CO vi . +.pp +This reference manual is the one provided with the +.EV nex nvi +versions of the +.EV ex vi +text editors. +.EV Nex nvi +are intended as bug-for-bug compatible replacements for the original +Fourth Berkeley Software Distribution (4BSD) +.EV ex vi +programs. +This reference manual is accompanied by a traditional-style manual page. +That manual page describes the functionality found in +.EV ex vi +in far less detail than the description here. +In addition, it describes the system interface to +.EV ex vi , +e.g. command line options, session recovery, signals, +environmental variables, and similar things. +.pp +This reference is intended for users already familiar with +.EV ex vi . +Anyone else should almost certainly read a good tutorial on the +editor first. +If you are in an unfamiliar environment, +and you absolutely have to get work done immediately, +see the section entitled +.QB "Fast Startup" +in the manual page. +It is probably enough to get you started. +.pp +There are a few features in +.EV nex nvi +that are not found in historic versions of +.EV ex vi . +Some of the more interesting of those features are briefly described +in the next section, entitled +.QB "Additional Features" . +For the rest of this document, +.EV nex nvi +is used only when it is necessary to distinguish it from the historic +implementations of +.EV ex vi . +.pp +Future versions of this software will be periodically made available +by anonymous ftp, and can be retrieved from +.LI ftp.cs.berkeley.edu , +in the directory +.LI ucb/4bsd . +.SH 1 "Additional Features in Nex/Nvi" +.pp +There are a few features in +.EV nex nvi +that are not found in historic versions of +.EV ex vi . +Some of the more interesting of these are as follows: +.IP "8-bit clean data, large lines, files" +.EV Nex nvi +will edit any format file. +Line lengths are limited by available memory, +and file sizes are limited by available disk space. +The +.CO vi +text input mode command +.CO <control-X> +can insert any possible character value into the text. +.IP "Background and foreground screens" +The +.CO bg +command backgrounds the current screen, and the +.CO fg +command foregrounds backgrounded screens. +The +.CO display +command can be used to list the background screens. +.IP "Command Editing" +You can enter a normal editing window on the collected commands that +you've entered on the +.CO vi +colon command-line, +and then modify and/or execute the commands. +See the +.OP cedit +edit option for more information. +.IP "Displays" +The +.CO display +command can be used to display the current buffers, the backgrounded +screens, and the tags stack. +.IP "Extended Regular Expressions" +The +.CO extended +option causes Regular Expressions to be interpreted as as Extended +Regular Expressions, (i.e. \fIegrep\fP(1) style Regular Expressions). +.IP "File Name Completion" +It is possible to do file name completion and file name displays when +entering commands on the +.CO vi +colon command-line. +See the +.OP filec +option for more information. +.IP "Infinite undo" +Changes made during an edit session may be rolled backward and forward. +A +.CO \&. +command immediately after a +.CO u +command continues either forward or backward depending on whether the +.CO u +command was an undo or a redo. +.IP "Left-right scrolling" +The +.CO leftright +option causes +.CO nvi +to do left-right screen scrolling, instead of the traditional +.CO vi +line wrapping. +.IP "Message Catalogs" +It is possible to display informational and error messages in different +languages by providing a catalog of messages. +See the +.OP msgcat +option and the file +.LI "catalog/README" +for more information. +.IP "Incrementing numbers" +The +.CO \&# +command increments or decrements the number referenced by the cursor. +.IP "Previous file" +The +.CO previous +command edits the previous file from the argument list. +.IP "Scripting languages" +The +.CO ":pe[rl] cmd" , +.CO ":perld[o] cmd" +and +.CO ":tc[l] cmd" +commands execute Perl and Tcl/Tk commands, respectively, +on lines from the edit buffer. +See the +.QB "Scripting Languages" +section and the specific commands for more information. +.\".IP "Shell screens" +.\"The +.\".CO ":sc[ript] [file ...]" +.\"command runs a shell in the screen. +.\"Editing is unchanged, with the exception that a \fC<carriage-return>\fP +.\"enters the current line (stripped of any prompt) as input to the +.\"shell. +.IP "Split screens" +The +.CO Edit , +.CO Ex , +.CO Next , +.CO Previous , +.CO Tag +and +.CO Visual +(in +.CO vi +mode) commands divide the screen into multiple editing regions and +then perform their normal function in a new screen area. +The +.CO <control-W> +command rotates between the foreground screens. +The +.CO resize +command can be used to grow or shrink a particular screen. +.IP "Tag stacks" +Tags are now maintained in a stack. +The +.CO <control-T> +command returns to the previous tag location. +The +.CO tagpop +command returns to the most recent tag location by default, or, +optionally to a specific tag number in the tag stack, +or the most recent tag from a specified file. +The +.CO display +command can be used to list the tags stack. +The +.CO tagtop +command returns to the top of the tag stack. +.IP "Usage information" +The +.CO exusage +and +.CO viusage +commands provide usage information for all of the +.CO ex +and +.CO vi +commands by default, or, optionally, for a specific command or key. +.IP "Word search" +The +.CO <control-A> +command searches for the word referenced by the cursor. +.SH 1 "Startup Information" +.pp +.EV Ex vi +interprets one of two possible environmental variables and reads up to +three of five possible files during startup. +The variables and files are expected to contain +.CO ex +commands, not +.CO vi +commands. +In addition, they are interpreted +.i before +the file to be edited is read, and therefore many +.CO ex +commands may not be used. +Generally, any command that requires output to the screen or that +needs a file upon which to operate, will cause an error if included +in a startup file or environmental variable. +.pp +Because the +.CO ex +command set supported by +.EV nex nvi +is a superset of the command set supported by historical implementations of +.CO ex , +.EV nex nvi +can use the startup files created for the historical implementations, +but the converse may not be true. +.pp +If the +.b \-s +(the historic \- option) +is specified, or if standard input is redirected from a file, +all environmental variables and startup files are ignored. +.pp +Otherwise, startup files and environmental variables are handled +in the following order: +.np +The file +.LI /etc/vi.exrc +is read, +as long as it is owned by root or the effective user ID of the user. +.np +The environmental variable +.LI NEXINIT +(or the variable +.LI EXINIT , +if +.LI NEXINIT +is not set) is interpreted. +.np +If neither +.LI NEXINIT +or +.LI EXINIT +was set, and the +.LI HOME +environmental variable is set, the file +.LI $HOME/.nexrc +(or the file +.LI $HOME/.exrc , +if +.LI $HOME/.nexrc +does not exist) is read, +as long as the effective user ID of the user is root or is the same as +the owner of the file. +.sp +When the $HOME directory is being used for both +.EV nex nvi +and an historic implementation of +.EV ex vi , +a possible solution is to put +.EV nex nvi +specific commands in the +.LI \&.nexrc +file, along with a +.CO ":source $HOME/.exrc" +command to read in the commands common to both implementations. +.np +If the +.OP exrc +option was turned on by one of the previous startup information +sources, the file +.LI \&.nexrc +(or the file +.LI \&.exrc , +if +.LI \&.nexrc +does not exist) is read, as long as the effective user ID of the user +is the same as the owner of the file. +.pp +No startup file is read if it is writable by anyone other than its owner. +.pp +It is not an error for any of the startup environmental variables or files +not to exist. +.pp +Once all environmental variables are interpreted, +and all startup files are read, +the first file to be edited is read in (or a temporary file is created). +Then, any commands specified using the +.b \-c +option are executed, in the context of that file. +.SH 1 "Recovery" +.pp +There is no recovery program for +.EV nex nvi , +nor does +.EV nex nvi +run setuid. +Recovery files are created readable and writable by the owner only. +Users may recover any file which they can read, +and the superuser may recover any edit session. +.pp +Edit sessions are backed by files in the directory named by the +.OP recdir +option (the directory +.LI /var/tmp/vi.recover +by default), and are named +.QC vi.XXXXXX , +where +.QC XXXXXX +is a number related to the process ID. +When a file is first modified, +a second recovery file containing an email message for the user is created, +and is named +.QC recover.XXXXXX , +where, again, +.QC XXXXXX +is associated with the process ID. +Both files are removed at the end of a normal edit session, +but will remain if the edit session is abnormally terminated +or the user runs the +.CO ex +.CO preserve +command. +.pp +The +.OP recdir +option may be set in either the user's or system's startup information, +changing the recovery directory. +(Note, however, that if a memory based file system is used as the backup +directory, each system reboot will delete all of the recovery files! +The same caution applies to directories such as +.LI /tmp +which are cleared of their contents by a system reboot, or +.LI /usr/tmp +which is periodically cleared of old files on many systems.) +.pp +The recovery directory should be owned by root, or at least by a pseudo-user. +In addition, if directory +.QQ sticky-bit +semantics are available, the directory should have the sticky-bit +set so that files may only be removed by their owners. +The recovery directory must be read, write, and executable by any user, +i.e. mode 1777. +.pp +If the recovery directory does not exist, +.EV ex vi +will attempt to create it. +This can result in the recovery directory being owned by a normal user, +which means that that user will be able to remove other user's recovery +and backup files. +This is annoying, but is not a security issue as the user cannot +otherwise access or modify the files. +.pp +The recovery file has all of the necessary information in it to enable the +user to recover the edit session. +In addition, it has all of the necessary email headers for +.XR sendmail 8 . +When the system is rebooted, all of the files in +.LI /var/tmp/vi.recover +named +.QC recover.XXXXXX +should be sent to their owners, by email, using the +.b \-t +option of +.CO sendmail +(or a similar mechanism in other mailers). +If +.EV ex vi +receives a hangup (SIGHUP) signal, or the user executes the +.CO ex +.CO preserve +command, +.EV ex vi +will automatically email the recovery information to the user. +.pp +If your system does not have the +.CO sendmail +utility (or a mailer program which supports its interface) +the source file +.LI nvi/common/recover.c +will have to be modified to use your local mail delivery programs. +Note, if +.EV nex nvi +is changed to use another mailer, +it is important to remember that the owner of the file given to +the mailer is the +.EV nex nvi +user, so nothing in the file should be trusted as it may have been +modified in an effort to compromise the system. +.pp +Finally, the owner execute bit is set on backup files when they are +created, and unset when they are first modified, e.g. backup files +that have no associated email recovery file will have this bit set. +(There is also a small window where empty files can be created and +not yet have this bit set. +This is due to the method in which the files are created.) +Such files should be deleted when the system reboots. +.pp +A simple way to do this cleanup is to run the Bourne shell script +.CO recover , +from your +.LI /etc/rc.local +(or other system startup) file. +The script should work with the historic Bourne shell, +a POSIX 1003.2 shell or the Korn shell. +The +.CO recover +script is installed as part of the +.EV nex nvi +installation process. +.pp +Consult the manual page for details on recovering preserved or +aborted editing sessions. +.SH 1 "Sizing the Screen" +.pp +The size of the screen can be set in a number of ways. +.EV Ex vi +takes the following steps until values are obtained for both the +number of rows and number of columns in the screen. +.np +If the environmental variable +.LI LINES +exists, +it is used to specify the number of rows in the screen. +.np +If the environmental variable +.LI COLUMNS +exists, +it is used to specify the number of columns in the screen. +.np +The TIOCGWINSZ +.XR ioctl 2 +is attempted on the standard error file descriptor. +.np +The termcap entry (or terminfo entry on System V machines) +is checked for the +.QQ li +entry (rows) and the +.QQ co +entry (columns). +.np +The number of rows is set to 24, and the number of columns is set to 80. +.pp +If a window change size signal (SIGWINCH) is received, +the new window size is retrieved using the TIOCGWINSZ +.XR ioctl 2 +call, and all other information is ignored. +.SH 1 "Character Display" +.pp +In both +.CO ex +and +.CO vi +printable characters as defined by +.XR isprint 3 +are displayed using the local character set. +.pp +Non-printable characters, for which +.XR iscntrl 3 +returns true, and which are less than octal \e040, +are displayed as the string +.QT ^<character> , +where +.LI <character> +is the character that is the original character's value offset from the +.QT @ +character. +For example, the octal character \e001 is displayed as +.QT ^A . +If +.XR iscntrl 3 +returns true for the octal character \e177, +it is displayed as the string +.QT ^? . +All other characters are displayed as either hexadecimal values, +in the form +.QT "0x<high-halfbyte> ... 0x<low-halfbyte>" , +or as octal values, in the form +.QT "\e<high-one-or-two-bits> ... \e<low-three-bits>" . +The display of unknown characters is based on the value of the +.OP octal +option. +.pp +In +.CO vi +command mode, the cursor is always positioned on the last column of +characters which take up more than one column on the screen. +In +.CO vi +text input mode, the cursor is positioned on the first column of +characters which take up more than one column on the screen. +.SH 1 "Multiple Screens" +.pp +.CO Nvi +supports multiple screens by dividing the window into regions. +It also supports stacks of screens by permitting the user to change +the set of screens that are currently displayed. +.pp +The +.CO Edit , +.CO Ex , +.CO Fg , +.CO Next , +.CO Previous , +.CO Tag +and +.CO Visual +(in +.CO vi +mode) +commands divide the current screen into two regions of approximately +equal size and then perform their usual action in a new screen area. +If the cursor is in the lower half of the screen, the screen will split +up, i.e. the new screen will be above the old one. +If the cursor is in the upper half of the screen, the new screen will be +below the old one. +.pp +When more than one screen is editing a file, changes in any screen are +reflected in all other screens editing the same file. +Exiting a screen without saving any changes (or explicitly discarding +them) is permitted until the last screen editing the file is exited, +at which time the changes must be saved or discarded. +.pp +The +.CO resize +command permits resizing of individual screens. +Screens may be grown, shrunk or set to an absolute number of rows. +.pp +The +.CO ^W +command is used to switch between screens. +Each +.CO ^W +moves to the next lower screen in the window, or to the first screen +in the window if there are no lower screens. +.pp +The +.CO bg +command +.QQ backgrounds +the current screen. +The screen disappears from the window, +and the rows it occupied are taken over by a neighboring screen. +It is an error to attempt to background the only screen in the window. +.pp +The +.CO "display screens" +command displays the names of the files associated with the current +backgrounded screens in the window. +.pp +The +.CO "fg [file]" +command moves the specified screen from the list of backgrounded screens +to the foreground. +If no file argument is specified, the first screen on the list is +foregrounded. +By default, +foregrounding consists of backgrounding the current screen, +and replacing its space in the window with the foregrounded screen. +.pp +Capitalizing the first letter of the command, i.e. +.CO Fg , +will foreground the backgrounded screen in a new screen instead of +swapping it with the current screen. +.pp +If the last foregrounded screen in the window is exited, +and there are backgrounded screens, +the first screen on the list of backgrounded screens takes over the window. +.SH 1 "Tags, Tag Stacks, and Cscope" +.pp +.CO Nvi +supports the historic +.CO vi +tag command +.CO <control-]> , +and the historic +.CO ex +tag command +.CO tag . +These commands change the current file context to a new location, +based on information found in the +.LI tags +files. +If you are unfamiliar with these commands, +you should review their description in the +.CO ex +and +.CO vi +commands section of this manual. +For additional information on tags files, +see the discussion of the +.OP tags +edit option and the system +.XR ctags 1 +manual page. +.pp +In addition, +.CO nvi +supports the notion of +.QQ "tags stacks" , +using the +.CO <control-T> +command. +The +.CO <control-T> +command returns the user to the previous context, i.e., +the last place from which a +.CO <control-]> +or +.CO "tag" +command was entered. +These three commands provide the basic functionality which allows you +to use +.CO vi +to review source code in a structured manner. +.pp +.CO Nvi +also provides two other basic +.CO ex +commands for tag support: +.CO tagpop +and +.CO tagtop . +The +.CO tagpop +command is identical to the +.CO <control-T> +command, +with the additional functionality that you may specify that modifications +to the current file are to be discarded. +This cannot be done using the +.CO <control-T> +command. +The +.CO tagtop +command discards all of the contexts that have been pushed onto the tag +stack, returning to the context from which the first +.CO <control-]> +or +.CO tag +command was entered. +.pp +The historic +.XR ctags 1 +tags file format supports only a single location per tag, +normally the function declaration or structure or string definition. +More sophisticated source code tools often provide multiple locations +per tag, e.g., +a list of the places from which a function is called or a string +definition is used. +An example of this functionality is the System V source code tool, +.CO cscope . +.sp +.CO Cscope +creates a database of information on source code files, +and supports a query language for that information as described in the +.XR cscope 1 +manual page. +.CO Nvi +contains an interface to the +.CO cscope +query language which permits you to query +.CO cscope +and then sequentially step through the locations in the sources files which +.CO cscope +returns. +There are two +.CO nvi +commands which support this ability to step through multiple locations. +They are the +.CO ex +commands +.CO tagnext +and +.CO tagprev . +The +.CO tagnext +command moves to the next location for the current tag. +The +.CO tagprev +command moves to the previous location for the current tag. +(See the +.CO tagnext +and +.CO tagprev +command discussion in the +.CO ex +commands section of this manual for more information.) +At any time during this sequential walk, +you may use the +.CO <control-]> , +.CO tag +or +.CO cscope +commands to move to a new tag context, and then use the +.CO <control-T> +or +.CO tagpop +commands to return and continue stepping through the locations for this +tag. +This is similar to the previous model of a simple tag stack, +except that each entry in the tag stack may have more than one file context +that is of interest. +.pp +Although there is no widely distributed version of +.XR ctags 1 +that creates tags files with multiple locations per tag, +.CO nvi +has been written to understand the obvious extension to the historic +tags file format, i.e., more than a single line in the tags file with +the same initial tag name. +If you wish to extend your +.CO ctags +implementation or other tool with which you build tags files, +this extension should be simple and will require no changes to +.CO nvi . +.pp +The +.CO nvi +and +.CO cscope +interface is based on the new +.CO ex +command +.CO cscope , +which has five subcommands: +.CO add , +.CO find , +.CO help , +.CO kill +and +.CO reset . +The subcommand +.CO find +itself has eight subcommands: +.CO \&c , +.CO \&d , +.CO \&e , +.CO \&f , +.CO \&g , +.CO \&i , +.CO \&s +and +.CO \&t . +.pp +.IP "cs[cope] a[dd] file" +The +.CO add +command attaches to the specified +.CO cscope +database. +The file name is expanded using the standard filename expansions. +If +.CO file +is a directory, the file +.QQ cscope.out +in that directory is used as the database. +.pp +After +.CO nvi +attaches to a new database, +all subsequent +.CO cscope +queries will be asked of that database. +The result of any single query is the collection of response to the query +from all of the attached databases. +.sp +If the +.QQ CSCOPE_DIRS +environmental variable is set when +.CO nvi +is run, +it is expected to be a <colon> or <blank>-separated list of +.CO cscope +databases or directories containing +.CO cscope +databases, to which the user wishes to attach. +.IP ":cs[cope] f[ind] c|d|e|f|g|i|s|t buffer|pattern" +The +.CO find +command is the +.CO cscope +query command for +.CO nvi . +For this command, +.CO nvi +queries all attached +.CO cscope +databases for the pattern. +If the pattern is a double-quote character followed by a valid buffer +name (e.g., +.LI """<character>" ), +then the contents of the named buffer are used as the pattern. +Otherwise, the pattern is a Regular Expression. +.sp +The +.CO find +command pushes the current location onto the tags stack, +and switches to the first location resulting from the query, +if the query returned at least one result. +.sp +File names returned by the +.CO cscope +query, if not absolute paths, are searched for relative to the directory +where the +.CO cscope +database is located. +In addition, if the file +.QQ cscope.tpath +appears in the same directory as the +.CO cscope +database, +it is expected to contain a colon-separated list of directory names +where files referenced by its associated +.CO cscope +database may be found. +.sp +The +.CO find +subcommand is one of the following: +.SS +.SP \&c +Find callers of the name. +.SP \&d +Find all function calls made from name. +.SP \&e +Find pattern. +.SP \&f +Find files with name as substring. +.SP \&g +Find definition of name. +.SP \&i +Find files #including name. +.SP \&s +Find all uses of name. +.SP \&t +Find assignments to name. +.SE +.IP ":cs[cope] h[elp] [command]" +List the +.CO cscope +commands, +or optionally list usage help for any single +.CO cscope +command. +.IP ":display c[onnections]" +Display the list of +.CO cscope +databases to which +.CO nvi +is currently connected. +.IP ":cs[cope] k[ill] #" +Disconnect from a specific +.CO cscope +database. +The connection number is the one displayed by the +.CO ex +.CO "display connections" +command. +.IP ":cs[cope] r[eset]" +Disconnect from all attached +.CO cscope +databases. +.pp +Cscope is not freely redistributable software, +but is fairly inexpensive and easily available. +To purchase a copy of +.CO cscope , +see http://www.att.com/ssg/products/toolchest.html. +.SH 1 "Regular Expressions and Replacement Strings" +.pp +Regular expressions are used in line addresses, +as the first part of the +.CO ex +.CO substitute , +.CO global , +and +.CO v +commands, and in search patterns. +.pp +The regular expressions supported by +.EV ex vi +are, by default, the Basic Regular Expressions (BRE's) described in the +IEEE POSIX Standard 1003.2. +The +.OP extended +option causes all regular expressions to be interpreted as the Extended +Regular Expressions (ERE's) described by the same standard. +(See +.XR re_format 7 +for more information.) +Generally speaking, BRE's are the Regular Expressions found in +.XR ed 1 +and +.XR grep 1 , +and ERE's are the Regular Expressions found in +.XR egrep 1 . +.pp +The following is not intended to provide a description of Regular +Expressions. +The information here only describes strings and characters which +have special meanings in the +.EV ex vi +version of RE's, +or options which change the meanings of characters that normally +have special meanings in RE's. +.np +An empty RE (e.g. +.QT // +or +.QT ?? +is equivalent to the last RE used. +.np +The construct +.QT \e< +matches the beginning of a word. +.np +The construct +.QT \e> +matches the end of a word. +.np +The character +.QT ~ +matches the replacement part of the last +.CO substitute +command. +.pp +When the +.OP magic +option is +.i not +set, the only characters with special meanings are a +.QT ^ +character at the beginning of an RE, a +.QT $ +character at the end of an RE, and the escaping character +.QT \e . +The characters +.QT \&. , +.QT * , +.QT [ +and +.QT ~ +are treated as ordinary characters unless preceded by a +.QT \e ; +when preceded by a +.QT \e +they regain their special meaning. +.pp +Replacement strings are the second part of a +.CO substitute +command. +.pp +The character +.QT & +(or +.QT \e& +if the +.OP magic +option is +.i not +set) in the replacement string stands for the text matched by the RE +that is being replaced. +The character +.QT ~ +(or +.QT \e~ +if the +.OP magic +option is +.i not +set) stands for the replacement part of the previous +.CO substitute +command. +It is only valid after a +.CO substitute +command has been performed. +.pp +The string +.QT \e# , +where +.QT # +is an integer value from 1 to 9, stands for the text matched by +the portion of the RE enclosed in the +.QT # 'th +set of escaped parentheses, e.g. +.QT \e( +and +.QT \e) . +For example, +.QT "s/abc\e(.*\e)def/\e1/" +deletes the strings +.QT abc +and +.QT def +from the matched pattern. +.pp +The strings +.QT \el , +.QT \eu , +.QT \eL +and +.QT \eU +can be used to modify the case of elements in the replacement string. +The string +.QT \el +causes the next character to be converted to lowercase; +the string +.QT \eu +behaves similarly, but converts to uppercase +(e.g. +.LI s/abc/\eU&/ +replaces the string +.LI abc +with +.LI ABC ). +The string +.QT \eL +causes characters up to the end of the string or the next occurrence +of the strings +.QT \ee +or +.QT \eE +to be converted to lowercase; +the string +.QT \eU +behaves similarly, but converts to uppercase. +.pp +If the entire replacement pattern is +.QT % , +then the last replacement pattern is used again. +.pp +In +.CO vi , +inserting a +.LI <control-M> +into the replacement string will cause +the matched line to be split into two lines at that point. +(The +.LI <control-M> +will be discarded.) +.SH 1 "Scripting Languages" +.pp +The +.CO nvi +editor currently supports two scripting languages, Tcl/Tk and Perl. +(Note that Perl4 isn't sufficient, and that the Perl5 used must be +version 5.002 or later. +See the +.QB "Building Nvi" +section for more information. +.pp +The scripting language interface is still being worked on, +therefore the following information is probably incomplete, +probably wrong in cases, and likely to change. +See the +.LI perl_api +and +.LI tcl_api +source directories for more information. +As a quick reference, the following function calls are provided for +both the Perl and Tcl interfaces. +The Perl interface uses a slightly different naming convention, +e.g. ``viFindScreen'' is named ``VI::FindScreen''. +.IP "viFindScreen file" +Return the +.LI "screenId" associated with +.LI file . +.IP "viAppendLine screenId lineNumber text" +Append +.LI text +as a new line after line number +.LI lineNumber , +in the screen +.LI screenId . +.IP "viDelLine screenId lineNum" +Delete the line +.LI lineNumber +from the screen +.LI screenId . +.IP "viGetLine screenId lineNumber" +Return the line +.LI lineNumber +from the screen +.LI screenId . +.IP "viInsertLine screenId lineNumber text" +Insert +.LI text +as a new line before line number +.LI lineNumber +in the screen +.LI screenId . +.IP "viLastLine screenId" +Return the line number of the last line in the screen +.LI screenId . +.IP "viSetLine screenId lineNumber text" +Change the line +.LI lineNumber +in the screen +.LI screenId +to match the specified +.LI text . +.IP "viGetMark screenId mark" +Return the current line and column for the specified +.LI mark +from the screen +.LI screenId . +.IP "viSetMark screenId mark line column" +Set the specified +.LI mark +to be at line +.LI line , +column +.LI column , +in the screen +.LI screenId . +.IP "viGetCursor screenId" +Return the current line and column for the cursor in the screen +.LI screenId . +.IP "viSetCursor screenId line column" +Set the cursor in the screen +.LI screenId +to the specified +.LI line +and +.LI column . +.IP "viMsg screenId text" +Display the specified +.LI text +as a vi message in the screen +.LI screenId . +.IP "viNewScreen screenId [file]" +Create a new screen. +.IP "viEndScreen screenId" +Exit the screen +.LI screenId . +.IP "viSwitchScreen screenId screenId" +Switch from the screen +.LI screenId +to the screen +.LI screenId . +.IP "viMapKey screenId key tclproc" +Map the specified +.LI key +in the screen +.LI screenId +to the Tcl procedure +.LI tclproc . +.IP "viUnmMapKey screenId key" +Unmap the specified +.LI key +in the screen +.LI screenId +.IP "viGetOpt screenId option" +Return the value of the specified +.LI option +from the screen +.LI screenId . +.IP "viSetOpt screenId command" +Set one or more options in the screen +.LI screenId . +.SH 1 "General Editor Description" +.pp +When +.CO ex +or +.CO vi +are executed, +the text of a file is read (or a temporary file is created), +and then all editing changes happen within the context of the +copy of the file. +.i "No changes affect the actual file until the file is written out" , +either using a write command or another command which is affected by the +.OP autowrite +option. +.pp +All files are locked (using the +.XR flock 2 +or +.XR fcntl 2 +interfaces) during the edit session, +to avoid inadvertently making modifications to multiple copies of the file. +If a lock cannot be obtained for a file because it is locked by another +process, the edit session is read-only (as if the +.OP readonly +option or the +.b \-R +flag had been specified). +If a lock cannot be obtained for other reasons, the edit session will +continue, but the file status information +(see the +.CO <control-G> +command) will reflect this fact. +.pp +Both +.CO ex +and +.CO vi +are modeful editors, i.e. they have two modes, +.QQ command +mode and +.QQ "text input" +mode. +The former is intended to permit you to enter commands which modifies +already existing text. +The latter is intended to permit you to enter new text. +When +.CO ex +first starts running, it is in command mode, and usually displays a prompt +(see the +.OP prompt +option for more information). +The prompt is a single colon +.PQ : +character. +There are three commands that switch +.CO ex +into text input mode: +.CO append , +.CO change +and +.CO insert . +Once in input mode, entering a line containing only a single period +.PQ \&. +ends text input mode and returns to command mode, +where the prompt is redisplayed. +.pp +When +.CO vi +first starts running, it is in command mode as well. +There are eleven commands that switch +.CO vi +into text input mode: +.CO A , +.CO a , +.CO C , +.CO c , +.CO I , +.CO i , +.CO O , +.CO o , +.CO R , +.CO S +and +.CO s . +Once in input mode, entering an +.LI <escape> +character ends text input mode and returns to command mode. +.pp +.EV Ex vi +present three different interfaces to editing a file. +.CO Ex +presents a line oriented interface. +.CO Vi +presents a full screen display oriented interface, +also known as +.QQ "visual mode" . +In addition, there is a third mode, +.QQ "open mode" , +which is line oriented, +but supports cursor movement and editing within the displayed line, +similarly to visual mode. +Open mode is not yet implemented in +.CO nvi . +.pp +The following words have special meanings in both the +.CO ex +and +.CO vi +command descriptions: +.KY <interrupt> +.IP <interrupt> +The interrupt character is used to interrupt the current operation. +Normally +.LI <control-C> , +whatever character is set for the current terminal is used. +.KY "<literal-next>" +.IP "<literal-next>" +The literal next character is used to escape the subsequent character +from any special meaning. +This character is always +.LI <control-V> . +If the terminal is not set up to do XON/XOFF flow control, +then +.LI <control-Q> +is used to mean literal next as well. +.KY "current pathname" +.IP "current pathname" +The pathname of the file currently being edited by vi. +When the percent character +.PQ % +appears in a file name entered as part of an +.CO ex +command argument, it is replaced by the current pathname. +(The +.QT % +character can be escaped by preceding it with a backslash.) +.KY "alternate pathname" +.IP "alternate pathname" +The name of the last file name mentioned in an +.CO ex +command, or, +the previous current pathname if the last file mentioned +becomes the current file. +When the hash mark character +.PQ # +appears in a file name entered as part of an +.CO ex +command argument, it is replaced by the alternate pathname. +(The +.QT # +character can be escaped by preceding it with a backslash.) +.KY buffer +.IP buffer +One of a number of named areas for saving copies of text. +Commands that change or delete text can save the changed or deleted +text into a specific buffer, for later use, if the command allows +it (i.e. the +.CO ex +.CO change +command cannot save the changed text in a named buffer). +Buffers are named with a single character, preceded by a double quote, +e.g. +.LI """<character>" +in +.CO vi +and +without the double quote, e.g. +.LI <character> , +in +.CO ex . +(The double quote isn't necessary for +.CO ex +because buffers names are denoted by their position in the command line.) +Historic implementations of +.EV ex vi +limited +.LI <character> +to the alphanumeric characters; +.EV nex nvi +permits the use of any character without another meaning in the position +where a buffer name is expected. +.sp +Buffers named by uppercase characters are the same as buffers +named by lowercase characters, e.g. the buffer named by the +English character +.QT A +is the same as the buffer named by the character +.QT a , +with the exception that, if the buffer contents are being changed (as +with a text deletion or +.CO vi +.CO change +command), the text is +.i appended +to the buffer, instead of replacing the current contents. +.sp +The buffers named by the numeric characters (in English, +.QT 1 +through +.QT 9 ), +are special. +If a region of text including characters from more than one line, +or a single line of text specified by using a line-oriented motion, +is changed or deleted in the file using the +.CO vi +.CO change +or +.CO delete +commands, a copy of the text is placed into the numeric buffer +.QT 1 , +regardless of the user specifying another buffer in which to save it. +In addition, there are a few commands which, when used as a +.LI motion +with the +.CO vi +.CO change +and +.CO delete +commands, +.i always +copy the specified region of text into the numeric buffers regardless +of the region including characters from more than one line. +These commands are: +.sp +.ne 3v +.ft C +.TS +r r r r. +<control-A> % ( ) +`<character> / ? N +n { } +.TE +.ft R +.sp +Before this copy is done, the previous contents of buffer +.QT 1 +are moved into buffer +.QT 2 , +.QT 2 +into buffer +.QT 3 , +and so on. +The contents of buffer +.QT 9 +are discarded. +In +.CO vi , +text may be explicitly stored into the numeric buffers. +In this case, the buffer rotation described above occurs before the +replacement of the buffer's contents. +The numeric buffers are only available in +.LI visual +and +.LI open +modes, +and are not accessible by +.CO ex +in any way, although changed and deleted text is still stored there +while in +.CO ex +mode. +.sp +When a +.CO vi +command synopsis shows both a +.LI [buffer] +and a +.LI [count] , +they may be presented in any order. +.sp +Finally, all buffers are either +.QQ line +or +.QQ character +oriented. +All +.CO ex +commands which store text into buffers are line oriented. +Some +.CO vi +commands which store text into buffers are line oriented, +and some are character oriented; the description for each applicable +.CO vi +command notes whether text copied into buffers using the command +is line or character oriented. +In addition, the +.CO vi +command +.CO "display buffers" +displays the current orientation for each buffer. +Generally, the only importance attached to this orientation is that +if the buffer is subsequently inserted into the text, line oriented +buffers create new lines for each of the lines they contain, and +character oriented buffers create new lines for any lines +.i other +than the first and last lines they contain. +The first and last lines are inserted into the text at the current +cursor position, becoming part of the current line. +If there is more than one line in the buffer, however, the current +line itself will be split. +.KY "unnamed buffer" +.IP "unnamed buffer" +The unnamed buffer is a text storage area which is used by commands +that use or operate on a buffer when no buffer is specified by the user. +If the command stores text into a buffer, +the text is stored into the unnamed buffer even if a buffer is also +specified by the user. +It is not possible to append text to the unnamed buffer. +If text is appended to a named buffer, +the named buffer contains both the old and new text, +while the unnamed buffer contains only the new text. +There is no way to explicitly reference the unnamed buffer. +.sp +Historically, the contents of the unnamed buffer were discarded by many +different commands, even ones that didn't store text into it. +.EV Nex nvi +never discards the contents of the unnamed buffer until new text +replaces them. +.KY whitespace +.IP whitespace +The characters <tab> and <space>. +.KY "<carriage-return>" +.IP "<carriage-return>" +The character represented by an ASCII +.LI <control-M> . +This character is almost always treated identically to a +.LI <newline> +character, but differs in that it can be escaped into the file text or +into a command. +.KY <newline> +.IP <newline> +The character represented by an ASCII +.LI <control-J> . +This character is almost always treated identically to a +.LI <control-M> +character, but differs in that it cannot be escaped into the file text or +into a command. +.oh 'Vi/Ex Reference (Vi Commands)''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference (Vi Commands)' +.so vi.cmd.roff +.oh 'Vi/Ex Reference''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference' +.SH 1 "Ex Addressing" +.pp +Addressing in +.CO ex +(and when +.CO ex +commands are executed from +.CO vi ) +relates to the current line. +In general, the current line is the last line affected by a command. +The exact effect on the current line is discussed under the description +of each command. +When the file contains no lines, the current line is zero. +.pp +Addresses are constructed by one or more of the following methods: +.np +The address +.QT \&. +refers to the current line. +.np +The address +.QT $ +refers to the last line of the file. +.np +The address +.QT N , +where +.LI N +is a positive number, refers to the N-th line of the file. +.np +The address +.QT '<character> +or +.QT `<character> +refers to the line marked with the name +.LI <character> . +(See the +.CO k +or +.CO m +commands for more information on how to mark lines.) +.np +A regular expression (RE) enclosed by slashes +.PQ / +is an address, +and it refers to the first line found by searching forward from the line +.i after +the current line toward the end of the file, and stopping at the +first line containing a string matching the RE. +(The trailing slash can be omitted at the end of the command line.) +.sp +If no RE is specified, i.e. the pattern is +.QT // , +the last RE used in any command is used in the search. +.sp +If the +.OP extended +option is set, the RE is handled as an extended RE, not a basic RE. +If the +.OP wrapscan +option is set, the search wraps around to the beginning of the file +and continues up to and including the current line, so that the entire +file is searched. +.sp +The form +.QT \e/ +is accepted for historic reasons, +and is identical to +.QT // . +.np +An RE enclosed in question marks +.PQ ? +addresses the first line found by searching backward from the line +.i preceding +the current line, toward the beginning of the file and stopping at the +first line containing a string matching the RE. +(The trailing question mark can be omitted at the end of a command line.) +.sp +If no RE is specified, i.e. the pattern is +.QT ?? , +the last RE used in any command is used in the search. +.sp +If the +.OP extended +option is set, the RE is handled as an extended RE, not a basic RE. +If the +.OP wrapscan +option is set, the search wraps around from the beginning of the file to +the end of the file and continues up to and including the current line, +so that the entire file is searched. +.sp +The form +.QT \e? +is accepted for historic reasons, and is identical to +.QT ?? . +.np +An address followed by a plus sign +.PQ + +or a minus sign +.PQ - +followed by a number is an offset address and refers to the address +plus (or minus) the indicated number of lines. +If the address is omitted, the addition or subtraction is done with +respect to the current line. +.np +An address of +.QT + +or +.QT \- +followed by a number is an offset from the current line. +For example, +.QT \-5 +is the same as +.QT \&.\-5 . +.np +An address ending with +.QT + +or +.QT - +has 1 added to or subtracted from the address, respectively. +As a consequence of this rule and of the previous rule, the address +.QT \- +refers to the line preceding the current line. +Moreover, trailing +.QT + +and +.QT \- +characters have a cumulative effect. +For example, +.QT ++\-++ +refers to the current line plus 3. +.np +A percent sign +.PQ % +is equivalent to the address range +.QT 1,$ . +.pp +.CO Ex +commands require zero, one, or two addresses. +It is an error to specify an address to a command which requires zero +addresses. +.pp +If the user provides more than the expected number of addresses to any +.CO ex +command, the first addresses specified are discarded. +For example, +.QT 1,2,3,5 print +prints lines 3 through 5, because the +.CO print +command only takes two addresses. +.pp +The addresses in a range are separated from each other by a comma +.PQ , +or a semicolon +.PQ ; . +In the latter case, the current line +.PQ \&. +is set to the first address, and only then is the second address calculated. +This feature can be used to determine the starting line for forward and +backward searches (see rules (5) and (6) above). +The second address of any two-address sequence corresponds to a line that +follows, in the file, the line corresponding to the first address. +The first address must be less than or equal to the second address. +The first address must be greater than or equal to the first line of the +file, and the last address must be less than or equal to the last line +of the file. +.oh 'Vi/Ex Reference (Ex Commands)''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference (Ex Commands)' +.so ex.cmd.roff +.oh 'Vi/Ex Reference (Options)''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference (Options)' +.so set.opt.roff +.oh 'Vi/Ex Reference''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference' +.bp +.SH 1 Index +.lp +.2c +0.5i 3 +.ta \n($luR +.nf +.so index.so +.fi +.\" Force the TOC to an odd page, in case it's a duplex printer. +.if o .bp +.bp 3 +.1c +.ce 1 +\fB\s+2Table of Contents\s0\fP +.sp +.xp diff --git a/share/doc/usd/18.msdiffs/Makefile b/share/doc/usd/18.msdiffs/Makefile new file mode 100644 index 000000000000..1945542dc282 --- /dev/null +++ b/share/doc/usd/18.msdiffs/Makefile @@ -0,0 +1,5 @@ +VOLUME= usd/18.msdiffs +SRCS= ms.diffs +MACROS= -ms + +.include <bsd.doc.mk> diff --git a/share/doc/usd/18.msdiffs/ms.diffs b/share/doc/usd/18.msdiffs/ms.diffs new file mode 100644 index 000000000000..986937a37c07 --- /dev/null +++ b/share/doc/usd/18.msdiffs/ms.diffs @@ -0,0 +1,281 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.nr LL 6.5i +.nr FL 6.0i +.if t .nr PD .5v +.if t .ds m \u\(ul\dm +.if n .ds m -m +.AM +.OH 'A Revised Version of \*ms''USD:18-%' +.EH 'USD:18-%''A Revised Version of \*ms' +.ND +.TL +A Revised Version of \*ms +.AU +Bill Tuthill +.AI +Computing Services +University of California +Berkeley, CA 94720 +.PP +The \*ms macros have been slightly revised and re\%arranged for the +Berkeley Unix distribution. +Because of the rearrangement, +the new macros can be read by the computer +in about half the time required by the previous version of \*ms. +This means that output will begin to appear between ten seconds +and several minutes more quickly, depending on the system load. +On long files, however, the savings in total time are not substantial. +The old version of \*ms is still available as \*mos. +.PP +Several bugs in \*ms have been fixed, including +a bad problem with the .1C macro, +minor difficulties with boxed text, +a break induced by .EQ before initialization, +the failure to set tab stops in displays, +and several bothersome errors in the \fBrefer\fP macros. +Macros used only at Bell Laboratories have been removed. +There are a few extensions to previous \*ms macros, +and a number of new macros, but all the documented \*ms macros +still work exactly as they did before, and have the same names as before. +Output produced with \*ms should look like output produced with \*mos. +.PP +One important new feature is automatically numbered footnotes. +Footnote numbers are printed by means of a pre-defined string +(\e\(**\(**), which you invoke separately from .FS and .FE. +Each time it is used, this string increases the footnote number by one, +whether or not you use .FS and .FE in your text. +Footnote numbers will be superscripted on the phototypesetter +and on daisy-wheel terminals, but on low-resolution devices +(such as the lpr and a crt), they will be bracketed. +If you use \e\(**\(** to indicate numbered footnotes, +then the .FS macro will automatically include +the footnote number at the bottom of the page. +This footnote, for example, was produced as follows:\** +.DS +This footnote, for example, was produced as follows:\e\(**\(** +\&.FS +.sp -.2 + ... +\&.FE +.DE +.FS +If you never use the ``\e\(**\(**'' string, +no footnote numbers will appear anywhere in the text, +including down here. +The output footnotes will look exactly like +footnotes produced with \*mos. +.FE +If you are using \e\(**\(** to number footnotes, +but want a particular footnote to be marked with an asterisk or a dagger, +then give that mark as the first argument to .FS: \(dg +.DS +then give that mark as the first argument to .FS: \e(dg +\&.FS \e(dg +.sp -.2 + ... +\&.FE +.DE +.FS \(dg +In the footnote, the dagger will appear where the footnote +number would otherwise appear, as on the left. +.FE +Footnote numbering will be temporarily suspended, +because the \e\(**\(** string is not used. +Instead of a dagger, you could use an asterisk * +or double dagger \(dd, represented as \|\e(dd. +.PP +Another new feature is a macro for printing theses +according to Berkeley standards. +This macro is called .TM, which stands for thesis mode. +(It is much like the .th macro in \*me.) +It will put page numbers in the upper right-hand corner; +number the first page; suppress the date; +and doublespace everything except quotes, displays, and keeps. +Use it at the top of each file making up your thesis. +Calling .TM defines the .CT macro for chapter titles, +which skips to a new page and moves the pagenumber to the center footer. +The .P1 (P one) macro can be used even without thesis mode +to print the header on page 1, +which is suppressed except in thesis mode. +If you want roman numeral page numbering, +use an ``.af\0PN\0i'' request. +.PP +There is a new macro especially for bibliography entries, +called .XP, which stands for exdented paragraph. +It will exdent the first line of the paragraph by \en(PI units, +usually 5n (the same as the indent for the first line of a .PP). +Most bibliographies are printed this way. +Here are some examples of exdented paragraphs: +.XP +Lumley, Lyle S., \fISex in Crustaceans: Shell Fish Habits,\fP\| +Harbinger Press, Tampa Bay and San Diego, October 1979. +243 pages. +The pioneering work in this field. +.XP +Leffadinger, Harry A., ``Mollusk Mating Season: 52 Weeks, or All Year?'' +in \fIActa Biologica,\fP\| vol. 42, no. 11, November 1980. +A provocative thesis, but the conclusions are wrong. +.LP +Of course, you will have to take care of +italicizing the book title and journal, +and quoting the title of the journal article. +Indentation or exdentation can be changed +by setting the value of number register PI. +.PP +If you need to produce endnotes rather than footnotes, +put the references in a file of their own. +This is similar to what you would do if you were +typing the paper on a conventional typewriter. +Note that you can use automatic footnote numbering +without actually having .FS and .FE pairs in your text. +If you place footnotes in a separate file, +you can use .IP macros with \e\(**\(**\| as a hanging tag; +this will give you numbers at the left-hand margin. +With some styles of endnotes, +you would want to use .PP rather then .IP macros, +and specify \e\(**\(** before the reference begins. +.PP +There are four new macros to help produce a table of contents. +Table of contents entries must be enclosed in .XS and .XE pairs, +with optional .XA macros for additional entries; +arguments to .XS and .XA specify the page number, +to be printed at the right. +A final .PX macro prints out the table of contents. +Here is a sample of typical input and output text: +.DS +\&.XS ii +Introduction +\&.XA 1 +Chapter 1: Review of the Literature +\&.XA 23 +Chapter 2: Experimental Evidence +\&.XE +\&.PX +.sp .5 +.lt 5.5i +.tl ''\fBTable of Contents\fP'' +.ta 5i 5.5iR +.sp +Introduction ii\| +Chapter 1: Review of the Literature 1 +Chapter 2: Experimental Evidence 23 +.sp .5 +.DE +The .XS and .XE pairs may also be used in the text, +after a section header for instance, +in which case page numbers are supplied automatically. +However, most documents that require a table of contents +are too long to produce in one run, +which is necessary if this method is to work. +It is recommended that you do a table of contents +after finishing your document. +To print out the table of contents, use the .PX macro; +if you forget it, nothing will happen. +.PP +As an aid in producing text that will format correctly +with both \fBnroff\fP and \fBtroff\fP, +there are some new string definitions that define quotation marks +and dashes for each of these two formatting programs. +The \e\(**\^\u_\d string will yield two hyphens in \fBnroff\fP, +but in \fBtroff\fP it will produce an em dash\*- +like this one. +The \e\(**Q and \e\(**U strings will produce +`` and '' in \fBtroff\fP, but " in \fBnroff\fP. +(In typesetting, the double quote is traditionally considered bad form.) +.PP +There are now a large number of optional +foreign accent marks defined by the \*ms macros. +All the accent marks available in \*mos are present, +and they all work just as they always did. +However, there are better definitions available +by placing .AM at the beginning of your document. +Unlike the \*mos accent marks, +the accent strings should come \fIafter\fP\| the letter being accented. +Here is a list of the diacritical marks, +with examples of what they look like. +.DS +.ta 2i 3i +name of accent input output +\l'3.5i' +acute accent e\e\(**\' e\*' +grave accent e\e\(**\` e\*` +circumflex o\e\(**\d^\u o\*^ +cedilla c\e\(**, c\*, +tilde n\e\(**\d~\u n\*~ +question \e\(**? \*? +exclamation \e\(**! \*! +umlaut u\e\(**: u\*: +digraph s \e\(**8 \*8 +hac\*vek c\e\(**v c\*v +macron a\e\(**_ a\*_ +underdot s\e\(**. s\*. +o-slash o\e\(**/ o\*/ +angstrom a\e\(**o a\*o +yogh kni\e\(**3t kni\*3t +Thorn \e\(**(Th \*(Th +thorn \e\(**(th \*(th +Eth \e\(**(D- \*(D- +eth \e\(**(d- \*(d- +hooked o \e\(**q \*q +ae ligature \e\(**(ae \*(ae +AE ligature \e\(**(Ae \*(Ae +oe ligature \e\(**(oe \*(oe +OE ligature \e\(**(Oe \*(Oe +.DE +If you want to use these new diacritical marks, +don't forget the .AM at the top of your file. +Without it, some will not print at all, +and others will be placed on the wrong letter. +.PP +It is also possible to produce custom headers and footers +that are different on even and odd pages. +The .OH and .EH macros define odd and even headers, +while .OF and .EF define odd and even footers. +Arguments to these four macros are specified as with .tl. +This document was produced with: +.DS +\&.OH \'\ef\^IThe -mx Macros\'\'Page %\ef\^P\' +\&.EH \'\ef\^IPage %\'\'The -mx Macros\ef\^P\' +.DE +Note that it would be an error to have an apostrophe in the header text; +if you need one, you will have to use a different delimiter +around the left, center, and right portions of the title. +You can use any character as a delimiter, provided it doesn't appear +elsewhere in the argument to .OH, .EH, .OF, or EF. +.PP +The \*ms macros work in conjunction with +the \fBtbl\fR, \fBeqn\fR, and \fBrefer\fR preprocessors. +Macros to deal with these items are read in only as needed, +as are the thesis macros (.TM), +the special accent mark definitions (.AM), +table of contents macros (.XS and .XE), +and macros to format the optional cover page. +The code for the \*ms package lives in /usr/lib/tmac/tmac.s, +and sourced files reside in the directory /usr/ucb/lib/ms. +.sp diff --git a/share/doc/usd/19.memacros/Makefile b/share/doc/usd/19.memacros/Makefile new file mode 100644 index 000000000000..547eb25bd817 --- /dev/null +++ b/share/doc/usd/19.memacros/Makefile @@ -0,0 +1,15 @@ +VOLUME= usd/19.memacros +SRCS= meintro.me-sed +MACROS= -me +GROFFDIR= ${SRCTOP}/contrib/groff +SRCDIR= ${GROFFDIR}/doc + +version=`cat ${GROFFDIR}/VERSION` +revision=`sed -e 's/^0$$//' -e 's/^[1-9].*$$/.&/' ${GROFFDIR}/REVISION` + +meintro.me-sed: meintro.me + sed -e "s;@VERSION@;$(version)$(revision);" ${.ALLSRC} > ${.TARGET} + +CLEANFILES= ${SRCS} + +.include <bsd.doc.mk> diff --git a/share/doc/usd/20.meref/Makefile b/share/doc/usd/20.meref/Makefile new file mode 100644 index 000000000000..a0d7fe6cb2e4 --- /dev/null +++ b/share/doc/usd/20.meref/Makefile @@ -0,0 +1,15 @@ +VOLUME= usd/20.meref +SRCS= meref.me-sed +MACROS= -me +GROFFDIR= ${SRCTOP}/contrib/groff +SRCDIR= ${GROFFDIR}/doc + +version=`cat ${GROFFDIR}/VERSION` +revision=`sed -e 's/^0$$//' -e 's/^[1-9].*$$/.&/' ${GROFFDIR}/REVISION` + +meref.me-sed: meref.me + sed -e "s;@VERSION@;$(version)$(revision);" ${.ALLSRC} > ${.TARGET} + +CLEANFILES= ${SRCS} + +.include <bsd.doc.mk> diff --git a/share/doc/usd/21.troff/Makefile b/share/doc/usd/21.troff/Makefile new file mode 100644 index 000000000000..d2b140dc44bc --- /dev/null +++ b/share/doc/usd/21.troff/Makefile @@ -0,0 +1,5 @@ +VOLUME= usd/21.troff +SRCS= m.mac m0 m0a m1 m2 m3 m4 m5 table1 table2 +USE_TBL= + +.include <bsd.doc.mk> diff --git a/share/doc/usd/21.troff/m.mac b/share/doc/usd/21.troff/m.mac new file mode 100644 index 000000000000..16c4f2769362 --- /dev/null +++ b/share/doc/usd/21.troff/m.mac @@ -0,0 +1,284 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.if \n(mo=1 .ds mo January +.if \n(mo=2 .ds mo February +.if \n(mo=3 .ds mo March +.if \n(mo=4 .ds mo April +.if \n(mo=5 .ds mo May +.if \n(mo=6 .ds mo June +.if \n(mo=7 .ds mo July +.if \n(mo=8 .ds mo August +.if \n(mo=9 .ds mo September +.if \n(mo=10 .ds mo October +.if \n(mo=11 .ds mo November +.if \n(mo=12 .ds mo December +.if \n(dw=1 .ds dw Sunday +.if \n(dw=2 .ds dw Monday +.if \n(dw=3 .ds dw Tuesday +.if \n(dw=4 .ds dw Wednesday +.if \n(dw=5 .ds dw Thursday +.if \n(dw=6 .ds dw Friday +.if \n(dw=7 .ds dw Saturday +.\" +.bd S B 3 +.ds NR "\s-1NROFF\s+1 +.ds TR "\s-1TROFF\s+1 +.ds Nr "N\s-2ROFF\s+2 +.ds Tr "T\s-2ROFF\s+2 +.nr PS 10 +.hy 14 +.ds u \v'-0.3m'\s-2 +.ds d \s0\v'0.3m' +.nr 2C 0 +.ds H +.nr a .8i +.nr b 1.6i +.nr c 2.4i +.nr d 2.9i +.nr e 0.25i +.nr p 0 1 +.nr s 0 1 +.af p 1 +.af s 1 +.nr m -1i +.nr x 0 1 +.nr y 0+\nmu +.ev 1 +.ps \n(PS-2 +.vs \n(PS +.ll 6.5i +'in 0 +.ev +.tr &. +.de xx +.sp 0.4 +.. +.de ht +.tl `\*(Nr/\*(Tr User's Manual``USD:21-%` +.\" .tl 'updated to May 15, 1977'''\".tl 'Version \n(mo/\n(dy/\n(yr''' +.. +.de he +.tl `USD:21-%``\*(Nr/\*(Tr User's Manual` +.\" .tl 'updated to May 15, 1977'''\".tl 'Version \n(mo/\n(dy/\n(yr''' +.. +.de hd +.\".tl '\(rn''' +.if \\n%>1 \{'sp |.30i +.if e .he +.if o .ht +.ps \\n(S2 +.ps \\n(S1 +.ft +'sp |.9i\} +.nr x 0 1 +.nr y 0+\\nmu +.ch fo \\nmu +.if \\n(dn .fz +.ns +.if dmx .mx +.nr cl 0 1 +.mk +.. +.de fz +.fn +.nf +.fy +.fi +.ef +.. +.de fx +.if \\nx .di fy +.. +.de fo +.if dcx .cx +.nr dn 0 +.if \\nx .xf +.nr x 0 \"disable fx +.ie \\n(2C&(\\n+(cl<2) \{\ +.po +3.4i +.rt +.nr y 0+\\nmu +.ch fo \\nmu +.if \\n(dn .fz +.ns \} +.el \{\ +.po 26i/27u +.nr S1 \\n(.s +.ps +.nr S2 \\n(.s +.ps 10 +'bp +.\} +.. +.de 2C +.br +.mk +.nr 2C 1 +.ll 3.1i +.ev 1 +.ll 3.1i +.ev +.. +.de 1C +.br +.nr 2C 0 +.ll 6.5i +.ev 1 +.ll 6.5i +.ev +.. +.de co +.de cx +.br +\fI(Continued next page.)\fP +.br +.rm cx +\\.. +.. +.de pp +'ps \\n(PS +.ft R +.\"'tl ''- % -'' +'bp +.. +.wh 0 hd +.wh 12i fo +.wh \nmu fx +.ch fo \nmu +.de fn +.da FN +.ev 1 +.if \\n+x=1 .fs +.fi +.ti 0 +.. +.de xf +.ev 1 +.nf +.FN +.rm FN +.di +.ev +.. +.de fs +.ti 0 +\l'1i' +.br +.. +.de ef +.br +.ev +.di +.nr y -\\n(dn +.if \\nx=1 .nr y -2p +.ch fo \\nyu +.if \\n(nl+\\n(.v-\\n(.p-\\ny .ch fo \\n(nlu+\\n(.vu +.. +.wh -.6i pp +.de h1 +.xx +.ne 5 +.nf +.ta \\nau \\nbu \\ncu \\ndu +\\neu +.ft I +.bd I 3 +Request Initial If No +Form Value\\$2 Argument Notes\\$1 Explanation +.bd I +.ft R +.ft +.fi +.in \\ndu +.. +.de bt +.ft R +.xx +.ne 1.1 +.ti 0 +.. +.de b1 +.br +.ti 0 +.. +.de pg +.ft R +.fi +.in 0 +.xx +.ne 1.1 +.. +.de sc +.pg +\fI\\*H\\np.\\n+s.\|\\c +.ft R +.ul +.. +.de mh +.nr s 0 +.in 0 +.xx +.ne 2.5 +.ft B +\\*H\\n+p. +.. +.de x1 +.xx +.in .5i +.nf +.. +.de x2 +.xx +.in 0 +.fi +.. +.de EM +.br +\&\c +.pl 2i +.. +.em EM +.de TS +.sp +.. +.de TE +.sp +.ce 0 +.ft R +.ps \n(PS +.ta \\nau \\nbu \\ncu \\ndu +\\neu +.. +.de T& +.. diff --git a/share/doc/usd/21.troff/m0 b/share/doc/usd/21.troff/m0 new file mode 100644 index 000000000000..82f5483df395 --- /dev/null +++ b/share/doc/usd/21.troff/m0 @@ -0,0 +1,286 @@ +.\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode! +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.br +.rs +.sp |1.0i +.ce 1000 +.ps 12 +.ft B +\*(Nr\(sl\*(Tr User's Manual +.sp .2i +.ft I +.ps 10 +Joseph F. Ossanna +(updated for 4.3BSD by Mark Seiden) +.ft R +.sp +Bell Laboratories +Murray Hill, New Jersey 07974 +.ce 0 +.sp 2 +.ps \n(PS +.fi +.ft B +.ps +1 +NOTE: This document in its current form describes the \fItroff\fP\| program +supplied with 4.4BSD. The \fIgroff\fP\| program supplied with FreeBSD has a +number of additional features and a couple of small incompatibilities. See +\fIgroff(1)\fP\| for more details. +.ps +.sp 1 +Introduction +.pg +\*(NR and \*(TR are text processors under +the \s-1UNIX\s+1 Time-Sharing System +that format text for typewriter-like terminals and +for a \%Graphic Systems phototypesetter, respectively. +(Device-independent \*(TR, part of the Documenter's Workbench, +supports additional output devices.) +They accept lines of text interspersed with lines of +format control information and +format the text into a printable, paginated document +having a user-designed style. +\*(NR and \*(TR offer +unusual freedom in document styling, +including: +arbitrary style headers and footers; +arbitrary style footnotes; +multiple automatic sequence numbering for paragraphs, sections, etc; +multiple column output; +dynamic font and point-size control; +arbitrary horizontal and vertical local motions at any point; +and +a family of automatic overstriking, bracket construction, and +line drawing functions. +.pg +\*(NR and \*(TR are highly compatible with each other and it is almost always +possible to prepare input acceptable to both. +Conditional input is provided that enables +the user to embed input expressly destined for either program. +\*(NR can prepare output directly for a variety of terminal types and +is capable of utilizing the full resolution of each terminal. +.pg +.ft B +Usage +.pg +The general form of invoking \*(NR (or \*(TR) at \s-1UNIX\s+1 command level is +.x1 +\fBnroff \fIoptions files\fR\ +\h'|2i'(or \fBtroff \fIoptions files\fR) +.x2 +where \fIoptions\fR represents any of a number of option arguments +and \fIfiles\fR represents the list of files containing the document +to be formatted. +An argument consisting of a single minus (\fB\-\fR) is taken to be +a file name corresponding to the standard input. +If no file names are given input is taken from the standard input. +The options, which may appear in any order so long as they appear +before the files, are: +.sp +.ta .2i 1.0i +.ft I +.bd I 3 + Option Effect +.br +.bd I +.ft R +.ta .3i 1.0i +.in 1.0i +.ll -.3i +.bt + \fB\-i\fP Read standard input after the input files are exhausted. +.bt + \fB\-m\fIname\fR Prepends the macro file +\fB\(slusr\(sllib\(sltmac.\fIname\fR +to the input \fIfiles\fR. +.bt + \fB\-n\fIN\fR Number first generated page \fIN\fR. +.bt + \fB\-o\fIlist\fR \ +Print only pages whose page numbers appear in \fIlist\fR, +which consists of comma-separated numbers and number ranges. +A number range has the form \fIN\-M\fR +and means pages \fIN\fR through \fIM;\fR +a initial \fI\-N\fR means +from the beginning to page \fIN;\fR and a final \fIN\-\fR means +from \fIN\fR to the end. +.bt + \fB\-q\fR \ +Invoke the simultaneous input-output mode of the \fBrd\fR request. +.bt + \fB\-r\fIaN\fR Number register \fIa\fR (one-character) is set to \fIN\fR. +.bt + \fB\-s\fIN\fR Stop every \fIN\fR pages. +\*(NR will halt prior to every \fIN\fR pages (default \fIN\fR=1) +to allow paper loading or +changing, and will resume upon receipt of a newline. +\*(TR will stop the phototypesetter every \fIN\fR pages, +produce a trailer to allow changing cassettes, +and will resume after the phototypesetter \s-1START\s+1 button is pressed. +.bt + \fB\-z\fR Efficiently suppress formatted output. +Only produce output to standard error (from \fBtm\fP requests or +diagnostics). +.sp +.ne 5 +.ft I +.bd I 3 + \*(NR Only +.br +.bd I +.ft +.bt + \fB\-T\fIname\fR Specifies +the name of the output terminal type. +Currently defined names are \fB37\fR for the (default) Model 37 Teletype\(rg, +\fBtn300\fR for the GE TermiNet\ 300 (or any terminal without half-line +capabilities), +\fB300S\fR for the \s-1DASI\s+1-300S, +\fB300\fR for the \s-1DASI\s+1-300, +and +\fB450\fR for the \s-1DASI\s+1-450 (Diablo Hyterm). +.bt + \fB\-e\fR \ +Produce equally-spaced words in adjusted +lines, using full terminal resolution. +.bt + \fB\-h\fR \ +On output, use tabs during horizontal spacing to increase speed. +Device tabs setting are assumed to be (and input tabs are initially +set to) every 8 character widths. +.sp +.ne 3 +.ft I +.bd I 3 + \*(TR Only +.br +.bd I +.ft +.bt + \fB\-a\fP Send a printable \s-1(ASCII)\s+1 approximation +of the results to the standard output. +.bt + \fB\-b\fR \*(TR will report whether the phototypesetter +is busy or available. +No text processing is done. +.bt + \fB\-f\fP Refrain from feeding out paper and stopping +phototypesetter at the end of the run. +.bt + \fB\-t\fP Direct output to the standard output instead +of the phototypesetter. +.bt + \fB\-w\fP Wait until phototypesetter is available, if +currently busy. +.ll +.in 0 +.xx +.pg +Each option is invoked as a separate argument; +for example, +.x1 +\fBnroff \-o\fI4,8\-10 \fB\-T\fI300S \fB\-m\fIabc file1 file2\fR +.x2 +requests formatting of pages 4, 8, 9, and 10 of a document contained in the files +named \fIfile1\fR and \fIfile2\fR, +specifies the output terminal as a \s-1DASI\s+1-300S, +and invokes the macro package \fIabc\fR. +.pg +Various pre- and post-processors are available for use with \*(NR and \*(TR. +These include the equation preprocessors \s-1NEQN\s+1 and \s-1EQN\s+1\*u1\*d +(for \*(NR and \*(TR respectively), +and the table-construction preprocessor \s-1TBL\s+1\*u2\*d. +A reverse-line postprocessor \s-1COL\s+1\*u3\*d +is available for multiple-column \*(NR output on terminals without reverse-line ability; +\s-1COL\s+1 expects the Model 37 Teletype +escape sequences that \*(NR produces by default. +\s-1TK\s+1\*u3\*d +is a 37 Teletype simulator postprocessor for printing \*(NR output on a Tektronix 4014. +\s-1TC\s+1\*u5\*d +is a phototypesetter-simulator postprocessor +for \*(TR that produces an approximation of phototypesetter output +on a Tektronix 4014. +For example, in +.x1 +\fBtbl \fIfiles \fB| eqn | troff \-t \fIoptions \fB| tc\fR +.x2 +the first \|\fB|\fR\| indicates the piping of \s-1TBL\s+1's output to \s-1EQN\s+1's input; +the second the piping of \s-1EQN\s+1's output to \*(TR's input; +and the third indicates the piping of \*(TR's output to \s-1TC\s+1. +.br +.pg +The remainder of this manual consists of: +a Summary and outline; +a Reference Manual keyed to the outline; +and +a set of Tutorial Examples. +Another tutorial is [5]. +.sp .4 +.ps -1 +.vs -1p +.pg +.ft B +References +.pg +.ta .3i +.in .3i +.ti 0 +[1] B. W. Kernighan, L. L. Cherry, +.ul +Typesetting Mathematics \(em User's Guide (Second Edition), +Bell Laboratories. +.sp .4 +.ti 0 +[2] M. E. Lesk, +.ul +Tbl \(em A Program to Format Tables, +Bell Laboratories internal memorandum. +.sp .4 +.ti 0 +[3] Internal on-line documentation (\fIman\fP pages) on \s-1UNIX\s+1. +.sp .4 +.ti 0 +[4] B. W. Kernighan, \fIA TROFF Tutorial\fR, +Bell Laboratories. +.sp .4 +.ti 0 +[5] Your site may have similar programs for more modern displays. +.in 0 +.ps 10 +.vs 12 +.ft R +.bp diff --git a/share/doc/usd/21.troff/m0a b/share/doc/usd/21.troff/m0a new file mode 100644 index 000000000000..b1ec4b8a63f7 --- /dev/null +++ b/share/doc/usd/21.troff/m0a @@ -0,0 +1,604 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.br +.tr | +.ce +.ft B +SUMMARY OF REQUESTS AND OUTLINE OF THIS MANUAL +.ft R +.de mx +.ev 2 +.nf +.h1 +.in +.sp +.fi +.ev +.ns +.. +.xx +.h1 \s-1#\s+1 * +.fn +.sp .3 +*Values separated by "\fB;\fR" are for \*(NR and \*(TR respectively. +.sp .2 +\s-1#\s+1Notes are explained at the end of this Summary and Index +.ef +.mh +General Explanation +.mh +Font and Character Size Control +.bt +\fB&ps\fI\|\(+-N\fR 10\|point previous E Point size; also \fB\es\fI\(+-N\fR.\(dg +.b1 +\fB&fz\fI|F|\(+-N\fR off - E font \fIF\fR to point size \fI\(+-N\fR. +.b1 +\fB&fz|S|\fIF|\(+-N\fR off - E Special Font characters to point size \fI\(+-N\fR. +.b1 +\fB&ss\fI|N\fR 12\(sl36\|em ignored E Space-character size +set to \fIN\fR\(sl36\|em.\(dg +.b1 +\fB&cs\fI|F\|N\|M\fR off - P Constant character +space (width) +mode (font \fIF\^\fR\^).\(dg +.b1 +\fB&bd\fI|F|N\fR off - P Embolden font \fIF\fR by \fIN\fR\(mi1 units.\(dg +.b1 +\fB&bd|S|\fIF|N\fR off - P Embolden Special Font when current font is \fIF\fR.\(dg +.fn +.sp .2 +\(dgNo effect in \*(NR. +.ef +.b1 +\fB&ft\fI|F\fR Roman previous E Change to font +\fIF\fR|= \fIx\fR, \fIxx\fR, or 1-4. +Also \fB\ef\fIx\fR,\|\fB\ef(\fIxx\fR,\|\fB\ef\fIN\fR. +.b1 +\fB&fp\fI|N|F\fR R,I,B,S ignored - Font named \fIF\fR mounted on physical position 1\(<=\fIN\fR\(<=4. +.mh +Page Control +.bt +\fB&pl\fI|\(+-N\fR 11\|in 11\|in \fBv\fR Page length. +.b1 +\fB&bp|\fI\(+-N\fR \fIN\(eq\fR1 - B\(dd,\fBv\fR \ +Eject current page; next page number \fIN\fR. +.fn +.sp .2 +\(ddThe use of "\ \fB\'\fR\ " as control character (instead of "\fB.\fR") +suppresses the break function. +.ef +.b1 +\fB&pn\fI|\(+-N N\(eq\fR1 ignored - Next page number \fIN\fR. +.b1 +\fB&po\fI|\(+-N\fR 0;|26\(sl27\|in previous \fBv\fR Page offset. +.b1 +\fB&ne\fI|N\fR - \fIN\(eq\fR1\fIV\fR D,\fBv\fR Need \fIN\fR vertical space (\fIV\fR = vertical spacing). +.b1 +\fB&mk|\fIR\fR none internal D Mark current vertical place in register \fIR\fR. +.b1 +\fB&rt\fI|\(+-N\fR none internal D,\fBv\fR Return \fI(upward only)\fR to marked vertical place. +.mh +Text Filling, Adjusting, and Centering +.bt +\fB&br\fR - - B Break. +.b1 +.lg 0 +\fB&fi\fR \(fill - B,E Fill output lines. +.lg +.b1 +\fB&nf\fR fill - B,E No filling or adjusting of output lines. +.b1 +\fB&ad\fI|c\fR adj,both adjust E Adjust output lines with mode \fIc\fR. +.b1 +\fB&na\fR adjust - E No output line adjusting. +.b1 +\fB&ce\fI|N\fR off \fIN\(eq\fR1 B,E Center following \fIN\fR input text lines. +.mh +Vertical Spacing +.bt +\fB&vs\fI|N\fR 1\(sl6in;12pts previous E,\fBp\fR Vertical base line spacing (\fIV\fR\^). +.b1 +\fB&ls\fI|N N\(eq\fR1 previous E Output \fIN\(mi\fR1 \fIV\^\fRs after each text output line. +.b1 +\fB&sp\fI|N\fR - \fIN\(eq\fR1\fIV\fR B,\fBv\fR Space \ +vertical distance \fIN\fR \fIin either direction\fR. +.b1 +\fB&sv\fI|N\fR - \fIN\(eq\fR1\fIV\fR \fBv\fR Save vertical distance \fIN\fR. +.b1 +\fB&os\fR - - - Output saved vertical distance. +.b1 +\fB&ns\fR space - D Turn no-space mode on. +.b1 +\fB&rs\fR - - D Restore spacing; turn no-space mode off. +.mh +Line Length and Indenting +.bt +\fB&ll\fI|\(+-N\fR 6.5\|in previous E,\fBm\fR Line length. +.b1 +\fB&in\fI|\(+-N\fR \fIN\(eq\fR\^0 previous B,E,\fBm\fR Indent. +.b1 +\fB&ti\fI|\(+-N\fR - ignored B,E,\fBm\fR Temporary indent. +.mh +Macros, Strings, Diversion, and Position Traps +.bt +\fB&de\fI|xx|yy\fR - \fI.yy=\fB..\fR - Define or redefine macro \fIxx;\fR end at call of \fIyy\fR. +.b1 +\fB&am\fI|xx|yy\fR - \fI.yy=\fB..\fR - Append to a macro. +.b1 +\fB&ds\fI|xx|string\fR - ignored - Define a string \fIxx\fR containing \fIstring\fR. +.b1 +\fB&as\fI|xx|string\fR - ignored - Append \fIstring\fR to string \fIxx\fR. +.b1 +\fB&rm\fI|xx\fR - ignored - Remove request, macro, or string. +.b1 +\fB&rn\fI|xx|yy\fR - ignored - Rename request, macro, or string \fIxx\fR to \fIyy\fR. +.b1 +\fB&di\fI|xx\fR - end D Divert output to macro \fIxx\fR. +.b1 +\fB&da\fI|xx\fR - end D Divert and append to \fIxx\fR. +.b1 +\fB&wh\fI|N|xx\fR - - \fBv\fR Set location trap; negative is w.r.t. page bottom. +.b1 +\fB&ch\fI|xx|N\fR - - \fBv\fR Change trap location. +.b1 +\fB&dt\fI|N|xx\fR - off D,\fBv\fR Set a diversion trap. +.b1 +\fB&it\fI|N|xx\fR - off E Set an input-line count trap. +.b1 +\fB&em\fI|xx\fR none none - End macro is \fIxx\fI. +.mh +Number Registers +.bt +\fB&nr\fI|R|\(+-N|M\fR - - \fBu\fR Define and set number register \fIR\fR; auto-increment by \fIM\fR. +.b1 +\fB&af\fI|R|c\fR arabic - - Assign format to register \fIR\fR (\fIc=\fB1\fR, \fBi\fR, \fBI\fR, \fBa\fR, \fBA\fR). +.b1 +\fB&rr\fI|R\fR - - - Remove register \fIR\fR. +.mh +Tabs, Leaders, and Fields +.bt +\fB&ta\fI|Nt|...\fR 0.8;|0.5in none E,\fBm\fR Tab settings; \fIleft\fR type, unless \fIt=\fBR\fR(right), \fBC\fR(centered). +.b1 +\fB&tc\fI|c\fR none none E Tab repetition character. +.b1 +\fB&lc\fI|c\fR \fB.\fR none E Leader repetition character. +.b1 +\fB&fc\fI|a|b\fR off off - Set field delimiter \fIa\fR and pad character \fIb\fR. +.mh +Input and Output Conventions and Character Translations +.bt +\fB&ec\fI|c\fR \e \e - Set escape character. +.b1 +\fB&eo\fR on - - Turn off escape character mechanism. +.b1 +\fB&lg\fI|N\fR -;\|on on - Ligature mode +on if \fIN\fR>0. +.b1 +\fB&ul\fI|N\fR off \fIN\(eq\fR1 E Underline (italicize in \*(TR) \fIN\fR input lines. +.b1 +\fB&cu\fI|N\fR off \fIN\(eq\fR1 E Continuous underline in \*(NR; like \fBul\fR in \*(TR. +.b1 +\fB&uf\fI|F\fR Italic Italic - Underline font set to \fIF\fR (to be switched to by \fBul\fR). +.b1 +\fB&cc\fI|c\fR \fB. .\fR E Set control character to \fIc\fR. +.b1 +\fB&c2\fI|c\fR \fB\' \'\fR E Set nobreak control character to \fIc\fR. +.b1 +\fB&tr\fI|abcd....\fR none - O Translate \fIa\fR to \fIb\fR, etc. on output. +.mh +Local Horizontal and Vertical Motions, and the Width Function +.mh +Overstrike, Bracket, Line-drawing, and Zero-width Functions +.mh +Hyphenation. +.bt +\fB&nh\fR hyphenate - E No hyphenation. +.b1 +\fB&hy\fI|N\fR hyphenate hyphenate E Hyphenate; \fIN =\fR mode. +.b1 +\fB&hc\fI|c\fR \fB\e% \e%\fR E Hyphenation indicator character \fIc\fR. +.b1 +\fB&hw\fI|word1|...\fR ignored - Exception words. +.mh +Three Part Titles. +.bt +\fB&tl\fI|\'left\|\'center\|\'right\|\'\fR - - Three part title. +.b1 +\fB&pc\fI|c\fR \fB%\fR off - Page number character. +.b1 +\fB<\fI|\(+-N\fR 6.5\|in previous E,\fBm\fR Length of title. +.mh +Output Line Numbering. +.bt +\fB&nm\fI|\(+-N|M|S|I\fR off E Number mode on or off, set parameters. +.b1 +\fB&nn\fI|N\fR - \fIN\(eq\fR1 E Do not number next \fIN\fR lines. +.mh +Conditional Acceptance of Input +.bt +\fB&if\fI|c|anything\fR - - If condition \fIc\fR true, accept \fIanything\fR as input, +.b1 + for multi-line use \fI\e{anything\|\e}\fR. +.b1 +\fB&if|!\fIc|anything\fR - - If condition \fIc\fR false, accept \fIanything\fR. +.b1 +\fB&if\fI|N|anything\fR - \fBu\fR If expression \fIN\fR > 0, accept \fIanything\fR. +.b1 +\fB&if|!\fIN|anything\fR - \fBu\fR If expression \fIN\fR \(<= 0, accept \fIanything\fR. +.b1 +\fB&if\fI|\|\'string1\|\'string2\|\'|anything\fR - If \fIstring1\fR identical to \fIstring2\fR, +accept \fIanything\fR. +.b1 +\fB&if|!\fI\|\'string1\|\'string2\|\'|anything\fR - If \fIstring1\fR not identical to \fIstring2\fR, +accept \fIanything\fR. +.b1 +\fB&ie\fI|c|anything\fR - \fBu\fR If portion of if-else; all above forms (like \fBif\fR). +.b1 +\fB&el\fI|anything\fR - - Else portion of if-else. +.mh +Environment Switching. +.bt +\fB&ev\fI|N\fR \fIN\(eq\fR0 previous - Environment switched (\fIpush down\fR). +.mh +Insertions from the Standard Input +.bt +\fB&rd\fI|prompt\fR\fR - \fIprompt=\s-1\fRBEL\s+1 Read insertion. +.b1 +\fB&ex\fR - - - \ +Exit from \*(NR\(sl\*(TR. +.mh +Input\(slOutput File Switching +.bt +\fB&so\fI|filename\fR - - Switch source file \fI(push down)\fR. +.b1 +\fB&nx\fI|filename\fR end-of-file - Next file. +.b1 +\fB&pi\fI|program\fR - - Pipe output to \fIprogram\fR (\*(NR only). +.mh +Miscellaneous +.bt +\fB&mc\fI|c|N\fR - off E,\fBm\fR Set margin character \fIc\fR and separation \fIN\fR. +.b1 +\fB&tm\fI|string\fR - newline - Print \fIstring\fR on terminal \ +(\s-1UNIX\s+1 standard error output). +.b1 +\fB&ig\fI|yy\fR - \fI.yy=\fB..\fR - Ignore till call of \fIyy\fR. +.b1 +\fB&pm\fI|t\fR - all - Print macro names and sizes; +.b1 + if \fIt\fR present, print only total of sizes. +.b1 +\fB&ab\fI|string\fR - - - Print a message and abort. +.b1 +.lg 0 +\fB&fl\fR - - B Flush output buffer. +.lg +.mh +Output and Error Messages +.xx +.nf +.rm mx +.ft R +\l'\n(.lu' +.ft B +.xx +.ta .3iC .6i + Notes- +.xx +.ft R + B Request normally causes a break. + D Mode or relevant parameters associated with current diversion level. + E Relevant parameters are a part of the current environment. + O Must stay in effect until logical output. + P Mode must be still or again in effect at the time of physical output. + \fBv\fR,\fBp\fR,\fBm\fR,\fBu\fR Default scale indicator; if not specified, scale indicators are \fIignored\fR. +.br +.nr zz 11 +.de cl +.ie \\n+(cl<\n(zz \{\ +. po +\\n(.lu/\n(zzu +. rt +.\} +.el \{\ +.po 26i/27u +.\} +.. +.nr cl 0 1 +.di zz +.ta .3iR +.nf +.ps 8 +.vs 10 +ab 20 +ad 4 +af 8 +am 7 +as 7 +bd 2 +bp 3 +br 4 +c2 10 +cc 10 +ce 4 +ch 7 +cs 2 +cu 10 +da 7 +de 7 +di 7 +ds 7 +dt 7 +ec 10 +el 16 +em 7 +eo 10 +ev 17 +ex 18 +fc 9 +fi 4 +fl 20 +fp 2 +ft 2 +fz 2 +hc 13 +hw 13 +hy 13 +ie 16 +if 16 +ig 20 +in 6 +it 7 +lc 9 +lg 10 +li 10 +ll 6 +ls 5 +lt 14 +mc 20 +mk 3 +na 4 +ne 3 +nf 4 +nh 13 +nm 15 +nn 15 +nr 8 +ns 5 +nx 19 +os 5 +pc 14 +pi 19 +pl 3 +pm 20 +pn 3 +po 3 +ps 2 +rd 18 +rm 7 +rn 7 +rr 8 +rs 5 +rt 3 +so 19 +sp 5 +ss 2 +sv 5 +ta 9 +tc 9 +ti 6 +tl 14 +tm 20 +tr 10 +uf 10 +ul 10 +vs 5 +wh 7 +.di +.nr aa \n(dn/\n(zz +.ne \n(aau+10p +.sp +.ft B +Alphabetical Request and Section Number Cross Reference +.ft +.sp .3 +.wh \n(nlu+\n(aau cl +.nr qq \n(nlu+\n(aau +.ps +.vs +.mk +.zz +.rt +.sp \n(.tu +.ch cl 12i +.sp +.bp +.nf +.ft B +Escape Sequences for Characters, Indicators, and Functions +.ft R +.xx +.TS +c2l +c2l2l +n2l2l. +.ft I +.bd I 3 +Section Escape +Reference Sequence Meaning +.ft R +.bd I +.xx +10.1 \fB\e\e\fR \e (to prevent or delay the interpretation of \e\|) +10.1 \fB\ee\fR Printable version of the \fIcurrent\fR escape character. +2.1 \fB\e\'\fR \' (acute accent); equivalent to \fB\e(aa\fR +2.1 \fB\e\`\fR \` (grave accent); equivalent to \fB\e(ga\fR +2.1 \fB\e\-\fR \- Minus sign in the \fIcurrent\fR font +7 \fB\e\^.\fR Period (dot) (see \fBde\fR) +11.1 \fB\e\fR(space) Unpaddable space-size space character +11.1 \fB\e0\fR Digit width space +.tr || +11.1 \fB\e\||\fR 1\(sl6\|em narrow space character (zero width in \*(NR) +.tr | +11.1 \fB\e^\fR 1\(sl12\|em half-narrow space character (zero width in \*(NR) +.tr && +4.1 \fB\e&\fR Non-printing, zero width character +.tr &. +10.6 \fB\e!\fR Transparent line indicator +10.7 \fB\e"\fR Beginning of comment +7.3 \fB\e$\fIN\fR Interpolate argument 1\(<=\fIN\fR\(<=9 +13 \fB\e%\fR Default optional hyphenation character +2.1 \fB\e(\fIxx\fR Character named \fIxx\fR +7.1 \fB\e\(**\fIx\fR,|\fB\e\(**(\fIxx\fR Interpolate string \fIx\fR or \fIxx\fR +9.1 \fB\ea\fR Non-interpreted leader character +12.3 \fB\eb\fI\'abc...\|\'\fR Bracket building function +4.2 \fB\ec\fR Interrupt text processing +11.1 \fB\ed\fR Forward (down) 1\(sl2\|em vertical motion (1\(sl2 line in \*(NR) +2.2 \fB\ef\fIx\fR,\fB\ef(\fIxx\fR,\fB\ef\fIN\fR Change to font named \fIx\fR or \fIxx\fR, or position \fIN\fR +11.1 \fB\eh\fI\'N|\'\fR Local horizontal motion; move right \fIN\fR \fI(negative left)\fR +11.3 \fB\ek\fIx\fR Mark horizontal \fIinput\fR place in register \fIx\fR +12.4 \fB\el\fI\|\'Nc\|\'\fR Horizontal line drawing function (optionally with \fIc\fR\|) +12.4 \fB\eL\fI\'Nc\|\'\fR Vertical line drawing function (optionally with \fIc\fR\|) +8 \fB\en\fIx\fR,\fB\en(\fIxx\fR Interpolate number register \fIx\fR or \fIxx\fR +12.1 \fB\eo\fI\'abc...\|\'\fR Overstrike characters \fIa, b, c, ...\fR +4.1 \fB\ep\fR Break and spread output line +11.1 \fB\er\fR Reverse 1\|em vertical motion (reverse line in \*(NR) +2.3 \fB\es\fIN\fR,\|\fB\es\fI\(+-N\fR Point-size change function +9.1 \fB\et\fR Non-interpreted horizontal tab +11.1 \fB\eu\fR Reverse (up) 1\(sl2\|em vertical motion (1\(sl2 line in \*(NR) +11.1 \fB\ev\fI\'N\|\|\'\fR Local vertical motion; move down \fIN\fR \fI(negative up)\fR +11.2 \fB\ew\fI\'string\|\'\fR Interpolate width of \fIstring\fR +5.2 \fB\ex\fI\'N\|\|\'\fR Extra line-space function \fI(negative before, positive after)\fR +12.2 \fB\ez\fIc\fR Print \fIc\fR with zero width (without spacing) +16 \fB\e{\fR Begin conditional input +16 \fB\e}\fR End conditional input +10.7 \fB\e\fR(newline) Concealed (ignored) newline +- \fB\e\fIX\fR \fIX\fR, any character \fInot\fR listed above +.TE +.fi +.sp +The escape sequences +\fB\e\e\fR, +\fB\e\^.\fR, +\fB\e"\fR, +\fB\e$\fR, +\fB\e\(**\fR, +\fB\ea\fR, +\fB\en\fR, +\fB\et\fR, +and +\fB\e\fR(newline) are interpreted in \fIcopy mode\fR (\(sc7.2). +.bp +.ft B +.nf +Predefined General Number Registers +.ft +.TS +c2l +c2l2l +n2l2l. +.ft I +.bd I 3 +Section Register +Reference Name Description +.ft R +.bd I +.xx +3 \fB%\fR Current page number. +19 \fBc&\fR Number of \fIlines\fR read from current input file. +11.2 \fBct\fR Character type (set by \fIwidth\fR function). +7.4 \fBdl\fR Width (maximum) of last completed diversion. +7.4 \fBdn\fR Height (vertical size) of last completed diversion. +- \fBdw\fR Current day of the week (1-7). +- \fBdy\fR Current day of the month (1-31). +11.3 \fBhp\fR Current horizontal place on \fIinput\fR line (not in ditroff) +15 \fBln\fR Output line number. +- \fBmo\fR Current month (1-12). +4.1 \fBnl\fR Vertical position of last printed text base-line. +11.2 \fBsb\fR Depth of string below base line (generated by \fIwidth\fR function). +11.2 \fBst\fR Height of string above base line (generated by \fIwidth\fR function). +- \fByr\fR Last two digits of current year. +.TE +.sp +.ft B +Predefined Read-Only Number Registers +.ft R +.TS +c2l +c2l2l +n2l2l. +.ft I +.bd I 3 +Section Register +Reference Name Description +.ft R +.bd I +.xx +7.3 \fB&$\fR Number of arguments available at the current macro level. +- \fB&A\fR Set to 1 in \*(TR, if \fB\-a\fR option used; always 1 in \*(NR. +11.1 \fB&H\fR Available horizontal resolution in basic units. +5.3 \fB&L\fR Set to current \fIline-spacing\fR (\fBls\fR) parameter +- \fB&P\fR Set to 1 if the current page is being printed; otherwise 0. +- \fB&T\fR Set to 1 in \*(NR, if \fB\-T\fR option used; always 0 in \*(TR. +11.1 \fB&V\fR Available vertical resolution in basic units. +5.2 \fB&a\fR Post-line extra line-space most recently utilized \ +using \fB\ex\fI\'N\|\'\fR. +19 \fB&c\fR Number of \fIlines\fR read from current input file. +7.4 \fB&d\fR Current vertical place in current diversion; equal to \fBnl\fR, if no diversion. +2.2 \fB&f\fR Current font as physical quadrant (1-4). +4 \fB&h\fR Text base-line high-water mark on current page or diversion. +6 \fB&i\fR Current indent. +4.2 \fB&j\fR Current adjustment mode and type. +4.1 \fB&k\fR Length of text portion on current partial output line. +6 \fB&l\fR Current line length. +4 \fB&n\fR Length of text portion on previous output line. +3 \fB&o\fR Current page offset. +3 \fB&p\fR Current page length. +2.3 \fB&s\fR Current point size. +7.5 \fB&t\fR Distance to the next trap. +4.1 \fB&u\fR Equal to 1 in fill mode and 0 in nofill mode. +5.1 \fB&v\fR Current vertical line spacing. +11.2 \fB&w\fR Width of previous character. +- \fB&x\fR Reserved version-dependent register. +- \fB&y\fR Reserved version-dependent register. +7.4 \fB&z\fR Name of current diversion. +.TE +.in 0 +.fi +.ps 10 +.vs 12 +.ft R +.bp diff --git a/share/doc/usd/21.troff/m1 b/share/doc/usd/21.troff/m1 new file mode 100644 index 000000000000..8b1579b6ff2c --- /dev/null +++ b/share/doc/usd/21.troff/m1 @@ -0,0 +1,742 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.nr p 0 1 +.tr | +.tr ~| +.rm mx +.br +.ce +.ft B +.ps +2 +.rs +.\".sp1.0i +REFERENCE MANUAL +.ft R +.ps -2 +.sp +.mh +General Explanation +.sc +Form of input. +Input consists of \fItext lines\fR, which are destined to be printed, +interspersed with \fIcontrol lines\fR, +which set parameters or otherwise control subsequent processing. +Control lines begin with a \fIcontrol character\fR\(em\ +normally \fB.\fR (period) or \fB\'\fR (acute accent)\(em\ +followed by a one or two character name that specifies +a basic \fIrequest\fR or the substitution of +a user-defined \fImacro\fR in place of the control line. +The control character \fB\'\fR suppresses the \fIbreak\fR function\(em\ +the forced output of a partially filled line\(em\ +caused by certain requests. +The control character may be separated from the request/macro name by +white space (spaces and/or tabs) for \(aesthetic reasons. +Names must be followed by either +space or newline. +Control lines with unrecognized names are ignored. +.pg +Various special functions may be introduced anywhere in the input by +means of an \fIescape\fR character, normally \fB\e\fR. +For example, the function +\fB\en\fIR\fR +causes the interpolation (insertion in place) of the contents of the +\fInumber register R\fR +in place of the function; +here \fIR\fR is either a single character name +as in \fB\en\fIx\fR, +or left-parenthesis-introduced, two-character name as in \fB\en(\fIxx\fR. +.sc +Formatter and device resolution. +\*(TR internally uses 432 units\(slinch, (for historical reasons, corresponding to +the Graphic Systems phototypesetter +which had a horizontal resolution of +1\(sl432 inch and a vertical resolution +of 1\(sl144 inch.) +\*(NR internally uses 240 units\(slinch, +corresponding to the least common multiple of the +horizontal and vertical resolutions of various +typewriter-like output devices. +\*(TR rounds horizontal\(slvertical numerical parameter input to its own +internal horizontal\(slvertical resolution. +\*(NR similarly rounds numerical input to the actual resolution +of the output device indicated by the \fB\(miT\fR option +(default Model 37 Teletype). +.sc +Numerical parameter input. +Both \*(NR and \*(TR +accept numerical input with the scale +indicator suffixes +shown in the following table, +where +\fIS\fR is the current type size in points, +\fIV\fR is the current vertical line spacing in +basic units, +and +\fIC\fR is a \fInominal character width\fR in basic units. +.TS +center box; +c|c|ls +c|c|ll +c|l|l|l. +Scale Number of basic units +Indicator Meaning \*(TR \*(NR +_ +\fBi\fR Inch 432 240 +\fBc\fR Centimeter 432\(mu50\(sl127 240\(mu50\(sl127 +\fBP\fR Pica = 1\(sl6 inch 72 240\(sl6 +\fBm\fR Em = \fIS\fR points 6\(mu\fIS\fR \fIC\fR +\fBn\fR En = Em\(sl2 3\(mu\fIS\fR \fIC, same as Em\fR +\fBp\fR Point = 1\(sl72 inch 6 240\(sl72 +\fBu\fR Basic unit 1 1 +\fBv\fR Vertical line space \fIV\fR \fIV\fR +none Default, see below +.TE +In \*(NR, \fIboth\fR the em and the en are taken to be equal to the \fIC\fR, +which is output-device dependent; +common values are 1\(sl10 and 1\(sl12 inch. +Actual character widths in \*(NR need not be all the same and constructed characters +such as \(mi> (\(->) are often extra wide. +The default scaling is ems for the horizontally-oriented requests +and functions +\fBll\fR, +\fBin\fR, +\fBti\fR, +\fBta\fR, +\fBlt\fR, +\fBpo\fR, +\fBmc\fR, +\fB\eh\fR, +and +\fB\el\fR; +\fIV\^\fRs +for the vertically-oriented requests and functions +\fBpl\fR, +\fBwh\fR, +\fBch\fR, +\fBdt\fR, +\fBsp\fR, +\fBsv\fR, +\fBne\fR, +\fBrt\fR, +\fB\ev\fR, +\fB\ex\fR, +and +\fB\eL\fR; +\fBp\fR for the \fBvs\fR request; +and \fBu\fR for the requests +\fBnr\fR, +\fBif\fR, +and +\fBie\fR. +\fIAll\fR other requests ignore any scale indicators. +When a number register containing an already appropriately scaled number +is interpolated to provide numerical input, +the unit scale indicator +\fBu\fR may need to be appended to prevent +an additional inappropriate default scaling. +The number, \fIN\fR, may be specified in decimal-fraction form +but the parameter finally stored is rounded to an integer number of basic units. +.pg +The \fIabsolute position\fR indicator \fB~\fR may be prefixed +to a number \fIN\fR +to generate the distance to the vertical or horizontal place \fIN\fR. +For vertically-oriented requests and functions, \fB~\|\fIN\fR +becomes the distance in basic units from the current vertical place on the page or in a \fIdiversion\fR (\(sc7.4) +to the vertical place \fIN\fR. +For \fIall\fR other requests and functions, +\fB~\|\fIN\fR +becomes the distance from +the current horizontal place on the \fIinput\fR line to the horizontal place \fIN\fR. +For example, +.x1 +\&\fB.sp ~\|3.2c\fR +.x2 +will space \fIin the required direction\fR to 3.2 centimeters from the top of the page. +.sc +.tr && +Numerical expressions. +Wherever numerical input is expected, an expression involving parentheses, +the arithmetic operators \fB\(pl\fR, \fB\(mi\fR, \fB\(sl\fR, \fB\(**\fR, \fB%\fR (mod), +and the logical operators +\fB<\fR, +\fB>\fR, +\fB<\(eq\fR, +\fB>\(eq\fR, +\fB\(eq\fR (or \fB\(eq\(eq\fR), +\fB&\fR\ (and), +\fB:\fR\ (or) +may be used. +Except where controlled by parentheses, evaluation of expressions is left-to-right; +there is no operator precedence. +In the case of certain requests, an initial \fB\(pl\fR or \fB\(mi\fR is stripped +and interpreted as an increment or decrement indicator respectively. +In the presence of default scaling, the desired scale indicator must be +attached to \fIevery\fR number in an expression +for which the desired and default scaling differ. +For example, +if the number register \fBx\fR contains 2 +and the current point size is 10, +then +.br +.tr &. +.x1 +.ft B +\&.ll (4.25i\(pl\enxP\(pl3)\(sl2u +.ft R +.x2 +will set the line length to 1\(sl2 the sum of 4.25 inches \(pl 2 picas \(pl 30 points. +.sc +Notation. +Numerical parameters are indicated in this manual in two ways. +\(+-\fIN\fR means that the argument may take the forms \fIN\fR, \(pl\fIN\fR, or \(mi\fIN\fR and +that the corresponding effect is to set the affected parameter +to \fIN\fR, to increment it by \fIN\fR, or to decrement it by \fIN\fR respectively. +Plain \fIN\fR means that an initial algebraic sign is \fInot\fR +an increment indicator, +but merely the sign of \fIN\fR. +Generally, unreasonable numerical input is either ignored +or truncated to a reasonable value. +For example, +most requests expect to set parameters to non-negative +values; +exceptions are +\fBsp\fR, +\fBwh\fR, +\fBch\fR, +\fBnr\fR, +and +\fBif\fR. +The requests +\fBps\fR, +\fBft\fR, +\fBpo\fR, +\fBvs\fR, +\fBls\fR, +\fBll\fR, +\fBin\fR, +and +\fBlt\fR +restore the \fIprevious\fR parameter value in the \fIabsence\fR +of an argument. +.pg +Single character arguments are indicated by single lower case letters +and +one/two character arguments are indicated by a pair of lower case letters. +Character string arguments are indicated by multi-character mnemonics. +.mh +Font and Character Size Control +.sc +Character set. +The \*(TR character set consists of a typesetter-dependent basic +character set plus a Special Mathematical Font character +set\(emeach having 102 characters. +An example of these character sets is shown in the Appendix Table|I. +All printable \s-1ASCII\s+1 characters are included, +with some on the Special Font. +With three exceptions, these \s-1ASCII\s+1 characters are input as themselves, +and non-\s-1ASCII\s+1 characters are input in the form \fB\e(\fIxx\fR where +\fIxx\fR is a two-character name given in the Appendix Table|II. +The three \s-1ASCII\s+1 exceptions are mapped as follows: +.TS +center box; +cs|cs +cc|cc +cl|cl. +\s-1ASCII\s+1 Input Printed by \*(TR +Character Name Character Name +_ +\' acute accent ' close quote +\` grave accent ` open quote +\(mi minus - hyphen +.TE +.tr ~~ +The characters +\fB\'\fR, +\fB\`\fR, +and +\fB\-\fR +may be input +by \fB\e\'\fR, \fB\e\`\fR, and \fB\e\-\fR respectively or by their names (Table II). +The \s-1ASCII\s+1 characters \fB@\fR, \fB#\fR, \fB"\fR, \fB\(aa\fR, \fB\(ga\fR, \fB<\fR, \fB>\fR, \fB\e\fR, \fB{\fR, \fB}\fR, \fB~\fR, \fB^\fR, and \fB\(ul\fR exist +only on the Special Font and are printed as a 1-em space if that font +is not mounted. +.pg +.tr ~| +\*(NR understands the entire \*(TR character set, +but can in general print only \s-1ASCII\s+1 +characters, +additional characters as may be available on +the output device, +such characters as may be able to be constructed +by overstriking or other combination, +and those that can reasonably be mapped +into other printable characters. +The exact behavior is determined by a driving +table prepared for each device. +The characters +\fB\'\fR, +\fB\`\fR, +and +\fB\(ul\fR +print +as themselves. +.sc +Fonts. +The default mounted fonts are +Times Roman (\fBR\fR), +Times Italic (\fBI\fR), +Times Bold (\fBB\fR), +and the Special Mathematical Font (\fBS\fR) +on physical typesetter positions 1, 2, 3, and 4 respectively. +These fonts are used in this document. +The \fIcurrent\fR font, initially Roman, may be changed +(among the mounted fonts) +by use of the \fBft\fR request, +or by imbedding at any desired point +either \fB\ef\fIx\fR, \fB\ef(\fIxx\fR, or \fB\ef\fIN\fR +where +\fIx\fR and \fIxx\fR are the name of a mounted font +and \fIN\fR is a numerical font position. +It is \fInot\fR necessary to change to the Special Font; +characters on that font are automatically handled. +A request for a named but not-mounted font is \fIignored\fR. +\*(TR can be informed that any particular font is mounted +by use of the \fBfp\fR request. +The list of known fonts is installation dependent. +In the subsequent discussion of font-related requests, +\fIF\fR represents either a one\(sltwo-character +font name or the numerical font position, 1-4. +The current font is available (as numerical position) in the read-only number register \fB.f\fR. +.pg +\*(NR understands font control +and normally underlines Italic characters (see \(sc10.5). +.sc +Character size. +Character point sizes available are typesetter dependent, but often include +6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36. +This is a range of 1\(sl12 inch to 1\(sl2 inch. +The \fBps\fR request is used to change or restore the point size. +Alternatively the point size may be changed between any two characters +by imbedding a \fB\es\fIN\fR +at the desired point +to set the size to \fIN\fR, +or a \fB\es\fI\(+-N\fR (1\(<=\fIN\fR\(<=9) +to increment\(sldecrement the size by \fIN\fR; +\fB\es0\fR restores the \fIprevious\fR size. +Requested point size values that are between two valid +sizes yield the larger of the two. +The current size is available in the \fB.s\fR register. +\*(NR ignores type size control. +.h1 * +.fn +.xx +*Notes are explained at the end of the Summary and Index above. +.ef +.bt +\fB&ps\fI|\(+-N\fR 10\|point previous E Point size +set to \(+-\fIN\fR. +Alternatively imbed \fB\es\fIN\fR or \fB\es\fI\(+-N\fR. +Any positive size value may be requested; +if invalid, the next larger valid size will result, with a +maximum of 36. +A paired sequence +\(pl\fIN\fR,\|\(mi\fIN\fR +will work because the previous requested value is also remembered. +Ignored in \*(NR. +.bt +\fB&fz\fI|F|\(+-N\fR off - E The characters in font \fIF\fR will be adjusted to +be in size \(+-\fIN\fR. Characters in the Special Font encountered during the +use of font \fIF\fR will have the same size modification. (Use the \fB&fz S\fR +request if different treatment of Special Font characters is required). \fB&fz\fR +must follow any \fB&fp\fR request for the position. +.bt +\fB&fz|S|\fIF|\(+-N\fR off - E The characters in the Special Font +will be in size \(+-\fIN\fR independent of previous \fB&fz\fR requests. +.bt +\fB&ss\fI|N\fR 12\(sl36\|em ignored E Space-character size +is set to \fIN\fR\(sl36\|ems. +This size is the minimum word spacing in adjusted text. +Ignored in \*(NR. +.bt +\fB&cs|\fIF\|N\|M\fR off - P Constant character space +(width) mode is +set on for font \fIF\fR (if mounted); the width of every character will be +taken to be \fIN\fR\(sl36 ems. +If \fIM\fR is absent, +the em is that of the character's point size; +if \fIM\fR is given, +the em is \fIM\fR-points. +All affected characters +are centered in this space, including those with an actual width +larger than this space. +Special Font characters occurring while the current font +is \fIF\fR are also so treated. +If \fIN\fR is absent, the mode is turned off. +The mode must be still or again in effect when the characters are physically printed. +Ignored in \*(NR. +.bt +\fB&bd\fI|F|N\fR off - P The characters in font \fIF\fR will be artificially +emboldened by printing each one twice, separated by \fIN\fR\^\(mi1 basic units. +A reasonable value for \fIN\fR is 3 when the character size is in the vicinity +of 10 points. +If \fIN\fR is missing the embolden mode is turned off. +The column heads above were printed with \fB.bd|I|3\fR. +The mode must be still or again in effect when the characters are physically printed. +Ignored in \*(NR. +.bt +\fB&bd|S|\fIF|N\fR off - P The characters in the Special Font +will be emboldened whenever the current font is \fIF\fR. +This manual was printed with \fB.bd\|S\|B\|3\fR. +The mode must be still or again in effect when the characters are physically printed. +.bt +\fB&ft|\fIF\fR Roman previous E Font changed to +\fIF\fR. +Alternatively, imbed \fB\ef\fIF\fR. +The font name \fBP\fR is reserved to mean the previous font. +.bt +\fB&fp|\fIN|F\fR R,I,B,S ignored - Font position. +This is a statement +that a font named \fIF\fR is mounted on position \fIN\fR (1-4). +It is a fatal error if \fIF\fR is not known. +The phototypesetter has four fonts physically mounted. +Each font consists of a film strip which can be mounted on a numbered +quadrant of a wheel. +The default mounting sequence assumed by \*(TR is +R, I, B, and S on positions 1, 2, 3 and 4. +.mh +Page control +.pg +Top and bottom margins are \fInot\fR automatically provided; +it is conventional to define two \fImacros\fR and to set \fItraps\fR +for them at vertical positions 0 (top) and \fI\(miN\fR (\fIN\fR from the bottom). +See \(sc7 and Tutorial Examples \(scT2. +A pseudo-page transition onto the \fIfirst\fR page occurs +either when the first \fIbreak\fR occurs or +when the first \fInon-diverted\fR text processing occurs. +Arrangements +for a trap to occur at the top of the first page +must be completed before this transition. +In the following, references to the \fIcurrent diversion\fR (\(sc7.4) +mean that the mechanism being described works during both +ordinary and diverted output (the former considered as the top diversion level). +.pg +The usable page width on the Graphic Systems phototypesetter +was about 7.54|inches, +beginning about 1\(sl27|inch from the left edge of the +8|inch wide, continuous roll paper, but these characteristics are typesetter- +dependent. +The physical limitations on \*(NR output +are output-device dependent. +.h1 +.bt +\fB&pl\fI|\(+-N\fR 11\|in 11\|in \fBv\fR Page length set to \fI\(+-N\fR. +The internal limitation is about 75|inches in \*(TR and +about 136|inches in \*(NR. +The current page length is available in the \fB.p\fR register. +.bt +\fB&bp\fI|\(+-N\fR \fIN\(eq\fR1 - B*,\fBv\fR Begin page. +.fn +.xx +*The use of "\ \fB\'\fR\ " as control character (instead of "\fB.\fR") +suppresses the break function. +.ef +The current page is ejected and a new page is begun. +If \fI\(+-N\fR is given, the new page number will be \fI\(+-N\fR. +Also see request \fBns\fR. +.bt +\fB&pn\fI|\(+-N\fR \fIN\fR\(eq1 ignored - Page number. +The next page (when it occurs) will have the page number \fI\(+-N\fR. +A \fBpn\fR must occur before the initial pseudo-page transition +to affect the page number of the first page. +The current page number is in the \fB%\fR register. +.bt +\fB&po\fI|\(+-N\fR 0;|26\(sl27\|in\(dg previous \fBv\fR Page offset. +.fn +.xx +\(dgValues separated by ";" are for \*(NR and \*(TR respectively. +.ef +The current \fIleft margin\fR is set to \fI\(+-N\fR. +The \*(TR initial value provides about 1|inch of paper margin +including the physical typesetter margin of 1\(sl27|inch. +In \*(TR the maximum (line-length)+(page-offset) is about 7.54 inches. +See \(sc6. +The current page offset is available in the \fB.o\fR register. +.bt +\fB&ne\fI|N\fR - \fIN\(eq\fR1\|\fIV\fR D,\fBv\fR Need \fIN\fR vertical space. +If the distance, \fID\fR, to the next trap position (see \(sc7.5) is less than \fIN\fR, +a forward vertical space of size \fID\fR occurs, +which will spring the trap. +If there are no remaining +traps on the page, +\fID\fR is the distance to the bottom of the page. +If \fID\|<\|V\fR, another line could still be output +and spring the trap. +In a diversion, \fID\fR is the distance to the \fIdiversion trap\fR, if any, +or is very large. +.bt +\fB&mk\fI|R\fR none internal D Mark the \fIcurrent\fR vertical place +in an internal register (both associated with the current diversion level), +or in register \fIR\fR, if given. +See \fBrt\fR request. +.bt +\fB&rt\fI|\(+-N\fR none internal D,\fBv\fR Return \fIupward only\fR to a marked vertical place +in the current diversion. +If \fI\(+-N\fR (w.r.t. current place) is given, +the place is \fI\(+-N\fR from the top of the page or diversion +or, if \fIN\fR is absent, to a +place marked by a previous \fBmk\fR. +Note that the \fBsp\fR request (\(sc5.3) may be used +in all cases instead of \fBrt\fR +by spacing to the absolute place stored in an explicit register; +e.|g. using the sequence \fB.mk|\fIR\fR ... \fB.sp|~\|\en\fIR\fBu\fR. +.mh +Text Filling, Adjusting, and Centering +.sc +Filling and adjusting. +Normally, +words are collected from input text lines +and assembled into an output text line +until some word doesn't fit. +An attempt is then made +to hyphenate the word to assemble a part +of it into the output line. +The spaces between the words on the output line +are then increased to spread out the line +to the current \fIline length\fR +minus any current \fIindent\fR. +A \fIword\fR is any string of characters delimited by +the \fIspace\fR character or the beginning/end of the input line. +Any adjacent pair of words that must be kept together +(neither split across output lines nor spread apart +in the adjustment process) +can be tied together by separating them with the +\fIunpaddable space\fR character +"\fB\e\ \ \fR" (backslash-space). +The adjusted word spacings are uniform in \*(TR +and the minimum interword spacing can be controlled +with the \fBss\fR request (\(sc2). +In \*(NR, they are normally nonuniform because of +quantization to character-size spaces; +however, +the command line option \fB\-e\fR causes uniform +spacing with full output device resolution. +Filling, adjustment, and hyphenation (\(sc13) can all be +prevented or controlled. +The \fItext length\fR on the last line output is available in the \fB.n\fR register, +and text base-line position on the page for this line is in the \fBnl\fR register. +The text base-line high-water mark (lowest place) on the current page is in +the \fB.h\fR register. The \fB.k\fR register (read-only) contains the horizontal size of +the text portion (without indent) of the current partially-collected output +line (if any) in the current environment. +.pg +An input text line ending with \fB.\fR\^, \fB?\fR, or \fB!\fR is taken +to be the end of a \fIsentence\fR, and an additional space character is +automatically provided during filling. +Multiple inter-word space characters found in the input are retained, +except for trailing spaces; +initial spaces also cause a \fIbreak\fR. +.pg +When filling is in effect, a \fB\ep\fR may be imbedded or attached to a word to +cause a \fIbreak\fR at the \fIend\fR of the word and have the resulting output +line \fIspread out\fR to fill the current line length. +.pg +.tr && +A text input line that happens to begin +with a control character (\(sc10.4) can +be made to not look like a control line +by preceding it by +the non-printing, zero-width filler character \fB\e&\fR. +Still another way is to specify output translation of some +convenient character into the control character +using \fBtr\fR (\(sc10.5). +.tr &. +.sc +Interrupted text. +The copying of an input line in \fInofill\fR +(non-fill) mode can be \fIinterrupted\fR by terminating +the partial line with a \fB\ec\fR. +The \fInext\fR encountered input text line will be considered to be a continuation +of the same line of input text. +Similarly, +a word within \fIfilled\fR text may be interrupted by terminating the +word (and line) with \fB\ec\fR; +the next encountered text will be taken as a continuation of the +interrupted word. +If the intervening control lines cause a break, +any partial line will be forced out along with any partial word. +.h1 +.bt +\fB&br\fR - - B Break. +The filling of the line currently +being collected is stopped and +the line is output without adjustment. +Text lines beginning with space characters +and empty text lines (blank lines) also cause a break. +.bt +.lg 0 +\fB&fi\fR \(fill|on - B,E Fill subsequent output lines. +.lg +The register \fB.u\fR is 1 in fill mode and 0 in nofill mode. +.bt +\fB&nf\fR fill|on - B,E Nofill. +Subsequent output lines are \fIneither\fR filled \fInor\fR adjusted. +Input text lines are copied directly to output lines +\fIwithout regard\fR for the current line length. +.bt +\fB&ad\fI|c\fR adj,both adjust E \ +Line adjustment is begun. +If fill mode is not on, adjustment will be deferred until +fill mode is back on. +If the type indicator \fIc\fR is present, +the adjustment type is changed as shown in the following table. +The type indicator can also be a value saved from the read-only \fB.j\fR number +register, which is set to contain the current adjustment mode and type. +.TS +center box; +c|c +c|l. +Indicator Adjust Type +_ +\fBl\fR adjust left margin only +\fBr\fR adjust right margin only +\fBc\fR center +\fBb\fR or \fBn\fR adjust both margins +absent unchanged +.TE +.bt +\fB&na\fR adjust - E Noadjust. +Adjustment is turned off; +the right margin will be ragged. +The adjustment type for \fBad\fR is not changed. +Output line filling still occurs if fill mode is on. +.bt +\fB&ce\fI|N\fR off \fIN\fR\(eq1 B,E Center the next \fIN\fR input text lines +within the current (line-length minus indent). +If \fIN\fR\(eq\^0, any residual count is cleared. +A break occurs after each of the \fIN\fR input lines. +If the input line is too long, +it will be left adjusted. +.mh +Vertical Spacing +.sc +Base-line spacing. +The vertical spacing \fI(V)\fR between the base-lines of successive +output lines can be set +using the \fBvs\fR request +with a resolution of 1\(sl144\|inch\|\(eq\|1\(sl2|point +in \*(TR, +and to the output device resolution in \*(NR. +\fIV\fR must be large enough to accommodate the character sizes +on the affected output lines. +For the common type sizes (9-12 points), +usual typesetting practice is to set \fIV\fR to 2\ points greater than the +point size; +\*(TR default is 10-point type on a 12-point spacing +(as in this document). +The current \fIV\fR is available in the \fB.v\fR register. +Multiple-\fIV\|\fR line separation (e.\|g. double spacing) may be requested +with \fBls\fR. +.sc +Extra line-space. +If a word contains a vertically tall construct requiring +the output line containing it to have extra vertical space +before and\(slor after it, +the \fIextra-line-space\fR function \fB\ex\fI\'N\|\|\'\fR +can be imbedded in or attached to that word. +In this and other functions having a pair of delimiters around +their parameter (here \fB\'\fR\|), +the delimiter choice is arbitrary, +except that it can't look like the continuation of a number expression for \fIN\fR. +If \fIN\fR is negative, +the output line containing the word will +be preceded by \fIN\fR extra vertical space; +if \fIN\fR is positive, +the output line containing the word +will be followed by \fIN\fR extra vertical space. +If successive requests for extra space apply to the same line, +the maximum values are used. +The most recently utilized post-line extra line-space is available in the \fB.a\fR register. +.sc +Blocks of vertical space. +A block of vertical space is ordinarily requested using \fBsp\fR, +which honors the \fIno-space\fR mode and which does +not space \fIpast\fR a trap. +A contiguous block of vertical space may be reserved using \fBsv\fR. +.h1 +.bt +\fB&vs\fI|N\fR 1\(sl6in;12pts previous E,\fBp\fR Set vertical base-line spacing size \fIV\fR. +Transient \fIextra\fR vertical space available with \fB\ex\fI\'N\|\|\'\fR (see above). +.bt +\fB&ls\fI|N\fR \fIN\(eq\^\fR1 previous E \fILine\fR spacing +set to \fI\(+-N\fR. +\fIN\(mi\fR1 \fIV\fR\^s \fI(blank lines)\fR are +appended to each output text line. The (read-only) number register \fB.L\fR +is set to contain the current line-spacing value. +Appended blank lines are omitted, if the text or previous appended blank line reached a trap position. +.bt +\fB&sp\fI|N\fR - \fIN\fR\(eq1\fIV\fR B,\fBv\fR Space vertically in \fIeither\fR direction. +If \fIN\fR is negative, the motion is \fIbackward\fR (upward) +and is limited to the distance to the top of the page. +Forward (downward) motion is truncated to the distance to the +nearest trap. +If the no-space mode is on, +no spacing occurs (see \fBns\fR, and \fBrs\fR below). +.bt +\fB&sv\fI|N\fR - \fIN\(eq\fR1\fIV\fR \fBv\fR Save a contiguous vertical block of size \fIN\fR. +If the distance to the next trap is greater +than \fIN\fR, \fIN\fR vertical space is output. +No-space mode has \fIno\fR effect. +If this distance is less than \fIN\fR, +no vertical space is immediately output, +but \fIN\fR is remembered for later output (see \fBos\fR). +Subsequent \fBsv\fR requests will overwrite any still remembered \fIN\fR. +.bt +\fB&os\fR - - - Output saved vertical space. +No-space mode has \fIno\fR effect. +Used to finally output a block of vertical space requested +by an earlier \fBsv\fR request. +.bt +\fB&ns\fR space - D No-space mode turned on. +When on, the no-space mode inhibits \fBsp\fR requests and +\fBbp\fR requests \fIwithout\fR a next page number. +The no-space mode is turned off when a line of +output occurs, or with \fBrs\fR. +.bt +\fB&rs\fR space - D Restore spacing. +The no-space mode is turned off. +.bt +Blank|text|line. - B Causes a break and +outputs a blank line just like \fBsp|1\fR. diff --git a/share/doc/usd/21.troff/m2 b/share/doc/usd/21.troff/m2 new file mode 100644 index 000000000000..019f88ec53a8 --- /dev/null +++ b/share/doc/usd/21.troff/m2 @@ -0,0 +1,396 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.tr | +.rm mx +.br +.mh +Line Length and Indenting +.pg +The maximum line length for fill mode may be set with \fBll\fR. +The indent may be set with \fBin\fR; +an indent applicable to \fIonly\fR the \fInext\fR output line may be set with \fBti\fR. +The line length includes indent space but \fInot\fR +page offset space. +The line-length minus the indent is the basis for centering with \fBce\fR. +The effect of \fBll\fR, \fBin\fR, or \fBti\fR +is delayed, if a partially collected line exists, +until after that line is output. +In fill mode the length of text on an output line is less than or equal to +the line length minus the indent. +The current line length and indent are available in registers \fB.l\fR and \fB.i\fR respectively. +The length of \fIthree-part titles\fR produced by \fBtl\fR +(see \(sc14) is \fIindependently\fR set by \fBlt\fR. +.h1 +.bt +\fB&ll\fI|\(+-N\fR 6.5\|in previous E,\fBm\fR Line length is set to \(+-\fIN\fR. +In \*(TR the maximum (line-length)+(page-offset) is about 7.54 inches. +.bt +\fB&in\fI|\(+-N\fR \fIN\(eq\^\fR0 previous B,E,\fBm\fR Indent is set to \fI\(+-N\fR. +The indent is prepended to each output line. +.bt +\fB&ti\fI|\(+-N\fR - ignored B,E,\fBm\fR Temporary indent. +The \fInext\fR output text line will be indented a distance \fI\(+-N\fR +with respect to the current indent. +The resulting total indent may not be negative. +The current indent is not changed. +.mh +Macros, Strings, Diversion, and Position Traps +.sc +Macros and strings. +A \fImacro\fR is a named set of arbitrary \fIlines\fR that may be invoked by name or +with a \fItrap\fR. +A \fIstring\fR is a named string of \fIcharacters\fR, +\fInot\fR including a newline character, +that may be interpolated by name at any point. +Request, macro, and string names share the \fIsame\fR name list. +Macro and string names +may be one or two characters long and may usurp previously defined +request, macro, or string names. +Any of these entities may be renamed with \fBrn\fR +or removed with \fBrm\fR. +Macros are created by \fBde\fR and \fBdi\fR, and appended to by \fBam\fR and \fBda\fR; +\fBdi\fR and \fBda\fR cause normal output to be stored in a macro. +Strings are created by \fBds\fR and appended to by \fBas\fR. +A macro is invoked in the same way as a request; +a control line beginning \fB.\fIxx\fR will interpolate the contents of macro \fIxx\fR. +The remainder of the line may contain up to nine \fIarguments\fR. +The strings \fIx\fR and \fIxx\fR are interpolated at any desired point with +\fB\e\(**\fIx\fR and \fB\e\(**(\fIxx\fR respectively. +String references and macro invocations may be nested. +.sc +Copy mode input interpretation. +During the definition and extension +of strings and macros (not by diversion) +the input is read in \fIcopy mode\fR. +The input is copied without interpretation +\fIexcept\fR that: +.x1 +.ds + \v'-.1m'\s-4\(bu\s+4\v'+.1m' +\(bu The contents of number registers indicated by \fB\en\fR are interpolated. +\(bu Strings indicated by \fB\e\(**\fR are interpolated. +\(bu Arguments indicated by \fB\e$\fR are interpolated. +\(bu Concealed newlines indicated by \fB\e\fR(newline) are eliminated. +\(bu Comments indicated by \fB\e"\fR are eliminated. +\(bu \fB\et\fR and \fB\ea\fR are interpreted as \s-1ASCII\s+1 horizontal tab and \s-1SOH\s+1 respectively (\(sc9). +\(bu \fB\e\e\fR is interpreted as \fB\e\fR. +\(bu \fB\e.\fR is interpreted as "\fB.\fR". +.x2 +These interpretations can be suppressed by +prepending +a \fB\e\fR. +For example, since \fB\e\e\fR maps into a \fB\e\fR, \fB\e\en\fR will copy as \fB\en\fR which +will be interpreted as a number register indicator when the +macro or string is reread. +.sc +Arguments. +When a macro is invoked by name, the remainder of the line is +taken to contain up to nine arguments. +The argument separator is the space character, and arguments +may be surrounded by double-quotes to permit imbedded space characters. +Pairs of double-quotes may be imbedded in double-quoted arguments to +represent a single double-quote. +If the desired arguments won't fit on a line, +a concealed newline may be used to continue on the next line. +.pg +When a macro is invoked the \fIinput level\fR is \fIpushed down\fR and +any arguments available at the previous level become unavailable +until the macro is completely read and the previous level is restored. +A macro's own arguments can be interpolated at \fIany\fR point +within the macro with \fB\e$\fIN\fR, which interpolates the \fIN\fR\^th +argument +(1\(<=\fIN\fR\^\(<=9). +If an invoked argument doesn't exist, +a null string results. +For example, the macro \fIxx\fR may be defined by +.x1 +.ft B +.ta .75i +&de xx \e"begin definition +Today is \e\e$1 the \e\e$2. +&. \e"end definition +.ft R +.x2 +and called by +.x1 +.ft B +&xx Monday 14th +.ft R +.x2 +to produce the text +.x1 +.ft B +Today is Monday the 14th. +.ft R +.x2 +Note that the \fB\e$\fR +was concealed in the definition with a prepended \fB\e\fR. +The number of currently available +arguments is in the \fB.$\fR register. +.pg +No arguments are available at the top (non-macro) level +in this implementation. +Because string referencing is implemented +as an input-level push down, +no arguments are available from \fIwithin\fR a string. +No arguments are available within a trap-invoked macro. +.pg +Arguments are copied in \fIcopy mode\fR onto a stack +where they are available for reference. +The mechanism does not allow an argument to contain +a direct reference to a \fIlong\fR string +(interpolated at copy time) and it is advisable to +conceal string references (with an extra \fB\e\fR\|) +to delay interpolation until argument reference time. +.sc +Diversions. +Processed output may be diverted into a macro for purposes +such as footnote processing (see Tutorial \(scT5) +or determining the horizontal and vertical size of some text for +conditional changing of pages or columns. +A single diversion trap may be set at a specified vertical position. +The number registers \fBdn\fR and \fBdl\fR respectively contain the +vertical and horizontal size of the most +recently ended diversion. +Processed text that is diverted into a macro +retains the vertical size of each of its lines when reread +in \fInofill\fR mode +regardless of the current \fIV\fR. +Constant-spaced (\fBcs\fR) or emboldened (\fBbd\fR) text that is diverted +can be reread correctly only if these modes are again or still in effect +at reread time. +One way to do this is to imbed in the diversion the appropriate +\fBcs\fR or \fBbd\fR requests with the \fItransparent\fR +mechanism described in \(sc10.6. +.pg +Diversions may be nested +and certain parameters and registers +are associated +with the current diversion level +(the top non-diversion level may be thought of as the +0th diversion level). +These are the diversion trap and associated macro, +no-space mode, +the internally-saved marked place (see \fBmk\fR and \fBrt\fR), +the current vertical place (\fB.d\fR register), +the current high-water text base-line (\fB.h\fR register), +and the current diversion name (\fB.z\fR register). +.sc +Traps. +Three types of trap mechanisms are available\(empage traps, a diversion trap, and +an input-line-count trap. +Macro-invocation traps may be planted using \fBwh\fR at any page position including the top. +This trap position may be changed using \fBch\fR. +Trap positions at or below the bottom of the page +have no effect unless or until +moved to within the page or rendered effective by an increase in page length. +Two traps may be planted at the \fIsame\fR position only by first planting them at different +positions and then moving one of the traps; +the first planted trap will conceal the second unless and until the first one is moved +(see Tutorial Examples \(scT5). +If the first one is moved back, it again conceals the second trap. +The macro associated with a page trap is automatically +invoked when a line of text is output whose vertical size \fIreaches\fR +or \fIsweeps past\fR the trap position. +Reaching the bottom of a page springs the top-of-page trap, if any, +provided there is a next page. +The distance to the next trap position is available in the \fB.t\fR register; +if there are no traps between the current position and the bottom of the page, +the distance returned is the distance to the page bottom. +.pg +A macro-invocation trap effective in the current diversion may be planted using \fBdt\fR. +The \fB.t\fR register works in a diversion; if there is no subsequent trap a \fIlarge\fR +distance is returned. +For a description of input-line-count traps, see the \fBit\fR request below. +.h1 +.bt +\fB&de\fI|xx|yy\fR - \fI.yy=\fB..\fR - Define or redefine the macro \fIxx\fR. +The contents of the macro begin on the next input line. +Input lines are copied in \fIcopy mode\fR until the definition is terminated by a +line beginning with \fB.\fIyy\fR, +whereupon the macro \fIyy\fR is called. +In the absence of \fIyy\fR, the definition +is terminated by a +line beginning with "\fB..\fR". +A macro may contain \fBde\fR requests +provided the terminating macros differ +or the contained definition terminator is concealed. +\&"\fB..\fR" can be concealed as +\fB\e\e..\fR which will copy as \fB\e..\fR and be reread as "\fB..\fR". +.bt +\fB&am\fI|xx|yy\fR - \fI.yy=\fB..\fR - Append to macro (append version of \fBde\fR). +.bt +\fB&ds\fI|xx|string\fR - ignored - Define a string +\fIxx\fR containing \fIstring\fR. +Any initial double-quote in \fIstring\fR is stripped off to permit +initial blanks. +.bt +\fB&as\fI|xx|string\fR - ignored - Append +\fIstring\fR to string \fIxx\fR +(append version of \fBds\fR). +.bt +\fB&rm\fI|xx\fR - ignored - Remove +request, macro, or string. +The name \fIxx\fR is removed from the name list and +any related storage space is freed. +Subsequent references will have no effect. +.bt +\fB&rn\fI|xx|yy\fR - ignored - Rename request, macro, or string +\fIxx\fR to \fIyy\fR. +If \fIyy\fR exists, it is first removed. +.bt +\fB&di|\fIxx\fR - end D Divert output to macro \fIxx\fR. +Normal text processing occurs during diversion +except that page offsetting is not done. +The diversion ends when the request \fBdi\fR or \fBda\fR is encountered without an argument; +extraneous +requests of this type should not appear when nested diversions are being used. +.bt +\fB&da|\fIxx\fR - end D Divert, appending to \fIxx\fR +(append version of \fBdi\fR). +.bt +\fB&wh\fI|N|xx\fR - - \fBv\fR Install +a trap to invoke \fIxx\fR at page position \fIN;\fR +a \fInegative N\fR will be interpreted with respect to the +page \fIbottom\fR. +Any macro previously planted at \fIN\fR is replaced by \fIxx\fR. +A zero \fIN\fR refers to the \fItop\fR of a page. +In the absence of \fIxx\fR, the first found trap at \fIN\fR, if any, is removed. +.bt +\fB&ch\fI|xx|N\fR - - \fBv\fR Change +the trap position for macro \fIxx\fR to be \fIN\fR. +In the absence of \fIN\fR, the trap, if any, is removed. +.bt +\fB&dt\fI|N|xx\fR - off D,\fBv\fR Install a diversion trap +at position \fIN\fR in the \fIcurrent\fR diversion to invoke +macro \fIxx\fR. +Another \fBdt\fR will redefine the diversion trap. +If no arguments are given, the diversion trap is removed. +.bt +\fB&it\fI|N|xx\fR - off E Set an input-line-count trap +to invoke the macro \fIxx\fR after \fIN\fR lines of \fItext\fR input +have been read +(control or request lines don't count). +The text may be in-line text or +text interpolated by inline or trap-invoked macros. +.bt +\fB&em\fI|xx\fR none none - The +macro \fIxx\fR will be invoked +when all input has ended. +The effect is the same as if the contents of \fIxx\fR had been at the end +of the last file processed. +.mh +Number Registers +.pg +A variety of parameters are available to the user as +predefined, named \fInumber registers\fR (see Summary and Index, page 7). +In addition, the user may define his own named registers. +Register names are one or two characters long and \fIdo not\fR conflict +with request, macro, or string names. +Except for certain predefined read-only registers, +a number register can be read, written, automatically +incremented or decremented, and interpolated +into the input in a variety of formats. +One common use of user-defined registers is to +automatically number sections, paragraphs, lines, etc. +A number register may be used any time numerical input is expected or desired +and may be used in numerical \fIexpressions\fR (\(sc1.4). +.pg +Number registers are created and modified using \fBnr\fR, which +specifies the name, numerical value, and the auto-increment size. +Registers are also modified, if accessed +with an auto-incrementing sequence. +If the registers \fIx\fR and \fIxx\fR both contain +\fIN\fR and have the auto-increment size \fIM\fR, +the following access sequences have the effect shown: +.TS +center box; +c2|c2|c +c2|c2|c +l2|c2|c +l2|c2|c +l2|l2|c. + Effect on Value +Sequence Register Interpolated +_ +\fB\en\fIx\fR none \fIN\fR +\fB\en(\fIxx\fR none \fIN\fR +\fB\en+\fIx\fR \fIx\fR incremented by \fIM\fR \fIN+M\fR +\fB\en\-\fIx\fR \fIx\fR decremented by \fIM\fR \fIN\-M\fR +\fB\en+(\fIxx\fR \fIxx\fR incremented by \fIM\fR \fIN+M\fR +\fB\en\-(\fIxx\fR \fIxx\fR decremented by \fIM\fR \fIN\-M\fR +.TE +When interpolated, a number register is converted to +decimal (default), +decimal with leading zeros, +lower-case Roman, +upper-case Roman, +lower-case sequential alphabetic, +or +upper-case sequential alphabetic +according to the format specified by \fBaf\fR. +.h1 +.bt +\fB&nr\fI|R|\(+-N|M\fR - - \fBu\fR \ +The number register \fIR\fR is assigned the value \fI\(+-N\fR +with respect to the previous value, if any. +The increment for auto-incrementing is set to \fIM\fR. +.bt +\fB&af\fI|R|c\fR arabic - - Assign format \fIc\fR to register \fIR\fR. +The available formats are: +.TS +center box; +c2|c +c2|c +c2|l. + Numbering +Format Sequence +_ +\fB1\fR 0,1,2,3,4,5,... +\fB001\fR 000,001,002,003,004,005,... +\fBi\fR 0,i,ii,iii,iv,v,... +\fBI\fR 0,I,II,III,IV,V,... +\fBa\fR 0,a,b,c,...,z,aa,ab,...,zz,aaa,... +\fBA\fR 0,A,B,C,...,Z,AA,AB,...,ZZ,AAA,... +.TE +An arabic format having \fIN\fR digits +specifies a field width of \fIN\fR digits (example 2 above). +The read-only registers and the \fIwidth\fR function (\(sc11.2) +are always arabic. +.bt +\fB&rr\fI|R\fR - ignored - Remove register \fIR\fR. +If many registers are being created dynamically, it +may become necessary to remove no longer used registers +to recapture internal storage space for newer registers. diff --git a/share/doc/usd/21.troff/m3 b/share/doc/usd/21.troff/m3 new file mode 100644 index 000000000000..6369439c0f70 --- /dev/null +++ b/share/doc/usd/21.troff/m3 @@ -0,0 +1,518 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.tr | +.rm mx +.mh +Tabs, Leaders, and Fields +.sc +Tabs and leaders. +The \s-1ASCII\s+1 horizontal tab character and the \s-1ASCII\s+1 +\s-1SOH\s+1 (hereafter known as the \fIleader\fR character) +can both be used to generate either horizontal motion or +a string of repeated characters. +The length of the generated entity is governed +by internal \fItab stops\fR specifiable +with \fBta\fR. +The default difference is that tabs generate motion and leaders generate +a string of periods; +\fBtc\fR and \fBlc\fR +offer the choice of repeated character or motion. +There are three types of internal tab stops\(em\ +\fIleft\fR adjusting, \fIright\fR adjusting, +and \fIcentering\fR. +In the following table: +\fID\fR is the distance from the current position on the \fIinput\fR line +(where a tab or leader was found) +to the next tab stop; +\fInext-string\fR consists +of the input characters following the tab (or leader) up to the next tab (or leader) or end of line; +and +\fIW\fR is the width of \fInext-string\fR. +.TS +center box; +c2|c2|c +c2|c2|c +c2|c2|l. +Tab Length of motion or Location of +type repeated characters \fInext-string\fR +_ +Left \fID\fR Following \fID\fR +Right \fID\-W\fR Right adjusted within \fID\fR +Centered \fID\-W\(sl\fR2 Centered on right end of \fID\fR +.TE +The length of generated motion is allowed to be negative, but +that of a repeated character string cannot be. +Repeated character strings contain an integer number of characters, and +any residual distance is prepended as motion. +Tabs or leaders found after the last tab stop are ignored, but may be used +as \fInext-string\fR terminators. +.pg +Tabs and leaders are not interpreted in \fIcopy mode\fR. +\fB\et\fR and \fB\ea\fR always generate a non-interpreted +tab and leader respectively, and +are equivalent to actual tabs and leaders in \fIcopy mode\fR. +.sc +Fields. +A \fIfield\fR is contained between +a \fIpair\fR of \fIfield delimiter\fR characters, +and consists of sub-strings +separated by \fIpadding\fR indicator characters. +The field length is the distance on the +\fIinput\fR line from the position where the field begins to the next tab stop. +The difference between the total length of all the sub-strings +and the field length is incorporated as horizontal +padding space that is divided among the indicated +padding places. +The incorporated padding is allowed to be negative. +For example, +if the field delimiter is \fB#\fR and the padding indicator is \fB^\fR, +\fB#^\fIxxx\fB^\fIright\|\fB#\fR +specifies a right-adjusted string with the string \fIxxx\fR centered +in the remaining space. +.h1 +.bt +\fB&ta\fI|Nt|...\fR 8n;|0.5in none E,\fBm\fR \ +Set tab stops and types. +\fIt=\fBR\fR, right adjusting; +\fIt=\fBC\fR, centering; +\fIt\fR absent, left adjusting. +\*(TR tab stops are preset every 0.5in.; +\*(NR every 8 character widths. +The stop values are separated by spaces, and +a value preceded by \fB+\fR +is treated as an increment to the previous stop value. +.bt +\fB&tc\fI|c\fR none none E \ +The tab repetition character becomes \fIc\fR, +or is removed specifying motion. +.bt +\fB&lc\fI|c\fR \fB.\fR none E \ +The leader repetition character becomes \fIc\fR, +or is removed specifying motion. +.bt +\fB&fc\fI|a|b\fR off off - \ +The field delimiter is set to \fIa\fR; +the padding indicator is set to the \fIspace\fR character or to +\fIb\fR, if given. +In the absence of arguments the field mechanism is turned off. +.mh +Input and Output Conventions and Character Translations +.sc +Input character translations. +Ways of inputting the graphic character set were +discussed in \(sc2.1. +The \s-1ASCII\s+1 control characters horizontal tab (\(sc9.1), +\s-1SOH\s+1 (\(sc9.1), and backspace (\(sc10.3) are discussed elsewhere. +The newline delimits input lines. +In addition, +\s-1STX\s+1, \s-1ETX\s+1, \s-1ENQ\s+1, \s-1ACK\s+1, and \s-1BEL\s+1 +are accepted, +and may be used as delimiters or translated into a graphic with \fBtr\fR (\(sc10.5). +\fIAll\fR others are ignored. +.pg +The \fIescape\fR character \fB\e\fR +introduces \fIescape sequences\fR\(em\ +causes the following character to mean +another character, or to indicate +some function. +A complete list of such sequences is given in the Summary and Index on page 6. +\fB\e\fR +should not be confused with the \s-1ASCII\s+1 control character \s-1ESC\s+1 of the +same name. +The escape character \fB\e\fR can be input with the sequence \fB\e\e\fR. +The escape character can be changed with \fBec\fR, +and all that has been said about the default \fB\e\fR becomes true +for the new escape character. +\fB\ee\fR can be used to print whatever the current escape character is. +If necessary or convenient, the escape mechanism may be turned off with \fBeo\fR, +and restored with \fBec\fR. +.h1 +.bt +\fB&ec\fI|c\fR \fB\e\fR \fB\e\fR - \ +Set escape character to \fB\e\fR, or to \fIc\fR, if given. +.bt +\fB&eo\fR on - - Turn escape mechanism off. +.sc +Ligatures. +.lg 0 +Five ligatures are available +in the current \*(TR character set \(em +\fB\(fi\fR, \fB\(fl\fR, \fB\(ff\fR, \fB\(Fi\fR, and \fB\(Fl\fR. +They may be input (even in \*(NR) by +\fB\e(fi\fR, \fB\e(fl\fR, \fB\e(ff\fR, \fB\e(Fi\fR, and \fB\e(Fl\fR respectively. +.lg +The ligature mode is normally on in \*(TR, and \fIautomatically\fR invokes +ligatures during input. +.h1 +.bt +\fB&lg\fI|N\fR off;|on on - Ligature mode +is turned on if \fIN\fR is absent or non-zero, +and turned off if \fIN\(eq\^\fR0. +If \fIN\fR\(eq\^2, only the two-character ligatures are automatically invoked. +Ligature mode is inhibited for +request, macro, string, register, or file names, +and in \fIcopy mode\fR. +No effect in \*(NR. +.sc +Backspacing, underlining, overstriking, etc. +Unless in \fIcopy mode\fR, the \s-1ASCII\s+1 backspace character is replaced +by a backward horizontal motion having the width of the +space character. +Underlining as a form of line-drawing is discussed in \(sc12.4. +A generalized overstriking function is described in \(sc12.1. +.pg +\*(NR automatically underlines +characters in the \fIunderline\fR font, +specifiable with \fBuf\fR, +normally Times Italic on font position 2 (see \(sc2.2). +In addition to \fBft\fR and \fB\ef\fIF\fR, +the underline font may be selected by \fBul\fR and \fBcu\fR. +Underlining is restricted to an output-device-dependent +subset of \fIreasonable\fR characters. +.h1 +.bt +\fB&ul\fI|N\fR off \fIN\(eq\fR1 E \ +Underline in \*(NR (italicize in \*(TR) the next \fIN\fR +input text lines. +Actually, switch to \fIunderline\fR font, saving the +current font for later restoration; +\fIother\fR font changes within the span of a \fBul\fR +will take effect, +but the restoration will undo the last change. +Output generated by \fBtl\fR (\(sc14) \fIis\fR affected by the +font change, but does \fInot\fR decrement \fIN\fR. +If \fIN\fR\^>\^1, there is the risk that +a trap interpolated macro may provide text +lines within the span; +environment switching can prevent this. +.bt +\fB&cu\fI|N\fR off \fIN\(eq\fR1 E \ +A variant of \fBul\fR that causes \fIevery\fR character to be underlined in \*(NR. +Identical to \fBul\fR in \*(TR. +.bt +\fB&uf\fI|F\fR Italic Italic - \ +Underline font set to \fIF\fR. +In \*(NR, +\fIF\fR may \fInot\fR be on position 1 (initially Times Roman). +.sc +Control characters. +Both the control character \fB.\fR and the \fIno-break\fR +control character \fB\'\fR may be changed, if desired. +Such a change must be compatible with the design +of any macros used in the span of the change, +and +particularly of any trap-invoked macros. +.h1 +.bt +\fB&cc\fI|c\fR \fB.\fR \fB.\fR E \ +The basic control character is set to \fIc\fR, +or reset to "\fB.\fR". +.bt +\fB&c2\fI|c\fR \fB\' \'\fR E The \fInobreak\fR control character is set +to \fIc\fR, or reset to "\fB\'\fR". +.sc +Output translation. +One character can be made a stand-in for another character using \fBtr\fR. +All text processing (e. g. character comparisons) takes place +with the input (stand-in) character which appears to have the width of the final +character. +The graphic translation occurs at the moment of output +(including diversion). +.h1 +.bt +\fB&tr\fI|abcd....\fR none - O Translate \ +\fIa\fR into \fIb\fR, \fIc\fR into \fId\fR, etc. +If an odd number of characters is given, +the last one will be mapped into the space character. +To be consistent, a particular translation +must stay in effect from \fIinput\fR to \fIoutput\fR time. +.sc +Transparent throughput. +An input line beginning with a \fB\e!\fR is read in \fIcopy mode\fR and \fItransparently\fR output +(without the initial \fB\e!\fR); +the text processor is otherwise unaware of the line's presence. +This mechanism may be used to pass control information to a post-processor +or to imbed control lines in a macro created by a diversion. +.sc +Comments and concealed newlines. +An uncomfortably long input line that must stay +one line (e. g. a string definition, or nofilled text) +can be split into many physical lines by ending all but +the last one with the escape \fB\e\fR. +The sequence \fB\e\fR(newline) is \fIalways\fR ignored\(em\ +except in a comment. +Comments may be imbedded at the \fIend\fR of any line by +prefacing them with \fB\e"\fR. +The newline at the end of a comment cannot be concealed. +A line beginning with \fB\e"\fR will appear as a blank line and +behave like \fB.sp|1\fR; +a comment can be on a line by itself by beginning the line with \fB.\e"\fR. +.mh +Local Horizontal and Vertical Motions, and the Width Function +.sc +Local Motions. +The functions \fB\ev\'\fIN\fB\|\'\fR and +\fB\eh\'\fIN\fB\|\'\fR +can be used for \fIlocal\fR vertical and horizontal motion respectively. +The distance \fIN\fR may be negative; the \fIpositive\fR directions +are \fIrightward\fR and \fIdownward\fR. +A \fIlocal\fR motion is one contained \fIwithin\fR a line. +To avoid unexpected vertical dislocations, it is necessary that +the \fInet\fR vertical local motion within a word in filled text +and otherwise within a line balance to zero. +The above and certain other escape sequences providing local motion are +summarized in the following table. +.tr || +.ds X \0\0\0 +.TS +center box; +c2|cs2||c2|cs +c1|c2c2||c2|c2c. +Vertical Effect in Horizontal Effect in +Local Motion \*(TR \*(NR Local Motion \*(TR \*(NR +_ +.sp .4 +.T& +l2|ls2||l2|ls. +\fB\*X\ev\'\fIN\|\^\fB\'\fR Move distance \fIN\fR \ +\fB\*X\eh\'\fIN\|\^\fB\'\fR Move distance \fIN\fR +.T& +_2|_2_2||l2|ls. + \fB\*X\e\fR(space) Unpaddable space-size space +.T& +l2|l2|l2||l2|ls. +\fB\*X\eu\fR \(12 em up \(12 line up \fB\*X\e0\fR Digit-size space +.T& +l2|l2|l2||_2|_2_. +\fB\*X\ed\fR \(12 em down \(12 line down +.T& +l2|l2|l2||l2|l2|l. +\fB\*X\er\fR 1 em up 1 line up \fB\*X\e\||\fR 1\(sl6 em space ignored + \fB\*X\e^\fR 1\(sl12 em space ignored +.sp .4 +.TE +.rm X +.tr | +As an example, +\fBE\s-2\v'-.4m'2\v'.4m'\s+2\fR +could be generated by the sequence +\fBE\es\-2\ev\'\-0.4m\'2\ev\'0.4m\'\es+2\fR; +it should be noted in this example that +the 0.4|em vertical motions are at the smaller size. +.sc +Width Function. +The \fIwidth\fR function \fB\ew\'\fIstring\fB\|\'\fR +generates the numerical width of \fIstring\fR (in basic units). +Size and font changes may be safely imbedded in \fIstring\fR, +and will not affect the current environment. +For example, +\&\fB.ti|\-\\w\'1.|\'u\fR could be used to +temporarily indent leftward a distance equal to the +size of the string "\fB1.|\fR". +.pg +The width function also sets three number registers. +The registers \fBst\fR and \fBsb\fR are set respectively to the highest and +lowest extent of \fIstring\fR relative to the baseline; +then, for example, +the total \fIheight\fR of the string is \fB\en(stu\-\en(sbu\fR. +In \*(TR the number register \fBct\fR is set to a value +between 0|and|3: +0 means that all of the characters in \fIstring\fR were short lower +case characters without descenders (like \fBe\fR); +1 means that at least one character has a descender (like \fBy\fR); +2 means that at least one character is tall (like \fBH\fR); +and 3 means that both tall characters and characters with +descenders are present. +.sc +Mark horizontal place. +The escape sequence \fB\ek\fIx\fR will cause the \fIcurrent\fR horizontal +position in the \fIinput line\fR to be stored in register \fIx\fR. +As an example, +the construction \fB\ekx\fIword\|\fB\eh\'\|~\|\enxu+2u\'\fIword\fB\fR +will embolden \fIword\fR by backing up to almost its beginning and overprinting it, +resulting in \kz\fIword\fR\h'|\nzu+2u'\fIword\fR. +.mh +Overstrike, Bracket, Line-drawing, and Zero-width Functions +.sc +Overstriking. +Automatically centered overstriking of up to nine characters +is provided by the \fIoverstrike\fR function +\fB\eo\'\fIstring\fB\|\'\fR. +The characters in \fIstring\fR are overprinted with centers aligned; the total width +is that of the widest character. +\fIstring\fR should \fInot\fR contain local vertical motion. +As examples, +\fB\eo\'e\e\'\'\fR produces \fB\o'e\''\fR, and +\fB\eo\'\e(mo\e(sl\'\fR produces \fB\o'\(mo\(sl'\fR. +.sc +Zero-width characters. +The function \fB\ez\fIc\fR will output \fIc\fR without spacing over +it, and can be used to produce left-aligned overstruck +combinations. +As examples, +\fB\ez\e(ci\e(pl\fR will produce \fB\z\(ci\(pl\fR, and +\fB\e(br\ez\e(rn\e(ul\e(br\fR will produce the smallest possible +constructed box \fB\(br\z\(rn\(ul\(br\fR\|. +.sc +Large Brackets. +The Special Mathematical Font contains a number of bracket construction pieces +(\|\|\|\(lt\|\|\|\(lb\|\|\|\(rt\|\|\|\(rb\|\|\|\(lk\|\|\|\(rk\|\|\|\(bv\|\|\|\(lf\|\|\|\(rf\|\|\|\(lc\|\|\|\(rc\|\|) +that can be combined into various bracket styles. +The function \fB\eb\'\fIstring\fB\|\'\fR may be used to pile +up vertically the characters in \fIstring\fR +(the first character on top and the last at the bottom); +the characters are vertically separated by 1|em and the total +pile is centered 1\(sl2\|em above the current baseline +(\(12 line in \*(NR). +For example, +\fB\eb\'\|\e(lc\e(lf\|\'E\e\|~\|\eb\'\|\e(rc\e(rf\|\'\|\ex\'\|\-0.5m\'\|\ex\'0.5m\'\|\fR +produces +\x'-.5m'\x'.5m'\fB\b'\(lc\(lf'E\|\b'\(rc\(rf'\fR. +.sc +Line drawing. +.tr && +The function \fB\e\|l\|\'\fINc\fB\|\'\fR will draw a string of repeated \fIc\fR\|'s towards the right for a distance \fIN\fR. +(\|\fB\el\fR is \fB\e\fR(lower case L). +If \fIc\fR looks like a continuation of +an expression for \fIN\fR, it may insulated from \fIN\fR with a \fB\e&\fR. +If \fIc\fR is not specified, the \fB\(ru\fR (baseline rule) is used +(underline character in \*(NR). +If \fIN\fR is negative, a backward horizontal motion +of size \fIN\fR is made \fIbefore\fR drawing the string. +Any space resulting from \fIN\fR\|\(sl(size of \fIc\fR) having a remainder is put at the beginning (left end) +of the string. +In the case of characters +that are designed to be connected such as +baseline-rule\ \fB\(ru\fR\|, +underrule\ \fB\(ul\fR\|, +and +root-en\ \fB\(rn\fR\|, +the remainder space is covered by over-lapping. +If \fIN\fR is \fIless\fR than the width of \fIc\fR, +a single \fIc\fR is centered on a distance \fIN\fR. +As an example, a macro to underscore a string can be written +.br +.tr &. +.x1 +.ft B +.ne 2.1 +&de us +\e\e$1\e\|l\|\'\|~\|0\e(ul\' +&& +.ft R +.x2 +.ne 2.1 +.de xu +\\$1\l'|0\(ul' +.. +or one to draw a box around a string +.x1 +.ft B +&de bx +\e(br\e\|~\|\e\e$1\e\|~\|\e(br\e\|l\|\'\|~\|0\e(rn\'\e\|l\|\'\|~\|0\e(ul\' +&& +.ft R +.x2 +.de bx +\(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul' +.. +such that +.x1 +.ft B +&us "underlined words" +.ft R +.x2 +and +.x1 +.ft B +&bx "words in a box" +.ft R +.x2 +yield +.xu "underlined words" +and +.bx "words in a box" +\h'-\w'.'u'. +.pg +The function \fB\eL\'\|\fINc\fB\|\'\fR will draw a vertical line consisting +of the (optional) character \fIc\fR stacked vertically apart 1\|em +(1 line in \*(NR), +with the first two characters overlapped, +if necessary, to form a continuous line. +The default character is the \fIbox rule\fR |\(br| (\fB\|\e(br\fR); +the other suitable character is the \fIbold vertical\fR \|\(bv\| (\fB\|\e(bv\fR). +The line is begun without any initial motion relative to the +current base line. +A positive \fIN\fR specifies a line drawn downward and +a negative \fIN\fR specifies a line drawn upward. +After the line is drawn \fIno\fR compensating +motions are made; +the instantaneous baseline is at the \fIend\fR of the line. +.pg +.de eb +.sp -1 +.nf +\h'-.5n'\L'|\\nzu-1'\l'\\n(.lu+1n\(ul'\L'-|\\nzu+1'\l'|0u-.5n\(ul' +.fi +.. +.ne 2i +.mk z +The horizontal and vertical line drawing functions may be used +in combination to produce large boxes. +The zero-width \fIbox-rule\fR and the \(12-em wide \fIunderrule\fR +were \fIdesigned\fR to form corners when using 1-em vertical +spacings. +For example the macro +.x1 +.ft B +\&.de eb +\&.sp \-1 \e"compensate for next automatic base-line spacing +\&.nf \e"avoid possibly overflowing word buffer +.tr || +\&\eh\'\-.5n\'\eL\'\||\|\e\enau\-1\'\el\'\e\en(.lu+1n\e(ul\'\eL\'\-\||\|\e\enau+1\'\el\'\||\|0u\-.5n\e(ul\' \e"draw box +.tr | +.lg 0 +\&.fi +.lg +\&.. +.ft R +.x2 +will draw a box around some text whose beginning vertical place was +saved in number register \fIa\fR +(e. g. using \fB.mk|a\fR) +as done for this paragraph. +.eb diff --git a/share/doc/usd/21.troff/m4 b/share/doc/usd/21.troff/m4 new file mode 100644 index 000000000000..b8e69046f095 --- /dev/null +++ b/share/doc/usd/21.troff/m4 @@ -0,0 +1,412 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.tr | +.mh +Hyphenation. +.pg +The automatic hyphenation may be switched off and on. +When switched on with \fBhy\fR, +several variants may be set. +A \fIhyphenation indicator\fR character may be imbedded in a word to +specify desired hyphenation points, +or may be prepended to suppress hyphenation. +In addition, +the user may specify a small exception word list. +.pg +Only words that consist of a central alphabetic string +surrounded by (usually null) non-alphabetic strings +are considered candidates for automatic hyphenation. +Words that were input containing hyphens +(minus), +em-dashes (\fB\e(em\fR), +or hyphenation indicator characters\ +\(emsuch as mother-in-law\(em\ +are \fIalways\fR subject to splitting after those characters, +whether or not automatic hyphenation is on or off. +.h1 +.bt +\fB&nh\fR hyphenate - E \ +Automatic hyphenation is turned off. +.bt +\fB&hy\fIN\fR on,\fIN=\fR1 on,\fIN=\fR1 E \ +Automatic hyphenation is turned on +for \fIN\fR\|\(>=1, or off for \fIN=\fR\|0. +If \fIN=\fR\|2, \fIlast\fR lines (ones that will cause a trap) +are not hyphenated. +For \fIN=\fR\|4 and 8, the last and first two characters +respectively of a word are not split off. +These values are additive; +i.|e. \fIN=\fR\|14 will invoke all three restrictions. +.bt +\fB&hc\fI|c\fR \fB\e% \e%\fR E Hyphenation indicator character is set +to \fIc\fR or to the default \fB\e%\fR. +The indicator does not appear in the output. +.bt +\fB&hw\fI|word1|...\fR ignored - Specify hyphenation points in words +with imbedded minus signs. +Versions of a word with terminal \fIs\fR are implied; +i.|e. \fIdig\-it\fR implies \fIdig\-its\fR. +This list is examined initially \fIand\fR after +each suffix stripping. +The space available is small\(emabout 128 characters. +.mh +Three Part Titles. +.pg +The titling function \fBtl\fR provides for automatic placement +of three fields at the left, center, and right of a line +with a title-length +specifiable with \fBlt\fR. +\fBtl\fR may be used anywhere, and is independent of the +normal text collecting process. +A common use is in header and footer macros. +.h1 +.bt +\fB&tl\fI|\'left\|\'center\|\'right\|\'\fR - - \ +The strings \fIleft\fR, \fIcenter\fR, and \fIright\fR are +respectively left-adjusted, centered, and right-adjusted +in the current title-length. +Any of the strings may be empty, +and overlapping is permitted. +If the page-number character (initially \fB%\fR) is found within any of the fields it is replaced +by the current page number having the format assigned to register \fB%\fR. +Any character may be used as the string delimiter. +.bt +\fB&pc\fI|c\fR \fB%\fR off - The page number character is set to \fIc\fR, +or removed. +The page-number register remains \fB%\fR. +.bt +\fB<\fI|\(+-N\fR 6.5\|in previous E,\fBm\fR Length of title set to \fI\(+-N\fR. +The line-length and the title-length are \fIindependent\fR. +Indents do not apply to titles; page-offsets do. +.mh +Output Line Numbering. +.pg +.ll -\w'0000'u +.nm 1 3 +Automatic sequence numbering of output lines may be +requested with \fBnm\fR. +When in effect, +a three-digit, arabic number plus a digit-space +is prepended to output text lines. +The text lines are thus offset by four digit-spaces, +and otherwise retain their line length; +a reduction in line length may be desired to keep the right margin +aligned with an earlier margin. +Blank lines, other vertical spaces, and lines generated by \fBtl\fR +are \fInot\fR numbered. +Numbering can be temporarily suspended with \fBnn\fR, +or with an \fB.nm\fR followed by a later \fB.nm|+0\fR. +In addition, +a line number indent \fII\fR, and the number-text separation \fIS\fR +may be specified in digit-spaces. +Further, it can be specified that only those line numbers that are +multiples of some number \fIM\fR are to be printed (the others will appear +as blank number fields). +.br +.nm +.ll +.h1 +.bt +\fB&nm\fI|\(+-N|M|S|I\fR off E \ +Line number mode. +If \fI\(+-N\fR is given, +line numbering is turned on, +and the next output line numbered is numbered \fI\(+-N\fR. +Default values are \fIM=\fR\|1, \fIS=\fR\|1, and \fII=\fR\|0. +Parameters corresponding to missing arguments are unaffected; +a non-numeric argument is considered missing. +In the absence of all arguments, numbering is turned off; +the next line number is preserved for possible further use +in number register \fBln\fR. +.bt +\fB&nn\fI|N\fR - \fIN=\fR1 E The next \fIN\fR text output lines are not +numbered. +.pg +.ll -\w'0000'u +.nm +0 +As an example, the paragraph portions of this section +are numbered with \fIM=\fR\|3: +\&\fB.nm|1|3\fR was placed at the beginning; +\&\fB.nm\fR was placed at the end of the first paragraph; +and \fB.nm|+0\fR was placed in front of this paragraph; +and \fB.nm\fR finally placed at the end. +Line lengths were also changed (by \fB\ew\'0000\'u\fR) to keep the right side aligned. +Another example is +\&\fB.nm|+5|5|x|3\fR which turns on numbering with the line number of the next +line to be five greater than the last numbered line, +with \fIM=\fR\|5, with spacing \fIS\fR untouched, and with the indent \fII\fR set to 3. +.br +.ll +.nm +.mh +Conditional Acceptance of Input +.pg +In the following, +\fIc\fR is a one-character, built-in \fIcondition\fR name, +\fB!\fR signifies \fInot\fR, +\fIN\fR is a numerical expression, +\fIstring1\fR and \fIstring2\fR are strings delimited by any non-blank, non-numeric character \fInot\fR in the strings, +and +\fIanything\fR represents what is conditionally accepted. +.h1 +.bt +\fB&if\fI|c|anything\fR - - If condition \fIc\fR true, accept \fIanything\fR as input; +in multi-line case use \fI\e{anything\|\e}\fR. +.bt +\fB&if|!\fIc|anything\fR - - If condition \fIc\fR false, accept \fIanything\fR. +.bt +\fB&if\fI|N|anything\fR - \fBu\fR If expression \fIN\fR > 0, accept \fIanything\fR. +.bt +\fB&if|!\fIN|anything\fR - \fBu\fR If expression \fIN\fR \(<= 0, accept \fIanything\fR. +.bt +\fB&if\fI|\|\'string1\|\'string2\|\'|anything\fR - If \fIstring1\fR identical to \fIstring2\fR, +accept \fIanything\fR. +.bt +\fB&if|!\fI\|\'string1\|\'string2\|\'|anything\fR - If \fIstring1\fR not identical to \fIstring2\fR, +accept \fIanything\fR. +.bt +\fB&ie\fI|c|anything\fR - \fBu\fR If portion of if-else; all above forms (like \fBif\fR). +.bt +\fB&el\fI|anything\fR - - Else portion of if-else. +.pg +The built-in condition names are: +.TS +center box; +c2|c +c2|c +c2|l. +Condition +Name True If +_ +\fBo\fR Current page number is odd +\fBe\fR Current page number is even +\fBt\fR Formatter is \*(TR +\fBn\fR Formatter is \*(NR +.TE +If the condition \fIc\fR is \fItrue\fR, or if the number \fIN\fR is greater than zero, +or if the strings compare identically (including motions and character size and font), +\fIanything\fR is accepted as input. +If a \fB!\fR precedes the condition, number, or string comparison, +the sense of the acceptance is reversed. +.pg +Any spaces between the condition and the beginning of \fIanything\fR are skipped over. +The \fIanything\fR can be either a single input line (text, macro, or whatever) +or a number of input lines. +In the multi-line case, +the first line must begin with a left delimiter \fB\e{\fR and +the last line must end with a right delimiter \fB\e}\fR. +.pg +The request \fBie\fR (if-else) is identical to \fBif\fR +except that the acceptance state is remembered. +A subsequent and matching \fBel\fR (else) request then uses the reverse sense of that state. +\fBie\fR|-|\fBel\fR pairs may be nested. +.pg +Some examples are: +.x1 +.ft B +.ne 1 +&if e .tl \'\|Even Page %\'\'\' +.ft R +.x2 +which outputs a title if the page number is even; and +.x1 +.ft B +.ne 3.1 +&ie \en%>1 \e{\e +\&\'sp 0.5i +&tl \'\|Page %\'\'\' +\&\'sp ~\|1.2i|\e} +&el .sp ~\|2.5i +.ft R +.x2 +which treats page 1 differently from other pages. +.mh +Environment Switching. +.pg +A number of the parameters that +control the text processing are gathered together into an +\fIenvironment\fR, which can be switched by the user. +The environment parameters are those associated +with requests noting E in their \fINotes\fR column; +in addition, partially collected lines and words are in the environment. +Everything else is global; examples are page-oriented parameters, +diversion-oriented parameters, number registers, and macro and string definitions. +All environments are initialized with default parameter values. +.h1 +.bt +\fB&ev\fI|N\fR \fIN\(eq\fR0 previous - Environment switched to +environment 0\(<=\fIN\fR\(<=2. +Switching is done in push-down fashion so that +restoring a previous environment \fImust\fR be done with \fB.ev\fR +rather than specific reference. +.mh +Insertions from the Standard Input +.pg +The input can be temporarily switched to the system \fIstandard input\fR +with \fBrd\fR, +which will switch back when \fItwo\fR newlines +in a row are found (the \fIextra\fR blank line is not used). +This mechanism is intended for insertions in form-letter-like documentation. +On \s-1UNIX\s+1, the \fIstandard input\fR can be the user's keyboard, +a \fIpipe\fR, or a \fIfile\fR. +.h1 +.bt +\fB&rd\fI|prompt\fR - \fIprompt=\fR\s-1BEL\s+1 \ +Read insertion from the standard input until two newlines in a row are found. +If the standard input is the user's keyboard, \fIprompt\fR (or a \s-1BEL\s+1) +is written onto the user's terminal. +\fBrd\fR behaves like a macro, +and arguments may be placed after \fIprompt\fR. +.bt +\fB&ex\fR - - - Exit from \*(NR\(sl\*(TR. +Text processing is terminated exactly as if all input had ended. +.pg +If insertions are to be +taken from the terminal keyboard \fIwhile\fR output is being printed +on the terminal, the command line option \fB\-q\fR will turn off the echoing +of keyboard input and prompt only with \s-1BEL\s+1. +The regular input and insertion input \fIcannot\fR +simultaneously come from the standard input. +.pg +As an example, +multiple copies of a form letter may be prepared by entering the insertions +for all the copies in one file to be used as the standard input, +and causing the file containing the letter to reinvoke itself using \fBnx\fR (\(sc19); +the process would ultimately be ended by an \fBex\fR in the insertion file. +.mh +Input\(slOutput File Switching +.pg +The (read-only) number register \fB.c\fR contains the input line number in +the current input file. The number register \fBc.\fR is a general register +serving the same purpose. +.h1 +.bt +\fB&so\fI|filename\fR - - Switch source file. +The top input (file reading) level is switched to \fIfilename\fR. +The effect of an \fBso\fR encountered in a macro +occurs immediately. +When the new file ends, +input is again taken from the original file. +\fBso\fR's may be nested. +.bt +\fB&nx\fI|filename\fR end-of-file - Next file is \fIfilename\fR. +The current file is considered ended, and the input is immediately switched +to \fIfilename\fR. +.bt +\fB&pi\fI|program\fR - - Pipe output to \fIprogram\fR (\*(NR only). +This request must occur \fIbefore\fR any printing occurs. +No arguments are transmitted to \fIprogram\fR. +.mh +Miscellaneous +.pg +.h1 +.bt +.mc \s12\(br\s0 +\fB&mc\fI|c|N\fR - off E,\fBm\fR \ +Specifies that a \fImargin\fR character \fIc\fR appear a distance +\fIN\fR to the right of the right margin +after each non-empty text line (except those produced by \fBtl\fR). +If the output line is too-long (as can happen in nofill mode) +the character will be appended to the line. +If \fIN\fR is not given, the previous \fIN\fR is used; the initial \fIN\fR is +0.2|inches in \*(NR and 1\|em in \*(TR. +The margin character used with this paragraph was a 12-point box-rule. +.br +.mc +.bt +\fB&tm\fI|string\fR - newline - \ +After skipping initial blanks, \fIstring\fR (rest of the line) is read in \fIcopy mode\fR +and written on the user's terminal. (see \(sc21). +.bt +\fB&ig\fI|yy\fR - \fI.yy=\fB..\fR - Ignore \ +input lines. +\fBig\fR behaves exactly like \fBde\fR (\(sc7) except that the +input is discarded. +The input is read in \fIcopy mode\fR, and any auto-incremented +registers will be affected. +.bt +\fB&pm\fI|t\fR - all - \ +Print macros. +The names and sizes of all of the defined macros and strings are printed +on the user's terminal; +if \fIt\fR is given, only the total of the sizes is printed. +The sizes is given in \fIblocks\fR +of 128 characters. +.bt +\fB&ab\fI|string\fR - - - \ +Print \fIstring\fR on standard error and terminate immediately. The +default \fIstring\fR is "User Abort". Does not cause a break. Only output +preceding the last break is written. +.bt +.lg 0 +\fB&fl\fR - - B \c +.lg +Flush output buffer. +Used in interactive debugging to force output. +.mh +Output and Error Messages. +.pg +The output from \fBtm\fR, \fBpm\fR, \fBab\fR and the prompt from \fBrd\fR, +as well as various \fIerror\fR messages are written onto +\s-1UNIX\s+1's \fIstandard error\fR output. +The latter is different from the \fIstandard output\fR, +where \*(NR formatted output goes. +By default, both are written onto the user's terminal, +but they can be independently redirected. +.pg +Various \fIerror\fR conditions may occur during +the operation of \*(NR and \*(TR. +Certain less serious errors having only local impact do not +cause processing to terminate. +Two examples are \fIword overflow\fR, caused by a word that is too large +to fit into the word buffer (in fill mode), and +\fIline overflow\fR, caused by an output line that grew too large +to fit in the line buffer; +in both cases, a message is printed, the offending excess +is discarded, +and the affected word or line is marked at the point of truncation +with a \(** in \*(NR and a \(lh in \*(TR. +The philosophy is to continue processing, if possible, +on the grounds that output useful for debugging may be produced. +If a serious error occurs, processing terminates, +and an appropriate message is printed. +Examples are the inability to create, read, or write files, +and the exceeding of certain internal limits that +make future output unlikely to be useful. +.ps 10 +.vs 12 +.ft R +.bp diff --git a/share/doc/usd/21.troff/m5 b/share/doc/usd/21.troff/m5 new file mode 100644 index 000000000000..3cffc2468ab2 --- /dev/null +++ b/share/doc/usd/21.troff/m5 @@ -0,0 +1,458 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.ds H T +.tr | +.tr ~| +.de x1 +.xx +.ft B +.in .2i +.nf +.ne 2.1 +.ta 1i +.. +.de x2 +.fi +.in 0 +.ft R +.xx +.. +.br +.ce +.ft B +.rs +.sp 0.5i +TUTORIAL EXAMPLES +.ft R +.sp 2 +.nr p 0 +.2C +.ns +.mh +.mk +Introduction +.pg +Although \*(NR and \*(TR +have by design a syntax reminiscent +of earlier text processors* +.fn +.xx +*For example: +P.|A.|Crisman, Ed., +.ul +The Compatible Time-Sharing System, +MIT Press, 1965, Section|AH9.01 +(Description of RUNOFF program on MIT's CTSS system). +.ef +with the intent of easing their use, +it is almost always necessary to +prepare at least a small set of macro definitions +to describe most documents. +Such common formatting needs +as page margins and footnotes +are deliberately not built into \*(NR and \*(TR. +Instead, +the macro and string definition, number register, diversion, +environment switching, page-position trap, and conditional input mechanisms +provide the basis for user-defined implementations. +.pg +The examples to be discussed are intended to be useful and somewhat realistic, +but won't necessarily cover all relevant contingencies. +Explicit numerical parameters are used +in the examples +to make them easier to read and to +illustrate typical values. +In many cases, number registers would really be used +to reduce the number of places where numerical +information is kept, +and to concentrate conditional parameter initialization +like that which depends on whether \*(TR or \*(NR is being used. +.mh +Page Margins +.pg +As discussed in \(sc3, +\fIheader\fR and \fIfooter\fR macros are usually defined +to describe the top and bottom page margin areas respectively. +A trap is planted at page position 0 for the header, and at +\fI\-N\fR (\fIN\fR from the page bottom) for the footer. +The simplest such definitions might be +.x1 +&de hd \e"define header +\'sp 1i +&& \e"end definition +&de fo \e"define footer +\'bp +&& \e"end definition +&wh 0 hd +&wh \-1i fo +.x2 +which provide blank 1|inch top and bottom margins. +The header will occur on the \fIfirst\fR page, +only if the definition and trap exist prior to +the initial pseudo-page transition (\(sc3). +In fill mode, the output line that springs the footer trap +was typically forced out because some part or whole word didn't fit on it. +If anything in the footer and header that follows causes a \fIbreak\fR, +that word or part word will be forced out. +In this and other examples, +requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using +the \fIno-break\fR control character \fB\'\fR +to avoid this. +When the header\(slfooter design contains material +requiring independent text processing, the +environment may be switched, avoiding +most interaction with the running text. +.pg +A more realistic example would be +.x1 +&de hd \e"header +&if t .tl \'\|\e(rn\'\'\e(rn\' \e"troff cut mark +&if \e\en%>1 \e{\e +\'sp ~\|0.5i\-1 \e"tl base at 0.5i +&tl \'\'\- % \-\'\' \e"centered page number +&ps \e"restore size +&ft \e"restore font +&vs \e} \e"restore vs +\'sp ~\|1.0i \e"space to 1.0i +&ns \e"turn on no-space mode +&& +&de fo \e"footer +&ps 10 \e"set footer\(slheader size +&ft R \e"set font +&vs 12p \e"set base-line spacing +&if \e\en%=1 \e{\e +\'sp ~\|\e\en(.pu\-0.5i\-1 \e"tl base 0.5i up +&tl \'\'\- % \-\'\' \e} \e"first page number +\'bp +&& +&wh 0 hd +&wh \-1i fo +.x2 +which sets the size, font, and base-line spacing for the +header\(slfooter material, and ultimately restores them. +The material in this case is a page number at the bottom of the +first page and at the top of the remaining pages. +If \*(TR is used, a \fIcut mark\fR is drawn in the form +of \fIroot-en\fR's at each margin. +The \fBsp\fR's refer to absolute positions to avoid +dependence on the base-line spacing. +Another reason for this in the footer +is that the footer is invoked by printing a line whose +vertical spacing swept past the trap position by possibly +as much as the base-line spacing. +The \fIno-space\fR mode is turned on at the end of \fBhd\fR +to render ineffective +accidental occurrences of \fBsp\fR at the top of the running text. +.pg +The above method of restoring size, font, etc. presupposes +that such requests (that set \fIprevious\fR value) are \fInot\fR +used in the running text. +A better scheme is save and restore both the current \fIand\fR +previous values as shown for size in the following: +.x1 +&de fo +&nr s1 \e\en(.s \e"current size +&ps +&nr s2 \e\en(.s \e"previous size +& --- \e"rest of footer +&& +&de hd +& --- \e"header stuff +&ps \e\en(s2 \e"restore previous size +&ps \e\en(s1 \e"restore current size +&& +.x2 +Page numbers may be printed in the bottom margin +by a separate macro triggered during the footer's +page ejection: +.x1 +&de bn \e"bottom number +&tl \'\'\- % \-\'\' \e"centered page number +&& +&wh \-0.5i\-1v bn \e"tl base 0.5i up +.x2 +.mh +Paragraphs and Headings +.pg +The housekeeping +associated with starting a new paragraph should be collected +in a paragraph macro +that, for example, +does the desired preparagraph spacing, +forces the correct font, size, base-line spacing, and indent, +checks that enough space remains for \fImore than one\fR line, +and +requests a temporary indent. +.x1 +&de pg \e"paragraph +&br \e"break +&ft R \e"force font, +&ps 10 \e"size, +&vs 12p \e"spacing, +&in 0 \e"and indent +&sp 0.4 \e"prespace +&ne 1+\e\en(.Vu \e"want more than 1 line +&ti 0.2i \e"temp indent +&& +.x2 +The first break in \fBpg\fR +will force out any previous partial lines, +and must occur before the \fBvs\fR. +The forcing of font, etc. is +partly a defense against prior error and +partly to permit +things like section heading macros to +set parameters only once. +The prespacing parameter is suitable for \*(TR; +a larger space, at least as big as the output device vertical resolution, would be +more suitable in \*(NR. +The choice of remaining space to test for in the \fBne\fR +is the smallest amount greater than one line +(the \fB.V\fR is the available vertical resolution). +.pg +A macro to automatically number section headings +might look like: +.x1 +&de sc \e"section +& --- \e"force font, etc. +&sp 0.4 \e"prespace +&ne 2.4+\e\en(.Vu \e"want 2.4+ lines +.lg 0 +&fi +.lg +\e\en+S. +&& +&nr S 0 1 \e"init S +.x2 +The usage is \fB.sc\fR, +followed by the section heading text, +followed by \fB.pg\fR. +The \fBne\fR test value includes one line of heading, +0.4 line in the following \fBpg\fR, and +one line of the paragraph text. +A word consisting of the next section number and a period is +produced to begin the heading line. +The format of the number may be set by \fBaf\fR (\(sc8). +.pg +Another common form is the labeled, indented paragraph, +where the label protrudes left into the indent space. +.x1 +&de lp \e"labeled paragraph +&pg +&in 0.5i \e"paragraph indent +&ta 0.2i 0.5i \e"label, paragraph +&ti 0 +\et\e\e$1\et\ec \e"flow into paragraph +&& +.x2 +The intended usage is "\fB.lp\fR \fIlabel\fR\|"; +\fIlabel\fR will begin at 0.2\|inch, and +cannot exceed a length of 0.3\|inch without intruding into +the paragraph. +The label could be right adjusted against 0.4\|inch by +setting the tabs instead with \fB.ta|0.4iR|0.5i\fR. +The last line of \fBlp\fR ends with \fB\ec\fR so that +it will become a part of the first line of the text +that follows. +.mh +Multiple Column Output +.pg +The production of multiple column pages requires +the footer macro to decide whether it was +invoked by other than the last column, +so that it will begin a new column rather than +produce the bottom margin. +The header can initialize a column register that +the footer will increment and test. +The following is arranged for two columns, but +is easily modified for more. +.x1 +&de hd \e"header +& --- +&nr cl 0 1 \e"init column count +&mk \e"mark top of text +&& +&de fo \e"footer +&ie \e\en+(cl<2 \e{\e +&po +3.4i \e"next column; 3.1+0.3 +&rt \e"back to mark +&ns \e} \e"no-space mode +&el \e{\e +&po \e\enMu \e"restore left margin +& --- +\'bp \e} +&& +&ll 3.1i \e"column width +&nr M \e\en(.o \e"save left margin +.x2 +Typically a portion of the top of the first page +contains full width text; +the request for the narrower line length, +as well as another \fB.mk\fR would +be made where the two column output was to begin. +.mh +Footnote Processing +.pg +The footnote mechanism to be described is used by +imbedding the footnotes in the input text at the +point of reference, +demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR: +.x1 +&fn +\fIFootnote text and control lines...\fP +&ef +.x2 +In the following, +footnotes are processed in a separate environment and diverted +for later printing in the space immediately prior to the bottom +margin. +There is provision for the case where the last collected +footnote doesn't completely fit in the available space. +.x1 +&de hd \e"header +& --- +&nr x 0 1 \e"init footnote count +&nr y 0\-\e\enb \e"current footer place +&ch fo \-\e\enbu \e"reset footer trap +&if \e\en(dn .fz \e"leftover footnote +&& +&de fo \e"footer +&nr dn 0 \e"zero last diversion size +&if \e\enx \e{\e +&ev 1 \e"expand footnotes in ev1 +&nf \e"retain vertical size +&FN \e"footnotes +&rm FN \e"delete it +&if "\e\en(.z"fy" .di \e"end overflow diversion +&nr x 0 \e"disable fx +&ev \e} \e"pop environment +& --- +\'bp +&& +&de fx \e"process footnote overflow +&if \e\enx .di fy \e"divert overflow +&& +&de fn \e"start footnote +&da FN \e"divert (append) footnote +&ev 1 \e"in environment 1 +&if \e\en+x=1 .fs \e"if first, include separator +.lg 0 +&fi \e"fill mode +.lg +&& +&de ef \e"end footnote +&br \e"finish output +&nr z \e\en(.v \e"save spacing +&ev \e"pop ev +&di \e"end diversion +&nr y \-\e\en(dn \e"new footer position, +&if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e + \e"uncertainty correction +&ch fo \e\enyu \e"y is negative +&if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e +&ch fo \e\en(nlu+1v \e"it didn't fit +&& +&de fs \e"separator +\el\'\|1i\' \e"1 inch rule +&br +&& +&de fz \e"get leftover footnote +&fn +&nf \e"retain vertical size +&fy \e"where fx put it +&ef +&& +&nr b 1.0i \e"bottom margin size +&wh 0 hd \e"header trap +&wh 12i fo \e"footer trap, temp position +&wh \-\e\enbu fx \e"fx at footer position +&ch fo \-\e\enbu \e"conceal fx with fo +.x2 +The header \fBhd\fR initializes a footnote count register \fBx\fR, +and sets both the current footer trap position register \fBy\fR and +the footer trap itself to a nominal position specified in +register \fBb\fR. +In addition, if the register \fBdn\fR indicates a leftover footnote, +\fBfz\fR is invoked to reprocess it. +The footnote start macro \fBfn\fR begins a diversion (append) in environment 1, +and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR +is interpolated. +The separator is kept in a separate macro to permit user redefinition. +The footnote end macro \fBef\fR restores +the previous environment and ends the diversion after saving the spacing size in register \fBz\fR. +\fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR; +then on the first footnote, \fBy\fR is further decremented by the difference +in vertical base-line spacings of the two environments, to +prevent the late triggering the footer trap from causing the last +line of the combined footnotes to overflow. +The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR) +plus one line, to allow for printing the reference line. +If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode +in environment 1, +and deletes \fBFN\fR. +If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert +the overflow into \fBfy\fR, +and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty. +Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order +that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved. +The footer then terminates the overflow diversion, if necessary, and +zeros \fBx\fR to disable \fBfx\fR, +because the uncertainty correction +together with a not-too-late triggering of the footer can result +in the footnote rereading finishing before reaching the \fBfx\fR trap. +.pg +A good exercise for the student is to combine the multiple-column and footnote mechanisms. +.mh +The Last Page +.pg +After the last input file has ended, \*(NR and \*(TR +invoke the \fIend macro\fR (\(sc7), if any, +and when it finishes, eject the remainder of the page. +During the eject, any traps encountered are processed normally. +At the \fIend\fR of this last page, processing terminates +\fIunless\fR a partial line, word, or partial word remains. +If it is desired that another page be started, the end-macro +.x1 +&de en \e"end-macro +\ec +\'bp +&& +&em en +.x2 +will deposit a null partial word, +and effect another last page. +.1C +'bp diff --git a/share/doc/usd/21.troff/table1 b/share/doc/usd/21.troff/table1 new file mode 100644 index 000000000000..90806f8ca7dd --- /dev/null +++ b/share/doc/usd/21.troff/table1 @@ -0,0 +1,125 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.pn 30 +.rm mx +.br +.tr && +.tr || +.tr ~~ +.de aa +.nf +abcdefghijklmnopqrstuvwxyz +ABCDEFGHIJKLMNOPQRSTUVWXYZ +1234567890 +.ss 9 +! $ % & ( ) ` ' * + \- . , / : ; = ? [ ] | +.fi +\(bu \(sq \(em \(hy \(ru \(14 \(12 \(34 \(fi \(fl \(ff +\(Fi \(Fl +\(de \(dg \(fm +\(ct \(rg \(co +.ss 12 +.. +.de bb +.ss 9 +.fi +.ll 5i +" \' \e ^ \_ \` ~ \(sl < > { } # @ \(pl \(mi \(eq \(** +.br +\(*a \(*b \(*g \(*d \(*e \(*z \(*y \(*h \(*i \(*k \(*l \(*m +\(*n \(*c \(*o \(*p \(*r \(*s \(ts \(*t \(*u \(*f \(*x \(*q \(*w +.br +\(*G \(*D \(*H \(*L \(*C \(*P \(*S \(*U \(*F \(*Q \(*W +.br +\(sr \(rn \(>= \(<= \(== \(ap \(~= \(!= +\(-> \(<- \(ua \(da \(mu +\(di \(+- \(cu \(ca \(sb \(sp \(ib \(ip \(if \(pd +.br +\(sc \(gr \(no \(is \(pt \(es \(mo +\(dd \(rh \(lh \(or \(ci +\(lt \(lb \(rt \(rb \(lk \(rk \(bv \(lf \(rf \(lc \(rc +\(br +.br +.ss 12 +.nf +.. +.nf +.ps 12 +.vs 14p +.ft B +.ce +.sp 3 +Table I +.sp +.ce +Font Style Examples +.sp .5i +.ft R +.ps 10 +.fi +.vs 12p +.na +The following fonts are printed in 12-point, with a vertical spacing of 14-point, +and with +non-alphanumeric characters separated by \(14\|em space (all measurements +on 8.5 \(mu 11 inch paper prior to photoreduction). +This font sample is printed on an Apple Laserwriter +at University of California, Berkeley. +.sp .5i +.ps 12 +.vs 14p +.ft R +Times Roman +.sp .5 +.aa +.sp +.ft I +Times Italic +.sp .5 +.aa +.sp +.ft B +Times Bold +.sp .5 +.aa +.sp +.ft R +Special Mathematical Font +.sp .5 +.fi +.ll 5i +.bb +.bp diff --git a/share/doc/usd/21.troff/table2 b/share/doc/usd/21.troff/table2 new file mode 100644 index 000000000000..560441481d2d --- /dev/null +++ b/share/doc/usd/21.troff/table2 @@ -0,0 +1,250 @@ +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.sp 100 +.br +.de mx +.nf +.ft I +.ta .25iC .5i +.45i 3.25iC +.25i +.45i + Input Character Input Character + Char Name Name Char Name Name +.ft R +.sp .2 +.nr cl 0 +.mk +.. +.br +.tr ~~ +.nf +.ps 12 +.vs 14p +.ft B +.ce +Table II +.sp +.ce 2 +Input Naming Conventions for \', \`, and \- +and for Non-ASCII Special Characters +.sp .5i +.ft R +.ps 10 +.vs 12p +.ft B +.bd I 3 +Non-\s-1ASCII\s+1 characters and \fIminus\fP on the standard fonts. +.sp +.ft R +.de cl +.ie \\n+(cl<2 \{\ +.po +3.0i +.rt +.\} +.el .sc +.. +.de sc +.po 26i/27u +.nr cl 0 +.. +.nr cl 0 1 +.de qq + \&' \' close quote + ` \` open quote + \(em \e\|(em 3\(sl4 Em dash + - \- hyphen or + \(hy \e\|(hy hyphen + \- \e\- current font minus + \(bu \e\|(bu bullet + \(sq \e\|(sq square + \(ru \e\|(ru rule + \(14 \e\|(14 1\(sl4 + \(12 \e\|(12 1\(sl2 + \(34 \e\|(34 3\(sl4 + \(fi \e\|(fi fi + \(fl \e\|(fl fl + \(ff \e\|(ff ff + \(Fi \e\|(Fi ffi + \(Fl \e\|(Fl ffl + \(de \e\|(de degree + \(dg \e\|(dg dagger + \(fm \e\|(fm foot mark + \(ct \e\|(ct cent sign + \(rg \e\|(rg registered + \(co \e\|(co copyright +.. +.di zz +.lg 0 +.qq +.di +.lg +.mx +.nr aa \n(dn/2 +.ne \n(aau+1 +.nr bb \n(nl+\n(aa +.wh \n(bbu cl +.qq +.sp |\n(bbu +.ch cl 12i +.fi +.sp 2 +.ft B +.bd I +Non-\s-1ASCII\s+1 characters and \', \`, \_\|, \(pl, \(mi, \(eq, and \(** on the special font. +.sp .4 +.ft R +.fi +.ps 10 +The ASCII characters @, #, ", \', \`, <, >, \\, {, }, ~, ^, and \(ul exist +\fIonly\fR on the special font and are printed as a 1-em space if that font +is not mounted. +The following characters exist only on the special font except +for the upper case Greek letter names followed by \(dg which are mapped into +upper case English letters in +whatever font is mounted on font position one (default Times Roman). +The special math plus, minus, and equals are provided to +insulate the appearance of equations from the choice of standard fonts. +.bd I 3 +.nf +.ps 10 +.sp +.ch cl \nmu-\n(.vu-1u +.mx +.lg 0 + \(pl \e\|(pl math plus + \(mi \e\|(mi math minus + \(eq \e\|(eq math equals + \(** \e\|(** math star + \(sc \e\|(sc section + \(aa \e\|(aa acute accent + \(ga \e\|(ga grave accent + \(ul \e\|(ul underrule + \(sl \e\|(sl slash (matching backslash) + \(*a \e\|(*a alpha + \(*b \e\|(*b beta + \(*g \e\|(*g gamma + \(*d \e\|(*d delta + \(*e \e\|(*e epsilon + \(*z \e\|(*z zeta + \(*y \e\|(*y eta + \(*h \e\|(*h theta + \(*i \e\|(*i iota + \(*k \e\|(*k kappa + \(*l \e\|(*l lambda + \(*m \e\|(*m mu + \(*n \e\|(*n nu + \(*c \e\|(*c xi + \(*o \e\|(*o omicron + \(*p \e\|(*p pi + \(*r \e\|(*r rho + \(*s \e\|(*s sigma + \(ts \e\|(ts terminal sigma + \(*t \e\|(*t tau + \(*u \e\|(*u upsilon + \(*f \e\|(*f phi + \(*x \e\|(*x chi + \(*q \e\|(*q psi + \(*w \e\|(*w omega + \(*A \e\|(*A Alpha\(dg + \(*B \e\|(*B Beta\(dg + \(*G \e\|(*G Gamma + \(*D \e\|(*D Delta + \(*E \e\|(*E Epsilon\(dg + \(*Z \e\|(*Z Zeta\(dg + \(*Y \e\|(*Y Eta\(dg + \(*H \e\|(*H Theta + \(*I \e\|(*I Iota\(dg + \(*K \e\|(*K Kappa\(dg + \(*L \e\|(*L Lambda + \(*M \e\|(*M Mu\(dg + \(*N \e\|(*N Nu\(dg + \(*C \e\|(*C Xi + \(*O \e\|(*O Omicron\(dg + \(*P \e\|(*P Pi + \(*R \e\|(*R Rho\(dg + \(*S \e\|(*S Sigma + \(*T \e\|(*T Tau\(dg + \(*U \e\|(*U Upsilon + \(*F \e\|(*F Phi + \(*X \e\|(*X Chi\(dg + \(*Q \e\|(*Q Psi + \(*W \e\|(*W Omega + \(sr \e\|(sr square root + \(rn \e\|(rn root en extender + \(>= \e\|(>= >= + \(<= \e\|(<= <= + \(== \e\|(== identically equal + \(~= \e\|(~= approx = + \(ap \e\|(ap approximates + \(!= \e\|(!= not equal + \(-> \e\|(\(mi> right arrow + \(<- \e\|(<\(mi left arrow + \(ua \e\|(ua up arrow + \(da \e\|(da down arrow + \(mu \e\|(mu multiply + \(di \e\|(di divide + \(+- \e\|(+\(mi plus-minus + \(cu \e\|(cu cup (union) + \(ca \e\|(ca cap (intersection) + \(sb \e\|(sb subset of + \(sp \e\|(sp superset of + \(ib \e\|(ib improper subset + \(ip \e\|(ip improper superset + \(if \e\|(if infinity + \(pd \e\|(pd partial derivative + \(gr \e\|(gr gradient + \(no \e\|(no not + \(is \e\|(is integral sign + \(pt \e\|(pt proportional to + \(es \e\|(es empty set + \(mo \e\|(mo member of + \(br \e\|(br box vertical rule + \(dd \e\|(dd double dagger + \(rh \e\|(rh right hand + \(lh \e\|(lh left hand + \(or \e\|(or or + \(ci \e\|(ci circle + \(lt \e\|(lt left top of big curly bracket + \(lb \e\|(lb left bottom + \(rt \e\|(rt right top + \(rb \e\|(rb right bot + \(lk \e\|(lk left center of big curly bracket + \(rk \e\|(rk right center of big curly bracket + \(bv \e\|(bv bold vertical + \(lf \e\|(lf left floor (left bottom of big + square bracket) + \(rf \e\|(rf right floor (right bottom) + \(lc \e\|(lc left ceiling (left top) + \(rc \e\|(rc right ceiling (right top) diff --git a/share/doc/usd/22.trofftut/Makefile b/share/doc/usd/22.trofftut/Makefile new file mode 100644 index 000000000000..003fb8c27b25 --- /dev/null +++ b/share/doc/usd/22.trofftut/Makefile @@ -0,0 +1,43 @@ +# 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: +# +# Redistributions of source code and documentation must retain the above +# copyright notice, this list of conditions and the following +# disclaimer. +# +# 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. +# +# 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +# IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +# + +VOLUME= usd/22.trofftut +SRCS= tt.mac tt00 tt01 tt02 tt03 tt04 tt05 tt06 tt07 tt08 tt09 tt10 \ + tt11 tt12 tt13 tt14 ttack ttcharset ttindex +MACROS= -ms + +.include <bsd.doc.mk> diff --git a/share/doc/usd/22.trofftut/tt.mac b/share/doc/usd/22.trofftut/tt.mac new file mode 100644 index 000000000000..60a08ab0f04f --- /dev/null +++ b/share/doc/usd/22.trofftut/tt.mac @@ -0,0 +1,108 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.tr _\(em +.tr *\(** +.de UL +.if n .ul +.if n \\$3\\$1\\$2 +.if t \\$3\f3\\$1\fP\\$2 +.. +.de UC +\\$3\s-1\\$1\s+1\\$2 +.. +.de C +.if n .ul +.if n \\$3\\$1\\$2 +.if t \\$3\f3\\$1\fP\\$2 +.. +.de IT +.if t \\$3\f2\\$1\fP\\$2 +.if n .ul +.if n \\$3\\$1\\$2 +.. +.de UI +\f3\\$1\fI\\$2\fR\\$3 +.. +.de P1 +.if n .ls 1 +.nf +.\" use first argument as indent if present +.if \\n(.$ .DS I \\$1 +.if !\\n(.$ .DS I 5 +.ta .75i 1.5i 2.25i 3i 3.75i +.tr '\' +.. +.de P2 +.tr '' +.DE +.if n .ls 2 +.lg +.. +.if t .ds m \(mi +.if n .ds m - +.if t .ds n \(no +.if n .ds n - +.if t .ds s \v'.41m'\s+4*\s-4\v'-.41m' +.if n .ds s * +.if t .ds S \(sl +.if n .ds S / +.if t .ds d \s+4\&.\&\s-4 +.if n .ds d \&.\& +.if t .ds a \z@@ +.if n .ds a @ +.hy 14 +.\" XXX is this supposed to be a comment? . 2=not last lines; 4= no -xx; 8=no xx- +.de WS +.sp \\$1 +.. +.\" ACCENTS say \*'e or \*`e to get e acute or e grave +.ds ' \h'\w'e'u*4/10'\z\(aa\h'-\w'e'u*4/10' +.ds e \o"e\'" +.ds ` \h'\w'e'u*4/10'\z\(ga\h'-\w'e'u*4/10' +.\" UMLAUT \*:u, etc. +.ds : \v'-0.6m'\h'(1u-(\\n(.fu%2u))*0.13m+0.06m'\z.\h'0.2m'\z.\h'-((1u-(\\n(.fu%2u))*0.13m+0.26m)'\v'0.6m' +.\" TILDE and CIRCUMFLEX +.ds ^ \\k:\h'-\\n(.fu+1u/2u*2u+\\n(.fu-1u*0.13m+0.06m'\z^\h'|\\n:u' +.ds ~ \\k:\h'-\\n(.fu+1u/2u*2u+\\n(.fu-1u*0.13m+0.06m'\z~\h'|\\n:u' +.de BD +\&\\$3\f1\\$1\h\(ts-\w\(ts\\$1\(tsu+1u\(ts\\$1\fP\\$2\& +.. +.hw semi-colon diff --git a/share/doc/usd/22.trofftut/tt00 b/share/doc/usd/22.trofftut/tt00 new file mode 100644 index 000000000000..8d52a4692d0b --- /dev/null +++ b/share/doc/usd/22.trofftut/tt00 @@ -0,0 +1,120 @@ +.\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode! +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.EH 'USD:22-%''A TROFF Tutorial' +.OH 'A TROFF Tutorial''USD:22-%' +.\".RP +.\" .....TM 76-1273-7 39199 39199-11 +.ND +.TL +A TROFF Tutorial +.AU "MH 2C-518" 6021 +Brian W. Kernighan +(updated for 4.3BSD by Mark Seiden) +.AI +.\" What's this? .MH +.\" And this? .OK +\"Typesetting +\"Text formatting +\"NROFF +.AB +.PP +.UL troff +is a text-formatting program for +typesetting on the +.UX +operating system. +This device is capable of producing high quality +text; +this paper is an example of +.UL troff +output. +.PP +The phototypesetter itself normally runs with four fonts, +containing roman, italic and bold letters +(as on this page), +a full greek alphabet, and a substantial number of +special characters and mathematical symbols. +Characters can be printed in a range of sizes, +and placed anywhere on the page. +.PP +.UL troff +allows the user full control over fonts, +sizes, and character positions, +as well as the usual features of a formatter _ +right-margin justification, automatic hyphenation, +page titling and numbering, and so on. +It also provides macros, arithmetic variables and operations, +and conditional testing, for complicated formatting tasks. +.PP +This document is an introduction to the most basic use of +.UL troff . +It presents just enough information to enable the user +to do simple formatting +tasks like making viewgraphs, +and to make incremental changes to existing packages +of +.UL troff +commands. +In most respects, the +.UC UNIX +formatter +.UL nroff +and a more recent version +.ul +(device-independent +.UL troff) +are identical to +the version described here, so this document also serves as a tutorial for +them as well. +.PP +.vs 12p +\fB\s+1NOTE: This document refers to the historical \f(BItroff\fB program, and +not to \f(BIgroff\fB. This is a first cut at importing the tutorial from +4.4BSD, now that the code has been released. It should at some time be modified +to describe \f(BIgroff\fR.\s0 +.AE +.nr LL 6.5i +.nr LT 6.5i +.\" Unknown macro .CS 13 1 14 0 0 5 +.if t .2C +.nr PS 9 +.nr VS 11 diff --git a/share/doc/usd/22.trofftut/tt01 b/share/doc/usd/22.trofftut/tt01 new file mode 100644 index 000000000000..89961f3b8344 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt01 @@ -0,0 +1,220 @@ +.\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode! +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Introduction +.tr ^. +.PP +.UL troff +[1] +is a text-formatting program, +written originally by J. F. Ossanna, +for producing +high-quality printed output from the phototypesetter +on the +.UC UNIX +operating system. +This document is an example of +.UL troff +output. +.PP +The single most important rule +of using +.UL troff +is +not to use it directly, but through some intermediary. +In many ways, +.UL troff +resembles an assembly language _ +a remarkably powerful and flexible one _ +but nonetheless such that many operations must be specified +at a level of detail and in a form that is too hard +for most people to use effectively. +.PP +For two special applications, there are programs that provide +an interface to +.UL troff +for the majority of users. +.UL eqn +[2] +provides an easy to learn language for typesetting mathematics; +the +.UL eqn +user +need know no +.UL troff +whatsoever +to typeset mathematics. +.UL tbl +[3] +provides the same convenience for producing tables of arbitrary +complexity. +.PP +For producing straight text (which may well contain mathematics or tables), there are a number of `macro packages' +that define formatting rules and operations for specific styles +of documents, +and reduce the amount of +direct contact with +.UL troff . +In particular, the `\-ms' +[4], +PWB/MM [5], and `\-me' [6] +packages +for internal memoranda and external papers +provide most of the facilities needed +for a wide range of document preparation.\(dg +.FS +\(dg Most Berkeley Unix sites only have \-ms and \-me. +.FE +(This memo was prepared with `\-ms'.) +There are also packages for viewgraphs, +for simulating the older +.UL roff +formatters, +and for other special applications. +Typically you will find these packages easier to use +than +.UL troff +once you get beyond the most trivial operations; +you should always consider them first. +.PP +In the few cases where existing packages don't do the whole job, +the solution is +.ul +not +to write an entirely new set of +.UL troff +instructions from scratch, but to make small changes +to adapt packages that already exist. +.WS +.PP +In accordance with this philosophy of letting someone else +do the work, +the part of +.UL troff +described here is only a small part of the whole, +although it tries to concentrate on the more useful parts. +In any case, there is no attempt to be complete. +Rather, the emphasis is on showing how to do simple things, +and how to make incremental changes to what already exists. +The contents of the remaining sections are: +.sp +.nf +.in .1i +.ta .3i +\02. Point sizes and line spacing +\03. Fonts and special characters +\04. Indents and line length +\05. Tabs +\06. Local motions: Drawing lines and characters +\07. Strings +\08. Introduction to macros +\09. Titles, pages and numbering +10. Number registers and arithmetic +11. Macros with arguments +12. Conditionals +13. Environments +14. Diversions + Appendix: Typesetter character set +.sp +.in 0 +.fi +The +.UL troff +described here is the C-language version supplied with +.UC UNIX +Version 7 and 32V as documented in [1]. +.WS +.PP +To use +.UL troff +you have to prepare not only the actual text you want printed, +but some information that tells +.ul +how +you want it printed. +(Readers who use +.UL roff +will find the approach familiar.) +For +.UL troff +the text +and +the formatting information are often intertwined quite intimately. +Most commands to +.UL troff +are placed on a line separate from the text itself, +beginning with a period (one command per line). +For example, +.P1 +Some text. +^ps 14 +Some more text. +.P2 +will change the `point size', +that is, +the size of the letters being printed, +to `14 point' (one point is 1/72 inch) like this: +.P1 +.fi +Some text. +.ps 14 +Some more text. +.ps 10 +.P2 +.PP +Occasionally, though, +something special occurs in the middle of a line _ +to produce +.P1 +Area = \(*p\fIr\fR\|\s8\u2\d\s0 +.P2 +you have to type +.P1 +Area = \e(*p\efIr\efR\e\^|\^\es8\eu2\ed\es0 +.P2 +(which we will explain shortly). +The backslash character +.BD \e +is used +to introduce +.UL troff +commands and special characters within a line of text. diff --git a/share/doc/usd/22.trofftut/tt02 b/share/doc/usd/22.trofftut/tt02 new file mode 100644 index 000000000000..4da04f4d3b23 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt02 @@ -0,0 +1,241 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Point Sizes; Line Spacing +.PP +As mentioned above, +the command +.BD .ps +sets the point size. +One point is 1/72 inch, +so 6-point characters are at most 1/12 inch high, +and 36-point characters are \(12 inch. +There are 15 point sizes, listed below. +.P1 1 +.ps 6 +6 point: Pack my box with five dozen liquor jugs. +.ps 7 +.vs 8p +7 point: Pack my box with five dozen liquor jugs. +.vs 9p +.ps 8 +8 point: Pack my box with five dozen liquor jugs. +.vs 10p +.ps 9 +9 point: Pack my box with five dozen liquor jugs. +.vs 11p +.ps 10 +10 point: Pack my box with five dozen liquor +.vs 12p +.ps 11 +11 point: Pack my box with five dozen +.vs 14p +.ps 12 +12 point: Pack my box with five dozen +.vs 16p +.ps 14 +14 point: Pack my box with five +.vs 24p +\s1616 point\s18 18 point\s20 20 point +.vs 40p +\s2222\s24 24\s28 28\s36 36 +.ps 10 +.vs 12p +.P2 +.PP +If the number after +.BD .ps +is not one of these +legal sizes, +it is rounded up to the next valid value, +with a maximum of 36. +If no number follows +.BD .ps , +.UL troff +reverts to the previous size, whatever it was. +.UL troff +begins with point size 10, +which is usually fine. +The original of this document (on 8.5 by 11 inch paper) is in 9 point. +.PP +The point size can also be changed in the middle of a line +or even a word +with the in-line command +.BD \es . +To produce +.P1 +\s8UNIX\s10 runs on a \s8PDP-\s1011/45 +.P2 +type +.P1 +\es8UNIX\es10 runs on a \es8PDP-\es1011/45 +.P2 +As above, +.BD \es +should be followed by a legal point size, +except that +.BD \es0 +causes the size to revert to +its previous value. +Notice that +.BD \es1011 +can be understood correctly as `size 10, followed by an 11', if the size is legal, +but not otherwise. +Be cautious with similar constructions. +.PP +Relative size changes are also legal and useful: +.P1 +\es\-2UNIX\es+2 +.P2 +temporarily decreases the size, whatever it is, by two points, then +restores it. +Relative size changes have the advantage that the size difference +is independent of the starting size of the document. +The amount of the relative change is restricted +to a single digit. +.WS +.PP +The other parameter that determines what the type looks like +is the spacing between lines, +which is set independently of the point size. +Vertical spacing is measured from the bottom of one line to +the bottom of the next. +The command to control vertical spacing is +.BD .vs . +For running text, it is usually best to set the vertical spacing +about 20% bigger than the character size. +For example, so far in this document, we have used +``9 on 11'', that is, +.P1 +^ps 9 +^vs 11p +.P2 +If we changed to +.P1 +^ps 9 +^vs 9p +.P2 +.vs 9p +.ne 3 +the running text would look like this. +After a few lines, you will agree it looks a little cramped. +The right vertical spacing is partly a matter of taste, depending on how +much text you want to squeeze into a given space, +and partly a matter of traditional printing style. +By default, +.UL troff +uses 10 on 12. +.PP +.vs 14p +.ps 12 +Point size and vertical spacing make a substantial difference in the amount of text +per square inch. +This is 12 on 14. +.ne 2 +.PP +.ne 2 +.ps 6 +.vs 7p +Point size and vertical spacing make a substantial difference in the amount of text +per square inch. +For example, +10 on 12 uses about twice as much space as 7 on 8. +This is 6 on 7, which is even smaller. +It packs a lot more words per line, +but you can go blind trying to read it. +.PP +When used without arguments, +.BD .ps +and +.BD .vs +revert to the previous size and vertical spacing +respectively. +.WS +.PP +The command +.BD .sp +is used to get extra vertical space. +Unadorned, +it gives you one extra blank line (one +.BD .vs , +whatever that has been set to). +Typically, that's more or less than you want, +so +.BD .sp +can be followed by +information about how much space you want _ +.P1 +^sp 2i +.P2 +means `two inches of vertical space'. +.P1 +^sp 2p +.P2 +means `two points of vertical space'; +and +.P1 +^sp 2 +.P2 +means `two vertical spaces' _ two of whatever +.BD .vs +is set to +(this can also be made explicit with +.BD .sp\ 2v ); +.UL troff +also understands decimal fractions in most places, +so +.P1 +^sp 1.5i +.P2 +is a space of 1.5 inches. +These same scale factors can be used after +.BD .vs +to define line spacing, and in fact after most commands +that deal with physical dimensions. +.PP +It should be noted that all size numbers are converted internally +to `machine units', which are 1/432 inch +(1/6 point). +For most purposes, this is enough resolution +that you don't have to worry about the accuracy of the representation. +The situation is not quite so good vertically, +where resolution is 1/144 inch +(1/2 point). diff --git a/share/doc/usd/22.trofftut/tt03 b/share/doc/usd/22.trofftut/tt03 new file mode 100644 index 000000000000..a544df0e8b58 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt03 @@ -0,0 +1,237 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Fonts and Special Characters +.PP +.UL troff +and the typesetter allow four different fonts at any one time. +Normally three fonts (Times roman, italic and bold) and one collection of special characters +are permanently +mounted. +.P1 2 +.ft R +abcdefghijklmnopqrstuvwxyz 0123456789 +ABCDEFGHIJKLMNOPQRSTUVWXYZ +.ft I +abcdefghijklmnopqrstuvwxyz 0123456789 +ABCDEFGHIJKLMNOPQRSTUVWXYZ +.ft B +abcdefghijklmnopqrstuvwxyz 0123456789 +ABCDEFGHIJKLMNOPQRSTUVWXYZ +.ft R +.P2 +The +greek, mathematical symbols and miscellany +of the special font are +listed in Appendix A. +.PP +.UL troff +prints in roman unless told otherwise. +To switch into bold, use +the +.BD .ft +command +.P1 +^ft B +.P2 +and for italics, +.P1 +^ft I +.P2 +To return to roman, use +.BD .ft\ R ; +to return to the previous font, +whatever it was, +use either +.BD .ft\ P +or just +.BD .ft . +The `underline' command +.P1 +^ul +.P2 +causes the next input line to print in italics. +.BD .ul +can be followed by a count to +indicate that more than one line is to be italicized. +.PP +Fonts can also be changed within a line or word +with the in-line command +.BD \ef : +.P1 +\fBbold\fIface\fR text +.P2 +is produced by +.P1 +\efBbold\efIface\efR text +.P2 +If you want to do this so the previous font, whatever it was, +is left undisturbed, insert extra +.BD \efP +commands, like this: +.P1 +\efBbold\efP\efIface\efP\efR text\efP +.P2 +Because only the immediately previous font is remembered, +you have to restore the previous font after each change +or you can lose it. +The same is true of +.BD .ps +and +.BD .vs +when used without an argument. +.PP +There are other fonts available besides the standard set, +although you can still use only four at any given time. +The command +.BD .fp +tells +.UL troff +what fonts are physically mounted on the typesetter: +.P1 +^fp 3 H +.P2 +says that the Helvetica font is mounted on position 3. +(The complete list of font sizes and styles depends on +your typesetter or laser printer.) +Appropriate +.BD .fp +commands should appear at the beginning of your document +if you do not use the standard fonts. +.PP +It is possible to make a document relatively independent +of the actual fonts used to print it +by using font numbers instead of names; +for example, +.BD \ef3 +and +.BD .ft\ 3 +mean `whatever font is mounted at position 3', +and thus work for any setting. +Normal settings are roman font on 1, italic on 2, +bold on 3, +and special on 4. +.PP +There is also a way to get `synthetic' bold fonts +by overstriking letters with a slight offset. +Look at the +.BD .bd +command in [1]. +.WS +.PP +Special characters have four-character names beginning with +.BD \e( , +and they may be inserted anywhere. +For example, +.P1 +\(14 + \(12 = \(34 +.P2 +is produced by +.P1 +\e(14 + \e(12 = \e(34 +.P2 +In particular, +greek letters are all of the form +.BD \e(*\- , +where +.BD \- +is an upper or lower case roman letter +reminiscent of the greek. +Thus +to get +.P1 +\(*S(\(*a\(mu\(*b) \(-> \(if +.P2 +in bare +.UL troff +we have to type +.P1 +\e(*S(\e(*a\e(mu\e(*b) \e(\(mi> \e(if +.P2 +That line is unscrambled as follows: +.P1 +.ta 1i 2i 3i +\e(*S \(*S +( ( +\e(*a \(*a +\e(mu \(mu +\e(*b \(*b +) ) +\e(\(mi> \(-> +\e(if \(if +.P2 +A complete list of these special names occurs in Appendix A. +.PP +In +.UL eqn +[2] +the same effect can be achieved with the input +.P1 +SIGMA ( alpha times beta ) \-> inf +.P2 +which is less concise, but clearer to the uninitiated. +.PP +Notice that +each +four-character name is a single character +as far as +.UL troff +is concerned _ +the +`translate' command +.P1 +^tr \e(mi\e(em +.P2 +is perfectly clear, meaning +.P1 +^tr \(mi\(em +.P2 +that is, to translate \(mi into \(em. +.PP +Some characters are automatically translated into others: +grave \(ga and acute \(aa accents (apostrophes) become open and close single quotes +`\|'\|; +the combination of ``...'' is generally preferable to the double quotes "...". +Similarly a typed minus sign becomes a hyphen -. +To print an explicit \- sign, use +.BD \e\|- . +To get a backslash printed, use +.BD \ee . diff --git a/share/doc/usd/22.trofftut/tt04 b/share/doc/usd/22.trofftut/tt04 new file mode 100644 index 000000000000..23f2630aa31f --- /dev/null +++ b/share/doc/usd/22.trofftut/tt04 @@ -0,0 +1,185 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.NH +Indents and Line Lengths +.PP +.UL troff +starts with a line length of 6.5 inches, +which some people think is too wide for 8\(12\(mu11 paper. +To reset the line length, +use +the +.BD .ll +command, as in +.P1 +^ll 6i +.P2 +As with +.BD .sp , +the actual length can be specified in several ways; +inches are probably the most intuitive. +.PP +The maximum line length provided by the typesetter is 7.5 inches, by the way. +To use the full width, you will have to reset the default physical left margin (``page offset''), +which is normally slightly less than one inch from the left edge +of the paper. +This is done by the +.BD .po +command. +.P1 +^po 0 +.P2 +sets the offset as far to the left as it will go. +.WS +.PP +The indent command +.BD .in +causes the left margin to be indented +by some specified amount from the page offset. +If we use +.BD .in +to move the left margin in, +and +.BD .ll +to move the right margin to the left, +we can +make offset blocks of text: +.P1 +^in 0.3i +^ll \(mi0.3i +text to be set into a block +^ll +0.3i +^in \(mi0.3i +.P2 +will create a block that looks like this: +.P1 +.fi +.ll -0.3i +Pater noster qui est in caelis sanctificetur nomen tuum; +adveniat regnum tuum; fiat voluntas tua, sicut in caelo, +et in terra. ... +Amen. +.ll +0.3i +.P2 +Notice the use of `+' and `\(mi' +to specify the amount of change. +These change the previous setting by the specified amount, +rather than just overriding it. +The distinction is quite important: +.BD .ll\ +1i +makes lines one inch longer; +.BD .ll\ 1i +makes them one inch +.ul +long. +.PP +With +.BD .in , +.BD .ll +and +.BD .po , +the previous value is used if no argument is specified. +.PP +To indent a single line, use the `temporary indent' +command +.BD .ti . +For example, all paragraphs in this memo +effectively begin with the command +.P1 +^ti 3 +.P2 +Three of what? +The default unit for +.BD .ti , +as for most horizontally oriented commands +.BD .ll , ( +.BD .in , +.BD .po ), +is ems; +an em is roughly the width of the letter `m' +in the current point size. +(Precisely, an em in size +.ul +p +is +.ul +p +points.) +Although inches are usually clearer than ems to people who don't set type +for a living, +ems have a place: +they are a measure of size that is proportional to the current point size. +If you want to make text that keeps its proportions +regardless of point size, +you should use ems for all dimensions. +Ems can be specified as scale factors directly, +as in +.BD .ti\ 2.5m . +.PP +Lines can also be indented negatively +if the indent is already positive: +.P1 +^ti \(mi0.3i +.P2 +causes the next line to be moved back three tenths of an inch. +Thus to make a decorative initial capital, +we indent the whole paragraph, then move the letter `P' back with +a +.BD .ti +command: +.P1 +.ll -0.3i +.fi +.in +.3i +.ti -0.3i +\s36\v'2'P\v'-2'\s0ater noster qui est in caelis sanctificetur +nomen tuum; +adveniat regnum tuum; +'in -.3i +fiat voluntas tua, +sicut in caelo, et in terra. ... +Amen. +.ll +0.3i +.P2 +Of course, there is also some trickery to make the `P' +bigger (just a `\es36P\es0'), +and to move it +down from its normal position +(see the section on local motions). diff --git a/share/doc/usd/22.trofftut/tt05 b/share/doc/usd/22.trofftut/tt05 new file mode 100644 index 000000000000..86b68f626a79 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt05 @@ -0,0 +1,127 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Tabs +.PP +Tabs +(the \s8ASCII\s0 `horizontal tab' character) +can be used to produce output in columns, +or to set the horizontal position of output. +Typically +tabs are used only in unfilled text. +Tab stops are set by default every half inch from the +current indent, +but +can be changed by the +.BD .ta +command. +To set stops every inch, for example, +.P1 +^ta 1i 2i 3i 4i 5i 6i +.P2 +.PP +Unfortunately the stops are left-justified only +(as on a typewriter), +so lining up columns of right-justified numbers can be painful. +If you have many numbers, +or if you need more complicated table layout, +.ul +don't +use +.UL troff +directly; +use the +.UL tbl +program described in [3]. +.PP +For a handful of numeric columns, you can do it this way: +Precede every number by enough blanks to make it line up +when typed. +.P1 +^nf +^ta 1i 2i 3i +\0\01\0\fItab\fR\0\0\02\0\fItab\fR\0\0\03 +\040\0\fItab\fR\0\050\0\fItab\fR\0\060 +700\0\fItab\fR\0800\0\fItab\fR\0900 +^fi +.P2 +Then change each leading blank into the string +.BD \e0 . +This is a character that does not print, but that has +the same width as a digit. +When printed, this will produce +.P1 +.ta 1i 2i 3i +\0\01 \0\02 \0\03 +\040 \050 \060 +700 800 900 +.P2 +.PP +It is also possible to fill up tabbed-over space with +some character other than blanks by setting the `tab replacement character' +with the +.BD .tc +command: +.P1 +^ta 1.5i 2.5i +^tc \e(ru (\e(ru is "\(ru") +Name \fItab\fR Age \fItab\fR +.P2 +produces +.P1 3 +.ta 1.5i 2.5i +.tc \(ru +Name Age +.tc +.P2 +To reset the tab replacement character to a blank, use +.BD .tc +with no argument. +(Lines can also be drawn with the +.BD \el +command, described in Section 6.) +.PP +.UL troff +also provides a very general mechanism called `fields' +for setting up complicated columns. +(This is used by +.UL tbl ). +We will not go into it in this paper. diff --git a/share/doc/usd/22.trofftut/tt06 b/share/doc/usd/22.trofftut/tt06 new file mode 100644 index 000000000000..e252e5bd6d4f --- /dev/null +++ b/share/doc/usd/22.trofftut/tt06 @@ -0,0 +1,348 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Local Motions: Drawing lines and characters +.PP +Remember `Area = \(*pr\u2\d' and the big `P' +in the Paternoster. +How are they done? +.UL troff +provides a host of commands for placing characters of any size +at any place. +You can use them to draw special characters +or to tune your output for a particular appearance. +Most of these commands are straightforward, but messy to read +and tough to type correctly. +.PP +If you won't use +.UL eqn , +subscripts and superscripts are most easily done with +the half-line local motions +.BD \eu +and +.BD \ed . +To go back up the page half a point-size, insert a +.BD \eu +at the desired place; +to go down, insert a +.BD \ed . +.BD \eu \& ( +and +.BD \ed +should always +be used in pairs, as explained below.) +Thus +.P1 +Area = \e(*pr\eu2\ed +.P2 +produces +.P1 +Area = \(*pr\u2\d +.P2 +To make the `2' smaller, bracket it with +.BD \es\-2...\es0 . +Since +.BD \eu +and +.BD \ed +refer to the current point size, +be sure to put them either both inside or both outside +the size changes, +or you will get an unbalanced vertical motion. +.PP +Sometimes the space given by +.BD \eu +and +.BD \ed +isn't the right amount. +The +.BD \ev +command can be used to request an arbitrary amount of vertical motion. +The in-line command +.P1 +\ev'(amount)' +.P2 +causes motion up or down the page by the amount specified in +`(amount)'. +For example, to move the `P' down, we used +.P1 2 +.ta 1i +^in +0.6i (move paragraph in) +^ll \-0.3i (shorten lines) +^ti \-0.3i (move P back) +\ev'2'\es36P\es0\ev'\-2'ater noster qui est +in caelis ... +.P2 +A minus sign causes upward motion, while +no sign or a plus sign means down the page. +Thus +.BD \ev\(fm\-2\(fm +causes an upward vertical motion +of two line spaces. +.PP +There are many other ways to specify the amount of motion _ +.P1 +\ev'0.1i' +\ev'3p' +\ev'\-0.5m' +.P2 +and so on are all legal. +Notice that the scale specifier +.BD i +or +.BD p +or +.BD m +goes inside the quotes. +Any character can be used in place of the quotes; +this is also true of all other +.UL troff +commands described in this section. +.PP +Since +.UL troff +does not take within-the-line vertical motions into account +when figuring out where it is on the page, +output lines can have unexpected positions +if the left and right ends aren't at the same +vertical position. +Thus +.BD \ev , +like +.BD \eu +and +.BD \ed , +should always balance upward vertical motion in a line with +the same amount in the downward direction. +.PP +Arbitrary horizontal motions are also available _ +.BD \eh +is quite analogous to +.BD \ev , +except that the default scale factor is ems instead of line spaces. +As an example, +.P1 +\eh'\-0.1i' +.P2 +causes a backwards motion of a tenth of an inch. +As a practical matter, consider printing the mathematical symbol +`>>'. +The default spacing is too wide, so +.UL eqn +replaces this by +.P1 +>\eh'\-0.3m'> +.P2 +to produce >\h'-.3m'>. +.PP +Frequently +.BD \eh +is used with the `width function' +.BD \ew +to generate motions equal to the width +of some character string. +The construction +.P1 +\ew'thing' +.P2 +is a number equal to the width of `thing' in machine units +(1/432 inch). +All +.UL troff +computations are ultimately done in these units. +To move horizontally the width of an `x', +we can say +.P1 +\eh'\ew'x'u' +.P2 +As we mentioned above, +the default scale factor for +all horizontal dimensions is +.BD m , +ems, so here we must have the +.BD u +for machine units, +or the motion produced will be far too large. +.UL troff +is quite happy with the nested quotes, by the way, +so long as you don't leave any out. +.PP +As a live example of this kind of construction, +all of the command names in the text, like +.BD .sp , +were done by overstriking with a slight offset. +The commands for +.BD .sp +are +.P1 +^sp\eh'\-\ew'.sp'u'\eh'1u'.sp +.P2 +That is, put out `.sp', move left by the width of `.sp', +move right 1 unit, and print +`.sp' again. +(Of course there is a way to avoid typing that much input +for each command name, which we will discuss in Section 11.) +.WS +.PP +There are also several special-purpose +.UL troff +commands for local motion. +We have already seen +.BD \e0 , +which is an unpaddable white space +of the same width as a digit. +`Unpaddable' means that it will never be widened +or split across a line by line justification and filling. +There is also +.BD \e (blank), +.tr ^^ +which is an unpaddable character the width of a space, +.BD \e| , +which is half that width, +.BD \e^ , +which is one quarter of the width of a space, +and +.BD \e& , +which has zero width. +.tr ^. +(This last one is useful, for example, in entering +a text line which would otherwise begin with a `.'.) +.PP +The command +.BD \eo , +used like +.P1 +\eo'set of characters' +.P2 +causes (up to 9) +characters to be overstruck, +centered on the widest. +This is nice for accents, as in +.P1 2 +syst\eo"e\e(ga"me t\eo"e\e(aa"l\eo"e\e(aa"phonique +.P2 +which makes +.P1 +syst\o"e\(ga"me t\o"e\(aa"l\o"e\(aa"phonique +.P2 +The accents are +.BD \e(ga +and +.BD \e(aa , +or +.BD \e\` +and +.BD \e\' ; +remember that each is just one character to +.UL troff . +.PP +You can make your own overstrikes with another special convention, +.BD \ez , +the zero-motion command. +.BD \ezx +suppresses the normal horizontal motion +after printing the single character +.BD x , +so another character can be laid on top of it. +Although sizes can be changed within +.BD \eo , +it centers the characters on the widest, +and +there can be no horizontal or vertical motions, +so +.BD \ez +may be the only way to get what you want: +.P1 +.sp 2 +\s8\z\(sq\s14\z\(sq\s22\z\(sq\s36\(sq +.P2 +is produced by +.P1 +^sp 2 +\es8\ez\e(sq\es14\ez\e(sq\es22\ez\e(sq\es36\e(sq +.P2 +The +.BD .sp +is needed to leave room for the result. +.PP +As another example, an extra-heavy semicolon +that looks like +.P1 +\s+6\z,\v'-0.25m'.\v'0.25m'\s0 instead of ; or \s+6;\s0 +.P2 +can be constructed with a big comma and a big period above it: +.P1 +\es+6\ez,\ev'\(mi0.25m'.\ev'0.25m'\es0 +.P2 +`0.25m' is an experimentally-derived constant. +.PP +A more ornate overstrike is given by the bracketing function +.BD \eb , +which piles up characters vertically, +centered on the current baseline. +Thus we can get big brackets, +constructing them with piled-up smaller pieces: +.P1 +.sp +.ne 3 +\b'\(lt\(lk\(lb' \b'\(lc\(lf' x \b'\(rc\(rf' \b'\(rt\(rk\(rb' +.sp +.P2 +by typing in only this: +.P1 0 +\&^sp +\eb\(fm\e(lt\e(lk\e(lb\(fm \eb\(fm\e(lc\e(lf\(fm x \eb\(fm\e(rc\e(rf\(fm \eb\(fm\e(rt\e(rk\e(rb\(fm +.P2 +.PP +.UL troff +also provides a convenient facility for drawing horizontal and vertical +lines of arbitrary length with arbitrary characters. +.BD \el\(fm1i\(fm +draws a line one inch long, like this: +\l'1i'\|. +The length can be followed by +the character to use if the \(ru isn't appropriate; +.BD \el\(fm0.5i.\(fm +draws a half-inch line of dots: \l'.5i.'. +The construction +.BD \eL +is entirely analogous, +except that it draws a vertical line instead of horizontal. diff --git a/share/doc/usd/22.trofftut/tt07 b/share/doc/usd/22.trofftut/tt07 new file mode 100644 index 000000000000..61e116b5ef4e --- /dev/null +++ b/share/doc/usd/22.trofftut/tt07 @@ -0,0 +1,121 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Strings +.PP +Obviously if a paper contains a large number of occurrences +of an acute accent over a letter `e', +typing +.BD \eo"e\e\'" +for each \*e +would be a great nuisance. +.PP +Fortunately, +.UL troff +provides a way in which you can store an arbitrary +collection of text in a `string', +and thereafter use the string name as a shorthand +for its contents. +Strings are one of several +.UL troff +mechanisms whose judicious use +lets you type a document +with less effort and organize +it +so that extensive format changes +can be made with few editing changes. +.PP +A reference to a string is replaced by whatever +text +the string was defined as. +Strings are defined with the command +.BD .ds . +The line +.P1 +\&^ds e \eo"e\e'" +.P2 +defines the string +.BD e +to have the value +.BD \eo"e\e\'" +.PP +String names may be either one or two characters long, +and are referred to by +.BD \e*x +for one character names or +.BD \e*(xy +for two character names. +Thus to get +t\*el\*ephone, +given the definition of the string +.BD e +as above, +we can say +t\e*el\e*ephone. +.PP +If a string must begin with blanks, define it as +.P1 +\&.ds xx " text +.P2 +The double quote signals the beginning of the definition. +There is no trailing quote; +the end of the line terminates the string. +.PP +A string may actually be several lines long; +if +.UL troff +encounters a +.BD \e +at the end of +.ul +any +line, it is thrown away and the next line +added to the current one. +So you can make a long string simply by ending each line +but the last with a backslash: +.P1 +\&^ds xx this \e +is a very \e +long string +.P2 +.PP +Strings may be defined in terms of other strings, or even in terms of themselves; +we will discuss some of these possibilities later. diff --git a/share/doc/usd/22.trofftut/tt08 b/share/doc/usd/22.trofftut/tt08 new file mode 100644 index 000000000000..f6b4c7ee34c2 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt08 @@ -0,0 +1,196 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Introduction to Macros +.PP +Before we can go much further in +.UL troff , +we need to learn a bit about the +macro +facility. +In its simplest form, a macro is just a shorthand notation +quite similar to a string. +Suppose we want every paragraph to start +in exactly the same way _ +with a space and a temporary indent of two ems: +.P1 +^sp +^ti +2m +.P2 +Then to save typing, we would like to collapse these into +one shorthand line, +a +.UL troff +`command' like +.P1 +^PP +.P2 +that would be treated by +.UL troff +exactly as +.P1 +^sp +^ti +2m +.P2 +.BD .PP +is called a +.ul +macro. +The way we tell +.UL troff +what +.BD .PP +means is to +.ul +define +it with the +.BD .de +command: +.P1 +^de PP +^sp +^ti +2m +^^ +.P2 +The first line names the macro +(we used +.BD .PP ' ` +for `paragraph', +and upper case so it wouldn't conflict with +any name that +.UL troff +might +already know about). +The last line +.BD .. +marks the end of the definition. +In between is the text, +which is simply inserted whenever +.UL troff +sees the `command' +or macro call +.P1 +^PP +.P2 +A macro +can contain any mixture of text and formatting commands. +.PP +The definition of +.BD .PP +has to precede its first use; +undefined macros are simply ignored. +Names are restricted to one or two characters. +.PP +Using macros for commonly occurring sequences of commands +is critically important. +Not only does it save typing, +but it makes later changes much easier. +Suppose we decide that the paragraph indent is too small, +the vertical space is much too big, +and roman font should be forced. +Instead of changing the whole document, +we need only change the definition of +.BD .PP +to +something like +.P1 +^de PP \e" paragraph macro +^sp 2p +^ti +3m +^ft R +^^ +.P2 +and the change takes +effect everywhere we used +.BD .PP . +.PP +.BD \e" +is a +.UL troff +command that causes the rest of the line to be ignored. +We use it here to add comments to the macro +definition +(a wise idea once definitions get complicated). +.PP +As another example of macros, +consider these two which start and end a block of offset, +unfilled text, like most of the examples in this paper: +.P1 +^de BS \e" start indented block +^sp +^nf +^in +0.3i +^^ +^de BE \e" end indented block +^sp +^fi +^in \(mi0.3i +^^ +.P2 +Now we can surround text like +.P1 +Copy to +John Doe +Richard Roberts +Stanley Smith +.P2 +by the commands +.BD .BS +and +.BD .BE , +and it will come out as it did above. +Notice that we indented by +.BD .in\ +0.3i +instead of +.BD .in\ 0.3i . +This way we can nest our uses of +.BD .BS +and +.BD BE +to get blocks within blocks. +.PP +If later on we decide that the indent +should be 0.5i, then it is only necessary to +change the definitions of +.BD .BS +and +.BD .BE , +not the whole paper. diff --git a/share/doc/usd/22.trofftut/tt09 b/share/doc/usd/22.trofftut/tt09 new file mode 100644 index 000000000000..d6da03b8408a --- /dev/null +++ b/share/doc/usd/22.trofftut/tt09 @@ -0,0 +1,319 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Titles, Pages and Numbering +.PP +This is an area where things get tougher, +because nothing is done for you automatically. +Of necessity, some of this section is a cookbook, +to be copied literally until you get some experience. +.PP +Suppose you want a title at the top of each page, +saying just +.sp 3p +.lt 2.8i +.tl 'left top'center top'right top' +.lt +.sp 3p +In +.UL roff , +one can say +.P1 2 +^he 'left top'center top'right top' +^fo 'left bottom'center bottom'right bottom' +.P2 +to get headers and footers automatically on every page. +Alas, this doesn't work so easily in +.UL troff , +a serious hardship for the novice. +Instead you have to do a lot of specification (or use +a macro package, which makes it effortless). +.PP +You have to say what the actual title is (easy); +when to print it (easy enough); +and what to do at and around the title line (harder). +Taking these in reverse order, +first we define a macro +.BD .NP +(for `new page') to process +titles and the like at the end of one page +and the beginning of the next: +.P1 +^de NP +\(fmbp +\(fmsp 0.5i +\&.tl 'left top'center top'right top' +\(fmsp 0.3i +^^ +.P2 +To make sure we're at the top of a page, +we issue a `begin page' command +.BD \(fmbp , +which causes a skip to top-of-page +(we'll explain the +.BD \(fm +shortly). +Then we space down half an inch, +print the title +(the use of +.BD .tl +should be self explanatory; later we will discuss parameterizing the titles), +space another 0.3 inches, +and we're done. +.PP +To ask for +.BD .NP +at the bottom of each page, +we have to say something like +`when the text is within an inch +of the bottom of the page, +start the processing +for a new page.' +This is done with a `when' command +.BD .wh : +.P1 +^wh \-1i NP +.P2 +(No `.' is used before NP; +this is simply the name of a macro, not a macro call.) +The minus sign means +`measure up from the bottom of the page', +so +`\-1i' means `one inch from the bottom'. +.PP +The +.BD .wh +command appears in the input outside the definition of +.BD .NP ; +typically the input would be +.P1 +^de NP +^^^ +^^ +^wh \-1i NP +.P2 +.PP +Now what happens? +As text is actually being output, +.UL troff +keeps track of its vertical position on the page, +and after a line is printed within one inch from the bottom, +the +.BD .NP +macro is activated. +(In the jargon, the +.BD .wh +command sets a +.ul +trap +at the specified place, +which is `sprung' when that point is passed.) +.BD .NP +causes a skip to the top of the next page +(that's what the +.BD \(fmbp +was for), +then prints the title with the appropriate margins. +.PP +Why +.BD \(fmbp +and +.BD \(fmsp +instead of +.BD .bp +and +.BD .sp ? +The answer is that +.BD .sp +and +.BD .bp , +like several other commands, +cause a +.ul +break +to take place. +That is, all the input text collected but not yet printed +is flushed out as soon as possible, +and the next input line is guaranteed to start +a new line of output. +If we had used +.BD .sp +or +.BD .bp +in the +.BD .NP +macro, +this would cause a break in the middle +of the current output line when a new page is started. +The effect would be to print the left-over part of that line +at the top of the page, followed by the next input line on a new output line. +This is +.ul +not +what we want. +Using +.BD \(fm +instead of +.BD . +for a command +tells +.UL troff +that +no break is to take place _ +the output line +currently being filled +should +.ul +not +be forced out before the space or new page. +.PP +The list of commands that cause a break +is short and natural: +.P1 +^bp ^br ^ce ^fi ^nf ^sp ^in ^ti +.P2 +All others cause +.ul +no +break, +regardless of whether you use a +.BD . +or a +.BD \(fm . +If you really need a break, add a +.BD .br +command at the appropriate place. +.PP +One other thing to beware of _ +if you're changing fonts or point sizes a lot, +you may find that +if you cross a page boundary +in an unexpected font or size, +your titles come out in that size and font +instead of what you intended. +Furthermore, the length of a title is independent of the current line length, +so titles will come out at the default length of 6.5 inches +unless you change it, +which is done with the +.BD .lt +command. +.PP +There are several ways to fix the problems of point sizes +and fonts in titles. +For the simplest applications, we can change +.BD .NP +to set the proper size and font for the title, +then restore the previous values, like this: +.P1 2 +.ta .8i +^de NP +\(fmbp +\(fmsp 0.5i +^ft R \e" set title font to roman +^ps 10 \e" and size to 10 point +^lt 6i \e" and length to 6 inches +^tl 'left'center'right' +^ps \e" revert to previous size +^ft P \e" and to previous font +\(fmsp 0.3i +^^ +.P2 +.PP +This version of +.BD .NP +does +.ul +not +work if the fields in the +.BD .tl +command contain size or font changes. +To cope with that +requires +.UL troff 's +`environment' mechanism, +which we will discuss in Section 13. +.PP +To get a footer at the bottom of a page, +you can modify +.BD .NP +so it does +some processing before +the +.BD \(fmbp +command, +or split the job into a footer macro invoked +at the bottom margin and a header macro invoked +at the top of the page. +These variations are left as exercises. +.WS +.PP +Output page numbers are computed automatically +as each page is produced (starting at 1), +but no numbers are printed unless you ask for them explicitly. +To get page numbers printed, +include the character +.BD % +in the +.BD .tl +line at +the position where you want the number to appear. +For example +.P1 +^tl ''- % -'' +.P2 +centers the page number inside hyphens, as on this page. +You can set the page number at any time +with either +.BD .bp\ n , +which immediately starts a new page numbered +.BD n , +or with +.BD .pn\ n , +which sets the page number for the next page +but doesn't cause a skip to the new page. +Again, +.BD .bp\ +n +sets the page number to +.BD n +more than its current value; +.BD .bp +means +.BD .bp\ +1 . diff --git a/share/doc/usd/22.trofftut/tt10 b/share/doc/usd/22.trofftut/tt10 new file mode 100644 index 000000000000..7366c448e7d9 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt10 @@ -0,0 +1,253 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Number Registers and Arithmetic +.PP +.UL troff +has a facility for doing arithmetic, +and for defining and using variables with numeric values, +called +.ul +number registers. +Number registers, like strings and macros, can be useful in setting up a document +so it is easy to change later. +And of course they serve for any sort of arithmetic computation. +.PP +Like strings, number registers have one or two character names. +They are set by the +.BD .nr +command, +and are referenced anywhere by +.BD \enx +(one character name) or +.BD \en(xy +(two character name). +.PP +There are quite a few pre-defined number registers maintained by +.UL troff , +among them +.BD % +for the current page number; +.BD nl +for the current vertical position on the page; +.BD dy , +.BD mo +and +.BD yr +for the current day, month and year; and +.BD .s +and +.BD .f +for the current size and font. +(The font is a number from 1 to 4.) +Any of these can be used in computations like any other register, +but some, like +.BD .s +and +.BD .f , +cannot be changed with +.BD .nr . +.PP +As an example of the use of number registers, +in the +.BD \-ms +macro package [4], +most significant parameters are defined in terms of the values +of a handful of number registers. +These include the point size for text, the vertical spacing, +and the line and title lengths. +To set the point size and vertical spacing for the following paragraphs, for example, a user may say +.P1 +^nr PS 9 +^nr VS 11 +.P2 +The paragraph macro +.BD .PP +is defined (roughly) as follows: +.P1 +.ta 1i +^de PP +^ps \e\en(PS \e" reset size +^vs \e\en(VSp \e" spacing +^ft R \e" font +^sp 0.5v \e" half a line +^ti +3m +^^ +.P2 +This sets the font to Roman and the point size and line spacing +to whatever values are stored in the number registers +.BD PS +and +.BD VS . +.PP +Why are there two backslashes? +This is the eternal problem of how to quote a quote. +When +.UL troff +originally reads the macro definition, +it peels off one backslash +to see what's coming next. +To ensure that another is left in the definition when the +macro is +.ul +used, +we have to put in two backslashes in the definition. +If only one backslash is used, +point size and vertical spacing will be frozen at the time the macro +is defined, not when it is used. +.PP +Protecting by an extra layer of backslashes +is only needed for +.BD \en , +.BD \e* , +.BD \e$ +(which we haven't come to yet), +and +.BD \e +itself. +Things like +.BD \es , +.BD \ef , +.BD \eh , +.BD \ev , +and so on do not need an extra backslash, +since they are converted by +.UL troff +to an internal code immediately upon being seen. +.WS +.PP +Arithmetic expressions can appear anywhere that +a number is expected. +As a trivial example, +.P1 +^nr PS \e\en(PS\-2 +.P2 +decrements PS by 2. +Expressions can use the arithmetic operators +, \-, *, /, % (mod), +the relational operators >, >=, <, <=, =, and != (not equal), +and parentheses. +.PP +Although the arithmetic we have done so far +has been straightforward, +more complicated things are somewhat tricky. +First, +number registers hold only integers. +.UL troff +arithmetic uses truncating integer division, just like Fortran. +Second, in the absence of parentheses, +evaluation is done left-to-right +without any operator precedence +(including relational operators). +Thus +.P1 +7*\-4+3/13 +.P2 +becomes `\-1'. +Number registers can occur anywhere in an expression, +and so can scale indicators like +.BD p , +.BD i , +.BD m , +and so on (but no spaces). +Although integer division causes truncation, +each number and its scale indicator is converted +to machine units (1/432 inch) before any arithmetic is done, +so +1i/2u +evaluates to +0.5i +correctly. +.PP +The scale indicator +.BD u +often has to appear +when you wouldn't expect it _ +in particular, when arithmetic is being done +in a context that implies horizontal or vertical dimensions. +For example, +.P1 +^ll 7/2i +.P2 +would seem obvious enough _ +3\(12 inches. +Sorry. +Remember that the default units for horizontal parameters like +.BD .ll +are ems. +That's really `7 ems / 2 inches', +and when translated into machine units, it becomes zero. +How about +.P1 +^ll 7i/2 +.P2 +Sorry, still no good _ +the `2' is `2 ems', so `7i/2' is small, +although not zero. +You +.ul +must +use +.P1 +^ll 7i/2u +.P2 +So again, a safe rule is to +attach a scale indicator to every number, +even constants. +.PP +For arithmetic done within a +.BD .nr +command, +there is no implication of horizontal or vertical dimension, +so the default units are `units', +and 7i/2 and 7i/2u +mean the same thing. +Thus +.P1 +^nr ll 7i/2 +^ll \e\en(llu +.P2 +does just what you want, +so long as you +don't forget the +.BD u +on the +.BD .ll +command. diff --git a/share/doc/usd/22.trofftut/tt11 b/share/doc/usd/22.trofftut/tt11 new file mode 100644 index 000000000000..403e138d52c3 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt11 @@ -0,0 +1,230 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Macros with arguments +.PP +The next step is to define macros that can change from one +use to the next +according to parameters supplied as arguments. +To make this work, we need two things: +first, when we define the macro, we have to indicate that some +parts of it will be provided as arguments when the macro is called. +Then when the macro is +called +we have to provide actual arguments +to be plugged into the definition. +.PP +Let us illustrate by defining a macro +.BD .SM +that will print its argument two points +smaller than the surrounding text. +That is, the macro call +.P1 +^SM TROFF +.P2 +will produce +.UC TROFF . +.PP +The definition of +.BD .SM +is +.P1 +^de SM +\es\-2\e\e$1\es+2 +^^ +.P2 +Within a macro definition, +the symbol +.BD \e\e$n +refers to the +.BD n th +argument +that the macro was called with. +Thus +.BD \e\e$1 +is the string to be placed in a smaller point +size when +.BD .SM +is called. +.PP +As a slightly more complicated version, the following definition of +.BD .SM +permits optional second and third arguments +that will be printed in the normal size: +.P1 +^de SM +\e\e$3\es\-2\e\e$1\es+2\e\e$2 +^^ +.P2 +Arguments not provided when the macro is called are treated +as empty, +so +.P1 +^SM TROFF ), +.P2 +produces +.UC TROFF ), +while +.P1 +^SM TROFF ). ( +.P2 +produces +.UC TROFF ). ( +It is convenient to reverse +the order of arguments because trailing punctuation +is much more common than leading. +.PP +By the way, the number of arguments that a macro was called with +is available in number register +.BD .$ . +.PP +The following macro +.BD ^BD +is the one used to make the +`bold roman' we have been using for +.UL troff +command names in text. +It combines horizontal motions, width computations, +and argument rearrangement. +.P1 2 +\&.de BD +\e&\e\e$3\ef1\e\e$1\eh'\-\ew'\e\e$1'u+1u'\e\e$1\efP\e\e$2 +\&.. +.P2 +The +.BD \eh +and +.BD \ew +commands need no extra backslash, as we discussed above. +The +.BD \e& +is there in case the argument begins with a period. +.WS +.PP +Two backslashes are needed with the +.BD \e\e$n +commands, though, +to protect one of them when the macro is +being defined. +Perhaps a second example will make this clearer. +Consider a macro called +.BD .SH +which +produces section headings rather like those in this paper, +with the sections numbered automatically, +and the title in bold in a smaller size. +The use is +.P1 +^SH "Section title ..." +.P2 +(If the argument to a macro is to contain blanks, +then it must be +.ul +surrounded +by double quotes, +unlike a string, where only one leading quote is permitted.) +.PP +Here is the definition of the +.BD .SH +macro: +.P1 +.ta .75i 1.15i +^nr SH 0 \e" initialize section number +^de SH +^sp 0.3i +^ft B +^nr SH \e\en(SH+1 \e" increment number +^ps \e\en(PS\-1 \e" decrease PS +\e\en(SH. \e\e$1 \e" number. title +^ps \e\en(PS \e" restore PS +^sp 0.3i +^ft R +^^ +.P2 +The section number is kept in number register SH, which is incremented each +time just before it is used. +(A number register may have the same name as a macro +without conflict but a string may not.) +.PP +We used +.BD \e\en(SH +instead of +.BD \en(SH +and +.BD \e\en(PS +instead of +.BD \en(PS . +If we had used +.BD \en(SH , +we would get the value of the register at the time the macro was +.ul +defined, +not at the time it was +.ul +used. +If that's what you want, fine, +but not here. +Similarly, +by using +.BD \e\en(PS , +we get the point size at the time the macro is called. +.WS +.PP +As an example that does not involve numbers, +recall our +.BD .NP +macro which had a +.P1 +^tl 'left'center'right' +.P2 +We could make these into parameters by using instead +.P1 +^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT' +.P2 +so the title comes from three strings called LT, CT and RT. +If these are empty, then the title will be a blank line. +Normally CT would be set with something like +.P1 +\&^ds CT - % - +.P2 +to give just the page number between hyphens (as on the top of this page), +but a user could supply private definitions for +any of the strings. diff --git a/share/doc/usd/22.trofftut/tt12 b/share/doc/usd/22.trofftut/tt12 new file mode 100644 index 000000000000..44e3932495bf --- /dev/null +++ b/share/doc/usd/22.trofftut/tt12 @@ -0,0 +1,161 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Conditionals +.PP +Suppose we want the +.BD .SH +macro to leave two extra inches of space just before section 1, +but nowhere else. +The cleanest way to do that is to test inside the +.BD .SH +macro +whether +the section number is 1, +and add some space if it is. +The +.BD .if +command provides the conditional test +that we can add +just before the heading line is output: +.P1 4 +^if \e\en(SH=1 ^sp 2i \e" first section only +.P2 +.PP +The condition after the +.BD .if +can be any arithmetic or logical expression. +If the condition is logically true, or arithmetically greater than zero, +the rest of the line is treated as if +it were text _ +here a command. +If the condition is false, or zero or negative, +the rest of the line is skipped. +.PP +It is possible to do more than one command if a condition is true. +Suppose several operations are to be done before section 1. +One possibility is to define a macro +.BD .S1 +and invoke it +if we are about to do section 1 +(as determined by an +.BD .if ). +.P1 +^de S1 +--- processing for section 1 --- +^^ +^de SH +^^^ +^if \e\en(SH=1 ^S1 +^^^ +^^ +.P2 +.PP +An alternate way is to use the +extended form of the +.BD .if , +like this: +.P1 +^if \e\en(SH=1 \e{--- processing +for section 1 ----\e} +.P2 +The braces +.BD \e{ +and +.BD \e} +must occur in the positions shown +or you will get unexpected extra lines in your output. +.UL troff +also provides +an `if-else' construction, +which we will not go into here. +.PP +A condition can be negated by preceding it with +.BD ! ; +we get the same effect as above (but less clearly) by using +.P1 +^if !\e\en(SH>1 ^S1 +.P2 +.PP +There are a handful of +other conditions that can be tested with +.BD .if . +For example, is the current page even or odd? +.P1 +^if o ^tl 'odd page title''- % -' +^if e ^tl '- % -''even page title' +.P2 +gives facing pages different titles and page numbers on the +outside edge when used inside an appropriate new page macro. +.PP +Two other conditions +are +.BD t +and +.BD n , +which tell you whether the formatter is +.UL troff +or +.UL nroff . +.P1 +^if t troff stuff ... +^if n nroff stuff ... +.P2 +.PP +Finally, string comparisons may be made in an +.BD .if : +.P1 +^if 'string1'string2' stuff +.P2 +does `stuff' if +.ul +string1 +is the same as +.ul +string2. +The character separating the strings can be anything +reasonable that is +not contained in either string. +The strings themselves can reference strings with +.BD \e* , +arguments with +.BD \e$ , +and so on. diff --git a/share/doc/usd/22.trofftut/tt13 b/share/doc/usd/22.trofftut/tt13 new file mode 100644 index 000000000000..e768c15e43fb --- /dev/null +++ b/share/doc/usd/22.trofftut/tt13 @@ -0,0 +1,96 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Environments +.PP +As we mentioned, there is a potential problem +when going across a page boundary: +parameters like size and font +for a page title may well be different from those +in effect in the text when the page boundary occurs. +.UL troff +provides a very general way to deal with this and +similar situations. +There are three `environments', +each of which has independently settable versions of +many of the parameters associated with processing, +including size, font, line and title lengths, +fill/nofill mode, tab stops, and even partially collected lines. +Thus the titling problem may be readily solved by processing the main text +in one environment and titles in a separate one +with its own suitable parameters. +.PP +The command +.BD .ev\ n +shifts to environment +.BD n ; +.BD n +must be 0, 1 or 2. +The command +.BD .ev +with no argument returns to the +previous environment. +Environment names are maintained in a stack, so calls +for different environments may be nested and unwound consistently. +.PP +Suppose we say that the main text is processed in environment 0, +which is where +.UL troff +begins by default. +Then we can modify the new page macro +.BD .NP +to process titles in environment 1 like this: +.P1 2 +^de NP +^ev 1 \e" shift to new environment +^lt 6i \e" set parameters here +^ft R +^ps 10 +\&... any other processing ... +^ev \e" return to previous environment +^^ +.P2 +It is also possible to initialize the parameters for an environment +outside the +.BD .NP +macro, +but the version shown keeps all the processing in one place +and is thus easier to understand and change. diff --git a/share/doc/usd/22.trofftut/tt14 b/share/doc/usd/22.trofftut/tt14 new file mode 100644 index 000000000000..962fb4a21553 --- /dev/null +++ b/share/doc/usd/22.trofftut/tt14 @@ -0,0 +1,152 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.NH +Diversions +.PP +There are numerous occasions in page layout when it is necessary to store some text +for a period of time without actually printing it. +Footnotes are the most obvious example: +the text of the footnote usually appears in the input well before the place +on the page where it is to be printed is reached. +In fact, +the place where it is output normally depends on how big it is, +which implies that there must be a way +to process the footnote at least +enough to decide its size +without printing it. +.PP +.UL troff +provides a mechanism called a diversion +for doing this processing. +Any part of the output may be diverted into a macro instead +of being printed, +and then at some convenient time the macro may be put back into +the input. +.PP +The command +.BD .di\ xy +begins a diversion _ all subsequent output is collected into the macro +.BD xy +until the command +.BD .di +with no arguments is encountered. +This terminates the diversion. +The processed text is available at any time thereafter, simply +by giving the command +.P1 +^xy +.P2 +The vertical size of the last finished diversion is contained in +the built-in number register +.BD dn . +.PP +As a simple example, +suppose we want to implement a `keep-release' +operation, +so that text between the commands +.BD .KS +and +.BD .KE +will not be split across a page boundary +(as for a figure or table). +Clearly, when a +.BD .KS +is encountered, we have to begin diverting +the output so we can find out how big it is. +Then when a +.BD .KE +is seen, we decide +whether the diverted text will fit on the current page, +and print it either there if it fits, or at the top of the next page if it doesn't. +So: +.P1 2 +.ta .6i +^de KS \e" start keep +^br \e" start fresh line +^ev 1 \e" collect in new environment +^fi \e" make it filled text +^di XX \e" collect in XX +^^ +.P2 +.P1 2 +.ta .6i +^de KE \e" end keep +^br \e" get last partial line +^di \e" end diversion +^if \e\en(dn>=\e\en(.t .bp \e" bp if doesn't fit +^nf \e" bring it back in no-fill +^XX \e" text +^ev \e" return to normal environment +^^ +.P2 +Recall that number register +.BD nl +is the current position +on the output page. +Since output was being diverted, this remains +at its value when the diversion started. +.BD dn +is the amount of text in the diversion; +.BD .t +(another built-in register) +is the distance to the next trap, +which we assume is at the bottom margin of the page. +If the diversion is large enough to go past the trap, +the +.BD .if +is satisfied, and +a +.BD .bp +is issued. +In either case, the diverted output is then brought back with +.BD .XX . +It is essential to bring it back in no-fill mode so +.UL troff +will do no further processing on it. +.PP +This is not the most general keep-release, +nor is it robust in the face of all conceivable inputs, +but it would require more space than we have here to write it +in full generality. +This section is not intended +to teach everything about diversions, +but to sketch out enough that you can read +existing macro packages with some comprehension. diff --git a/share/doc/usd/22.trofftut/ttack b/share/doc/usd/22.trofftut/ttack new file mode 100644 index 000000000000..305a22a0ff17 --- /dev/null +++ b/share/doc/usd/22.trofftut/ttack @@ -0,0 +1,97 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.SH +Acknowledgements +.PP +I am deeply indebted to J. F. Ossanna, +the author of +.UL troff , +for his repeated patient explanations +of +fine points, +and for his continuing willingness to +adapt +.UL troff +to make other uses easier. +I am also grateful to Jim Blinn, Ted Dolotta, +Doug McIlroy, Mike Lesk and Joel Sturman +for helpful comments on this paper. +.SH +References +.LP +.IP [1] +J. F. Ossanna, +.ul +.UC NROFF/TROFF +User's Manual, +Bell Laboratories +Computing Science Technical Report 54, 1976. +.IP [2] +B. W. Kernighan, +.ul +A System for Typesetting Mathematics _ User's Guide +.ul +(Second Edition), +Bell Laboratories +Computing Science Technical Report 17, 1977. +.IP [3] +M. E. Lesk, +.ul +TBL _ A Program to Format Tables, +Bell Laboratories +Computing Science Technical Report 49, 1976. +.IP [4] +M. E. Lesk, +.ul +Typing Documents on UNIX, +Bell Laboratories, 1978. +.IP [5] +J. R. Mashey and D. W. Smith, +.ul +PWB/MM _ +.ul +Programmer's Workbench Memorandum Macros, +Bell Laboratories internal memorandum. +.IP [6] +Eric P. Allman, +.ul +Writing Papers with NROFF using -me, +University of California, Berkeley. diff --git a/share/doc/usd/22.trofftut/ttcharset b/share/doc/usd/22.trofftut/ttcharset new file mode 100644 index 000000000000..21c613a7009d --- /dev/null +++ b/share/doc/usd/22.trofftut/ttcharset @@ -0,0 +1,132 @@ +.\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode! +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.bp +.tr __ +.nr VS 12 +.vs 12p +.1C +.SH +Appendix A: Phototypesetter Character Set (APS-5) +.LP +These characters exist in roman, italic, and bold. +To get the one on the left, type the +four-character name on the right. +.sp +.ta .2i .8i 1i 1.6i 1.8i 2.4i 2.6i 3.2i 3.4i 4.0i 4.2i 4.8i 5i 5.6i 5.8i +.nf +.in 0.5i +\(ff \\(ff \(fi \\(fi \(fl \\(fl \(Fi \\(Fi \(Fl \\(Fl +\(ru \\(ru \(em \\(em \(14 \\(14 \(12 \\(12 \(34 \\(34 +\(co \\(co \(de \\(de \(dg \\(dg \(fm \\(fm \(ct \\(ct +\(rg \\(rg \(bu \\(bu \(sq \\(sq \(hy \\(hy + (In bold, \e(sq is \fB\(sq\fP.) +.sp +.in 0 +.tr ~~ +.ps 9 +.fi +The following are special-font characters: +.sp +.in 0.5i +.tr ~~ +.nf +.ta .3i 1i 1.3i 2i 2.3i 3i 3.3i +\(pl \\(pl \(mi \\(mi \(mu \\(mu \(di \\(di +\(eq \\(eq \(== \\(== \(>= \\(>= \(<= \\(<= +\(!= \\(!= \(+- \\(+- \(no \\(no \(sl \\(sl +\(ap \\(ap \(~= \\(~= \(pt \\(pt \(gr \\(gr +\(-> \\(-> \(<- \\(<- \(ua \\(ua \(da \\(da +\(is \\(is \(pd \\(pd \(if \\(if \(sr \\(sr +\(sb \\(sb \(sp \\(sp \(cu \\(cu \(ca \\(ca +\(ib \\(ib \(ip \\(ip \(mo \\(mo \(es \\(es +\(aa \\(aa \(ga \\(ga \(ci \\(ci (gone) \\(bs +\(sc \\(sc \(dd \\(dd \(lh \\(lh \(rh \\(rh +\(lt \\(lt \(rt \\(rt \(lc \\(lc \(rc \\(rc +\(lb \\(lb \(rb \\(rb \(lf \\(lf \(rf \\(rf +\(lk \\(lk \(rk \\(rk \(bv \\(bv \(ts \\(ts +\(br \\(br \(or \\(or \(ul \\(ul \(rn \\(rn +\(** \\(** +.sp +.in 0 +.ps 9 +.fi +These +four +characters also have two-character names. +The \' is the apostrophe on terminals; +the \` is the other quote mark. +.sp +.in .5i +\' \e\(aa \` \e\(ga \(mi \e\(mi \_ \e\_ +.sp +.in 0 +These +characters exist only on the special font, +but they do not have four-character names: +.sp +.in .5i +.nf +.tr ^^ +" { } < > ~ ^ \e # @ +.sp +.in 0 +.fi +For greek, precede the roman letter by +.BD \e(* +to get the corresponding greek; +for example, +.BD \e(*a +is +\(*a. +.sp +.in 0.5i +.nf +.cs R 36 +abgdezyhiklmncoprstufxqw +\(*a\(*b\(*g\(*d\(*e\(*z\(*y\(*h\(*i\(*k\(*l\(*m\(*n\(*c\(*o\(*p\(*r\(*s\(*t\(*u\(*f\(*x\(*q\(*w +.sp +ABGDEZYHIKLMNCOPRSTUFXQW +\(*A\(*B\(*G\(*D\(*E\(*Z\(*Y\(*H\(*I\(*K\(*L\(*M\(*N\(*C\(*O\(*P\(*R\(*S\(*T\(*U\(*F\(*X\(*Q\(*W +.ps 9 +.cs R +.in 0 +.fi diff --git a/share/doc/usd/22.trofftut/ttindex b/share/doc/usd/22.trofftut/ttindex new file mode 100644 index 000000000000..fcb467c2eb1f --- /dev/null +++ b/share/doc/usd/22.trofftut/ttindex @@ -0,0 +1,197 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" 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: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" 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. +.\" +.\" 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. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.bp +.2C +.SH +Index +.LP +.nf +.ps 8 +.vs 9p +! (negating conditionals) 17 +#$ (macro argument) 16 +#*x, #(xy (invoke string macro) 14 +#b (bracketing function) 13 +#d (subscript) 11 +#f (font change) 5 +#h (horizontal motion) 12 +#nx, #n(xy (number register) 15 +#o (overstrike) 13 +#s (size change) 3 +#u (superscript) 11 +#v (vertical motion) 11 +#w (width function) 12 +#z (zero motion) 13 +\(fmcommand instead of ^command 9 +% (page number register) 10,15 +^^ (end of macro definition) 7 +^bp 9,10 +^br (break) 9 +^ce (center) 2 +^ds (define string macro) 7,14 +^fi (fill) 2 +^ft (change font) 5 +^if (conditional test) 16 +^in (indent) 6 +^lg (set ligatures 5 +^ll (line length) 6 +^nf (nofill) 2 +^nr (set number register) 14 +^pn (page number) 10 +^ps (change point size) 1,3 +^sp (space) 4 +^ss (set space size) 10 +^ta (set tab stops) 11 +^tc (set tab character) 10 +^tl (title) 9 +^tr (translate characters) 2,6 +^ul (italicize) 6 +^vs (vertical spacing) 3 +^wh (when conditional) 9,17 +accents 6,13 +apostrophes 6 +arithmetic 15 +backslash 1,3,5,14,16 +begin page (^bp) 9 +block macros (B1,B2) 8 +bold font (.ft B) 5 +boustrophedon 12 +bracketing function (##b) 13 +break (^br) 9 +break-causing commands 9 +centering (^ce) 2 +changing fonts (^ft, #f) 5 +changing macros 15 +character set 4,5,19 +character translation (^tr) 2,6 +columnated output 10 +commands 1 +commands that cause break 9 +conditionals (^if) 16 +constant proportion 7 +default break list 9 +define macro (^de) 7 +define string macro (^ds) 14 +drawing lines 11 +em 7,11 +end of macro (^^) 7 +even page test (e) 17 +fill (^fi) 2 +fonts (^ft) 4,19 +Greek (#(*-) 5,19 +hanging indent (^ti) 12 +hints 20 +horizontal motion (#h) 12 +hp (horizontal position register) 15 +hyphen 6 +i scale indicator 4 +indent (^in) 6 +index 21 +italic font (.ft I) 4 +italicize (^ul) 6 +legal point sizes 3 +ligatures (ff,fi,fl; ^lg) 5 +line length (^ll) 6 +line spacing (^vs) 3 +local motions (#u,#d,#v,#h,#w,#o,#z,#b) 11 ff +m scale indicator 7 +machine units 4,12 +macro arguments 15 +macros 7 +macros that change 15 +multiple backslashes 14 +negating conditionals (!) 17 +new page macro (NP) 8 +nl (current vertical position register) 15 +nofill (^nf) 2 +NROFF test (n) 17 +nested quotes 12 +number registers (^nr,#n) 14 +numbered paragraphs 12 +odd page test (o) 17 +order of evaluation 14 +overstrike (#o) 13 +p scale indicator 3 +page number register (%) 10 +page numbers (^pn, ^bp) 10 +paragraph macro (PG) 7 +Paternoster 6 +point size (^ps) 1,3 +previous font (#fP, ^ft P) 5 +previous point size (#s0,^ps) 3 +quotes 6 +relative change (\(+-) 6 +ROFF 1 +ROFF header and footer 8 +Roman font (.ft R) 4 +scale indicator i 4 +scale indicator m 7 +scale indicator p 3 +scale indicator u 12 +scale indicators in arithmetic 15 +section heading macro (SC) 15 +set space size (^ss) 10 +size _ see point size +space (^sp) 4 +space between lines (^vs) 3 +special characters (#(xx) 5,19 +string macros (^ds,#*) 14 +subscripts (#d) 11 +superscripts (#u) 11 +tab character (^tc) 11 +tabs (^ta) 10 +temporary indent (^ti) 7 +titles (^tl) 8 +translate (^tr) 2,6,12 +TROFF examples 19 +TROFF test (t) 17 +truncating division 15 +type faces _ see fonts +u scale indicator 12 +underline (^ul) 6 +valid point sizes 3 +vertical motion (#v) 11 +vertical position on page 9 +vertical spacing (^vs) 3 +when (^wh) 9,17 +width function (#w) 12 +width of digits 10 +zero motion (#z) 13 diff --git a/share/doc/usd/Makefile b/share/doc/usd/Makefile new file mode 100644 index 000000000000..16d98b85506f --- /dev/null +++ b/share/doc/usd/Makefile @@ -0,0 +1,21 @@ +# The following modules are not provided: +# 14.jove + +SUBDIR= title \ + contents \ + 04.csh \ + 05.dc \ + 06.bc \ + 07.mail \ + 10.exref \ + 11.vitut \ + 12.vi \ + 13.viref \ + 18.msdiffs \ + 19.memacros \ + 20.meref \ + 21.troff \ + 22.trofftut +SUBDIR_PARALLEL= + +.include <bsd.subdir.mk> diff --git a/share/doc/usd/contents/Makefile b/share/doc/usd/contents/Makefile new file mode 100644 index 000000000000..860f1199707d --- /dev/null +++ b/share/doc/usd/contents/Makefile @@ -0,0 +1,6 @@ +VOLUME= usd +DOC= contents +SRCS= contents.ms +MACROS= -ms + +.include <bsd.doc.mk> diff --git a/share/doc/usd/contents/contents.ms b/share/doc/usd/contents/contents.ms new file mode 100644 index 000000000000..34d9e11738e1 --- /dev/null +++ b/share/doc/usd/contents/contents.ms @@ -0,0 +1,306 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.de ND +.KE +.sp +.KS +.. +.OH '''USD Contents' +.EH 'USD Contents''' +.ND +.TL +UNIX User's Supplementary Documents (USD) +.if !r.U .nr .U 0 +.if \n(.U \{\ +.br +.>> <a href="Title.html">Title.html</a> +.\} +.sp +\s-2 4.4 Berkeley Software Distribution\s+2 +.sp +\fRJune, 1993\fR +.PP +This volume contains documents which supplement the manual pages in +.I +The Unix User's Reference Manual +.R +for the 4.4BSD system as distributed by U.C. Berkeley. +.sp +.KS +.SH +Getting Started +.ND +.IP +.tl 'Unix for Beginners \- Second Edition''USD:1' +.QP +An introduction to the most basic uses of the system. +.ND +.IP +.tl 'Learn \- Computer\-Aided Instruction on UNIX (Second Edition)''USD:2' +.QP +Describes a computer-aided instruction program that walks new users through +the basics of files, the editor, and document prepararation software. +.ND +.SH +Basic Utilities +.ND +.IP +.tl 'An Introduction to the UNIX Shell''USD:3' +.QP +Steve Bourne's introduction to the capabilities of +.I sh, +a command interpreter especially popular for writing shell scripts. +.ND +.IP +.tl 'An Introduction to the C shell''USD:4' +.if \n(.U \{\ +.br +.>> <a href="04.csh/paper.html">04.csh/paper.html</a> +.\} +.QP +This introduction to +.I csh, +(a command interpreter popular for interactive work) describes many +commonly used UNIX commands, assumes little prior knowledge of UNIX, +and has a glossary useful for beginners. +.ND +.IP +.tl 'DC \- An Interactive Desk Calculator''USD:5' +.QP +A super HP calculator, if you do not need floating point. +.ND +.IP +.tl 'BC \- An Arbitrary Precision Desk-Calculator Language''USD:6' +.QP +A front end for DC that provides infix notation, control flow, and +built\-in functions. +.ND +.SH +Communicating with the World +.ND +.IP +.tl 'Mail Reference Manual''USD:7' +.if \n(.U \{\ +.br +.>> <a href="07.mail/paper.html">07.mail/paper.html</a> +.\} +.QP +Complete details on one of the programs for sending and reading your mail. +.ND +.IP +.tl 'The Rand MH Message Handling System''USD:8' +.QP +This system for managing your computer mail uses lots of small programs, +instead of one large one. +.ND +.SH +Text Editing +.ND +.IP +.tl 'A Tutorial Introduction to the Unix Text Editor''USD:9' +.QP +An easy way to get started with the line editor, +.I ed. +.ND +.IP +.tl 'Advanced Editing on Unix''USD:10' +.if \n(.U \{\ +.br +.>> <a href="10.exref/paper.html">10.exref/paper.html</a> +.\} +.QP +The next step. +.ND +.IP +.tl 'An Introduction to Display Editing with Vi''USD:11' +.if \n(.U \{\ +.br +.>> <a href="11.vitut/paper.html">11.vitut/paper.html</a> +.\} +.QP +The document to learn to use the \fIvi\fR screen editor. +.ND +.IP +.tl 'Ex Reference Manual (Version 3.7)''USD:12' +.if \n(.U \{\ +.br +.>> <a href="12.vi/paper.html">12.vi/paper.html</a> +.\} +.QP +The final reference for the \fIex\fR editor. +.ND +.IP +.tl 'Vi Reference Manual''USD:13' +.if \n(.U \{\ +.br +.>> <a href="13.viref/paper.html">13.viref/paper.html</a> +.\} +.QP +The definitive reference for the \fInvi\fR editor. +.ND +.IP +.tl 'Jove Manual for UNIX Users''USD:14' +.QP +Jove is a small, self-documenting, customizable display editor, based on +EMACS. A plausible alternative to +.I vi. +.ND +.IP +.tl 'SED \- A Non-interactive Text Editor''USD:15' +.QP +Describes a one-pass variant of +.I ed +useful as a filter for processing large files. +.ND +.IP +.tl 'AWK \- A Pattern Scanning and Processing Language (Second Edition)''USD:16' +.QP +A program for data selection and transformation. +.ND +.SH +Document Preparation +.ND +.IP +.tl 'Typing Documents on UNIX: Using the \-ms Macros with Troff and Nroff''USD:17' +.QP +Describes and gives examples of the basic use of the typesetting tools and +``-ms'', a frequently used package of formatting requests that make it easier +to lay out most documents. +.ND +.IP +.tl 'A Revised Version of \-ms''USD:18' +.if \n(.U \{\ +.br +.>> <a href="18.msdiffs/paper.html">18.msdiffs/paper.html</a> +.\} +.QP +A brief description of the Berkeley revisions made to the \-ms formatting +macros for nroff and troff. +.ND +.IP +.tl 'Writing Papers with \fInroff\fR using \-me''USD:19' +.if \n(.U \{\ +.br +.>> <a href="19.memacros/paper.html">19.memacros/paper.html</a> +.\} +.QP +Another popular macro package for +.I nroff. +.ND +.IP +.tl '\-me Reference Manual''USD:20' +.if \n(.U \{\ +.br +.>> <a href="20.meref/paper.html">20.meref/paper.html</a> +.\} +.QP +The final word on \-me. +.ND +.IP +.tl 'NROFF/TROFF User\'s Manual''USD:21' +.QP +Extremely detailed information about these document formatting programs. +.ND +.IP +.tl 'A TROFF Tutorial''USD:22' +.QP +An introduction to the most basic uses of +.I troff +for those who really want to know such things, or want to write their +own macros. +.ND +.IP +.tl 'A System for Typesetting Mathematics''USD:23' +.QP +Describes +.I eqn, +an easy-to-learn language for high-quality mathematical typesetting. +.ND +.IP +.tl 'Typesetting Mathematics \- User\'s Guide (Second Edition)''USD:24' +.QP +More details about how to use +.I eqn. +.ND +.IP +.tl 'Tbl \- A Program to Format Tables''USD:25' +.QP +A program for easily typesetting tabular material. +.ND +.IP +.tl 'Refer \- A Bibliography System''USD:26' +.QP +An introduction to one set of tools used to maintain bibliographic databases. +The major program, +.I refer, +is used to automatically retrieve and format the references +based on document citations. +.ND +.IP +.tl 'Some Applications of Inverted Indexes on the UNIX System''USD:27' +.QP +Mike Lesk's paper describes the +.I refer +programs in a somewhat larger context. +.ND +.IP +.tl 'BIB \- A Program for Formatting Bibliographies''USD:28' +.QP +This is an alternative to +.I refer +for expanding citations in documents. +.ND +.IP +.tl 'Writing Tools \- The STYLE and DICTION Programs''USD:29' +.QP +These are programs which can help you understand and improve your +writing style. +.ND +.SH +Amusements +.ND +.IP +.tl 'A Guide to the Dungeons of Doom''USD:30' +.if \n(.U \{\ +.br +.>> <a href="30.rogue/paper.html">30.rogue/paper.html</a> +.\} +.QP +An introduction to the popular game of \fIrogue\fP, a fantasy game +which is one of the biggest known users of VAX cycles. +.ND +.IP +.tl 'Star Trek''USD:31' +.if \n(.U \{\ +.br +.>> <a href="31.trek/paper.html">31.trek/paper.html</a> +.\} +.QP +You are the Captain of the Starship Enterprise. Wipe out the +Klingons and save the Federation. +.KE diff --git a/share/doc/usd/title/Makefile b/share/doc/usd/title/Makefile new file mode 100644 index 000000000000..3a0b41aee339 --- /dev/null +++ b/share/doc/usd/title/Makefile @@ -0,0 +1,5 @@ +VOLUME= usd +DOC= Title +SRCS= Title + +.include <bsd.doc.mk> diff --git a/share/doc/usd/title/Title b/share/doc/usd/title/Title new file mode 100644 index 000000000000..3723f616a11f --- /dev/null +++ b/share/doc/usd/title/Title @@ -0,0 +1,114 @@ +.\" Copyright (c) 1986, 1993 The Regents of the University of California. +.\" 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 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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. +.\" +.ps 18 +.vs 22 +.sp 2.75i +.ft B +.ce 2 +UNIX User's Supplementary Documents +(USD) +.ps 14 +.vs 16 +.sp |4i +.ce 2 +4.4 Berkeley Software Distribution +.sp |5.75i +.ft R +.ps 12 +.vs 16 +.ce +June, 1993 +.sp |8.2i +.ce 5 +Computer Systems Research Group +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California +Berkeley, California 94720 +.bp +\& +.sp |1i +.hy 0 +.ps 10 +.vs 12p +Copyright 1979, 1980, 1983, 1986, 1993 +The Regents of the University of California. All rights reserved. +.sp 2 +Other than the specific documents listed below as copyrighted by AT&T, +redistribution and use of this manual in source and binary forms, +with or without modification, are permitted provided that the +following conditions are met: +.sp 0.5 +.in +0.2i +.ta 0.2i +.ti -0.2i +1) Redistributions of this manual must retain the copyright +notices on this page, this list of conditions and the following disclaimer. +.ti -0.2i +2) Software or documentation that incorporates part of this manual must +reproduce the copyright notices on this page, this list of conditions and +the following disclaimer in the documentation and/or other materials +provided with the distribution. +.ti -0.2i +3) All advertising materials mentioning features or use of this software +must display the following acknowledgement: +``This product includes software developed by the University of +California, Berkeley and its contributors.'' +.ti -0.2i +4) Neither the name of the University nor the names of its contributors +may be used to endorse or promote products derived from this software +without specific prior written permission. +.in -0.2i +.sp +\fB\s-1THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 THE REGENTS OR CONTRIBUTORS 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.\s+1\fP +.sp 2 +Documents USD:1, 2, 3, 5, 6, 9, 10, 15, 16, 17, 21, 22, 23, 24, 25, 26, 27, +and 29 are copyright 1979, AT&T Bell Laboratories, Incorporated. +Holders of \x'-1p'UNIX\v'-4p'\s-3TM\s0\v'4p'/32V, +System III, or System V software licenses are +permitted to copy these documents, or any portion of them, +as necessary for licensed use of the software, +provided this copyright notice and statement of permission +are included. +.sp 2 +Documents USD:8, 14, and 28 are part of the +user contributed software. +.sp 2 +The views and conclusions contained in this manual are those of the +authors and should not be interpreted as representing official policies, +either expressed or implied, of the Regents of the University of California. |