===================================================================
FAQ 0: How do I use Axiom?
===================================================================

Look at the online book. It is automatically built during the 'make'.
However, you can also do

make book

Either way, it will show up in

(yourpath)/axiom/mnt/linux/doc/book.dvi

===================================================================
FAQ 1: Xlib.h is not found
===================================================================

You need to have Xlib.h to build the graphics. If you are building
on a RedHat 8 system you need to install the following RPM:

  rpm -i XFree86-devel-4.2.0-72.i386.rpm

On Debian GNU/Linux, the package 'xlibs-dev' is needed.

===================================================================
FAQ 2: axiom.sty is not found
===================================================================

The build of noweb creates 3 files in the mnt/linux/bin directory:
notangle, noweave, and tex/axiom.sty. The build of the src/scripts
directory copies the document command to the mnt/linux/bin
directory. These four files are necessary to rebuild a Makefile.

These can be recreated in a clean system by typing:

   make start


===================================================================
FAQ 3: make hangs
===================================================================

A pamphlet file was modified and has a syntax error.  The document
command has its output redirected to a file called
obj/linux/tmp/trace.  Latex has found the syntax error and put up a
prompt which stops the make. Look in this file for the error.  You can
also see the error by rerunning make thus:

   make NOISE=

which will override the redirection and allow the latex output to go
to the console.

===================================================================
FAQ 4: noweb needs to be rebuilt
===================================================================

The first time noweb is built a dummy file called noweb
is written into the top level directory. If this file is
removed noweb will be rebuilt. The following sequence should work:

  rm noweb
  make noweb


===================================================================
FAQ 5: lisp needs to be rebuilt
===================================================================

The first time lisp is built a dummy file called gcldir
is written into the top level directory. If this file is
removed lisp will be rebuilt. The following sequence should work:

  rm lsp/gcldir
  make 


===================================================================
FAQ 6: The interpreter is badly broken
===================================================================

If you look in src/interp/Makefile.pamphlet you'll see a stanza that
is marked debugsys. You can add ${DEBUGSYS} to the "all" stanza, make
the system and run debugsys. This is a copy of the interpsys image
except that all of the files are interpreted.  Note that you will have
to edit src/interp/debugsys.lisp.pamphlet.  Read the comments
there. At this point you are able to do deep system internal debugging
(which pretty much assumes you know how to navigate the underground
caves in the dark without fear of dragons. If you can play the game at
this level send axiom-developer a note and we'll inscribe your name on
a log and throw it on the fire.)

===================================================================
FAQ 7: The wrong version of GCL was used
===================================================================

If you are building a version of Axiom on GCL there are several tested
versions. The first is GCL-2.4.1 which is an version 1 Common Lisp.
GCL-2.5 is a version 2 Common Lisp. There is a shell variable called
GCLVERSION that must be changed to choose the version.  Be sure it is
set to either gcl-2.4.1, gcl-2.5 gcl-2.5.2, or gcl-2.6.1 as these are
the only known-good versions of GCL for Axiom.

===================================================================
FAQ 8: Parallel make (i.e. make -j) fails
===================================================================

This is a complex issue. In theory, in order to build the algebra
files we have a whole graph of constraints between the algebra files.
In order to bootstrap the algebra the whole graph of algebra files
need to be built in a particular order to ensure that the required
files exist. This would argue for including the constraint as part of
the makefile stanzas.

However, once the algebra is bootstrapped these constraints are
checked at compile and runtime so it is possible to recompile an
algebra file without compiling the files it depends upon.

If we decided to include the constraints on each stanza then we
gain the benefit that "make -j" works. However, if we later change
a single algebra file it may trigger a rebuild of the entire algebra
library unnecessarily. Since bootstrap happens only once but algebra
compiles happen often it was decided to elide the constraints. This
will cause "make -j" to fail on initial build but vastly improve
later builds.

===================================================================
FAQ 9: GCL does not build on my system: libbfd.a and bfd.a are missing
===================================================================

We are using the option \texttt{--enable-statsysbfd} when building GCL (see
lsp/Makefile) so libbfd.a and bfd.h files are necessary on your system.

On Debian GNU/Linux, the needed package is 'binutils-dev'.

===================================================================
FAQ 10: The axiom.input file is ignored
===================================================================

The standard startup file, "axiom.input", has been renamed to
".axiom.input" to follow convention. This is an incompatible change.
On unix-style systems a filename that begins with a period is not
normally printed in a directory listing. This keeps the user's home
directory from being cluttered up by initialization files.

===================================================================
FAQ 11: How do I add a new pamphlet file
===================================================================

Pamphlet files are the only file format used by Axiom at the source
level. There are several steps to adding a new file to ensure that
Axiom will build it properly.

First, you have to decide where it should reside. Almost all files
reside under the src subdirectory. Never put anything into lsp, int,
obj, or mnt as these will be destroyed by "make clean".

Assume you add a file that extends the interpreter and will
go into the src/interp] subdirectory. You must modify the
src/interp/Makefile.pamphlet to correctly build the file.

You must also modify src/doc/axiom.bib.pamphlet to include
the file. Axiom uses bibtex to cross-reference the various 
pamphlet files. The normal method of citing a file involves
just using the name, for example \cite{asq.c} will build
a citation to the ./src/etc/asq.c.pamphlet file.

You must include the following two lines in your pamphlet file:

\bibliographystyle{plain}
\bibliography{axiom}

===================================================================
FAQ 12: The axiom command fails.
===================================================================

This is likely one of two problems. Axiom uses clef as its command
line editor. This has functionality similar to GNU Readline but 
was written independently. The axiom command uses:

  clef -e $AXIOM/bin/AXIOMsys

Clef attempts to create new terminals and this might fail.
The first thing to check is the permission bits on /dev/pty.

Next it is possible to run the axiom image, called AXIOMsys, directly.
Just type AXIOMsys. It won't have command recall or command line
editing but everything else is there.

===================================================================
FAQ 13: How can I create and access Lisp functions from Axiom?
===================================================================

SExpression is the domain that handles raw lisp objects.
It is possible to create SExpression elements directly contruction:

m:=[1::SEX, 2::SEX]
  [1,2]
                             Type: List SExpression
n:=m::SEX
  (1 2)
                             Type: SExpression
car(n)
  1
                             Type: SExpression

You can access lisp functions directly with:

GENSYM()$Lisp

Lisp is the domain, known to the interpreter and compiler, that contains
lisp functions and symbols.

Notice that Axiom is case-sensitive and that generally lisp symbols
are upper case. 

You can also create and call lisp functions. For instance:

)lisp (defun foo () (print "it works"))
    Value = FOO

FOO()$Lisp
 "it works"

    it works
                             Type: SExpression

While accessing and writing functions in Lisp is possible it is
generally not recommended as Axiom contains a programming language
that should be able to achieve almost everything you need.

===================================================================
FAQ 14: It still doesn't work
===================================================================

Send email to:

axiom-developer@nongnu.org

===================================================================
FAQ 15: How can I see what the interpreter is trying to do?
===================================================================

)set message bottomup on

will tell you the signatures that the interpreter is trying to use.

===================================================================
FAQ 16: How can I record console output?
===================================================================
)spool filename
    starts sending output to the file called filename
)spool )off
    stops sending output to the file
