fix xminor bugs in manual

docs/install.tex

@@ -0,0 +1,389 @@
+@c -*- mode: texinfo; coding: utf-8; -*-
+
+@node Install, Run, Intro, Top
+@chapter Installing YAP
+@cindex installation
+
+
+@menu
+* Configuration Options:: Tuning the Functionality of YAP Machine
+* Machine Options:: Tuning YAP for a Particular Machine and Compiler
+@end menu
+
+To compile YAP it should be sufficient to:
+
+@enumerate 
+@item @command{autoconf}. Recent versions of YAP try to follow GNU
+conventions on where to place software.
+
+@itemize @bullet
+@item The main executable is placed at @var{$BINDIR}. This executable is
+actually a script that calls the Prolog engine, stored at @var{$LIBDIR}.
+
+@item @var{$LIBDIR} is the directory where libraries are stored. YAPLIBDIR is a
+subdirectory that contains the Prolog engine and a Prolog library.
+
+@item @var{$INCLUDEDIR} is used if you want to use YAP as a library.
+
+@item @var{$INFODIR} is where to store @code{info} files. Usually
+@file{/usr/local/info}, @file{/usr/info}, or @file{/usr/share/info}.
+@end itemize
+
+@item @command{make}.
+
+@item If the compilation succeeds, try @command{./yap}.
+
+@item If you feel satisfied with the result, do @command{make install}.
+
+@item @command{make install-info} will create the info files in the
+standard info directory.
+
+@item @command{make html} will create documentation in html format in the
+predefined directory.
+
+@end enumerate
+In most systems you will need to be superuser in order to do @command{make
+install} and @command{make info} on the standard directories.
+
+@node Configuration Options, Machine Options, ,Install
+@section Tuning the Functionality of YAP 
+@cindex syntax
+
+Compiling YAP with the standard options give you a plain vanilla
+Prolog. You can tune YAP to include extra functionality by calling
+@command{configure} with the appropriate options:
+
+@itemize @bullet
+ @item @command{--enable-rational-trees=yes} gives you support for infinite
+rational trees.
+
+ @item @command{--enable-coroutining=yes} gives you support for coroutining,
+including freezing of goals, attributed variables, and
+constraints. This will also enable support for infinite rational
+trees.
+
+ @item @command{--enable-depth-limit=yes} allows depth limited evaluation, say for
+implementing iterative deepening.
+
+ @item @command{--enable-low-level-tracer=yes} allows support for tracing all calls,
+retries, and backtracks in the system. This can help in debugging your
+application, but results in performance loss.
+
+ @item @command{--enable-wam-profile=yes} allows profiling of abstract machine
+instructions. This is useful when developing YAP, should not be so
+useful for normal users.
+
+ @item @command{--enable-condor=yes} allows using the Condor system that
+support High Throughput Computing (HTC) on large collections of
+distributively owned computing resources.
+
+ @item @command{--enable-tabling=yes} allows tabling support. This option
+is still experimental.
+
+ @item @command{--enable-parallelism=@{env-copy,sba,a-cow@}} allows
+or-parallelism supported by one of these three forms. This option is
+still highly experimental.
+
+ @item @command{--with-max-workers} allows definition of the maximum 
+number of parallel processes (its value can be consulted at runtime 
+using the flag @command{max_workers}).
+
+ @item @command{--with-gmp[=DIR]} give a path to where one can find the
+@code{GMP} library if not installed in the default path.
+
+ @item @command{--enable-threads} allows using of the multi-threading 
+predicates provided by YAP. Depending on the operating system, the 
+option @command{--enable-pthread-locking} may also need to be used.
+
+ @item @command{--with-max-threads} allows definition of the maximum 
+number of threads (the default value is 1024; its value can be consulted 
+at runtime using the flag @code{max_threads}).
+
+@end itemize
+
+Next section discusses machine dependent details.
+
+@node Machine Options, , Configuration Options,Install
+@section Tuning YAP for a Particular Machine and Compiler
+@cindex machine optimizations
+
+The default options should give you best performance under
+@command{GCC}. Although the system is tuned for this compiler
+we have been able to compile versions of YAP under lcc in Linux,
+Sun's cc compiler, IBM's xlc, SGI's cc, and Microsoft's Visual C++
+6.0.
+
+@menu
+* Tuning for GCC:: Using the GNUCC compiler
+* Compiling Under Visual C++:: Using Microsoft's Visual C++ environment
+* Tuning for SGI cc:: Compiling Under SGI's @command{cc}
+@end menu
+
+
+@node Tuning for GCC, Compiling Under Visual C++, , Machine Options
+@section Tuning YAP for @command{GCC}.
+
+YAP has been developed to take advantage of @command{GCC} (but not to
+depend on it). The major advantage of @command{GCC} is threaded code and
+explicit register reservation.
+
+YAP is set by default to compile with the best compilation flags we
+know. Even so, a few specific options reduce portability.  The option 
+@itemize @bullet
+ @item @command{--enable-max-performance=yes} will try to support the best
+available flags for a specific architectural model. Currently, the option
+assumes a recent version of @command{GCC}.
+ @item @command{--enable-debug-yap} compiles YAP so that it can be debugged
+by tools such as @command{dbx} or @command{gdb}.
+@end itemize
+
+Here follow a few hints:
+
+On x86 machines the flags:
+
+@example
+YAP_EXTRAS= ... -DBP_FREE=1
+@end example
+
+tells us to use the @code{%bp} register (frame-pointer) as the emulator's
+program counter. This seems to be stable and is now default.
+
+On  Sparc/Solaris2 use:
+
+@example
+YAP_EXTRAS= ...   -mno-app-regs -DOPTIMISE_ALL_REGS_FOR_SPARC=1
+@end example
+
+and YAP will get two extra registers! This trick does not work on
+SunOS 4 machines.
+
+Note that versions of GCC can be tweaked to recognize different
+processors within the same instruction set, e.g. 486, Pentium, and
+PentiumPro for the x86; or Ultrasparc, and Supersparc for
+Sparc. Unfortunately, some of these tweaks do may make YAP run slower or
+not at all in other machines with the same instruction set, so they
+cannot be made default.
+
+Last, the best options also depends on the version of GCC you are using, and
+it is a good idea to consult the GCC manual under the menus "Invoking
+GCC"/"Submodel Options". Specifically, you should check
+@command{-march=XXX} for recent versions of GCC/EGCS. In the case of
+@command{GCC2.7} and other recent versions of @command{GCC} you can check:
+
+@itemize @bullet
+
+@item 486:
+In order to take advantage of 486 specific optimizations in GCC 2.7.*:
+
+@example
+YAP_EXTRAS= ... -m486 -DBP_FREE=1
+@end example
+
+@item Pentium:
+@example
+YAP_EXTRAS= ... -m486 -malign-loops=2 -malign-jumps=2 \
+                      -malign-functions=2
+@end example
+
+@item PentiumPro and other recent Intel and AMD machines:
+PentiumPros are known not to require alignment. Check your version of
+@command{GCC} for the best @command{-march} option.
+
+@item Super and UltraSparcs:
+@example
+YAP_EXTRAS= ... -msupersparc
+@end example
+
+@item MIPS: if have a recent machine and you need a 64 bit wide address
+space you can use the abi 64 bits or eabi option, as in:
+@example
+CC="gcc -mabi=64" ./configure --...
+@end example
+Be careful. At least for some versions of @command{GCC}, compiling with
+@command{-g} seems to result in broken code.
+
+@item WIN32: GCC is distributed in the MINGW32 and CYGWIN packages.
+
+The Mingw32 environment is available from the URL:
+
+@url{http://www.mingw.org}
+
+You will need to install the @command{msys} and @command{mingw}
+packages. You should be able to do configure, make and make install.
+
+If you use mingw32 you may want to search the contributed packages for
+the @command{gmp} multi-precision arithmetic library. If you do setup YAP
+with @code{gmp} note that @file{libgmp.dll} must be in the path,
+otherwise YAP will not be able to execute.
+
+CygWin environment is available from the URL:
+
+@url{http://www.cygwin.com}
+
+@noindent
+and mirrors. We suggest using recent versions of the cygwin shell. The
+compilation steps under the cygwin shell are as follows:
+
+@example
+mkdir cyg
+$YAPSRC/configure --enable-coroutining \\
+                  --enable-depth-limit \\
+                  --enable-max-performance
+make
+make install
+@end example
+
+By default, YAP will use the @command{-mno-cygwin} option to
+disable the use of the cygwin dll and to enable the mingw32 subsystem
+instead. YAP thus will not need the cygwin dll. It instead accesses
+the system's @file{CRTDLL.DLL} @code{C} run time library supplied with
+Win32 platforms through the mingw32 interface. Note that some older
+WIN95 systems may not have @file{CRTDLL.DLL}, in this case it should
+be sufficient to import the file from a newer WIN95 or WIN98 machine.
+
+You should check the default installation path which is set to
+@file{/YAP} in the standard Makefile. This string will usually
+be expanded into @file{c:\YAP} by Windows.
+
+The cygwin environment does not provide @t{gmp} on the MINGW
+subsystem. You can fetch a dll for the @t{gmp} library from
+@url{http://www.sf.net/projects/mingwrep}.
+
+It is also possible to configure YAP to be a part of the cygwin
+environment. In this case you should use:
+@example
+mkdir cyg
+$YAPSRC/configure --enable-max-performance \\
+                  --enable-cygwin=yes
+make
+make install
+@end example
+YAP will then compile using the cygwin library and will be installed
+in cygwin's @file{/usr/local}. You can use YAP from a cygwin console,
+or as a standalone application as long as it can find
+@file{cygwin1.dll} in its path. Note that you may use to use
+@command{--enable-depth-limit} for Aleph compatibility, and that you may
+want to be sure that GMP is installed.
+
+@end itemize
+
+@node Compiling Under Visual C++, Tuning for SGI cc, Tuning for GCC, Machine Options
+@subsection  Compiling Under Visual C++
+
+YAP compiles cleanly under Microsoft's Visual C++ release 6.0. We next
+give a step-by-step tutorial on how to compile YAP manually using this
+environment.
+
+First, it is a good idea to build YAP as a DLL:
+
+@enumerate
+
+@item create a project named yapdll using File.New. The project will be a
+DLL project, initially empty.
+
+Notice that either the project is named yapdll or you must replace the
+preprocessors variable @var{$YAPDLL_EXPORTS} to match your project names
+in the files @file{YAPInterface.h} and @code{c_interface.c}.
+
+@item add all .c files in the @file{$YAPSRC/C} directory and in the
+@file{$YAPSRC\OPTYAP} directory to the Project's @code{Source Files} (use
+FileView).
+
+@item add all .h files in the @var{$YAPSRC/H} directory,
+@var{$YAPSRC\include} directory and in the @var{$YAPSRC\OPTYAP}
+subdirectory to the Project's @code{Header Files}.
+
+@item Ideally, you should now use @code{m4} to generate extra  .h from .m4 files and use
+@code{configure} to create a @code{config.h}. Or, you can be lazy, and
+fetch these files from @var{$YAPSRC\VC\include}.
+
+@item You may want to go to @code{Build.Set Active Configuration} and
+set @code{Project Type} to @code{Release}
+
+@item To use YAP's own include directories you have to set the Project
+option  @code{Project.Project Settings.C/C++.Preprocessor.Additional
+Include Directories} to include the directories @var{$YAPSRC\H},
+@var{$YAPSRC\VC\include}, @var{$YAPSRC\OPTYAP} and
+@var{$YAPSRC\include}.  The syntax is:
+
+@example
+$YAPSRC\H, $YAPSRC\VC\include, $YAPSRC\OPTYAP, $YAPSRC\include
+@end example
+
+@item  Build: the system should generate an @file{yapdll.dll} and an @file{yapdll.lib}.
+
+@item Copy the file @file{yapdll.dll} to your path. The file
+@file{yapdll.lib} should also be copied to a location where the linker can find it.
+@end enumerate
+
+Now you are ready to create a console interface for YAP:
+@enumerate
+@item create a second project  say @code{wyap} with @code{File.New}. The project will be a
+WIN32 console project, initially empty.
+
+@item add @var{$YAPSRC\console\yap.c} to the @code{Source Files}.
+
+@item add @var{$YAPSRC\VC\include\config.h} and the files in @var{$YAPSRC\include} to
+the @code{Header Files}.
+
+@item You may want to go to @code{Build.Set Active Configuration} and set
+@code{Project Type} to @code{Release}.
+
+@item you will eventually need to bootstrap the system by booting from
+@code{boot.yap}, so write:
+
+@example
+        -b $YAPSRC\pl\boot.yap
+@end example
+
+        in @code{Project.Project Settings.Debug.Program Arguments}.
+
+@item You need the sockets and yap libraries. Add
+
+@example
+ws2_32.lib yapdll.lib
+@end example
+
+to @code{Project.Project Settings.Link.Object/Library Modules}
+
+You may also need to set the @code{Link Path} so that VC++ will find @code{yapdll.lib}.
+
+@item set @code{Project.Project Settings.C/C++.Preprocessor.Additional Include Directories} to include the 
+@var{$YAPSRC/VC/include} and
+@var{$YAPSRC/include}.
+
+The syntax is:
+
+@example
+$YAPSRC\VC\include, $YAPSRC\include
+@end example
+
+@item Build the system.
+
+@item Use @code{Build.Start Debug} to boot the system, and then create the saved state with
+
+@example
+['$YAPSRC\\pl\\init'].
+qsave_program('startup.yss').
+^Z
+@end example
+
+That's it, you've got YAP and the saved state!
+@end enumerate
+
+The $YAPSRC\VC directory has the make files to build YAP4.3.17 under VC++ 6.0.
+
+@node Tuning for SGI cc, , Compiling Under Visual C++ ,Machine Options
+@subsection  Compiling Under SGI's cc
+
+YAP should compile under the Silicon Graphic's @code{cc} compiler,
+although we advise using the GNUCC compiler, if available.
+
+@table @code
+@item 64 bit
+Support for 64 bits should work by using (under Bourne shell syntax):
+@example
+CC="cc -64" $YAP_SRC_PATH/configure --...
+@end example
+@end table
+

docs/run.tex

@@ -0,0 +1,214 @@
+@c -*- mode: texinfo; coding: utf-8; -*-
+
+@node Run, Syntax, Install, Top
+@chapter Running YAP
+
+@menu
+* Running YAP Interactively:: Interacting with YAP
+* Running Prolog Files:: Running Prolog files as scripts
+@end menu
+
+@cindex booting
+We next describe how to invoke YAP in Unix systems.
+
+@node Running YAP Interactively, ,Running Prolog Files,Run
+@section Running YAP Interactively
+
+Most often you will want to use YAP in interactive mode. Assuming that
+YAP is in the user's search path, the top-level can be invoked under
+Unix with the following command:
+
+@example
+yap [-s n] [-h n] [-a n] [-c IP_HOST port ] [filename]
+@end example
+
+@noindent
+All the arguments and flags are optional and have the following meaning:
+@table @code
+@item -?
+print a short error message.
+@item -s@var{Size}
+allocate @var{Size} KBytes for local and global stacks. The user may
+ specify @t{M} bytes.
+@item -h@var{Size}
+allocate @var{Size} KBytes for heap and auxiliary stacks
+@item -t@var{Size}
+allocate @var{Size} KBytes for the trail stack
+@item -L@var{Size} 
+SWI-compatible option to allocate @var{Size} K bytes for local and global stacks, the local stack
+ cannot be expanded. To avoid confusion with the load option, @var{Size}
+ must immediately follow the letter @code{L}.
+@item -G@var{Size}
+SWI-compatible option to allocate @var{Size} K bytes for local and global stacks; the global
+stack cannot be expanded
+@item -T@var{Size}
+SWI-compatible option to allocate @var{Size} K bytes for the trail stack; the trail cannot be expanded.
+@item -l @var{YAP_FILE}
+compile the Prolog file @var{YAP_FILE} before entering the top-level.
+@item -L @var{YAP_FILE}
+compile the Prolog file @var{YAP_FILE} and then halt. This option is
+useful for implementing scripts.
+@item -g @var{Goal}
+run the goal @var{Goal} before top-level. The goal is converted from
+an atom to a Prolog term.
+@item -z @var{Goal}
+run the goal @var{Goal} as top-level. The goal is converted from
+an atom to a Prolog term.
+@item -b @var{BOOT_FILE}
+boot code is in Prolog file @var{BOOT_FILE}. The filename must define
+the predicate @code{'$live'/0}.
+@item -c @t{IP_HOST} @t{port}
+connect standard streams to host @t{IP_HOST} at port @t{port}
+@item filename
+restore state saved in the given file
+@item -f
+do not consult initial files
+@item -q
+do not print informational messages
+@item --
+separator for arguments to Prolog code. These arguments are visible
+through the @code{unix/1} built-in predicate.
+@end table
+
+Note that YAP will output an error message on the following conditions:
+
+@itemize @bullet
+@item
+a file name was given but the file does not exist or is not a saved
+YAP state;
+@item 
+the necessary amount of memory could not be allocated;
+@item
+the allocated memory is not enough to restore the state.
+@end itemize
+
+When restoring a saved state, YAP will allocate the
+same amount of memory as that in use when the state was saved, unless a
+different amount is specified by flags in the command line. By default,
+YAP restores the file @file{startup.yss} from the current directory or from
+the YAP library.
+@cindex environment variables
+
+@findex YAPBINDIR
+@itemize @bullet
+@item
+YAP usually boots from a saved state. The saved state will use the default
+installation directory to search for the YAP binary unless you define
+the environment variable YAPBINDIR.
+
+@findex YAPLIBDIR
+@item
+YAP always tries to find saved states from the current directory
+first. If it cannot it will use the environment variable YAPLIBDIR, if
+defined, or search the default library directory.
+
+@findex YAPSHAREDIR
+@item
+YAP will try to find library files from the YAPSHAREDIR/library
+directory.
+@end itemize
+
+@node Running Prolog Files, Running YAP Interactively, , Run
+@section Running Prolog Files
+
+YAP can also be used to run Prolog files as scripts, at least in
+Unix-like environments. A simple example is shown next (do not forget
+that the shell comments are very important):
+
+@example
+@cartouche
+#!/usr/local/bin/yap -L --
+#
+# Hello World script file using YAP
+#
+# put a dot because of syntax errors .
+
+:- write('Hello World'), nl.
+
+@end cartouche
+@end example
+
+The @code{#!}  characters specify that the script should call the binary
+file YAP. Notice that many systems will require the complete path to the
+YAP binary. The @code{-L} flag indicates that YAP should consult the
+current file when booting and then halt. The remaining arguments are
+then passed to YAP. Note that YAP will skip the first lines if they
+start with @code{#} (the comment sign for Unix's shell). YAP will
+consult the file and execute any commands.
+
+A slightly more sophisticated example is:
+
+@example
+@cartouche
+#!/usr/bin/yap -L --
+#
+# Hello World script file using YAP
+# .
+
+:- initialization(main).
+
+main :- write('Hello World'), nl.
+
+@end cartouche
+@end example
+
+The @code{initialization} directive tells YAP to execute the goal main
+after consulting the file. Source code is thus compiled and @code{main}
+executed at the end. The @code{.} is useful while debugging the script
+as a Prolog program: it guarantees that the syntax error will not
+propagate to the Prolog code.
+
+Notice that the @code{--} is required so that the shell passes the extra
+arguments to YAP.  As an example, consider the following script
+@code{dump_args}:
+
+@example
+@cartouche
+#!/usr/bin/yap -L --
+#.
+
+main( [] ).
+main( [H|T] ) :-
+        write( H ), nl,
+        main( T ).
+
+:- unix( argv(AllArgs) ), main( AllArgs ).
+
+@end cartouche
+@end example
+
+If you this run this script with the arguments:
+@example
+./dump_args -s 10000
+@end example
+@noindent
+the script will start an YAP process with stack size @code{10MB}, and
+the list of arguments to the process will be empty.
+
+Often one wants to run the script as any other program, and for this it
+is convenient to ignore arguments to YAP. This is possible by using
+@code{L --} as in the next version of @code{dump_args}:
+
+@example
+@cartouche
+#!/usr/bin/yap -L --
+
+main( [] ).
+main( [H|T] ) :-
+        write( H ), nl,
+        main( T ).
+
+:- unix( argv(AllArgs) ), main( AllArgs ).
+
+@end cartouche
+@end example
+
+The @code{--} indicates the next arguments are not for YAP. Instead,
+they must be sent directly to the @code{argv} built-in. Hence, running
+@example
+./dump_args test
+@end example
+@noindent
+will write @code{test} on the standard output.
+
+

docs/swi.tex

@@ -310,7 +310,7 @@ enumeration is undefined.
 Delete the named global variable.
 @end table
 
-@section Compatibility of Global Variables
+@subsubsection Compatibility of Global Variables
 
 Global variables have been introduced by various Prolog
 implementations recently.  YAP follows their implementation in SWI-Prolog, itself

docs/yap.bib

@@ -0,0 +1,13 @@
+@book{TheArtOfProlog,
+     Author = "Sterling, Leon and Shapiro, Ehud",
+     Title = "The Art of Prolog",
+     Publisher = "MIT Press",
+     Year = "1986"	}
+
+@Book{ProgrammingInProlog,
+	Author       ="William F. Clocksin and Christopher S. Mellish",
+	Title        ={Programming in Prolog},
+	Publisher    ={Springer-Verlag},
+	Year         =1986
+}
+