samrc.5 - 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
---
samrc.5 (8475B)
---
1 .Dd $Mdocdate$
2 .Dt SAMRC 5
3 .Os
4 .Sh NAME
5 .Nm samrc
6 .Nd configure samterm
7 .Sh SYNOPSIS
8 .Pa ~/.samrc
9 .Sh DESCRIPTION
10 A
11 .Nm
12 file in the user's home directory can be used to configure the downloaded
13 portion of the
14 .Xr sam 1
15 editor
16 .Pq "that is, samterm" "."
17 This file,
18 if it exists,
19 is read at startup.
20 .Pp
21 Each line begins with a configuration directive and some number of arguments.
22 Lines whose first printing character is a
23 .Dq "#"
24 are considered comments and are ignored.
25 The following configuration directives are supported:
26 .Bl -tag
27 .It bind
28 Bind a key sequence to a command or a raw character.
29 The forms are:
30 .Bd -literal
31
32 bind M K command C A
33 bind M K command C
34 bind M K raw C
35
36 .Ed
37 Where
38 .Em M
39 is a string describing a set of modifier keys
40 .Po
41 see
42 .Sx "Modifier Keys"
43 below
44 .Pc ","
45 .Em K
46 is the name of a keyboard symbol suitable for passing to
47 .Xr XStringToKeysym 3 ","
48 .Em C
49 is either a command name
50 .Po
51 for command bindings;
52 see
53 .Sx "Command Names"
54 below
55 .Pc
56 or a literal or hexadecimal specification of a character,
57 and
58 .Em A
59 is an arbitrary string to use as an argument to a bound command.
60 .Pp
61 Note that keyboard symbol names are implementation-defined and often case-sensitive,
62 and that not all commands will make use of arguments.
63 .It unbind
64 Remove all bindings associated with a key sequence.
65 The form is:
66 .Bd -literal
67
68 unbind M K
69
70 .Ed
71 where
72 .Em M
73 is a string describing a set of modifier keys and
74 .Em K
75 is the name of a keyboard symbol,
76 as for
77 .Dq bind
78 above.
79 The key sequence may be subsequently rebound.
80 .It chord
81 Bind a mouse chord to a command.
82 The form is:
83 .Bd -literal
84
85 chord S1 S2 C T
86
87 .Ed
88 where
89 .Em S1
90 is a string describing the initial state of the mouse buttons
91 .Po
92 see
93 .Sx "Mouse Button States"
94 below
95 .Pc ","
96 .Em S2
97 is a string describing the following state of the mouse buttons,
98 .Em C
99 is a command name,
100 and
101 .Em T
102 is a target
103 .Po
104 see
105 .Sx "Targets"
106 below
107 .Pc "."
108 .It unchord
109 Remove all bindings for a given mouse chord.
110 The form is:
111 .Bd -literal
112
113 unchord S1 S2
114
115 .Ed
116 where
117 .Em S1
118 and
119 .Em S2
120 are strings describing the initial and following mouse button states.
121 The chord may be subsequently rebound.
122 .It foreground
123 Names the color used to draw text.
124 It is of the form:
125 .Bd -literal
126
127 foreground C
128
129 .Ed
130 where
131 .Em C
132 is a color name suitable for passing to
133 .Xr XAllocNamedColor 3 "."
134 .It background
135 Names the color used to draw the background of files being edited.
136 It is of the form:
137 .Bd -literal
138
139 background C
140
141 .Ed
142 where
143 .Em C
144 is a colon-separated list of color names as for the foreground directive.
145 If more than one color is specified,
146 files will cycle through these background colors.
147 .It border
148 Names the color used to draw file borders.
149 It is of the form:
150 .Bd -literal
151
152 border C
153
154 .Ed
155 where
156 .Em C
157 is a color specification as for foreground.
158 .It font
159 Specifies the font used to draw text.
160 It is of the form:
161 .Bd -literal
162
163 font F
164
165 .Ed
166 where
167 .Em F
168 is an
169 .Xr fc-match 1
170 compatible font pattern.
171 .It tabs
172 Specifies the width of tab characters in multiples of the width of the '0' character.
173 It is of the form:
174 .Bd -literal
175
176 tabs N
177
178 .Ed
179 where
180 .Em N
181 is an integer between 1 and 12.
182 .It expandtabs
183 Determines if tabs should be automatically expanded into spaces.
184 It is of the form:
185 .Bd -literal
186
187 expandtabs B
188
189 .Ed
190 where
191 .Em B
192 is the string
193 .Dq true
194 or
195 .Dq false "."
196 If
197 .Dq true ","
198 then tabs will be automatically expanded.
199 .It autoindent
200 Determines whether a line following a non-empty indented line is automatically indented.
201 It is of the form:
202 .Bd -literal
203
204 autoindent B
205
206 .Ed
207 where
208 .Em B
209 is the string
210 .Dq true
211 or
212 .Dq false "."
213 If
214 .Dq true ","
215 then a new line after a non-empty indented line is automatically indented.
216 .It snarfselection
217 Indicates which X selection should be exchanged with
218 .Nm
219 upon execution of the
220 .Em exchange
221 command
222 .Pq "either via the menu item or key binding" "."
223 The forms are:
224 .Bd -literal
225
226 snarfselection primary
227 snarfselection secondary
228 snarfselection clipboard
229 .Ed
230 .It followfocus
231 Determines window focus mode.
232 It is of the form:
233 .Bd -literal
234
235 followfocus B
236
237 .Ed
238 where
239 .Em B
240 is the string
241 .Dq true
242 or
243 .Dq false "."
244 If
245 .Dq true ","
246 then the window focus mode is set to follow the mouse pointer.
247 In this mode typing is directed to the window currently underneath the mouse pointer.
248 .El
249 .Ss Defaults
250 The default keybindings and mouse chords are those documented in
251 .Xr sam 1 "."
252 The default foreground and border color is black,
253 and the default background color is white.
254 Tabs are not expanded by default,
255 and tabstops are set at every eight characters.
256 The default X selection is
257 .Do primary
258 .Dc "."
259 The default window focus mode is "Click to focus". Typing is directed to the window which was last clicked.
260 .Ss "Modifier Keys"
261 The
262 .Em bind
263 directive expects a string describing the state of modifier keys.
264 This string consists of one or more of
265 .Dq "*"
266 meaning any set of modifiers,
267 .Dq "a"
268 meaning Alt
269 .Pq Mod1 ","
270 .Dq "c"
271 meaning Control, or
272 .Dq "s"
273 meaning Shift.
274 .Pp
275 For example,
276 bind the "exchange" command to
277 .Em Control-Shift-E ","
278 the following directive could be used:
279 .Bd -literal
280
281 bind CS e command exchange
282
283 .Ed
284 .Ss "Command Names"
285 The following names can be used for commands:
286 .TS
287 c | c | c
288 - | - | -
289 l | l | r.
290 Name Meaning Default Binding
291 escape Highlight recent text Escape
292 scrolldown Scroll down by page PgDn, Down/Right
293 scrollup Scroll up by page PgUp, Up/Left
294 scrolldownline Scroll down by line None
295 scrollupline Scroll up by line None
296 jump Jump to/from command window Control-K
297 charright Move dot one to the right Control-D
298 charleft Move dot one to the left Control-S
299 lineup Move dot up Control-E
300 linedown Move dot down Control-X
301 delbol Delete to BOL Control-U
302 delword Delete prev. word Control-W
303 delbs Delete prev. character BackSpace
304 del Delete next character Delete
305 cut Cut selection Control-Y
306 snarf Snarf selection Control-C
307 paste Paste snarf buffer Control-V
308 exchange Exchange snarf buffer Control-Q
309 eol Move to end of line None
310 bol Move to beginning of line None
311 tab Insert a tab Tab
312 send Append to command window None
313 write Write the current file to disk None
314 look Find next literal string None
315 search Find next regex None
316 .TE
317 .Pp
318 Additionally,
319 the command name
320 .Dq none
321 means that the given binding should perform no action
322 .Pq "not even insert a character" ","
323 and the command name
324 .Dq default
325 means that the given binding should perform whatever action was previously defined for it.
326 .Pp
327 For the
328 .Em send
329 command,
330 the text to send is specified in the argument of the binding.
331 For example, to bind
332 .Em Control-Z
333 to undo the last 10 changes, the following line binding could be used:
334 .Bd -literal
335
336 bind C z command send u10
337
338 .Ed
339 Note that the
340 .Dq send
341 command is analagous to the
342 .Dq send
343 menu item:
344 the argument text is simply appended to the text in the command window.
345 Thus,
346 one should exercise caution if partially-completed commands exist in the command window.
347 .Ss "Mouse Button States"
348 Chords are described using two states:
349 a beginning state and an end state.
350 When the mouse buttons are in the beginning state and then switch to being in the end state,
351 the chord is activated.
352 .Pp
353 States are described using button numbers between 1 and 5,
354 corresponding to the buttons on the mouse numbered from the left
355 .Pq "though this is up to your windowing system and may vary" "."
356 For example,
357 the string
358 .Bd -literal
359
360 12
361
362 .Ed
363 means
364 .Dq "buttons 1 and 2 are pressed".
365 The special string
366 .Dq "n"
367 means
368 .Dq "no buttons are pressed".
369 Thus to bind the
370 .Em cut
371 command to the chord
372 .Dq "hold button one, then click button two"
373 the following configuration directive can be used:
374 .Bd -literal
375
376 chord 1 12 cut current
377
378 .Ed
379 .Ss "Targets"
380 Mouse chords can send their commands to either the current file
381 .Pq "i.e. the one receiving typed input"
382 by specifying "current" as the target;
383 or to the file under the mouse pointer by specifying "mouse" as the target.
384 .Ss Ordering considerations
385 Commands are executed in the order they are present in the
386 .Nm
387 file.
388 Later commands will override earlier commands,
389 meaning that in the case of duplicate binding or chord definitions,
390 the last one wins.
391 .Pp
392 Note that this means that bindings defined with the
393 .Dq any
394 modifier set should be defined earlier in the file than those binding the same key with modifiers,
395 since otherwise the
396 .Dq any
397 binding will always win.
398 .Sh EXAMPLES
399 An example
400 .Nm
401 file is provided in the sam source distribution as
402 .Pa doc/samrc "."
403 .Sh SEE ALSO
404 .Xr sam 1