Skip to content

Latest commit

 

History

History
701 lines (552 loc) · 26 KB

README-standalone.md

File metadata and controls

701 lines (552 loc) · 26 KB
Raw
title author date
Readme for the Jasspa Microemacs Text Editor
Detlef Groth
2024-08-30 08:28

Table of Contents

Introduction

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

Main files

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.

Installation

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.
  • 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:

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<Username>\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<Username>\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 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

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.

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:-

 <name>.emf - The users start up profile - <user>.emf. 
 <name>.edf - The users spelling dictionary. 
 <name>.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.

<a name"Identity">

User Identification

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).

Creating Your Profile

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 &not &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 "" &not &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 &not &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"

COMPANY PROFILES

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

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

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.