GopherProxy

	README.rst - sam - An updated version of the sam text editor.
	git clone git://vernunftzentrum.de/sam.git
	Log
	Files
	Refs
	LICENSE
	---
	README.rst (14750B)
	---
	1 Introduction
	2 ============
	3
	4 sam is a text editor originally written for the Blit_ graphical terminal…
	5 It contained many useful innovations, the most famous of which was its u…
	6
	7 sam was the standard text editor for `Plan 9 from Bell Labs`_, and the P…
	8
	9 .. _Blit: https://en.wikipedia.org/wiki/Blit_(computer_terminal)
	10
	11 .. _`9th Edition Research Unix`: https://en.wikipedia.org/wiki/Research_…
	12
	13 .. _`structural regular expressions`: http://doc.cat-v.org/bell_labs/str…
	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 a…
	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 f…
	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/TheKingAdRo…
	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…
	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`_, i…
	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 suc…
	64
	65 .. _`XQuartz`: https://www.xquartz.org/
	66 .. _`desktop entry file`: https://specifications.freedesktop.org/desktop…
	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 `sa…
	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…
	83 such support has been present in OpenSSH since at least version 6.7 (rel…
	84 See the `sam(1)` manual page for information on how the remote shell cli…
	85
	86 Note that sam relies on the contents of the `LANG`, `LC_CTYPE`, and/or `…
	87 If you're using `ssh(1)` to run sam remotely, be sure to pass those vari…
	88
	89 Installation Paths
	90 -------------------
	91
	92 By default, `sam`, `samterm`, and `B` all end up in '$(BINDIR)' as defin…
	93
	94 Compatibility
	95 -------------
	96
	97 Note that Deadpixi sam has extended the binary protocol spoken between s…
	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…
	106
	107 Improved 64-bit Support
	108 The original sam had support for 32-bit architectures and big-endian…
	109 This version supports 64-bit architectures of any endianess (includi…
	110
	111 Scalable Font Support
	112 This version of sam is not limited to classic X fonts, but can use m…
	113 Inconsolata_ is this author's favorite, though `Courier Prime Code`_…
	114
	115 X Input Method and Composition Support
	116 This version of sam supports the X Input Method extension for input …
	117 This allows users to input text via the methods with which they are …
	118 Additionally, the XCompose(5) file can be used to bind arbitrary seq…
	119 to different input character sequences.
	120 This mechanism is both more portable and more extensible than the ol…
	121 input mechanism.
	122
	123 Multicolor Support
	124 This version of sam supports configurable text, selection, border, a…
	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…
	134 Keybindings and mouse chords are configurable at runtime via a confi…
	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 w…
	139 scrolling the display, snarfing, pasting, etc.
	140 The binding of these commands to keyboard sequences is configurable …
	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 us…
	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 …
	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 s…
	155
	156 Command Language Extensions
	157 Various minor and mostly-compatible changes have been made to the sa…
	158 Most notable is the `b` command, which now performs a fuzzy match on…
	159
	160 Improved Manual Page
	161 The manual page has been rewritten to use the modern `mdoc(7)` manua…
	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 encodi…
	169 That means that it is not limited to UTF-8, but can edit files in an…
	170 This also means that on modern systems, files containing codepoints …
	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…
	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 …
	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?WordStarD…
	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 la…
	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-li…
	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 ma…
	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`…
	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…
	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 …
	262
	263 - Bugfixes
	264 - Translation updates
	265 - Binary package updates
	266 - Updates necessary to keep sam compiling on whatever systems its users …
	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 …
	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 Stroust…
	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 C…
	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 …
	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 apologie…
	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 MA…
	375 REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
	376 OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.