sam.1 - sam - An updated version of the sam text editor.
(HTM) git clone git://vernunftzentrum.de/sam.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) LICENSE
---
sam.1 (27698B)
---
1 .Dd $Mdocdate$
2 .Dt SAM 1
3 .Os
4 .Sh NAME
5 .Nm sam
6 .Nd screen editor with structural regular expressions
7 .Sh SYNOPSIS
8 .Nm
9 .Op Fl d
10 .Op Fl t Ar terminal
11 .Ar
12 .Nm
13 .Fl r Ar machine
14 .Op Fl s Ar file
15 .Op Fl t Ar terminal
16 .Ar
17 .Nm sam.save
18 .Nm B
19 .Op Fl r Ar machine
20 .Ar
21 .Sh DESCRIPTION
22 .Nm sam
23 is a multi-file editor.
24 It modifies a local copy of an external file.
25 The copy is here called a
26 .Em file "."
27 The files are listed in a menu available through mouse button 3 or the
28 .Li n
29 command.
30 Each file has an associated name, usually the name of the external file from which it was read, and a
31 .Dq modified
32 bit that indicates whether the editor's file agrees with the external file.
33 The external file is not read into the editor's file until it first becomes the current file \[en] that file to which editing commands apply \[en] whereupon its menu entry is printed.
34 The options are
35 .Bl -tag -width Ds
36 .It Fl d
37 Do not download the terminal part of
38 .Nm "."
39 Editing will be done with the command language only, as in
40 .Xr ed 1 "."
41 .It Fl r Ar machine
42 Run the host part remotely on the specified machine, the terminal part locally; or
43 .Pq "in the case of the B command"
44 commands to be sent to an instance of
45 .Nm
46 associated with
47 .Ar machine "."
48 .It Fl s Ar file
49 Start the host part from the indicated file on the remote host.
50 .It Fl t Ar file
51 Start the terminal part from the indicated file.
52 Useful for debugging.
53 .El
54 .Ss Text Files
55 .Nm
56 can only edit text files,
57 encoded using the encoding specified in the
58 .Ev LC_ALL ","
59 .Ev LC_CTYPE ","
60 or
61 .Ev LANG
62 environment variables
63 .Po
64 see
65 .Xr locale 7
66 .Pc "."
67 .Nm
68 supports any encoding supported by the underlying operating system.
69 .Pp
70 Editing files that do not contain valid text in the current encoding
71 .Pq "including binary files"
72 will result in a warning and such files generally neither load nor display correctly.
73 The standard
74 .Xr iconv 1
75 utility can be used to convert among various text encodings,
76 and may be useful in converting files to the current encoding for editing.
77 .Ss Regular expressions
78 Regular expressions are more-or-less as they are in
79 .Xr regex 7 ","
80 with the addition of
81 .Li \[rs]n
82 to represent newlines.
83 A regular expression may never contain a literal newline character.
84 The elements of regular expressions are:
85 .Bl -tag -width Ds
86 .It Li "."
87 Match any character except newline.
88 .It Li \[rs]n
89 Match newline.
90 .It Li \[rs]x
91 For any character except
92 .Li n
93 match the character
94 .Po
95 here
96 .Sy x
97 .Pc "."
98 .It Li "[abc]"
99 Match any character in the square brackets.
100 .Li \[rs]n
101 may be mentioned.
102 .It Li "[^abc]"
103 Match any character not in the square brackets, but never a newline.
104 Both this and the positive form above accept a range of ASCII characters indicated by a dash, as in
105 .Li "a-z" "."
106 .It Li "^"
107 Match the null string immediately after a newline.
108 .It Li "$"
109 Match the null string immediately before a newline.
110 .El
111 .Pp
112 Any other character except newline matches itself.
113 .Pp
114 In the following,
115 .Sy r1
116 and
117 .Sy r2
118 are regular expressions.
119 .Bl -tag -width Ds
120 .It Pq Sy r1
121 Match what
122 .Sy r1
123 matches.
124 .It Sy r1|r2
125 Match what
126 .Sy r1
127 or
128 .Sy r2
129 matches.
130 .It Sy r1*
131 Match zero or more adjacent matches of
132 .Sy r1 "."
133 .It Sy r1+
134 Match one or more adjacent matches of
135 .Sy r1 "."
136 .It Sy "r1?"
137 Match zero or one matches of
138 .Sy r1 "."
139 .El
140 .Pp
141 The operators
142 .Li "*" ","
143 .Li "+" ","
144 and
145 .Li "?"
146 are highest precedence, then catenation, then
147 .Li "|"
148 is lowest.
149 The empty regular expression stands for the last complete expression encountered.
150 A regular expression in
151 .Nm
152 matches the longest leftmost substring formally matched by the expression.
153 Searching in the reverse direction is equivalent to search backwards with the catenation operations reversed in the expression.
154 .Ss Addresses
155 An address identifies a substring in a file.
156 In the following
157 .Do
158 character
159 .Sy n
160 .Pc
161 means the null string after the
162 .Sy n\fR-th
163 character in the file, with 1 the first character in the file.
164 .Do
165 Line
166 .Sy n
167 .Dc
168 means the
169 .Sy n\fR-th
170 match, starting at the beginning of the file, of the regular expression
171 .Li ".*\[rs]n?" "."
172 .Po
173 The peculiar properties of a last line without a newline are temporarily undefined.
174 .Pc
175 All files always have a current substring, called
176 .Sy dot ","
177 that is the default address.
178 .Ss Simple addresses
179 .Bl -tag -width Ds
180 .It Li # Sy n
181 The empty string after character
182 .Sy n ";"
183 .Li #0
184 is the beginning of the file.
185 .It Sy n
186 Line
187 .Sy n "."
188 .It Li / Sy regexp Li /
189 .It Li ? Sy regexp Li ?
190 The substring that matches the regular expression, found by looking toward the end
191 .Pq Li /
192 or beginning
193 .Pq Li "?"
194 of the file, and if necessary continuing the search from the other end to the starting point of the search.
195 The matched substring may straddle the starting point.
196 When entering a pattern containing a literal question mark for a backward search, the question mark should be specified as a member of a class.
197 .It Li 0
198 The string before the first full line.
199 This is not necessarily the null string; see
200 .Li +
201 and
202 .Li -
203 below.
204 .It Li $
205 The null string at the end of the file.
206 .It Li "."
207 Dot.
208 .It Li "'"
209 The mark in the file
210 .Po
211 see the
212 .Sy k
213 command below
214 .Pc "."
215 .It Do regexp Dc
216 .Po
217 A regular expression in double quotes.
218 .Pc
219 Preceding a simple address
220 .Po
221 default
222 .Li "."
223 .Pc ","
224 refers to the address evaluated in the unique file whose menu line matches the regular expression.
225 .El
226 .Ss Compound addresses
227 In the following,
228 .Sy a1
229 and
230 .Sy a2
231 are addresses.
232 .Bl -tag -width Ds
233 .It Sy a1+a2
234 The address
235 .Sy a2
236 evaulated starting at the end of
237 .Sy a1 "."
238 .It Sy a1-a2
239 The address
240 .Sy a2
241 evaluated looking the reverse direction starting at the beginning of
242 .Sy a1 "."
243 .It Sy "a1,a2"
244 The substring from the beinning of
245 .Sy a1
246 to the end of
247 .Sy a2 "."
248 If
249 .Sy a1
250 is missing,
251 .Li 0
252 is substituted.
253 If
254 .Sy a2
255 is missing,
256 .Li $
257 is substituted.
258 .It Sy a1;a2
259 Like
260 .Dq Sy a1,a2
261 but with
262 .Sy a2
263 evaluated at the end of, and dot set to,
264 .Sy a1 "."
265 .El
266 .Pp
267 The operators
268 .Li +
269 and
270 .Li -
271 are high precedence, while
272 .Li ,
273 and
274 .Li ;
275 are low precedence.
276 .Pp
277 In both
278 .Li +
279 and
280 .Li -
281 forms, if
282 .Sy a2
283 is a line or character address with a missing number, the number defaults to 1.
284 If
285 .Sy a1
286 is missing,
287 .Li "."
288 is subtituted.
289 If both
290 .Sy a1
291 and
292 .Sy a2
293 are present and distinguishable,
294 .Li +
295 may be elided.
296 .Sy a2
297 may be a regular expression; if it is delimited by
298 .Li ""?""
299 characters, the effect of the
300 .Li +
301 or
302 .Li -
303 is reversed.
304 .Pp
305 It is an error for a compound address to represent a malformed substring.
306 .Pp
307 Some useful idioms:
308 .Bl -tag -width Ds
309 .It Sy a1+- Po Sy a1-+ Pc
310 selects the line containing the end
311 .Dq beginning
312 of
313 .Sy a1 "."
314 .It Sy 0/regexp/
315 locates the first match of the expression in the file.
316 .Po
317 The form
318 .Li 0;//
319 sets dot unnecessarily.
320 .Pc
321 .It Sy "./regexp///"
322 find the second following occurence of the expression, and
323 .Sy ".,/regexp/"
324 extends dot.
325 .El
326 .Ss Commands
327 In the following, text demarcated by slashes represents text delimited by any printable ASCII character except alphanumerics.
328 Any number of trailing delimiters may be elided, with multiple elisions then representing null strings, but the first delimiter must always be present.
329 In any delimited text, newline may not appear literally;
330 .Li \[rs]n
331 may be typed for newline; and
332 .Li \[rs]/
333 quotes the delimiter, here
334 .Li / "."
335 Backslash is otherwise interpreted literally, except in
336 .Sy s
337 commands.
338 .Pp
339 Most commands may be prefixed with an address to indicate their range of operation.
340 Those that may not are marked with a
341 .Sy "*"
342 below.
343 If a command takes an address and none is supplied, dot is used.
344 The sole exception is the
345 .Sy w
346 command, which defaults to
347 .Li "0,$" "."
348 In the description,
349 .Dq range
350 is used to represent whatever address is supplied.
351 Many commands set the value of dot as a side effect.
352 If so, it is always to the
353 .Dq result
354 of the change: the empty string for a deletion, the new text for an insertion, etc.
355 .Po
356 but see the
357 .Sy s
358 and
359 .Sy e
360 commands
361 .Pc "."
362 .Ss Text commands
363 .Bl -tag -width Ds
364 .It Sy a/text/
365 Insert the text into the file after the range.
366 Set dot.
367 .Pp
368 May also be written as
369 .Bd -literal -offset indent
370 a
371 lines
372 of
373 text
374 .
375 .Ed
376 .It Sy c \fR or Sy i
377 Same as
378 .Sy a ","
379 but
380 .Sy c
381 replaces the text, while
382 .Sy i
383 inserts
384 .Em before
385 the range.
386 .It Sy d
387 Delete the text in range.
388 Set dot.
389 .It Sy s/regexp/text/
390 Substitute
391 .Sy text
392 for the first match to the regular expression in the range.
393 Set dot to the modified range.
394 In
395 .Sy text
396 the character
397 .Li "&"
398 stands for the string that matched the expression.
399 Backslash behaves as usual unless followed by a digit:
400 .Sy \[rs]d
401 stands for the string that matched the subexpression begun by the
402 .Sy d\fR-th
403 left parenthesis.
404 If
405 .Sy s
406 is followed immediately by a number
407 .Sy n ","
408 as in
409 .Li "s2/x/y/" ","
410 the
411 .Sy n\fR-th
412 match in the range is substituted.
413 If the command is followed by
414 .Sy g ","
415 as in
416 .Li "s/x/y/g" ","
417 all matches in the range are substituted.
418 .It Sy "m a1"
419 Move the range to after
420 .Sy a1 "."
421 Set dot.
422 .It Sy "t a1"
423 Copy the range to after
424 .Sy a1 "."
425 Set dot.
426 .El
427 .Ss Display commands
428 .Bl -tag -width Ds
429 .It Sy p
430 Print the text in the range.
431 Set dot.
432 .It Sy =
433 Print the line address and character address of the range.
434 .It Sy =#
435 Print just the character address of the range.
436 .El
437 .Ss File commands
438 .Bl -tag -width Ds
439 .It * Sy "b name"
440 Set the current file to the first window on file
441 .Ar name ","
442 if
443 .Nm
444 has such a file in its menu.
445 If no such file is present,
446 .Ar name
447 is compared against the
448 .Xr basename 3
449 of each menu file, and the first match is made current.
450 Finally, if no such file is present, the first menu file that contains
451 .Ar name
452 as a substring is selected.
453 The name may be expressed
454 .Sy "<shell-command"
455 in which case the file names are taken as words
456 .Pq "in the shell sense"
457 generated by the shell command and no fuzzy matching is performed.
458 .It * Sy "B file-list"
459 Same as
460 .Sy b ","
461 except that filenames not in the menu are entered there, and all file names in the list are examined.
462 .It * Sy n
463 Print a menu of files.
464 The format is:
465 .Bl -tag -width Ds
466 .It "' or blank"
467 indicating the file is modified or clean,
468 .It "- or +"
469 indicating the file is unread or has been read
470 .Po
471 in the terminal,
472 .Li "*"
473 means more than one window is open
474 .Pc ","
475 .It ". or blank"
476 indicating the current file,
477 .El
478 a blank,
479 and the filename.
480 .It "*" Sy "D file-list"
481 Delete the named files from the menu.
482 If no files are named, the current file is deleted.
483 It is an error to delete a modified file, but a subsequent
484 .Sy D
485 will delete such a file.
486 .El
487 .Ss I/O commands
488 .Bl -tag -width Ds
489 .It "*" Sy "e filename"
490 Replace the file by the contents of the named external file.
491 Set dot to the beginning of the file.
492 .It Sy "r filename"
493 Replace the text in the range by the contents of the named external file.
494 Set dot.
495 .It Sy "w filename"
496 Write the range
497 .Po
498 default
499 .Li 0,$
500 .Pc
501 to the named external file.
502 .It "*" Sy "f filename"
503 Set the file name and print the resulting menu entry.
504 .El
505 .Pp
506 If the file name argument is absent from any of these, the current file name is used.
507 .Sy e
508 always sets the file name,
509 .Sy r
510 and
511 .Sy w
512 will do so if the file has no name.
513 .Bl -tag -width Ds
514 .It Sy "< shell-command"
515 Replace the range by the standard output of the shell command.
516 .It Sy "> shell-command"
517 Sends the range to the standard input of the shell command.
518 .It Sy "| shell-command"
519 Send the range to the standard input, and replace it by the standard output, of the shell command.
520 .It "*" Sy "! shell-command"
521 Run the shell command.
522 .It "*" Sy "cd directory"
523 Change working directory.
524 If no directory is specified,
525 .Ev "$HOME"
526 is used.
527 .El
528 .Pp
529 In any of
530 .Sy "<" ","
531 .Sy ">" ","
532 .Sy "|" ", or"
533 .Sy "!" ","
534 if the shell command is omitted, the last shell command
535 .Pq "of any type"
536 is substituted.
537 If
538 .Nm
539 is downloaded,
540 .Sy "!"
541 sets standard input to
542 .Pa "/dev/null" ","
543 and otherwise unassigned output
544 .Po
545 .Pa stdout
546 for
547 .Sy "!"
548 and
549 .Sy ">" ","
550 .Pa stderr
551 for all
552 .Pc
553 is placed in
554 .Pa "${HOME}/sam.err"
555 and the first few lines are printed.
556 .Ss Loops and conditionals
557 .Bl -tag -width Ds
558 .It Sy "x/regexp/ command"
559 For each match of the regular expression in the range, run the command with dot set to the match.
560 Set dot to the last match.
561 If the regular expression and its slashes are omitted,
562 .Li "/.*\[rs]n/"
563 is assumed.
564 Null string matches potentially occur before every character of the range and at the end of the range.
565 .It Sy "y/regexp/ command"
566 Like
567 .Sy x ","
568 but run the command for each substring that lies before, between, or after the matches that would be generated by
569 .Sy x "."
570 There is no default behavior.
571 Null substrings potentially occur before every character in the range.
572 .It "*" Sy "X/regexp/ command"
573 For each file whose menu entry matches the regular expression, make that the current file and run the command.
574 If the expression is omitted, the command is run in every file.
575 .It "*" Sy "Y/regexp/ command"
576 Same as
577 .Sy X ","
578 but for files that do not match the regular expression, and the expression is required.
579 .It Sy "g/regexp/ command"
580 .It Sy "v/regexp/ command"
581 If the range contains
582 .Po
583 .Sy g
584 .Pc
585 or does not contain
586 .Po
587 .Sy v
588 .Pc
589 a match for the expression, set dot to the range and run the command.
590 .El
591 .Pp
592 These may be nested arbitrarily deeply, but only one instance of either
593 .Sy X
594 or
595 .Sy Y
596 may appear in a single command.
597 An empty command in an
598 .Sy x
599 or
600 .Sy y
601 defaults to
602 .Sy p ";"
603 an empty command in
604 .Sy X
605 or
606 .Sy Y
607 defaults to
608 .Sy f "."
609 .Sy g
610 and
611 .Sy v
612 do not have defaults.
613 .Ss Miscellany
614 .Bl -tag -width Ds
615 .It Sy k
616 Set the current file's mark to the range.
617 Does not set dot.
618 .It "*" Sy q
619 Quit.
620 It is an error to quit with modified files, but a second
621 .Sy q
622 will succeed.
623 .It "*" Sy "u n"
624 Undo the last
625 .Sy n
626 .Pq "default 1"
627 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.
628 Successive
629 .Sy u
630 commands move further back in time.
631 The only commands for which
632 .Sy u
633 is ineffective are
634 .Sy cd ","
635 .Sy u ","
636 .Sy q ","
637 .Sy w ","
638 and
639 .Sy D "."
640 .It Sy empty
641 .Dq "The empty string as a command."
642 If the range is explicit, set dot to the range.
643 If
644 .Nm
645 is downloaded, the resulting dot is selected on the screen; otherwise it is printed.
646 If no address is specified
647 .Pq "the command is a newline"
648 dot is extended in either direction to the line boundaries and printed.
649 If dot is thereby unchanged, i is set to
650 .Li ".+1"
651 and printed.
652 .El
653 .Ss Grouping and multiple changes
654 Commands may be grouped by enclosing them in curly braces.
655 Commands within the braces must appear on separate lines
656 .Pq "no backslashes are required between commands"
657 .Do
658 as those familiar with other editors might expect
659 .Dc "."
660 Semantically, the opening brance is like a command: it takes an
661 .Pq optional
662 address and sets dot for each sub-command.
663 Commands within the braces are executed sequentially, but changes made by one command are not visible to other commands
664 .Pq "see the next paragraph" "."
665 Braces may be nested arbitrarily.
666 .Pp
667 When a command makes a number of changes to a file, as in
668 .Li "x/re/c/text/" ","
669 the addresses of all changes to the file are computed in the original file.
670 If the changes are in sequence, they are applied to the file.
671 Successive insertions at the same address are catenated into a single insertion composed of the several insertions in the order applied.
672 .Ss The terminal
673 What follows refers to the behavior of
674 .Nm
675 when downloaded, that is, when operating as a display editor on a bitmap display.
676 This is the default behavior; invoking
677 .Nm
678 with the
679 .Fl d
680 .Pq "no download"
681 option provides access to the command language only.
682 .Pp
683 Each file may have zero or more windows open.
684 Each window is equivalent and is updated simultaneously with changes in other windows on the same file.
685 Each window has an independent value of dot, indicated by a highlighted substring on the display.
686 Dot may be in a region not within the window.
687 There is usually a
688 .Dq "current window" ","
689 marked with a dark border, to which typed text and editing commands apply.
690 The escape key selects
691 .Pq "sets dot to"
692 text typed since the last mouse button hit.
693 .Pp
694 The button 3 menu controls window operations.
695 The top of the menu provides the following operators, each of which uses one or more cursors to prompt for selection of a window or sweeping of a rectangle.
696 .Bl -tag -width Ds
697 .It Sy new
698 Create a new empty file:
699 Depress button 3 where one corner of the new rectangle should appear
700 .Pq "box cursor" ","
701 and move the mouse while holding down button 3 to the diagonally opposite corner.
702 .Dq Sweeping
703 a null rectangle gets a large window disjoint from the command window or the whole
704 .Nm
705 window, depending on where the null rectangle is.
706 .It Sy zerox
707 Create a copy of an existing window.
708 After selecting the window to copy with button 1,
709 sweep out the window for the copy.
710 .It Sy reshape
711 Change the size and location of a window.
712 First click button 3 in the window to be changed
713 .Pq "gunsight cursor" "."
714 Then sweep out a window as for the
715 .Sy new
716 menu selection.
717 .It Sy close
718 Delete the window.
719 In the last window of a file,
720 .Sy close
721 is equivalent to a
722 .Sy D
723 for the file.
724 .It Sy write
725 Equivalent to a
726 .Sy w
727 for the file.
728 .El
729 .Pp
730 Below these operators is a list of available files, starting with
731 .Sy "~~sam~~" ","
732 the command window.
733 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.
734 If no windows are open on the file, the user is prompted to open one.
735 Files other than
736 .Sy "~~sam~~"
737 are marked with one of the characters
738 .Li "-+*"
739 according as zero, one, or more windows are open on the file.
740 A further mark,
741 .Li "." ","
742 appears on the file in the current window and a single quote,
743 .Li "'" ","
744 on a file modified since last write.
745 .Pp
746 The command window, created automatically when
747 .Nm
748 starts, 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.
749 There is an
750 .Dq "output point"
751 that separates commands being typed from previous output.
752 Commands typed in the command window apply to the current open file\[en]the file in the most recently current window.
753 .Ss Manipulating text
754 Typed characters replace the current selection
755 .Pq dot
756 in the current window.
757 Backspace deletes the previous character.
758 .Pp
759 Button 1 changes the selection.
760 Pointing to a non-current window with button 1 makes it current; within the current window, button 1 selects text, thus setting dot.
761 Double-clicking selects text to the boundaries of words, lines, quoted strings, or bracketed strings, depending on the text at the click.
762 .Pp
763 Button 2 (or button 3 combined with the shift key) provides a menu of editing commands:
764 .Bl -tag -width Ds
765 .It Sy cut
766 Delete dot and save the deleted text in the snarf buffer.
767 .It Sy paste
768 Replace the text in dot by the contents of the snarf buffer.
769 .It Sy snarf
770 Save the text in dot in the snarf buffer.
771 .It Sy look
772 Search forward for the next occurence of the literal text in dot.
773 If dot is the null string, the text in the snarf buffer is used.
774 The snarf buffer is unaffected.
775 .It Sy <exch>
776 Exchange the snarf buffer with the current system-wide text selection.
777 The exchange of a large amount of selected text is truncated to the size of the editor's internal snarf buffer
778 .Pq "currently 4K"
779 without warning.
780 .It Sy "/regexp"
781 Search forward for the next match of the last regular expression typed in a command.
782 .Pq "Not in command window."
783 .It Sy send
784 Send the text in dot, or the snarf buffer if dot is the null string, as if it were typed to the command window.
785 Saves the sent text in the snarf buffer.
786 .Pq "Command window only."
787 .El
788 .Pp
789 The cut and paste operations can also be accessed combinations of mouse buttons, without using the menu.
790 After making a selection with button 1, pressing button 2 with button 1 still pressed will perform a cut operation.
791 Pressing button 3 with button 1 still pressed will perform a paste operation.
792 Performing both of these operations (pressing buttons 2 and then 3 with button 1 still pressed) is the equivalent of the snarf operation.
793 These button combinations are referred to as
794 .Dq "chords" "."
795 .Pp
796 A scroll wheel, if present, can be used to scroll a file up and down.
797 .Pp
798 Various editing functions are also available via the keyboard.
799 The notation
800 .Em "C-x"
801 below means
802 .Dq "hold the Control key while pressing x"
803 where
804 .Em x
805 is another key.
806 .Pp
807 .TS
808 box;
809 lb | lb
810 - | -
811 l | l.
812 Key Sequence Action
813 C-K Jump to/from the command window
814 C-E/X/D/S Collapse and move selection up/down/right/left
815 C-W/U Delete previous word/to beginning of line
816 C-Backspace Delete previous word
817 C-Y Cut selection
818 C-C Snarf selection
819 C-V Paste selection
820 C-Q Exchange selection
821 C-Tab Insert a tab (even when tab expansion is enabled)
822 Escape Highlight recently typed text
823 .TE
824 .Pp
825 Note that the key bindings,
826 mouse chords,
827 and scroll wheel configuration can be modified at runtime
828 .Po
829 see
830 .Xr samrc 5
831 and
832 .Sx "Runtime configuration"
833 below
834 .Pc
835 and thus may vary depending upon your configuration.
836 .Ss Runtime configuration
837 The terminal can be configured at runtime using environment variables
838 .Po
839 see
840 .Xs ENVIRONMENT
841 below
842 .Pc
843 or by writing a
844 .Pa samrc
845 file in your home directory
846 .Po
847 see
848 .Xr samrc 5
849 .Pc "."
850 The terminal's keybindings,
851 mouse chords,
852 tab handling,
853 colors,
854 and fonts may be set at runtime using these methods.
855 .Ss Abnormal termination
856 If
857 .Nm
858 terminates other than by a
859 .Sy q
860 command
861 .Pq "by hangup, deleting its window, etc." ","
862 modified files are saved in an executable file,
863 .Pq "${HOME}/sam.save" "."
864 This program, when executed, asks whether to write each file back to an external file.
865 The answer
866 .Sy y
867 causes writing; anything else skips the file.
868 Note that
869 .P "sam.save"
870 is a shell script,
871 passed directly to
872 .Xr sh 1 "."
873 A modicum of caution should therefore be taken before blindly executing it,
874 especially if one of the files being edited was itself a shell script.
875 .Pp
876 If a machine crash prevents the creation of a
877 .P "sam.save"
878 file, all changes are lost.
879 If an editing session is difficult to replicate, writing changed files often is recommended.
880 .Ss Remote execution
881 .Nm sam
882 allows the host and terminal parts of the editor to run on diffrent machines, in a process called
883 .Dq downloading "."
884 This process can be suppressed with the
885 .Fl d
886 option, which then runs only the host part in the manner of
887 .Xr ed 1 "."
888 .Pp
889 Running the host part on another machine is accomplished using the
890 .Fl r
891 option, which is used to specify a remote machine name suitable for passing to the remote shell command specified in the
892 .Ev RSH
893 environment variable.
894 .Pp
895 The only component of
896 .Nm sam
897 that needs to be on the remote machine is
898 .Nm sam ","
899 or whatever command specified as the argument to the
900 .Fl s
901 option.
902 Users may also like to have the
903 .Nm B
904 command present on the remote system; invoking this command on the remote system will
905 .Po
906 if
907 .Nm sam
908 was invoked with its default remote host command, i.e.
909 .Nm sam
910 .Pc
911 open files in the local terminal.
912 This allows users to run the terminal part of
913 .Nm sam
914 locally while controlling it via a remote shell connection.
915 .Ss Controlling running instances of Nm
916 .Nm B
917 is a shell command that causes a downloaded instance of
918 .Nm sam
919 to load the named files.
920 The
921 .Fl r
922 option causes the instance of
923 .Nm sam
924 connected to
925 .Ar machine
926 to load the named files; the default is the most-recently started local instance.
927 .Pp
928 .Nm B
929 may also be called on a remote machine, causing the downloaded instance of sam connected to that machine to load the named files.
930 .Sh ENVIRONMENT
931 The following environment variables affect the operation of
932 .Nm sam ":"
933 .Bl -tag -width Ds
934 .It Ev LC_CTYPE
935 .It Ev LC_ALL
936 .It Ev LANG
937 These variables are consulted to determine the encoding used for text files.
938 .It Ev FOREGROUND
939 Sets the foreground color used by
940 .Nm
941 to draw its terminal.
942 Common English color names can be used
943 .Po
944 see
945 .Xr rgb 5
946 .Pc ","
947 or exact colors can be specified as
948 .Sy "#rrggbb" ","
949 where
950 .Sy "rr" ","
951 .Sy "gg" ","
952 and
953 .Sy "bb"
954 are hexadecimal digits describing the red, green, and blue components of the color, respectively.
955 By default, this is the string
956 .Dq black "."
957 This can also be set using the
958 .Em foreground
959 directive in
960 .Xr samrc 5 "."
961 .It Ev BORDER
962 As
963 .Ev FOREGROUND ","
964 but describing the color used to draw borders.
965 This can also be set using the
966 .Em border
967 directive in
968 .Xr samrc 5 "."
969 .It Ev BACKGROUND
970 A colon-separated sequence of color descriptions as in
971 .Ev FOREGROUND ","
972 but describing the background color.
973 By default, this is the string
974 .Dq white "."
975 If multiple colors are specified,
976 .Nm
977 will cycle through this list when opening new files.
978 Note that the command text will use the first color specified.
979 .Pp
980 This can also be set using the
981 .Em background
982 directive in
983 .Xr samrc 5 "."
984 .It Ev FONT
985 A string representing a
986 .Xr fc-match 1
987 compatible font pattern.
988 The font described by this pattern will be used to render text in the terminal.
989 By default, this is the string
990 .Dq "monospace" "."
991 This can also be set using the
992 .Em font
993 directive in
994 .Xr samrc 5 "."
995 .It Ev RSH
996 The name of a command to be used to connect to a remote machine when
997 .Nm
998 is invoked with the
999 .Fl r
1000 option.
1001 It will be passed arguments of the form:
1002 .Bd -literal
1003
1004 -R REMOTE:LOCAL MACHINE COMMAND
1005
1006 .Ed
1007 where
1008 .Em REMOTE
1009 is the name of the remote UNIX domain socket for remote control,
1010 .Em LOCAL
1011 is the name of the local UNIX domain socket for remote control,
1012 .Em MACHINE
1013 is the hostname to connect to, and
1014 .Em COMMAND
1015 is the command
1016 .Po
1017 e.g.
1018 .Nm sam
1019 .Pc
1020 to execute on that machine.
1021 .Pp
1022 Note that this works out-of-the-box with recent versions of
1023 .Xr ssh 1 "."
1024 Any additional arguments should be passed to the command on the remote machine.
1025 By default, this is the string
1026 .Dq "ssh" "."
1027 .It Ev SAMRC
1028 If set,
1029 provides the name of the
1030 .Xr samrc 5
1031 file to read at startup.
1032 By default,
1033 this is
1034 .Pa ${HOME}/.samrc "."
1035 .It Ev SAMSOCKETPATH
1036 Names a directory in which
1037 .Nm
1038 remote control sockets should be placed.
1039 By default, the contents of
1040 .Ev HOME
1041 are used.
1042 .It Ev SAMSOCKETNAME
1043 Gives a full path name for a
1044 .Nm
1045 remote control socket; this will be used in preference to any file in the
1046 .Ev SAMSOCKETPATH
1047 directory.
1048 .It Ev RSAMSOCKETPATH
1049 Names a directory in which
1050 .Nm
1051 remote control sockets should be placed on remote systems.
1052 .It Ev TABS
1053 A number between 1 and 12, indicating the width of a tab character.
1054 This number is treated as a multiplier of the width of the '0' character.
1055 The default is 8.
1056 .Pp
1057 If the number specified for
1058 .Ev TABS
1059 is negative, the absolute value of that number is used and automatic tab expansion
1060 is enabled.
1061 Tab behavior can also be controlled using the
1062 .Em tabs
1063 and
1064 .Em expandtabs
1065 directives in
1066 .Xr samrc 5 "."
1067 .It Ev SHELL
1068 Specifies the full path of the shell to use for executing external commands.
1069 .El
1070 .Sh FILES
1071 .Bl -tag -width Ds
1072 .It Pa "${HOME}/.samrc"
1073 Provides runtime configuration of key bindings,
1074 mouse chords,
1075 colors,
1076 fonts,
1077 and tabs.
1078 .It Pa "${HOME}/sam.save"
1079 Created if
1080 .Nm
1081 terminates abnormally.
1082 Executing this file will prompt the user to restore the files that were being edited at the time of termination.
1083 .It Pa "${HOME}/sam.err"
1084 Stores output of shell commands executed by
1085 .Nm "."
1086 .El
1087 .Sh SEE ALSO
1088 .Xr ed 1
1089 .Xr samrc 5
1090 .Sh BUGS
1091 .Pp
1092 The only human language in which colors may be specified is English.
1093 .Pp
1094 The only human language in which output is generated is English.
1095 .Pp
1096 There is no support for right-to-left text, ligatures, composed characters, or any other complex text rendering.
1097 .Pp
1098 There is no support for font fallback: characters that do not exist in the configured font will display as unknown characters.