.\" history.1
.\"-------
.\" See rc.1 for man page portability notes.
.\"-------
.\" Dd	distance to space vertically before a "display"
.\" These are what n/troff use for interparagraph distance
.\"-------
.if t .nr Dd .4v
.if n .nr Dd 1v
.\"-------
.\" Ds	begin a display, indented .5 inches from the surrounding text.
.\"
.\" Note that uses of Ds and De may NOT be nested.
.\"-------
.de Ds
.\" .RS \\$1
.sp \\n(Ddu
.in +0.5i
.nf
..
.\"-------
.\" De	end a display (no trailing vertical spacing)
.\"-------
.de De
.fi
.in
.\" .RE
..
.\"-------
.\" I stole the Xf macro from the -man macros on my machine (originally
.\" "}S", I renamed it so that it won't conflict).
.\"-------
.\" Set Cf to the name of the constant width font.
.\" It will be "C" or "(CW", typically.
.\" NOTEZ BIEN the lines defining Cf must have no trailing white space:
.\"-------
.if t .ds Cf C
.if n .ds Cf R
.\"-------
.\" Rc - Alternate Roman and Courier
.\"-------
.de Rc
.Xf R \\*(Cf \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.\"-------
.\" Ic - Alternate Italic and Courier
.\"-------
.de Ic
.Xf I \\*(Cf \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.\"-------
.\" Bc - Alternate Bold and Courier
.\"-------
.de Bc
.Xf B \\*(Cf \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.\"-------
.\" Cr - Alternate Courier and Roman
.\"-------
.de Cr
.Xf \\*(Cf R \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.\"-------
.\" Ci - Alternate Courier and Italic
.\"-------
.de Ci
.Xf \\*(Cf I \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.\"-------
.\" Cb - Alternate Courier and Bold
.\"-------
.de Cb
.Xf \\*(Cf B \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.\"-------
.\" Xf - Alternate fonts
.\"
.\" \$1 - first font
.\" \$2 - second font
.\" \$3 - desired word with embedded font changes, built up by recursion
.\" \$4 - text for first font
.\" \$5 - \$9 - remaining args
.\"
.\" Every time we are called:
.\"
.\" If		there is something in \$4
.\" then	Call ourself with the fonts switched,
.\"		with a new word made of the current word (\$3) and \$4
.\"		rendered in the first font,
.\"		and with the remaining args following \$4.
.\" else	We are done recursing.  \$3 holds the desired output
.\"		word.  We emit \$3, change to Roman font, and restore
.\"		the point size to the default.
.\" fi
.\"
.\" Use Xi to add a little bit of space after italic text.
.\"-------
.de Xf
.ds Xi
.\"-------
.\" I used to test for the italic font both by its font position
.\" and its name.  Now just test by its name.
.\"
.\" .if "\\$1"2" .if !"\\$5"" .ds Xi \^
.\"-------
.if "\\$1"I" .if !"\\$5"" .ds Xi \^
.\"-------
.\" This is my original code to deal with the recursion.
.\" Evidently some nroffs can't deal with it.
.\"-------
.\" .ie !"\\$4"" \{\
.\" .	Xf \\$2 \\$1 "\\$3\\f\\$1\\$4\\*(Xi" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
.\" .\}
.\" .el \{\\$3
.\" .	ft R	\" Restore the default font, since we don't know
.\" .		\" what the last font change was.
.\" .	ps 10	\" Restore the default point size, since it might
.\" .		\" have been changed by an argument to this macro.
.\" .\}
.\"-------
.\" Here is more portable (though less pretty) code to deal with
.\" the recursion.
.\"-------
.if !"\\$4"" .Xf \\$2 \\$1 "\\$3\\f\\$1\\$4\\*(Xi" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
.if "\\$4"" \\$3\fR\s10
..
.TH HISTORY 1 "30 July 1991"
.SH NAME
\-, \-\|\-, \-p, \-\|\-p \- shell history programs
.SH SYNOPSIS
.B \-
.RI [ pattern ...]
.RI [ substitution ...]
.SH DESCRIPTION
This set of programs provides a crude history mechanism for the shell
.IR rc (1).
It is based on the v8 UNIX programs
.IR = ,
.IR == ,
etc.
.PP
The program
.RI `` \- ''
runs the shell on the command it is requested to find.
The program
.RI `` \-\|\- ''
edits that command first.
The programs
.RI `` \-p ''
and
.RI `` \-\|\-p ''
are similar, except that they print the final command on their standard
output instead of running the shell.
.PP
The commands work by looking for a file
named by the environment variable
.Cr $history ,
and by searching for previous commands in this file.
Old commands can be edited,
or simply re-executed according to the rules below:
.PP
A command is searched for by examining the lines in
.Cr $history
in reverse order.
Lines which contain a previous invocation of the history
program itself are ignored.
If one or more
.I pattern
is supplied on the command line,
then the patterns are used as a means of
limiting the search.
Patterns match any substring of a previous command,
and if more than one pattern is present then all patterns must be
matched before a command is selected.
.PP
Substitutions may also be specified on the command line.
These have the syntax:
.Ds
.Ic old :[:...] new
.De
.PP
(Note that the
.I old
pattern is used as a search-limiting pattern also.)
Substitutions happen from left to right and are repeated according to the
number of colons specified.
.PP
Finally, if the program was invoked as
.RI `` -- ''
or
.RI `` --p '',
a command may be edited in a crude line-mode fashion.  The line to be
edited is printed out, and below it the user supplies modifications to
the command.
.TP
.B any character except those below
Replaces the character above.
.TP
.B space or tab
Skips over the above character(s).
.TP
.B #
Deletes one character.
.TP
.B %
Replaces one character with a space.
.TP
.B ^
Inserts the rest of the typed line just before the character.
.TP
.B $
Deletes the rest of the line from that character on, and replaces
it with the rest of the typed line.
.TP
.B +
Appends the rest of the typed line.
.TP
.B \-
Backs up to a previous command satisfying the same matching
constraints.
.TP
.B end of line
If any changes have been made, the command is printed out again for
further editing.  If no changes have been made, the command is executed
or printed, and the program exits.
.TP
.B end of file
If an end-of-file is read from the keyboard by the editor,
it aborts with exit status 1 and does not produce any output.
.SH EXAMPLES
The history programs work best when their output is reinterpreted by
the shell using an
.Cr eval
command.
This can be achieved by writing a shell function to perform the
reinterpretation:
.Ds
.Cr "fn - -- {"
.Cr "	comm = \`{$0^p $*}"
.Cr "	if (! ~ $#comm 0) {"
.Cr "		echo $comm >[1=2]"
.Cr "		eval $comm"
.Cr "	}"
.Cr "}"
.De
.PP
Stuttering the `:' in a substitution allows things like:
.Ds
; prog 1 2 3 abc > /very/long/path/abc.out
etc.
- prog abc::xyz
prog 1 2 3 xyz > /very/long/path/xyz.out
;
.De