README.rst - 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
---
README.rst (14750B)
---
1 Introduction
2 ============
3
4 sam is a text editor originally written for the Blit_ graphical terminal connected to a machine running `9th Edition Research Unix`_.
5 It contained many useful innovations, the most famous of which was its use of `structural regular expressions`_.
6
7 sam was the standard text editor for `Plan 9 from Bell Labs`_, and the Plan 9 version was backported to Unix and the X Window Sytem in the 1990s.
8
9 .. _Blit: https://en.wikipedia.org/wiki/Blit_(computer_terminal)
10
11 .. _`9th Edition Research Unix`: https://en.wikipedia.org/wiki/Research_Unix
12
13 .. _`structural regular expressions`: http://doc.cat-v.org/bell_labs/structural_regexps/se.pdf
14
15 .. _`Plan 9 from Bell Labs`: http://plan9.bell-labs.com/plan9/
16
17 This version of sam is based on that 1990s Unix port, with many useful additions and modifications (see `New Features`_).
18
19 *Note that this is not stable software.*
20 This version of sam is under heavy development;
21 the goal being to get it working before making it beautiful.
22 That being said, it's my primary editor, so any major bugs tend to get fixed pretty quickly.
23 Still, be careful with it.
24
25 The Obiligatory Screenshot
26 --------------------------
27
28 .. image:: sam.png
29
30 Community
31 =========
32
33 Rob posts updates about sam on Twitter at http://twitter.com/TheKingAdRob.
34
35 Installation
36 ============
37
38 Basic Installation
39 -------------------
40 Installation and configuration is fairly simple:
41
42 - You need to be running X11 of some sort.
43 On the Mac, `XQuartz`_ seems to work well.
44 On Linux and BSD systems,
45 the operating system's installation of X should be fine.
46 - If you need to modify the default compile-time configuration (which is unlikely)
47 copy `config.mk.def` to `config.mk` and modify as needed
48 - Run `make clean`
49 - Run `make`
50 - Run `make install` or, if needed, `sudo make install`
51
52 Note that running `make install` will install a `desktop entry file`_, in either "system" or "user" mode.
53 This can be specified via the `MODE` make variable (the default is "user").
54 To isntall the desktop entry for the all users, use:
55
56 make MODE=system install
57
58 The `sam` command runs sam.
59 The `B` command adds a new file to a running instance of sam,
60 or starts sam if it's not already running.
61 To configure sam,
62 create a `.samrc` file in your home directory.
63 The file `doc/samrc <doc/samrc>`_ file serves as a useful example of such a file.
64
65 .. _`XQuartz`: https://www.xquartz.org/
66 .. _`desktop entry file`: https://specifications.freedesktop.org/desktop-entry-spec/latest/
67
68 Running Remotely
69 --------------------
70
71 Both the `sam` and `B` commands accept an '-r' argument,
72 naming a remote machine or
73 (assuming you're using `ssh(1)`,
74 an SSH host entry).
75 The remote machine only needs to have the `sam` binary.
76
77 The remote machine may also have the `B` command installed
78 (as a symbolic/hard link to `sam`).
79 If it is installed,
80 the `B` command can be executed both locally (on the machine running `samterm`) using the '-r' option,
81 and remotely (on the machine running `sam`) without the '-r' option.
82 The `B` command requires a remote shell client that supports UNIX domain socket forwarding;
83 such support has been present in OpenSSH since at least version 6.7 (released in 2014).
84 See the `sam(1)` manual page for information on how the remote shell client is invoked.
85
86 Note that sam relies on the contents of the `LANG`, `LC_CTYPE`, and/or `LC_ALL` environment variables to determine the character encoding to use.
87 If you're using `ssh(1)` to run sam remotely, be sure to pass those variables along or have them set remotely.
88
89 Installation Paths
90 -------------------
91
92 By default, `sam`, `samterm`, and `B` all end up in '$(BINDIR)' as defined in config.mk.
93
94 Compatibility
95 -------------
96
97 Note that Deadpixi sam has extended the binary protocol spoken between sam and samterm.
98 That means that a Deadpixi samterm won't work with a non-Deadpixi sam,
99 nor will a Deadpixi sam work with a non-Deadpixi samterm.
100
101 New Features
102 ============
103
104 Modern OS Support
105 This version of sam compiles and runs on modern Linux/Unix/BSD/macOS systems under X11.
106
107 Improved 64-bit Support
108 The original sam had support for 32-bit architectures and big-endian 64-bit architectures.
109 This version supports 64-bit architectures of any endianess (including, most importantly, x86_64).
110
111 Scalable Font Support
112 This version of sam is not limited to classic X fonts, but can use modern scalable fonts.
113 Inconsolata_ is this author's favorite, though `Courier Prime Code`_ and `Go Mono`_ are giving Inconsolata a run for its money.
114
115 X Input Method and Composition Support
116 This version of sam supports the X Input Method extension for input processing.
117 This allows users to input text via the methods with which they are most comfortable.
118 Additionally, the XCompose(5) file can be used to bind arbitrary sequences of keystrokes
119 to different input character sequences.
120 This mechanism is both more portable and more extensible than the old composed text
121 input mechanism.
122
123 Multicolor Support
124 This version of sam supports configurable text, selection, border, and background colors.
125 It also allows different files to have different background colors,
126 allowing different files to be easily distinguished.
127 The default is still the classic two-color appearance, of course.
128 These colors can be configured at runtime.
129 (Note that this does *not* mean that sam has syntax highlighting.
130 That will almost certainly never happen.)
131
132 Simplified and Dynamic Configuration
133 The graphical elements (colors and fonts) of this version of sam are controlled via environment variables, not X Resources.
134 Keybindings and mouse chords are configurable at runtime via a configuration file.
135
136 Far Better Keyboard Support
137 The selection ("cursor") can be moved using keyboard commands.
138 Additional keyboard-accessible commands allow jumping between file windows and the command window,
139 scrolling the display, snarfing, pasting, etc.
140 The binding of these commands to keyboard sequences is configurable at run-time (via the `~/.samrc` file).
141
142 Support for Two-Button Mice and Wheel Mice
143 The original sam required a three-button mouse.
144 This version is still easier to use with such a mouse, but can be used with a two-button mouse by simulating a button-3 press using shift-button-2.
145 This version also supports scrolling with mouse wheels.
146
147 Support for Mouse Chords
148 The commands available for keyboard binding are also accessible via mouse-button combinations ("chords").
149 By default, the snarf, cut, and paste commands are mapped to chords.
150 The binding of these chords is configurable at run-time.
151
152 Better Remote Editing Support
153 This version of sam can use `ssh(1)` as its remote shell.
154 Additionally, the B command works on both the local and the remote system during remote editing sessions.
155
156 Command Language Extensions
157 Various minor and mostly-compatible changes have been made to the sam command language.
158 Most notable is the `b` command, which now performs a fuzzy match on filenames, making switching between files much faster and easier.
159
160 Improved Manual Page
161 The manual page has been rewritten to use the modern `mdoc(7)` manual page macros.
162 It has been additionally cleaned up, clarified, and extended.
163
164 Support for Tab Expansion
165 When enabled, tabs will be expanded into spaces.
166
167 Arbitrary Encoding Support
168 This version of sam now uses the operating system's multibyte encoding functions.
169 That means that it is not limited to UTF-8, but can edit files in any encoding supported by the operating system.
170 This also means that on modern systems, files containing codepoints outside of the Basic Multilingual Plane can be edited
171 (as opposed to classic sam, which supported only the BMP).
172
173 Numerous Bug Fixes
174 This version of sam fixes some crashes and memory leaks that were in the original version.
175 It feels nice fixing a thirty year old memory leak. ☺
176
177 Code Cleanup and Modernization
178 This version of sam uses C99 standard integer types everywhere, and uses a much simpler buffer implementation.
179 This makes the code more portable and easier to understand.
180
181 .. _Inconsolata: http://www.levien.com/type/myfonts/inconsolata.html
182
183 .. _`Courier Prime Code`: http://quoteunquoteapps.com/courierprime/
184
185 .. _`Go Mono`: https://blog.golang.org/go-fonts
186
187 .. _`WordStar Diamond`: http://texteditors.org/cgi-bin/wiki.pl?WordStarDiamond
188
189 The Future
190 ==========
191
192 This project has an end goal:
193 once the issues listed here are complete,
194 this edition of sam will enter maintenance mode.
195
196 Primary Goals
197 -------------
198
199 - Scalable font support (DONE)
200 - Support big- and little-endian 64-bit systems (DONE)
201 - Support compilation and use on modern \*nix systems (DONE)
202 - Support two-button mice (DONE)
203 - Support tab expansion (DONE)
204 - Support runtime configuration of tab sizes (DONE)
205 - Support scroll wheels on mice (DONE)
206 - Support fuzzy matching in the `b` command (DONE)
207 - Raise the window when opening a new file (DONE)
208 - Support a configurable set of keybindings (i.e. rework the keyboard layer) (DONE)
209 - Support multiple background colors at once (DONE)
210 - Support the following commands for keybindings
211 - escape (DONE)
212 - scrollup / scrolldown (DONE)
213 - charright / charleft (DONE)
214 - lineup / linedown (DONE)
215 - jump to/from command window (DONE)
216 - delword / delbol / del / delbs (DONE)
217 - snarf / cut / paste / exchange (DONE)
218 - write (DONE)
219 - nextlayer / prevlayer (TODO)
220 - maximize / tile left / tile right (TODO, also looking into acme-like tiling)
221 - look (DONE)
222 - /regex (DONE)
223 - send (DONE)
224 - eol / bol (DONE)
225 - Support a configurable scroll factor;
226 scrolling is a bit drastic now (DONE)
227 - Support Unicode beyond the Basic Multilingual Plane (TODO, possibly making sam agnostic about encoding)
228 - Support font fallback (TODO)
229 - Allow runtime configuration of key bindings (DONE)
230 - Support a configurable set of mouse chords (DONE)
231 - Support runtime configuration of mouse chords (DONE)
232 - Support mouse button reassignment (TODO)
233 - Support runtime mouse button reassignment (TODO)
234 - Remove external command FIFO, switch to UNIX domain sockets for IPC
235 (email me if you want to know why I think this is a good idea) (DONE)
236 - Support the CDPATH environment variable for the `cd` command (TODO)
237 - Split the man page into documentation for `samterm`, `sam`, `keyboard`, and `samrc` (DONE)
238 - Add localization support (TODO)
239 - Add a Desktop Entry file, icon, etc (TODO)
240 - Create RPMs, DEBs, etc (TODO)
241 - Refactor all code to be as clean and standards-compliant as possible;
242 remove all legacy code (TODO)
243 - Compile with no warnings,
244 with all and extra warnings and `-pedantic` enabled on GCC in C99 mode (TODO)
245 - Run with no Valgrind-detected leaks or errors (DONE)
246
247 Stretch Goals
248 -------------
249 - Remove Xt dependency (TODO)
250 - Switch to a more X11-y model (e.g. one child window per layer) (TODO)
251 - Shell windows (TODO)
252
253 Very Unlikely Goals
254 -------------------
255 - Windows port (no, seriously, stop laughing)
256 - Non-X11 Mac OS X port
257 - Console port
258
259 Permissible Changes in Maintenance Mode
260 ---------------------------------------
261 Once the above goals are met, the only changes that will be made to sam are:
262
263 - Bugfixes
264 - Translation updates
265 - Binary package updates
266 - Updates necessary to keep sam compiling on whatever systems its users are using
267
268 Things That Won't Ever Happen (Sorry)
269 -------------------------------------
270 - Syntax highlighting
271 - Multiple cursors
272 - Complex text rendering
273 (I really am sorry about this one;
274 I want speakers of languages with more complex writing systems to use sam,
275 but getting it to work would be nigh impossible)
276
277 How You Can Help
278 ================
279
280 - *Use sam!*
281 Open up issues on GitHub if you see any problems or have any ideas.
282 - *Spread sam!*
283 Tell your friends and colleagues.
284 Anyone know Rob Pike, Brian Kernighan, Ken Thompson, or Bjarne Stroustrup?
285 They are known sam-users, see if they like this version. :)
286 - *Package sam!*
287 Create packages or ports of sam for your operating system of choice.
288 - *Document sam!*
289 I'm not particularly good at readable,
290 accessible documentation.
291 If you are,
292 I'd love help!
293 - *Translate sam!*
294 Currently, sam only speaks English.
295 I'd like to see sam speak all of the languages that its users speak.
296 - *Draw sam!*
297 I can't draw.
298 At all.
299 Sam needs a decent icon for use with various desktops.
300 If you can draw a nice scalable icon for sam,
301 I would be very happy to see it.
302 - *Write sam!*
303 Write code and send patches.
304
305 Credits
306 =======
307
308 These credits are in rough chronological order:
309
310 Rob Pike, Howard Trickey, Matty Farrow, Boyd Roberts, Doug Gwyn, James Clark, Mark H. Wilkinson, et al.
311 Authors and/or contributors to the original X version of sam,
312 upon which this version is based.
313
314 Rob King
315 Added most of the things mentioned in `New Features`_ above.
316 Rob is the author and maintainer of this version of sam.
317
318 Chris Siebenmann
319 Many many many suggestions, fixes, and improvements.
320
321 Aram Havarneanu
322 Improved the handling of Makefile variables.
323
324 Ishpeck
325 Improved C89 support.
326
327 Tommy Pettersson
328 Numerous bugfixes and suggestions.
329
330 Christian Neukirchen
331 Found and fixed numerous bugs.
332
333 Benjamin Scher Purcell
334 Added the Cbol and Ceol commands.
335
336 Mike Rosenberg
337 Helped get sam running on Mac OS X.
338 Extensive testing help.
339
340 RamKromberg
341 Offered numerous suggestions.
342
343 Erez Schatz
344 Extensive testing help and evangelism.
345
346 ckeen
347 Added Alt modifier support.
348
349 David Tolpin
350 Added support for optional automatic indentation.
351
352 Andrew Higham
353 Added support for focus-follows-mouse, based on a couple of patches posted
354 to the sam-fans mailing list in the ‘90s.
355
356 If I've forgotten you in this list of credits, please accept my apologies and email me (Rob King) at jking@deadpixi.com to be added.
357
358 Copyright and License
359 =====================
360
361 The authors of this software are Rob Pike and Howard Trickey.
362 Copyright (c) 1998 by Lucent Technologies.
363
364 Rob King made some changes.
365 Those changes, Copyright (c) 2014-2016 by Rob King.
366
367 Permission to use, copy, modify, and distribute this software for any
368 purpose without fee is hereby granted, provided that this entire notice
369 is included in all copies of any software which is or includes a copy
370 or modification of this software and in all copies of the supporting
371 documentation for such software.
372
373 THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
374 WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR LUCENT TECHNOLOGIES MAKE ANY
375 REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
376 OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.