Improved README. - 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
---
(DIR) commit 895af6b7b94a474dfbc4910718fb4fea4af2e33e
(DIR) parent ad6839270ae5425675a9eeaed743517b216c55ac
(HTM) Author: Rob King <jking@deadpixi.com>
Date: Thu, 26 May 2016 10:33:43 -0500
Improved README.
Diffstat:
README | 116 ------------------------------
README.md | 130 +++++++++++++++++++++++++++++++
2 files changed, 130 insertions(+), 116 deletions(-)
---
(DIR) diff --git a/README b/README
@@ -1,116 +0,0 @@
-
- * The authors of this software are Rob Pike and Howard Trickey.
- * Copyright (c) 1998 by Lucent Technologies.
- *
- * Rob King made some changes.
- * Those changes, Copyright (c) 2014-2015 by Rob King.
- *
- * Permission to use, copy, modify, and distribute this software for any
- * purpose without fee is hereby granted, provided that this entire notice
- * is included in all copies of any software which is or includes a copy
- * or modification of this software and in all copies of the supporting
- * documentation for such software.
- * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
- * WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR LUCENT TECHNOLOGIES MAKE ANY
- * REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
- * OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
-
-This is an X11 version of Rob Pike's editor, sam. Documentation describing
-its use and construction are provided in subdirectory doc. The file
-doc/sam.1 contains the manual page; doc/sam.1.pdf is a PDF version of that
-page. doc/sam.tut.ms is a tutorial that can be formatted with troff -ms.
-It substitutes Bold and Italics for the fonts named CW and CS; if your system
-has these fonts, remove the CW and CS macros at the beginning of the file. The
-files doc/sam.ps and doc/se.ps are postscript versions of published papers
-describing sam and structural regular expressions. These papers reflect
-sam's capabilities at the time of publication several years ago; while the
-general description remains accurate, some functions may have changed or been
-removed. The file doc/keyboard is an example of a Unicode input configuration
-file; it serves as a good starting point for a customized version (see the
-manual page for more information).
-
-Sam is composed of three programs: sam itself, which does the command
-processing and file manipulation; and samterm, which controls the display
-and interacts with the user. You can run sam on one machine and samterm on
-another connected via remote execution. A third program, rsam, is automatically
-interpolated between the terminal and the remote instance of sam by default
-to allow an additional control channel on the remote machine.
-
-This version of sam is based on the Plan 9 implementation. Its
-design and expression reflect the functionality of the Plan 9 environment;
-most notably, characters are represented internally by 16-bit values called
-Runes. Header files include/u.h and include/libc.h and source files
-libframe/misc.c, libXg/rune.c, sam/unix.c and samterm/unix.c contain
-code that insinuates sam into the Unix world. Two other files,
-sam/plan9.c and samterm/plan9.c, contain Plan 9-specific code; they
-are not used in the Unix version of sam and are provided as examples
-of the Plan 9 interface.
-
-The typedefs for uchar, ushort, and ulong defined in include/u.h, may conflict
-with exisiting definitions in include file <sys/types.h> on some systems.
-If this occurs, remove the offending definitions from include/u.h.
-
-The distribution consists of several directories:
-
- sam - The source for sam. It loads against libXg to pick
- up some utility routines.
-
- samterm - The source for samterm. It loads against libframe,
- libXg, and your local X11 libraries.
-
- rsam - The source for rsam.
-
- libframe - The source for the frame library. This library is used
- by samterm so it must be made first.
-
- libXg - The source code of the graphics library and some general
- utility modules. Header file u.h provides much of the
- interface between sam and the local environment. It is
- included in every source file. Sam's graphics
- operations are implemented by Plan 9 libg functions. This
- library emulates those functions using X11 operations.
-
- include - header files.
-
- doc - The documentation for sam.
-
-Each source directory contains a makefile.
-The master makefile in the top directory builds the subdirectories in
-proper order.
-
-Most customization effort is confined to configuring the makefiles.
-They are configured by editing config.mk; see that file for details.
-
-After configuring the makefiles, change to the top-level directory and
-type "make". Typing "make install" installs B, sam, samterm and samsave in
-their permanent homes as well as their on-line documentation.
-
-During testing, the path of samterm may be specified using the -t command line
-option to sam. Similarly, the path of sam itself may be specified using the
--s command line option; this is handy for testing the remote execution feature.
-
-The script doc/B is a Bourne shell-compatible script that sends a 'B' command
-to a running instance of sam.
-
-The original protocol between sam and samterm assumed that memory addresses
-and longs were 32 bits. Dave Hanson removed this dependency from the
-protocol allowing sam to run on 64-bit processors. However, other
-dependencies on structure alignment remain. The USE64BITS configuration
-variable in config.mk can be set to cope with 64-bit systems.
-
-Rob Pike designed and implemented the original Unix version of sam and
-the current version ported from Plan 9. Howard Trickey provided the X
-version of the graphics library, libXg. Matty Farrow and his colleagues
-at the University of Sydney extended libXg to support Runes. Boyd Roberts
-supplied the external command interface and the shell scripts for the 'B'
-command. Doug Gwyn contributed many useful ideas to the X implementation
-of sam. James Clark provided the simulations of the V10 Unix Man macros at
-the beginning of the original manual pages. Rob King updated sam to support
-little-endian 64-bit architectures, scalable fonts, dynamic composition
-configuration, two-button-mice, Linux, and more keyboard shortcuts.
-
-
-Please send bug fixes and comments to:
-
-Rob King, jking@deadpixi.com
-http://www.deadpixi.com/an-updated-version-of-sam
(DIR) diff --git a/README.md b/README.md
@@ -0,0 +1,130 @@
+Introduction
+============
+
+sam is a text editor originally written for the Blit_ graphical terminal connected to a machine running `9th Edition Research Unix`_.
+It contained many useful innovations, the most famous of which was its use of `structural regular expressions`_.
+
+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 1980s.
+
+.. _Blit: https://en.wikipedia.org/wiki/Blit_(computer_terminal)
+.. _`9th Edition Research Unix`: https://en.wikipedia.org/wiki/Research_Unix
+.. _`structural regular expressions`: http://doc.cat-v.org/bell_labs/structural_regexps/se.pdf
+.. _`Plan 9 from Bell Labs`: http://plan9.bell-labs.com/plan9/
+
+This version of sam is based on that 1980s Unix port, with many useful additions and modifications (see `New Features`_.
+
+New Features
+============
+
+Modern OS Support
+ This version of sam compiles and runs on modern Linux systems.
+
+Improved 64-bit Support
+ The original sam had support 32-bit architectures and big-endian 64-bit architectures.
+ This version supports 64-bit architectures of any endianess (including, most importantly, x86_64).
+
+Scalable Font Support
+ This version of sam is not limited to classic X fonts, but can use modern scalable fonts.
+ Inconsolata_ is this author's favorite, though `Courier Prime Code`_ is giving Inconsolata a run for its money.
+
+Simplified and Dynamic Configuration
+ The graphical elements (colors and fonts) of this version of sam are controlled via environment variables, not X Resources.
+ The table of composable characters is now dynamically configurable (via the `~/.keyboard` file), where it was once hard-coded.
+
+Far Better Keyboard Support
+ The cursor ("selection") can be moved using keyboard commands (a la the `WordStar Diamond`_).
+ A keyboard command (ctrl-k) is provided to jump between the command window and the current file window.
+ These commands are configurable at compile time (and more commands are in the works).
+
+Support for Two-Button Mice
+ The original sam required a three-button mouse.
+ 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.
+
+Support for Mouse Chords
+ The snarf, cut, and paste commands are accessible via mouse-button combinations ("chords").
+
+Better Remote Editing Support
+ This version of sam can use `ssh(1)` as its remote shell.
+ Additionally, the B command works on both the local and the remote system during remote editing sessions.
+
+Command Language Extensions
+ Various minor and mostly-compatible changes have been made to the sam command language.
+ Most notable is the `b` command, which now performs a fuzzy match on filenames, making switching between files much faster and easier.
+
+Improved Manual Page
+ The manual page has been rewritten to use the modern `mdoc(7)` manual page macros.
+ It has been additionally cleaned up, clarified, and extended.
+
+Support for Tab Expansion
+ When enabled, tabs will be expanded into spaces.
+
+.. _Inconsolata: http://www.levien.com/type/myfonts/inconsolata.html
+.. _`Courier Prime Code`: http://quoteunquoteapps.com/courierprime/
+.. _`WordStar Diamond`: http://texteditors.org/cgi-bin/wiki.pl?WordStarDiamond
+
+Credits
+=======
+
+These credits are in rough chronological order as determined by the ordering in the original README supplied with the X version of sam for those names included there, and then by order of GitHub commits for this version.
+
+Rob Pike
+ Original author of sam.
+
+Howard Trickey
+ Wrote the X version of the graphics library.
+
+Matty Farrow et al
+ Extended the X version of the graphics library to support Unicode.
+
+Boyd Roberts
+ Added the external command interface and associated scripts.
+
+Doug Gwyn
+ Contributed many useful ideas to the X implementation of sam.
+
+James Clark
+ Wrote troff macros to allow the man pages to be rendered on non-V10 Unix systems.
+
+Rob King
+ Added most of the things mentioned in `New Features`_ above.
+ Rob is the maintainer of this version of sam.
+
+Mark H. Wilkinson
+ Wrote the original mouse-chording code.
+
+Chris Siebenmann
+ Fixed various bugs in font rendering, and ported Mark H. Wilkinson's mouse chording code to this version of sam.
+
+Aram Hăvărneanu
+ Improved the handling of Makefile variables.
+
+Ishpeck
+ Improved C89 support.
+
+Tommy Pettersson
+ Fixed bugs in the cursor movement code.
+
+Christian Neukirchen
+ Fixed various Makefile bugs.
+
+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.
+
+Copyright and License
+=====================
+
+The authors of this software are Rob Pike and Howard Trickey.
+Copyright (c) 1998 by Lucent Technologies.
+
+Rob King made some changes.
+Those changes, Copyright (c) 2014-2015 by Rob King.
+
+Permission to use, copy, modify, and distribute this software for any
+purpose without fee is hereby granted, provided that this entire notice
+is included in all copies of any software which is or includes a copy
+or modification of this software and in all copies of the supporting
+documentation for such software.
+
+THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR LUCENT TECHNOLOGIES MAKE ANY
+REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
+OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.