https://github.com/mittelmark/microemacs
Modern Jasspa's Microemacs fork - based on Dave Conroy and Daniel Lawrences code. Text editor with GUI and terminal mode, with syntax highlighting, folding, outlines, abbreviations, own extension language, calendar, games, notes, ...
https://github.com/mittelmark/microemacs
crossplatform editor emacs gui-editor linux macos microemacs terminal-editor text-editor windows
Last synced: about 1 year ago
JSON representation
Modern Jasspa's Microemacs fork - based on Dave Conroy and Daniel Lawrences code. Text editor with GUI and terminal mode, with syntax highlighting, folding, outlines, abbreviations, own extension language, calendar, games, notes, ...
- Host: GitHub
- URL: https://github.com/mittelmark/microemacs
- Owner: mittelmark
- License: other
- Created: 2021-11-21T03:58:49.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-05-04T09:09:42.000Z (about 1 year ago)
- Last Synced: 2025-05-04T10:23:01.508Z (about 1 year ago)
- Topics: crossplatform, editor, emacs, gui-editor, linux, macos, microemacs, terminal-editor, text-editor, windows
- Language: C
- Homepage: https://github.com/mittelmark/microemacs
- Size: 34.4 MB
- Stars: 21
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README-standalone.md
- Changelog: ChangeLog
- License: COPYING
Awesome Lists containing this project
README
---
title: "Readme for the Jasspa Microemacs Text Editor"
author: Detlef Groth
date: 2024-08-30 08:28
---
## Table of Contents
- [Introduction](#Intro)
- [Main files](#Main)
- [Installation](#Install)
- [TTF-Fonts for X11](#Fonts)
- [X11 Font Tools](#Fonttools)
- [Spelling](#Spell)
- [Modification of the Executable](#Modi)
- [User Profile](#Profile)
- [User Identification](#Identity)
- [Personal Directory](#Personal)
- [Creating Your Profile](#Create)
- [Company Profiles](#Company)
- [Support](#Support)
The MicroEmacs 09 Text Editor is a small footprint text editor with the
following features:
- small single file binary approx 2.5Mb (with help file and American
dictionary embedded)
- fast startup and low memory footprint (less than 2Mb usually)
- Emacs like editing
- support for many programming and markup languages
- extensible macro language
- session management
- sophisticated embedded hypertext help system
- same interface for terminal and GUI application
- many themes
- menu AND shortcut enabled
- cross platform same functionality MacOS, Linux and Windows (many others on
request)
- easy embedding of other tools
The main cons:
- no Unicode support - only ISO 8859-1 .. 15 amd Windows-Cp1252 support -
because it is an __Micro__Emacs
- but: converting Unicode to these code pages and back would be possible if
really required
- no softwrap facilities, wrap mode means automatically wrapping with newlines
As these builds are stand-alone files, installation is simply a copy operation
on your file system after downloading the release file. The following files provide the
following functionality.
Mandatory:
- _mecb.bin_ - the terminal version of the MicroEmacs 09, rename it to mec (mec.exe
on Windows) and place it into a folder belonging to your PATH, contains as
well the help file and the American dictionary files.
- _mewb.bin_ - the GUI version (mewb.exe), using X11 on Linux and MacOS, rename it
to mew (mew.exe on Windows) and place it into a folder belonging to your
PATH, contains as well the help file and the American dictionary files.
Optional:
- _mecw.bin_ - the combined terminal and GUI version which is only available
for Unix systems like Linux and MacOS
- _xfontsel_ - X11 tool (Linux, MacOS) for better font selection, installable
via package manager (see below for details)
- _ttf-files.zip_ - for X11 (Linux, MacOS) selection of good looking TrueType fonts
in a form usable for MicroEmacs and other X11 applications (can be as well
installed for Windows)
- _mkfontscale_ - X11 (Linux, MacOS) tool to add your own TrueType font to
be used with MicroEmacs
- _bfs.bin_ (bfs.exe) - an archiving tool which allows you to modify a
MicroEmacs executable for instance adding your own macro or dictionary files
Details about these components are following below.
If you just need an Emacs like terminal editor for your server, grab the mecb
executable for your platform and place it into a folder belonging to your
PATH.
The prefered way is to install the single file binaries which can be of three
types:
- __mecb__ - terminal only editor, menu access using the "Esc =" shortcut
- __mewb__ - GUI only editor, menu access using "Alt-[Letter]" or as well "Esc ="
- __mecwb__ - terminal and GUI enabled, terminal mode can be used by using the
_-n_ command line option
After you downloaded the appropiate Zip file for your platform you will find
the following files within the Archive:
* `bin/mec` and `bin/mew` - the zero install standalone executables with all macro files attached in the following called `ME`
* `bin/bfs` - the archive tool to create and modify the standalone mec/mew executables
* `man/me.1` - the MicroEmacs manual page
* `share/jasspa/license.txt` - license.txt the GPL license - the source code is available from [https://github.com/mittelmark/microemacs](https://github.com/mittelmark/microemacs).
* `share/jasspa/README-standalone.md` - this README
* `readme.txt` a readme which explains the folder structure
The installation just follows these basic steps:
__Linux and MacOS:__
- create a folder `~/.jasspa` in your home directory - this folder will keep
your personal settings, macros, sessions etc
- copy the _mec-VERSION-PLATFORM.bin_ (or _mew-VERSION-PLATFORM.bin_) file as
mec (mew) to the folder `~/.local/bin` - this folder should
usually belong to your PATH variable, if not add to the PATH variable in
your `~/.bashrc` or `~/.zshrc` file like this: `export PATH=~/.local/bin:$PATH`
- make the file executable using `chmod 755 ~/.local/bin/me*`
- run the mec/mew executable and do do general setup and then run the user setup
"Esc x user-setup" or use the menu entry "Tools -> User Setup" by selecting
the users keyboard
- optionally install a few better looking TTF fonts in the users font folder
(see below)
If you like to have support for colors in the terminal version you should
check in the User-Setup in the Platform Tab the Termcap Color checkbox and
start me with a redefined terminal varianle like this:
```
TERM=xterm mec
### or ...
TERM=rxvt mec
```
It is advisible if this works on your terminal to make an alias in your shell
configuration file like this:
```bash
alias mec="TERM=xterm mec"
```
Check which settings cause no trouble for instance with colors and the
backspace key. This might depend on your used terminal emulator like
lxterminal or terminal multiplexer like tmux. It is usually adivisble to
stick with the default MicroEmacs color scheme using the terminal version and switch the
theme if required using the terminal emulator. On lxterminal you can use for
instance the Solarized themes for a more pastel like basic scheme.
__Windows:__
- if not yet existing - create a folder 'C:\Users\\bin'
- copy the mecb.exe and mewb.exe files to this folder as mec.exe and mew.exe
- add this folder to your PATH variable if it is not yet there like this:
- Right-click on "This PC" or "Computer" and select "Properties."
- Go to "Advanced system settings" on the left.
- Click on "Environment Variables."
- Under "System variables," find the Path variable and click "Edit."
- Add the path to your new directory (e.g., C:\Users\\bin) to the list of paths.
- run the mec/mew executables (Win-r and typing mew) and do general setup giving your username and
then the user setup "Esc x user-setup" mainly here selecting the right keyboard for your computer
- If you after selecting the keyboard get an error about not having writing the
_username.erf_ file you might to create the appropriate directory
`~./jasspa` by yourself and then repeat the procedure. To use the spell-checking facilities you have
to download and unpack the spell-checking files from here https://github.com/mittelmark/microemacs/releases/tag/v0.9.0
## TTF-Fonts for the X11-Application (mew) on Linux, MacOS and FreeBSD
The default X11 installation on Linux and MacOS using [XQuartz](https://www.xquartz.org/) has only a few
not so good looking fonts available for the base install. To get more fonts
it is advisible to use the collection of TrueType fonts from the MicroEmacs
project package by doing the following:
- download the file `ttf-files.zip` from the current release page
- unzip these files into the folder `~/.local/share/fonts` - if this
folder does not exists yet, create it
- for MacOS the path should be `~/Library/Fonts`
- add this folder to your current font-path by executing the following
commands
```
xset +fp ~/.local/share/fonts
### xset +fp ~/Library/Fonts (MacOS)
xset fp rehash
```
These commands are available as a shell script in the ttf-files folder.
You should place a desktop file into your ~/.config/autostart folder usually
for Window managers like Gnome or XFCE tp run this script automatically at
startup.
If this does not work for _MacOS_ it is probably since X11 applications on
MacOS typically use the system's font configuration, ensuring the fonts are
installed in the system or user font directories should make them available to
X11. However, if you need to specify font paths for X11 explicitly, you can
add the font paths to your X11 configuration. For example, you can add the
following lines to your `~/.Xresources` or `~/.Xdefaults` file text:
```
Xft.dpi: 96
Xft.antialias: true
Xft.hinting: true
Xft.hintstyle: hintfull
Xft.rgba: rgb
xft.fontpath: /Library/Fonts:/System/Library/Fonts:/Users/your_username/Library/Fonts
```
### X11 Font Tools
If you add more TTF fonts on your own to this folder you have later to update
the files `fonts.scale` and `fonts.dir` by using the _mkfontscale_
application.
To have a look at the available list of X11-fonts you can use the _xfontsel_
application on X11. If this tool is available on your machine it will as well
offer it in the font-selection part of the user-setup dialog as a possibility
to choose your own font.
You can install these applications with the following commands:
```
### Fedora and other RedHat like systems for instance AlmaLinux
sudo dnf install xorg-x11-apps # xfontsel
sudo dnf install mkfontscale # indexing X11 fonts
sudo dnf install xlsfonts # font list in the terminal
### Debian and distros based on it like Ubuntu, Linux Mint, MX Linux
sudo apt install x11-utils # xfontsel, xlsfonts
sudo apt install xfonts-utils # mkfontscale
### Arch-Linux and distros based on it like Manjaro Linux
sudo pacman -S xorg-xfontsel
sudo pacman -S xorg-mkfontscale
sudo pacman -S xorg-xlsfonts
### MacOS using MacPorts
sudo port install mkfontscale
sudo port install xfontsel
sudo port install xlsfonts
### FreeBSD
sudo pkg install mkfontscale
sudo pkg install xfontsel
```
As with MacOS the folders where these fonts are in should be then added to the FontPath.
Hint: On some Arch-Linux distros like Manjaro a few TTF fonts usuable by MicroEmacs can be
installed by the package manager as the folders where they are installed will
get a fonts.dir and fonts.scale file automatically be the package installer.
So you can do there a:
```
sudo pacman -S ttf-fira-mono
sudo pacman -S ttf-ubuntu-font-family
sudo pacman -S adobe-source-code-pro-fonts
xset fp rehash
```
To get these and other monospaced programming fonts.
Other package manager allow you as well to install a few TTF files but they do
not update the fontpaths for older X11 applications. For instance the FreeBSD
package manager requires afterwards to update the fontpath yourself:
```
### FreeBSD
### get two additional fonts if you do not use ttf-files
sudo pkg install liberation-fonts-ttf
sudo pkg install source-code-pro-ttf
xset +fp /usr/local/share/fonts/Liberation
xset +fp /usr/local/share/fonts/SourceCodePro
xset fp rehash
```
Hint: To view only monospaced programming fonts with _xfontsel_ run the tool
with the pattern argument like this:
```
xfontsel -pattern "*-m-*" -scaled
```
To install TTF fonts for use with X11 applications on a Mac, you need to ensure the fonts are accessible to both the Mac's native environment and the X11 environment. Here are the steps to follow:
Install Fonts for Mac Environment:
Using Font Book:
- Double-click the TTF font file to open it in Font Book.
- Click "Install Font" at the bottom of the preview window.
Manually:
- Open Finder and navigate to ~/Library/Fonts.
- Drag and drop the TTF font files into this folder.
- Make Fonts Available to X11:
## Spelling Dictionaries
Me supports spelling checks. You need to download the spelling files from the
Github release page here:
[https://github.com/mittelmark/microemacs/releases/tag/v0.9.0](https://github.com/mittelmark/microemacs/releases/tag/v0.9.0)
Just download the and unzip the required spelling directories into your
`~/.jasspa` folder for instance for the German spelling rules like this:
```
wget https://github.com/mittelmark/microemacs/releases/download/v0.9.0/ls_dede.zip
unzip ls_dede.zip -d ~/.jasspa/
```
## Modification of the MicroEmacs Executable
You can modify the macro tree of the executable using the `bfs` command line
application. The steps to do so are described in much detail here: [http://www.jasspa.com/zeroinst.html](http://www.jasspa.com/zeroinst.html).
Below the short version.
In case you created new macro files for a specific filetype or you modified
existing macro files and you would deploy these modifications in a standalone
executable you can create a new me-standalone file by:
* let's assume that you like to modify the terminal executable
* make a copy of it and name it `mec.bin`
* you can then detach the current archive from the stand-alone executable into
a folder *mearchive* like this:
```
bfs -x mearchive mec.bin
```
* thereafter you add your own or replace changed files into the folders
_spelling_ (for dictionaries), _macros_ (for macro files) and thereafter you
attach this changed folder to the old executable like this:
```
bfs -a mec.bin ./mearchive
```
This will replace the old archive with the new one. You can now copy simply
this file and use it on other machines having the same platform.
## Local User Profile
MicroEmacs uses local user configuration profiles to store user specific
information. The user information may be stored in the MicroEmacs
directory, or more typically in a users private directory. On login
systems then the user name and user private directory location is
automatically determined from the system.
The user name identified by MicroEmacs is `$user-name(5)` this value may be
set or re-defined using the environment variable `$MENAME(5)`.
The location of the user information depends upon your platform and
installation configuration. The private directory identified by MicroEmacs
is `$user-path(5)` this location may be changed by defining the environment
variable `$MEUSERPATH(5)`.
Microsoft Windows users may use the me32.ini(8) file to define MicroEmacs
configuration path and name information.
__User Profile Files__
Files contained in the user profiles typically include:-
.emf - The users start up profile - .emf.
.edf - The users spelling dictionary.
.erf - The users registry configuration file.
These files are automatically set up by MicroEmacs. These files are
established from the menu "Tools -> User Setup". The "Setup Path" item
defines the location of the files, but must be MANUALLY included in the
`$MEPATH` environment.
__Company Profiles__
Company profiles include standard files and extensions to the standard
files which may be related to a company, this is typically .emf
where is the name of the company.
The directory may also include template files etf(8) files which defines
the standard header template used in the files. Files in the "company"
directory would over-ride the standard template files.
In order to identify a user MicroEmacs 2009 uses information in the system
to determine the name of the user, and in turn the configuration to use.
On all systems the value of the environment variable $MENAME(5) takes
priority over any other means of user identification. If this variable is
not defined then the host system typically provides a mechanism to
determine the current user.
UNIX
The login name is determined from the `/etc/passwd` file and defines
`$user-name(5)`. The environment variable `$MENAME(5)` may be defined alter the
default user configuration file name.
Microsoft Windows
Microsoft windows environments may, or may not, have login enabled.
If login is enabled then `$user-name(5)` is set to the login user name.
The login name may be overridden by setting the environment variable
`$MENAME(5)` this may be performed in the environment or through the
`me32.ini(8)` file.
## Personal MicroEmacs Directory
The private user profile is stored in a separate directory. The directory
that MicroEmacs uses is typically automatically created at start up, but
may be created manually by the user. If the directory is to be placed in a
special location then the `$MEUSERPATH(5)` environment variable should be
defined and set to point at this directory location.
__UNIX__
In the UNIX environment then the local directory is typically created
in the users home directory obtained from the `/etc/passwd` file and is
called `~/.jasspa`. MicroEmacs will automatically look for this
directory and set the `$user-path(5)` variable to this value. The
location may be overridden by setting the environment variable
`$MEUSERPATH(5)` to reference a different directory location.
__Windows__
In Microsoft Windows environment using Explorer 4.0 or later then a
user application data directory exists (`$APPDATA`) and MicroEmacs will
create a directory jasspa in this directory location to hold private
data. If there is no such data area then all user configuration is
stored in the executable directory location (or a sub-directory
called `$user-name(5)`).
The user data area `$user-path(5)` may be modified by creating a new
directory and setting the environment variable `$MEUSERPATH(5)` to
point to this new directory location. The location be specified by a
meuserpath entry in the `me32.ini(8)` file rather than setting the
environment variable `$MEUSERPATH(5)`.
On starting MicroEmacs for the first time then the user is guided through
the configuration file setup to create any local configuration files. Once
set up then MicroEmacs may be configured using the user-setup(3) dialog:-
Tools -> User Setup
The User Profile
> Files created in the user directory include:-
* Setup registry and previous session history `$user-name.erf` (see
erf(8)). This stores the user-setup settings and the context from
previous edit sessions.
* Users start-up file `$user-name.emf` (see `emf(8)`). This is typically
referred to as "user.emf" in the documentation and means the users
private MicroEmacs macro file. The user may make local changes to
MicroEmacs in this file, this may include definition of new key
bindings, defining new hook functions etc. You should override the
standard MicroEmacs settings from your start-up file rather than
modifying the standard MicroEmacs files.
* Personal spelling dictionary lsdplang.edf (see `edf(8)`). Multiple
spelling dictionaries may be created, one for each language. Any
words that are added to the spelling dictionary are stored in these
files.
In addition to the above, if new private macro files are constructed then
they should be added to this directory (if they are not global to the
company).
__EXAMPLE:__
The following are examples of some individuals start-up files:-
```
; Jon's special settings
;
; Last Modified <190698.2226>
;
; Macro to delete the whitespace, or if an a word all of the
; word until the next word is reached.
define-macro super-delete
set-variable #l0 0
!while ¬ &sin @wc " \t\n"
forward-char
set-variable #l0 &add #l0 1
!done
!repeat
!force forward-char
!if $status
set-variable #l0 &add #l0 1
!endif
!until &or &seq @wc "" ¬ &sin @wc " \t\n"
#l0 backward-delete-char
!return
!emacro
; Make a previous-buffer command.
define-macro previous-buffer
&neg @# next-buffer
!emacro
; spotless; Perform a clean and remove any multi-blank lines.
define-macro spotless
-1 clean
!emacro
; comment-adjust; Used for comments in electric-c mode (and the other
; electic modes. Moves to the comment fill position, saves having to mess
; around with comments at the end of the line.
0 define-macro comment-adjust
; delete all spaces up until the next character
!while &sin @wc " \t"
forward-delete-char
!done
; Fill the line to the current $c-margin. We use this as
; this is the only variable that tells us where the margin
; should be.
!if &gre $window-acol 0
backward-char
!if &sin @wc " \t"
forward-delete-char
!jump -4
!else
forward-char
!endif
!endif
; Now fill to the $c-margin
&sub $c-margin $window-acol insert-string " "
!emacro
; Macro to force buffer to compile buffer for C-x '
define-macro compile-error-buffer
!force delete-buffer *compile*
change-buffer-name "*compile*"
!emacro
;
; Set up the bindings.
;
global-bind-key super-delete "C-delete"
global-bind-key beginning-of-line "home"
global-bind-key end-of-line "end"
global-bind-key undo "f4"
!if &seq %emulate "ERROR"
global-bind-key comment-adjust "esc tab"
global-bind-key comment-adjust "C-insert"
; Like a korn shell please.
ml-bind-key tab "esc esc"
!endif
;
; Setup for windows and UNIX.
;
; Define my hilighting colour for Windows and UNIX.
!if &equ &band $system 0x001 0
!if ¬ &seq $platform "win32"
; Small bold font is better for me.
change-font "-*-clean-medium-r-*-*-*-130-*-*-*-*-*-*"
!endif
!endif
; Change the default diff command-line for GNU diff utility all platforms
set-variable %diff-com "diff --context --minimal --ignore-space-change --report-identical-files --recursive"
set-variable %gdiff-com "diff --context --ignore-space-change -w"
; Setup for cygwin
!if &seq $platform "win32"
set-variable %cygwin-path "c:/cygwin"
set-variable %cygwin-hilight 1
!endif
; Set up the ftp flags. The letters have the following meaning:
; c - Create a console (*ftp-console* for ftp, *http-console* for http)
; s - Show the console
; p - Show download progress ('#' every 2Kb downloaded)
set-variable %ftp-flags "csp"
; Info files
;To hilight the .info and also the dir file
add-file-hook ".info dir" fhook-info ; Info-files
;To hilight all info files without the extension .info
;but starting with the text "This is info file..
-2 add-file-hook "This is Info file" fhook-info
; Finished
ml-write "Configured to Jon's requirements"
```
This section describes how a company profile should be incorporated into
MicroEmacs 2009. A company profile defines a set of extensions to
MicroEmacs which encapsulate settings which are used on a company wide
basis. This type of configuration is typically used with a networked
(shared) installation. The company profile would typically include:-
* Name of the company.
* Standard header files including company copyright statements.
* Standard file layouts
* Company defined language extensions.
Location Of The Company Information
It is suggested that all of the company extensions applied to MicroEmacs
2009 are performed in a separate directory location which shadows the
MicroEmacs standard macro file directory. This enables the original files
to be sourced if a user does not want to include the company files. This
method also allows MicroEmacs to be updated in the future, whilst
retaining the company files.
The company files are generally placed in the company sub-directory
described in the installation notes.
Content Of The Company Information
Company macro file
The company file is typically called by the company name (i.e.
jasspa.emf) create a new company file. The file includes your company
name and hook functions for any new file types that have been defined
for the company, an example company file for Jasspa might be defined
as:-
```
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;
; Author : Jasspa
; Created : Thu Jul 24 09:44:49 1997
; Last Modified : <090829.1633>
;
; Description Extensions for Jasspa
;
; Notes
;
; History
;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Define the name of the company.
set-variable %company-name "Jasspa"
; Add Jasspa specific file hooks
; Make-up foo file hook
add-file-hook ".foo" fhook-foo
1 add-file-hook "-!-[ \t]*foobar.*-!-" fhook-foo ; -!- foobar -!-
; Override the make with localised build command
set-variable %compile-com "build"
```
The file contains company specific file hooks and the name of the company.
Other Company Files
Files defined on behalf of the company are included in the company
directory. These would include:-
* Template header files etf(8).
* Hook file definitions (hkXXX.emf) for company specific files,
see add-file-hook(2).
* Extensions to the standard hook definitions (myXXX.emf) for
company specific language extensions to the standard hook files.
See File Hooks and File Language Templates.
## Support
__Issues:__
In case you find bugs or have suggestions for improvements or would like to
port the code to other platforms use the Issues tab on the Github page:
[https://github.com/mittelmark/microemacs/issues](https://github.com/mittelmark/microemacs/issues)
__Help:___
MicroEmacs contains an embedded help system. Use the 'Help' menu entry on the
right. There is as well a set of older HTML files online available from here:
[http://www.jasspa.com/me.html](http://www.jasspa.com/me.html)
__Contact:__
In case of questions, suggestions, trouble etc, write to dgroth (at) uni
(minus) potsdam (dot) de or use the issue tracker at the Github project page.
## Future
BTW: Currently a new release, named ME 2024, with more features (https, git)
support, is prepared.