build: Better Build System

1 files changed, 888 insertions, 0 deletions

diff --git a/static/unix-v10/man9/sam.9 b/static/unix-v10/man9/sam.9
new file mode 100644
index 00000000..314a1250
--- /dev/null
+++ b/static/unix-v10/man9/sam.9
@@ -0,0 +1,888 @@
+.ds a \fR*\ \fP
+.TH SAM 9.1
+.CT 1 editor
+.SH NAME
+sam \- screen editor with structural regular expressions 
+.SH SYNOPSIS
+.B sam
+[
+.I option ...
+] [
+.I files
+]
+.PP
+.I sam
+.B -r
+.I machine
+.PP
+.B sam.save
+.SH DESCRIPTION
+.I Sam
+is a multi-file editor.
+It modifies a local copy of a Unix file.
+The copy is here called a
+.IR file ;
+a Unix file is distinguished by the trademarked
+adjective.
+The files are listed in a menu available through mouse button 3
+or the
+.B n
+command.
+Each file has an associated name, usually the name of the
+Unix file from which it was read, and a `modified' bit that indicates whether
+the editor's file agrees with the Unix file.
+The Unix file is not read into
+the editor's file until it first becomes the current file\(emthat to
+which editing commands apply\(emwhereupon its menu entry is printed.
+The options are
+.TP
+.B -d
+Do not download the terminal part of
+.I sam.
+Editing will be done with the command language only, as in
+.IR ed (1).
+.TP
+.BI -r " machine
+Run the host part remotely
+on the specified machine, the terminal part locally.
+This extends graphic editing to files on machines that
+don't ordinarily support it or across 
+.RI non- nfs (8)
+connections.
+.SS Regular expressions
+Regular expressions are as in
+.IR egrep 
+(see
+.IR gre (1)),
+with the addition of
+.B @
+and
+.BR \en .
+A regular expression may never contain a literal newline character.
+The elements of regular expressions are:
+.TP
+.B .
+Match any character except newline.
+.TP
+.B \en
+Match newline.
+.TP
+.B \ex
+For any character except
+.B n
+match the character (here
+.BR x ).
+.TP
+.B @
+Match any character.
+.TP
+.B [abc]
+Match any character in the square brackets.
+.B \en
+may be mentioned.
+.TP
+.B [^abc]
+Match any character not in the square brackets, but never a newline.
+Both these forms accept a range of
+.SM ASCII
+characters indicated by
+a dash, as in
+.BR a-z .
+.TP
+.B ^
+Match the null string immediately after a newline.
+.TP
+.B $
+Match the null string immediately before a newline.
+.PP
+Any other character except newline matches itself.
+.PP
+In the following,
+.I r1
+and
+.I r2
+are regular expressions.
+.TP
+.BI ( r1 )
+Match what
+.I r1
+matches.
+.TP
+.IB r1 | r2
+Match what
+.I r1
+or what
+.IR r2
+matches.
+.TP
+.IB r1 *
+Match zero or more adjacent matches
+of
+.IR r1 .
+.TP
+.IB r1 +
+Match one or more adjacent matches of
+.IR r1 .
+.TP
+.IB  r1 ?
+Match zero or one matches of
+.IR r1 .
+.PP
+The operators
+.BR * ,
+.B +
+and
+.B ?
+are highest precedence, then catenation, then
+.B |
+is lowest.
+The empty
+regular expression stands for the last complete expression encountered.
+A regular expression in
+.I sam
+matches the longest leftmost substring formally
+matched by the expression.
+Searching in the reverse direction is equivalent
+to searching backwards with the catenation operations reversed in
+the expression.
+.SS Addresses
+An address identifies a substring in a file.
+In the following, `character
+.IR n '
+means the null string
+after the
+.IR n -th
+character in the file, with 1 the
+first character in the file.
+`Line
+.IR n '
+means the
+.IR n -th
+match,
+starting at the beginning of the file, of the regular expression
+.L .*\en? .
+(The peculiar properties of a last line without a newline are
+temporarily undefined.)
+All files always have a current substring, called dot,
+that is the default address.
+.SS Simple Addresses
+.TP
+.BI # n
+The empty string after character
+.IR n ;
+.B #0
+is the beginning of the file.
+.TP
+.I n
+Line
+.IR n .
+.TP
+.BI  / regexp /
+.PD0
+.TP
+.BI ? regexp ?
+The substring that matches the regular expression,
+found by looking toward the end 
+.RB ( / )
+or beginning
+.RB ( ? )
+of the file,
+and if necessary continuing the search from the other end to the
+starting point of the search.
+The matched substring may straddle
+the starting point.
+.PD
+.TP
+.B 0
+The string before the first full line.
+This is not necessarily
+the null string; see
+.B +
+and
+.B -
+below.
+.TP
+.B $
+The null string at the end of the file.
+.TP
+.B .
+Dot.
+.TP
+.B \&'
+The mark in the file (see the
+.B k
+command below).
+.TP
+\f(CW"\f2regexp\f(CW"\f1\f1
+Preceding a simple address (default
+.BR . ),
+refers to the address evaluated in the unique file whose menu line
+matches the regular expression.
+.SS Compound Addresses
+In the following,
+.I a1
+and
+.I a2
+are addresses.
+.TP
+.IB a1 + a2
+The address
+.I a2
+evaluated starting at the end of
+.IR a1 .
+.TP
+.IB a1 - a2
+The address
+.I a2
+evaluated looking in the reverse direction
+starting at the beginning of
+.IR a1 .
+.TP
+.IB a1 , a2
+The substring from the beginning of
+.I a1
+to the end of
+.IR a2 .
+If
+.I a1
+is missing,
+.B 0
+is substituted
+If
+.I a2
+is missing,
+.B $
+is substituted.
+.TP
+.IB  a1 ; a2
+Like
+.IB a1 , a2,
+but with
+.I a2
+evaluated at the end of, and dot set to,
+.IR a1 .
+.PP
+The operators
+.B +
+and
+.B -
+are high precedence, while
+.B ,
+and
+.B ;
+are low precedence.
+.PP
+In both
+.B +
+and
+.B -
+forms, if
+.I a2
+is a line or character address with a missing
+number, the number defaults to 1.
+If
+.I a1
+is missing,
+.L .
+is substituted.
+If both
+.I a1
+and
+.I a2
+are present and distinguishable,
+.B +
+may be elided.
+.I a2
+may be a regular
+expression; if it is delimited by
+.LR ? 's,
+the effect of the
+.B +
+or
+.B -
+is reversed.
+.PP
+It is an error for a compound address to represent a malformed substring.
+Some useful idioms: 
+.IB a1 +- 
+.RI ( a1 \&\f5-+\fP )
+selects the line containing
+the end (beginning) of a1.
+.BI 0/ regexp /
+locates the first match of the expression in the file.
+(The form
+.B 0;//
+sets dot unnecessarily.)
+.BI ./ regexp /// 
+finds the second following occurrence of the expression,
+and
+.BI .,/ regexp /
+extends dot.
+.SS Commands
+In the following, text demarcated by slashes represents text delimited
+by any printable
+.SM ASCII
+character except alphanumerics.
+Any number of
+trailing delimiters may be elided, with multiple elisions then representing
+null strings, but the first delimiter must always
+be present.
+In any delimited text,
+newline may not appear literally;
+.B \en
+may be typed for newline; and
+.B \e/
+quotes the delimiter, here 
+.LR / .
+Backslash is otherwise interpreted literally, except in
+.B s
+commands.
+.PP
+Most commands may be prefixed by an address to indicate their range
+of operation.
+Those that may not are marked with a 
+.L *
+below.
+If a command takes
+an address and none is supplied, dot is used.
+The sole exception is
+the
+.B w
+command, which defaults to
+.BR 0,$ .
+In the description, `range' is used
+to represent whatever address is supplied.
+Many commands set the
+value of dot as a side effect.
+If so, it is always set to the `result'
+of the change: the empty string for a deletion, the new text for an
+insertion, etc. (but see the
+.B s
+and
+.B e
+commands).
+.br
+.ne 1.2i
+.SS Text commands
+.PD0
+.TP
+.BI a/ text /
+.TP
+or
+.TP
+.B  a
+.TP
+.I lines of text
+.TP
+.B .
+Insert the text into the file after the range.
+Set dot.
+.TP
+.B c\fP
+.br
+.ns
+.TP
+.B i\fP
+Same as
+.BR a ,
+but
+.B c
+replaces the text, while
+.B i
+inserts
+.I before
+the range.
+.TP
+.B d
+Delete the text in the range.
+Set dot.
+.TP
+.BI s/ regexp / text /
+Substitute
+.I text
+for the first match to the regular expression in the range.
+Set dot to the modified range.
+In 
+.I text
+the character
+.B &
+stands for the string
+that matched the expression. 
+Backslash behaves as usual unless followed by
+a digit:
+.BI \e d
+stands for the string that matched the
+subexpression begun by the
+.IR d -th
+left parenthesis.
+If
+.I s
+is followed immediately by a
+number
+.IR n ,
+as in
+.BR s2/x/y/ ,
+the
+.IR n -th
+match in the range is substituted.
+If the
+command is followed by a
+.BR g ,
+as in
+.BR s/x/y/g ,
+all matches in the range
+are substituted.
+.TP
+.BI m " a1
+.br
+.ns
+.TP
+.BI t " a1
+Move the range to after
+.I a1
+.RB ( m ),
+or copy it
+.RB ( t ).
+Set dot.
+.SS Display commands
+.TP
+.B p
+Print the text in the range.
+Set dot.
+.TP
+.B =
+Print the line address and character address of the range.
+.TP
+.B =#
+Print just the character address of the range.
+.SS File commands
+In these commands a
+.I file-list
+may be expressed
+.BI < Unix-command
+in which case the file names are taken as words (in the shell sense)
+generated by the Unix command.
+.TP
+.BI \*ab " file-list
+Set the current file to the first file named in the list
+that
+.I sam
+also has in its menu.
+.TP
+.BI \*aB " file-list
+Same as
+.BR b ,
+except that file names not in the menu are entered there,
+and all file names in the list are examined.
+.TP
+.B \*an
+Print a menu of files.
+The format is:
+.RS
+.TP \w'\ \ or\ blank\ \'u
+.BR ' " or blank
+indicating the file is modified or clean,
+.TP
+.BR - " or \&" +
+indicating the the file is unread or has been read
+(in the terminal,
+.B *
+means more than one window is open),
+.TP
+.BR . " or blank
+indicating the current file,
+.TP
+a blank,
+.TP
+and the file name.
+.RE
+.TP 0
+.BI \*aD " file-list
+Delete the named files from the menu.
+If no files are named, the current file is deleted.
+It is an error to
+.B D
+a modified file, but a subsequent
+.B D
+will delete such a file.
+.SS I/O Commands
+.TP
+.BI \*ae " filename
+Replace the file by the contents of the named Unix file.
+Set dot to the beginning of the file.
+.TP
+.BI r " filename
+Replace the text in the range by the contents of the named Unix file.
+Set dot.
+.TP
+.BI w " filename
+Write the range (default
+.BR 0,$ )
+to the named Unix file.
+.TP
+.BI \*af " filename
+Set the file name and print the resulting menu entry.
+.PP
+If the file name is absent from any of these, the current file name is used.
+.B e
+always sets the file name,
+.B r
+and
+.B w
+do so if the file has no name.
+.TP
+.BI < " Unix-command
+Replace the range by the standard output of the
+Unix command.
+.TP
+.BI > " Unix-command
+Sends the range to the standard input of the
+Unix command.
+.TP
+.BI | " Unix-command
+Send the range to the standard input, and replace it by
+the standard output, of the
+Unix command.
+.TP
+.BI \*a! " Unix-command
+Run the
+Unix command.
+.TP
+.BI \*acd " directory
+Change working directory.
+If no directory is specified,
+.B $HOME
+is used.
+.PP
+In any of
+.BR < ,
+.BR > ,
+.B |
+or
+.BR ! ,
+if the
+.I Unix command
+is omitted the last
+.I Unix command
+(of any type) is substituted.
+If
+.I sam
+is downloaded,
+.B !
+sets standard input to
+.FR /dev/null ,
+and otherwise
+unassigned output
+.RB ( stdout
+for
+.B !
+and
+.BR > ,
+.B stderr
+for all) is placed in
+.F $HOME/sam.err
+and the first few lines are printed.
+.SS Loops and Conditionals
+.TP
+.BI x/ regexp / " command
+For each match of the regular expression in the range, run the command
+with dot set to the match.
+Set dot to the last match.
+If the regular
+expression and its slashes are omitted, 
+.L /.*\en/
+is assumed.
+Null string matches potentially occur before every character
+of the range and at the end of the range.
+.TP
+.BI y/ regexp / " command
+Like
+.B x,
+but run the command for each substring that lies before, between,
+or after
+the matches that would be generated by
+.BR x .
+There is no default behavior.
+Null substrings potentially occur before every character
+in the range.
+.TP
+.BI \*aX/ regexp / " command
+For each file whose menu entry matches the regular expression,
+run the command.
+If the expression is omitted, the command is run
+in every file.
+.TP
+.BI \*aY/ regexp / " command
+Same as
+.BR X ,
+but for files that do not match the regular expression,
+and the expression is required.
+.TP
+.BI g/ regexp / " command
+.br
+.ns
+.TP
+.BI v/ regexp / " command
+If the range contains
+.RB ( g )
+or does not contain
+.RB ( v )
+a match for the expression,
+set dot to the range and run the command.
+.PP
+These may be nested arbitrarily deeply, but only one instance of either
+.B X
+or
+.B Y
+may appear in a \%single command.
+An empty command in an
+.B x
+or
+.B y
+defaults to
+.BR p ;
+an empty command in
+.B X
+or
+.B Y
+defaults to
+.BR f .
+.B g
+and
+.B v
+do not have defaults.
+.SS Miscellany
+.TP
+.B k
+Set the current file's mark to the range.  Does not set dot.
+.TP
+.B \*aq
+Quit.
+It is an error to quit with modified files, but a second
+.B q
+will succeed.
+.TP
+.BI \*au " n
+Undo the last
+.I n
+(default 1)
+top-level commands that changed the contents or name of the
+current file, and any other file whose most recent change was simultaneous
+with the current file's change.
+Successive
+.BR u 's
+move further back in time.
+The only commands for which u is ineffective are
+.BR cd ,
+.BR u ,
+.BR q ,
+.B w
+and
+.BR D .
+.TP
+(empty)
+If the range is explicit, set dot to the range.
+If
+.I sam
+is downloaded, the resulting dot is selected on the screen;
+otherwise it is printed.
+If no address is specified (the
+command is a newline) dot is extended in either direction to
+line boundaries and printed.
+If dot is thereby unchanged, it is set to
+.B .+1 
+and printed.
+.PD
+.SS Grouping and multiple changes
+Commands may be grouped by enclosing them in braces
+.BR {} .
+Commands within the braces must appear on separate lines (no backslashes are
+required between commands).
+Semantically, an opening brace is like a command:
+it takes an (optional) address and sets dot for each sub-command.
+Commands within the braces are executed sequentially, but changes made
+by one command are not visible to other commands (see the next section
+of this manual).
+Braces may be nested arbitrarily.
+.PP
+When a command makes a number of changes to a file, as in
+.BR x/re/c/text/ ,
+the addresses of all changes to the file are computed in the original file.
+If the changes are in sequence,
+they are applied to the file.
+Successive insertions at the same address are catenated into a single
+insertion composed of the several insertions in the order applied.
+.SS The terminal
+What follows refers to behavior of
+.I sam
+when downloaded, that is, when
+operating as a display editor on a bitmap display.
+This is the default
+behavior; invoking
+.I sam
+with the
+.B -d
+(no download) option provides access
+to the command language only.
+.PP
+Each file may have zero or more windows open.
+Each window is equivalent
+and is updated simultaneously with changes in other windows on the same file.
+Each window has an independent value of dot, indicated by a highlighted
+substring on the display.
+Dot may be in a region not within
+the window.
+There is usually a `current window',
+marked with a dark border, to which typed text and editing
+commands apply.
+Text may be typed and edited as in
+.IR mux (9.1);
+also the escape key (ESC) selects (sets dot to) text typed
+since the last mouse button hit.
+.PP
+The button 3 menu controls window operations.
+The top of the menu
+provides the following operators, each of which prompts with one or
+more
+.IR mux -like
+cursors to prompt for selection of a window or sweeping
+of a rectangle.
+`Sweeping' a null rectangle gets a large window, disjoint
+from the command window or the whole screen, depending on
+where the null rectangle is.
+.TF reshape
+.TP 
+.B new
+Create a new, empty file.
+.TP
+.B xerox
+Create a copy of an existing window.
+.TP
+.B reshape
+As in
+.I mux.
+.TP
+.B close
+Delete the window.
+In the last window of a file,
+.B close
+is equivalent to a
+.B D
+for the file.
+.TP
+.B write
+Equivalent to a
+.B w
+for the file.
+.PD
+.PP
+Below these operators is a list of available files, starting with
+.BR ~~sam~~ ,
+the command window.
+Selecting a file from the list makes the most recently
+used window on that file current, unless it is already current, in which
+case selections cycle through the open windows.
+If no windows are open
+on the file, the user is prompted to open one.
+Files other than
+.B ~~sam~~
+are marked with one of the characters
+.B -+*
+according as zero, one, or more windows
+are open on the file.
+A further mark
+.L .
+appears on the file in the current window and
+a single quote,
+.BR ' ,
+on a file modified since last write.
+.PP
+Nothing can be done without a command window, for which
+.I sam
+prompts initially.
+The command window is an ordinary window except that text typed to it
+is interpreted as commands for the editor rather than passive text,
+and text printed by editor commands appears in it.
+The behavior is like
+.I mux,
+with a `command point' that separates commands being typed from
+previous output.
+Commands typed in the command window apply to the
+current open file\(emthe file in the most recently
+current window.
+.SS Manipulating text
+Button 1 changes selection, much like
+.I mux.
+Pointing to a non-current window with button 1 makes it current;
+within the current window, button 1 selects text, thus setting dot.
+Double-clicking selects text to the boundaries of words, lines,
+quoted strings or bracketed strings, depending on the text at the click.
+.PP
+Button 2 provides a menu of editing commands:
+.PD0
+.TP
+.B cut
+Delete dot and save the deleted text in the snarf buffer.
+.TP
+.B paste
+Replace the text in dot by the contents of the snarf buffer.
+.TP
+.B snarf
+Save the text in dot in the snarf buffer.
+.TP
+.B look
+Search forward for the next occurrence of the literal text in dot.
+If dot is the null string, the text in the snarf buffer is
+used.
+The snarf buffer is unaffected.
+.TP
+.B <mux>
+Exchange snarf buffers with
+.IR mux.
+.TP
+.BI / regexp
+Search forward for the next match of the last regular expression
+typed in a command.
+(Not in command window.)
+.TP
+.B send
+Send the text in dot, or the snarf buffer if
+dot is the null string, as if it were typed to the command window.
+Saves the sent text in the snarf buffer.
+(Command window only.) 
+.TP
+.B scroll
+.TP
+.B noscroll
+Select whether to reveal automatically text
+that appears off the end of the command window.
+(Command window only.)
+.PD
+.SS Abnormal termination
+If
+.I sam
+terminates other than by a
+.B q
+command (by hangup, deleting its layer, etc.), modified
+files are saved in an
+executable file,
+.FR $HOME/sam.save .
+This program, when executed, asks whether to write
+each file back to a Unix file.
+The answer
+.L y
+causes writing; anything else skips the file.
+.SH FILES
+.F $HOME/sam.save
+.br
+.F $HOME/sam.err
+.SH SEE ALSO
+.IR ed (1),
+.IR sed (1),
+.IR vi (1),
+.IR gre (1)
+.SH BUGS
+The
+.B u
+command undoes characters\(emand backspaces\(emtyped directly
+into a file window in unpredictable increments.