source: git/doc/INSTALL_win.plural.texi @ 7e96fe

@comment -*-texinfo-*-
@comment $Id: INSTALL_win.plural.texi,v 1.3 2009-04-08 12:44:41 seelisch Exp $
@c FILE: INSTALL_unix.texi
@c PURPOSE: Installation instruction for Singular on Unix
@c

@ifclear VERSION
@include version.texi
@end ifclear

@ifclear singularmanual
@majorheading Windows installation instructions for @sc{Singular::Plural} version @value{VERSION}
@end ifclear

@ifclear UNAME
@set _UNAME ix86-Win
@end ifclear

@ifset UNAME
@include uname.texi
@end ifset

To install @sc{Singular::Plural} on a Windows
platform, you need the following two archives:
@table @code
@item SingularPlural-@value{VERSION}-share.tar.gz
contains architecture independent data like documentation and libraries.
@item SingularPlural-@value{VERSION}-@value{_UNAME}.tar.gz
contains architecture dependent executables, like the @sc{Plural}
program.
@end table

You can obtain these (and other) archives from
@display
@uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/non-commutative/Plural/}.
@end display

@include register.texi

@heading To install SINGULAR::PLURAL

Make sure that you have approximately 12MByte of free disk space and follow
these steps.
@enumerate
@item
Simply change to the directory in which you wish to install
@sc{Singular::Plural}, for example, @code{C:\}.

@sc{Singular::Plural} specific subdirectories will be created in such a way
that multiple versions and multiple architecture dependent files
of @sc{Singular} and @sc{Singular::Plural} can peaceably coexist under the same 
tree.

@item
Unpack the archives either with your own program or with @code{gzip}
and @code{tar}:
@smallexample
gzip -dc <path_to>/SingularPlural-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf -
gzip -dc <path_to>/SingularPlural-@value{VERSION}-share.tar.gz | tar -pxf -
@end smallexample

This creates the directory @code{Plural/@value{VERSION}} with
@multitable @columnfractions .36 .64
@item (sub)directories
@tab which contain
@item @code{@value{_UNAME}}
@tab @code{Plural} and @code{EPlural} executables
@item @code{LIB}
@tab @sc{Singular} and @sc{Singular::Plural} libraries (@code{*.lib} files)
@item @code{emacs}
@tab files for the @sc{Plural} Emacs user interface
@item @code{info}
@tab info files of @sc{Plural} manual (Warning: plural.hlp is not a help file for Windows help but for @code{info} program!)
@item @code{html}
@tab html files of @sc{Plural} manual
@item @code{doc}
@tab miscellaneous documentation files
@c @item @code{examples}
@c @tab @sc{Singular} examples (@code{*.sing} files)
@end multitable

For the executable to work, the directory layout must look pretty much
like this; the executable will look for "sibling" directories at run-time
to figure out where its @sc{Singular::Plural} libraries and on-line
documentation files are. These constraints on the local directory layout
are necessary to avoid having to hard-code pathnames into the
executables, or require that environment variables be set before
running the executable. In particular, you @strong{must not move or copy}
the @sc{Plural} executables to another place, but use soft-links
instead.
@end enumerate

The following steps are optional:

@itemize @bullet
@item
Create a shortcut for @code{Plural}.

Start a new shortcut wizard and pick
@code{C:/Plural/@value{VERSION}/ix86-Win/Plural.exe} as the executable
and type, for example, @code{C:/Plural/@value{VERSION}/ix86-Win/} in the field "Execute in".

@item
Arrange that typing @code{Plural} at the command prompt starts up the
installed @sc{Plural} executable.

Just append the directory @code{Plural/@value{VERSION}/ix86-Win} to your @code{PATH} environment variable.

@strong{IMPORTANT:} Do @emph{never} move or copy the file
@code{Plural/@value{VERSION}/@value{_UNAME}/Plural} to another
place, but use shortcuts or soft-links instead.

@item
If you wish to use any of the following features of
@sc{Plural}, make sure that the respective programs are installed on your system:

@multitable @columnfractions .5 .5
@item @strong{Feature} @tab @strong{Requires}
@item running @code{EPlural}, or @code{Plural} within Emacs
@tab @uref{http://www.fsf.org/software/emacs/emacs.html,,Emacs} version
20 or higher, or, @uref{http://www.xemacs.org,,XEmacs} version 20.3 or
higher 
@item on-line @code{html} help
@tab @uref{http://www.netscape.com,,netscape} browser
@item on-line @code{info} help
@tab @uref{http://www.texinfo.org,,info}, or
@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/,,tkinfo} texinfo browser programs
@c @item TAB completion and history mechanism of ASCII-terminal interface
@c @tab shared @uref{ftp://ftp.de.uu.net/pub/gnu/readline/,,readline}
@c library, i.e. @code{/usr/lib/libreadline.so}
@c @item visualization of curves and surfaces
@c @tab
@c @uref{http://www.mathematik.uni-mainz.de/AlgebraischeGeometrie/surf/surf.shtml,,surf}
@c version 0.9 or higher (only available for Linux and Solaris).
@end multitable

@c You may download most of these programs from
@c @display
@c @uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils/}.
@c @end display

@item Customize the on-line help system:

By default, on-line help is displayed in @code{html} format using
the default Web browser on your system.

However, this behavior can be customized in several ways
using the @sc{Plural} commands @code{system("--browser",<browser>)}
and @code{system("--allow-net", 1)} (or, by starting up @sc{Plural}
with the respective command line options).

@end itemize

@c In particular, creating the file
@c @code{Plural/@value{VERSION}/LIB/.singularrc} and putting the
@c @sc{Plural} command
@c @smallexample
@c system("--allow-net", 1);
@c @end smallexample
@c in it, allows the on-line help system to fetch its @code{html} pages
@c from @uref{http://www.singular.uni-kl.de, Singular's WWW
@c home site}
@c in case its local html pages are not found. That is, you may delete your
@c local html pages, after setting this option.

See also
@ifset singularmanual
@ref{The online help system}, @ref{Command line options}, and
@ref{Startup sequence},
@end ifset
@ifclear singularmanual
the sections @emph{The online help system}, @emph{Command line options}, and
@emph{Startup sequence} in the @sc{Singular} manual
@end ifclear
for more details on customizing the on-line help system.

@heading Troubleshooting

@itemize @bullet
@item General: @sc{Plural} can not find its libraries or on-line help
@enumerate
@item
Make sure that you have read and/or execute permission on the files and
directories of the Plural distribution. 
@item
Start up @sc{Plural}, and issue the command @code{system("Singular");}.
If this does not return the correct and expanded location of the
@sc{Plural} executable, then you found a bug in @sc{Plural}, which we
ask you to report (see below).
@item
Check whether the directories containing the libraries and on-line help
files can be found by @sc{Plural}: If @code{$bindir} denotes the
directory where the @sc{Plural} executable resides, then @sc{Plural}
looks for library files as follows:
@* (0) the current directory
@* (1) all dirs of the environment variable SINGULARPATH
@* (2) @code{$bindir/LIB}
@* (3) @code{$bindir/../LIB}
@* (4) @code{/usr/local/Plural/@value{VERSION}/LIB}
@* (4) @code{/usr/local/Plural/LIB}
@* The on-line @code{info} files need to be at  @code{$bindir/../info} and the
@code{html} pages at @code{$bindir/../html}.
@end enumerate

You can inspect the found library and @code{info}/@code{html}
directories by starting up @sc{Plural} with the
@code{--version} option, or by issuing the @sc{Plural} command
@code{system("--version");}.

@item For any other troubles:
@*Please send an email to @email{singular@@mathematik.uni-kl.de}
and include the header which is displayed by starting up @sc{Plural}
with the @code{-v} option, and a description of your machine (issue the
command @code{uname -a} on your shell) in your report.
@end itemize

@include info.texi

@ifclear singularmanual
GOOD LUCK and ENJOY!
Your @sc{Singular::Plural} team.
@end ifclear