HTTPS SSH
AN AXIOM ENVIRONMENT FOR EMACS
==============================

The ``axiom-environment'' package is intended to make it easier to
work with, and understand, the Axiom, OpenAxiom and FriCAS computer
algebra systems.  It implements four different major modes for the
Emacs text editor:

  1. axiom-process-mode: for interaction with a running Axiom process.

  2. axiom-help-mode: for displaying help information about the Axiom
     system.
  
  3. axiom-input-mode: for editing a .input (Axiom script) file.

  4. axiom-spad-mode: for editing Axiom library code written in the
     SPAD language.

The main features of these modes (so far) are syntax highlighting to
display package, domain & category names (and their abbreviations) in
distinct colours, and to give quick access to popup buffers displaying
summary information about these types and their operations.  The
syntax highlighting feature allows to see at a glance which aspect of
the type system we are concerned with (domains or categories), and the
popup buffer feature allows to examine (and re-examine) these types
without interupting the workflow (i.e. interaction in the Axiom REPL).

Hint: to make a popup help buffer go away, press ``q'', emacs's window
configuration will be restored to what it was before the help window
appeared and the help buffer will be buried in the buffer list.

The ``ob-axiom'' package is an org-babel extension that integrates the
axiom-environment into org-mode, allowing a literate development &
presentation style with easy publishing to HTML, PDF, etc.

The ``company-axiom'' package is a company-mode backend for symbol
completion in the company framework.


INSTALLATION
============

The easiest way to install axiom-environment (and optionally the
ob-axiom and company-axiom packages) is via MELPA, the Emacs lisp
package server.  First ensure that you have access to the MELPA
package repository (by putting the following in your .emacs file if
it's not there already):-

  (require 'package)
  (add-to-list 'package-archives
	       '("melpa" . "http://melpa.org/packages/") t)

then simply do

  M-x list-packages

and select and install the axiom-environment and possibly ob-axiom and
company-axiom packages.

Alternatively, if you don't want to use MELPA, you can clone the
axiom-environment git repository (hosted at bitbucket.org) into
your directory of choice:

  cd /my/directory/of/choice

  git clone http://bitbucket.org/pdo/axiom-environment

then add the following line to your .emacs file:

  (load-file "/my/directory/of/choice/axiom-environment/axiom.el")

This will load the axiom-environment, ob-axiom and company-axiom
systems directly.

Either way you install it, this will allow Emacs to automatically put
.spad and .input files into ``Axiom SPAD'' and ``Axiom Input'' modes,
respectively, and give access to the ``Axiom'' menu in these modes.
See the menu for shortcuts to the helper commands.

Also available is the ``Axiom Selector'' function, to give quick
access to Axiom buffers.  This is most useful when bound to a key
sequence that is accessible from any buffer.  For example

  (global-set-key (kbd "C-c a") 'axiom-selector)

in your .emacs file will do nicely.  Then you can do `C-c a ?' to
bring up a summary of selector commands.  Highlights include `C-c a r'
to switch to the Axiom REPL buffer, and 'C-c a a' to bring up a buffer
listing all available Axiom buffers and allowing you to select one to
switch to, or display in another window.  Type `?' or the usual `C-h
m' to bring up a summary of Axiom Buffer Menu mode's commands.

To start an interactive Axiom session do:

  M-x run-axiom

Note that by default this will attempt to start the FriCAS program
(with command "fricas -nosman"), but that this can be changed using an
Emacs customization variable.  In fact many customization variables
exist, for different aspects of the environment, under the ``Axiom''
customization group.  Likely candidates you will want to change
include:-

  axiom-process-program
  axiom-process-spad-source-dirs

An easy way of managing arbitrary collections of customization
variables is available via the Emacs ``theme'' mechanism.  Example
themes showing how to setup the environment to work with FriCAS or
OpenAxiom on SBCL, and Axiom on GCL, are included in the ``themes''
subdirectory of the axiom-environment package.


REQUIREMENTS
============

Please note that development of this software started with Emacs 24.2
and it is quite likely that it won't work with earlier versions.


BUGS
====

Testing so far has been with Axiom, OpenAxiom and FriCAS running on
macOS and Linux (with OpenAxiom and FriCAS built with SBCL).  It
should of course run on other OSes too.

It should be noted that most development work is done with FriCAS, so
this is likely to give the least problematic user experience.

Please send bug reports to:

  Paul Onions <paul.onions@acm.org>

or click on the issue tracker tab at:

  http://bitbucket.org/pdo/axiom-environment/

and enter the details there.

--
Paul Onions
22 October 2017