<!-- 
  HAPPRIME - intro.xml
  Introduction documentation section 
  Paul Smith
  
  Copyright (C)  2007-2008
  Paul Smith
  National University of Ireland Galway
     
  This file is part of HAPprime. 

  HAPprime is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  HAPprime is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.

  $Id: intro.xml 224 2008-03-04 12:09:42Z pas $
-->
  
<!-- ********************************************************** -->
<Chapter> 
  <Heading>Introduction</Heading>
  <Section>
    <Heading>Introduction to the &HAPprime; package</Heading>

    &HAPprime; is a package for the &GAP; computer algebra system 
    (<URL>http://www.gap-system.org/</URL>), and which 
    extends the &HAP; `Homological Algebra Progamming' package 
    written by Graham Ellis (<URL>http://hamilton.nuigalway.ie/Hap/www/</URL>). 
    It provides algorithms and data structures for calculating resolutions of 
    small prime-power groups. The &HAPprime; functions use significantly less 
    memory than the equivalent function in &HAP;, allowing resolutions 
    (and cohomology ring presentations) of larger groups to be calculated 
    (see Section <Ref Sect="ExResolution"/>).
    <P/>
    Earlier versions of &HAPprime; also included functions to compute 
    polynomial ring presentations of cohomology rings, and to ensure that these
    rings are complete and correct. These functions have now been moved into
    the &HAP; package and are documented as part of that package (see for 
    example <Ref Func="Mod2CohomologyRingPresentation" BookName="HAP"/> and
    <Ref Func="PoincareSeriesLHS" BookName="HAP"/>).
  </Section>

  <Section>
    <Heading>Required software</Heading>

    The &HAPprime; package requires &GAP; version 4.4 or greater and &HAP; 
    version 1.9.3 or greater.
  </Section>
  
  <Section>
    <Heading>Installing &HAPprime;</Heading>

    To install the &HAPprime; Package, unpack the archive file
    into your &GAP; packages directory (either usually the <F>pkg</F> directory
    of your &GAP; 4 installation if you have access to it, or some local 
    <F>pkg</F> directory that &GAP; can find). The &HAPprime; files
    will all be installed in a subdirectory called 
    <F>happrime</F>.
  </Section>
  
  <Section Label="LoadingAndTesting">
    <Heading>Loading and testing &HAPprime;</Heading>

    The &HAPprime; package is not loaded by default when &GAP; is started. To
    load the package, type the following at the &GAP; prompt:
<Log>
gap> LoadPackage( "HAPprime");
</Log>
    
    If &HAPprime; isn't already in memory, it is 
    loaded and the author information is displayed.
    If you are a frequent user of &HAPprime;,
    you might consider putting this line in your <F>.gaprc</F> file, or
    using the <C>PackagesToLoad</C> option in your <F>gap.ini</F> file.
    <P/>
    The correct installation of &HAPprime; can be tested by using the test 
    routine <F>tst/testall.g</F>:
<Log>
gap> ReadPackage("HAPprime", "tst/testall.g");
+ HAPprime version <#Include SYSTEM "../../VERSION"> general tests
+ GAP4stones: 371057
+ HAPprime version <#Include SYSTEM "../../VERSION"> userguide examples
+ GAP4stones: 387662
+ HAPprime version <#Include SYSTEM "../../VERSION"> datatypes reference manual examples
+ GAP4stones: 382653
true
</Log>
    The number of <C>GAP4stones</C> will vary depending on your machine, but
    any additional lines of messages indicate problems with your installation.
    <P/>
    The test routine calls a set of test files 
    <Ref Sect="Test Files" BookName="ref"/> which can be found in the 
    <F>tst</F> directory of the &HAPprime; installation. All of the routines 
    listed in this user guide are tested, as are many of those in the datatype
    reference manual.
  </Section>
  
  <Section>
    <Heading>Documentation</Heading>

    The documentation for &HAPprime; is in two parts. This document is the
    user guide, which covers the main functions provided by &HAPprime; and
    examples of their use. There is also a more technical &HAPprime; datatypes 
    reference manual which gives details of the new &GAP; datatypes
    defined and used internally by &HAPprime;, as well as outlining the 
    algorithms used by the package.
    
    <#Include Label="MakeHAPprimeDoc_manMisc">
  </Section>
  
  <Section>
    <Heading>Displaying progress and calculation information</Heading>

    By default, the functions in &HAPprime; display no output (except for 
    returning the result). The <C>InfoHAPprime</C> info class can be used to 
    enable the printing of progress and calculation information during 
    processing. Since some computations with &HAPprime; can take several hours,
    setting this to a higher level can be particularly useful for monitoring 
    the progress of computations.
    
    <#Include Label="InfoHAPprime_manMisc">
  </Section>
  
  
  
</Chapter>
  
