address the comments

- moved the Reference Manual section "The GASMAN Interface for Weak Pointer
  Objects" to the dev manual

- changed formulation "GASMAN is running" to "GAP uses GASMAN" in several places

- added a new documented function `CollectGarbage`,
  call this function instead of `GASMAN` in manual examples

- removed the link to `https://www.gap-system.org/Download/INSTALL`
  in the Reference Manual, since this file may not fit to the version of GAP

- added an error message if the `-L` command line option is given but the
  garbage collector is different from `GASMAN`
  (I did not find a good place for this check in the GAP kernel,
  because of the preprocessor flags.)

doc/dev/kernel.xml

@@ -368,6 +368,29 @@ which does exactly this.
 
 </Subsection>
 
+<Subsection Label="The GASMAN Interface for Weak Pointer Objects">
+<Heading>The GASMAN Interface for Weak Pointer Objects</Heading>
+
+The key support for weak pointers is in the files <F>src/gasman.c</F> and
+<F>src/gasman.h</F>.
+This document assumes familiarity with the rest of the operation of GASMAN.
+A kernel type (tnum) of bags which are intended to act as weak pointers to
+their subobjects must meet three conditions.
+Firstly, the marking function installed for that tnum must use
+<C>MarkBagWeakly</C> for those subbags, rather than <C>MarkBag</C>.
+Secondly, before any access to such a subbag, it must be checked with
+<C>IsWeakDeadBag</C>.
+If that returns <K>true</K>, then the subbag has evaporated in a recent garbage
+collection and must not be accessed.
+Typically the reference to it should be removed.
+Thirdly, a <E>sweeping function</E> must be installed for that tnum
+which copies the bag, removing all references to dead weakly held subbags.
+<P/>
+The files <F>src/weakptr.c</F> and <F>src/weakptr.h</F> use this interface
+to support weak pointer objects.
+Other objects with weak behaviour could be implemented in a similar way.
+
+</Subsection>
 
 </Section>
 

doc/ref/debug.xml

@@ -1048,7 +1048,7 @@ variable <C>GAPInfo.KernelInfo.GC</C>.)
 
 <P/>
 
-If <C>GASMAN</C> is running then messages reporting garbage
+If &GAP; uses <C>GASMAN</C> then messages reporting garbage
 collections performed by <C>GASMAN</C> can be switched on
 by the <C>-g</C> command
 line option (see section <Ref Sect="Command Line Options"/>).
@@ -1058,6 +1058,7 @@ see below.
 
 </Subsection>
 
+<#Include Label="CollectGarbage">
 <#Include Label="GasmanStatistics">
 <#Include Label="GasmanMessageStatus">
 <#Include Label="GasmanLimits">

doc/ref/run.xml

@@ -54,8 +54,7 @@ and to <C>gap -b -q -b -q</C> etc.
 &GAP; for UNIX will distinguish between upper and lower case options.
 <P/>
 As described in the &GAP; installation instructions (see the 
-<F>INSTALL.md</F> file in the &GAP; root directory, or at
-<URL>https://www.gap-system.org/Download/INSTALL</URL>),
+<F>INSTALL.md</F> file in the &GAP; root directory),
 usually you will not execute &GAP; directly. Instead  you  will
 call a (shell) script, with the name <C>gap</C>, which in turn executes  &GAP;.
 This  script sets some options which are necessary  to  make  &GAP;

doc/ref/weakptr.xml

@@ -67,11 +67,11 @@ are not referenced by other objects than <C>w</C>,
 and that therefore these entries may disappear.
 <P/>
 <Log><![CDATA[
-gap> GASMAN("collect");
+gap> CollectGarbage( true );
 
 ... (perhaps more computations and garbage collections) ...
 
-gap> GASMAN("collect");
+gap> CollectGarbage( true );
 gap> w;
 WeakPointerObj( [ 1, , , fail ] )
 ]]></Log>
@@ -94,7 +94,7 @@ gap> l := [1,2,3];;
 gap> w[1] := l;;
 gap> w;
 WeakPointerObj( [ [ 1, 2, 3 ], , , fail ] )
-gap> GASMAN("collect");
+gap> CollectGarbage( true );
 gap> w;                
 WeakPointerObj( [ [ 1, 2, 3 ], , , fail ] )
 ]]></Example>
@@ -166,7 +166,7 @@ fail
 Now after some computations and garbage collections <M>\ldots</M>
 <P/>
 <Example><![CDATA[
-gap> 2;;3;;4;;GASMAN("collect"); # clear last, last2, last3
+gap> 2;; 3;; 4;; CollectGarbage( true );  # clear last, last2, last3
 ]]></Example>
 <P/>
 <M>\ldots</M> we get the following.
@@ -226,32 +226,6 @@ produces an immutable plain
 list containing immutable copies of the objects contained in the weak pointer
 object. An immutable weak pointer object is a contradiction in terms.
 
-</Section>
-
-
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
-<Section Label="The GASMAN Interface for Weak Pointer Objects">
-<Heading>The GASMAN Interface for Weak Pointer Objects</Heading>
-
-The key support for weak pointers is in the files <F>src/gasman.c</F> and
-<F>src/gasman.h</F>.
-This document assumes familiarity with the rest of the operation of GASMAN.
-A kernel type (tnum) of bags which are intended to act as weak pointers to
-their subobjects must meet three conditions.
-Firstly, the marking function installed for that tnum must use
-<C>MarkBagWeakly</C> for those subbags, rather than <C>MarkBag</C>.
-Secondly, before any access to such a subbag, it must be checked with
-<C>IsWeakDeadBag</C>.
-If that returns <K>true</K>, then the subbag has evaporated in a recent garbage
-collection and must not be accessed.
-Typically the reference to it should be removed.
-Thirdly, a <E>sweeping function</E> must be installed for that tnum
-which copies the bag, removing all references to dead weakly held subbags.
-<P/>
-The files <F>src/weakptr.c</F> and <F>src/weakptr.h</F> use this interface
-to support weak pointer objects.
-Other objects with weak behaviour could be implemented in a similar way.
-
 </Section>
 </Chapter>
 

lib/gasman.gd

@@ -12,6 +12,44 @@
 ##  the GASMAN garbage collector.
 ##
 
+
+#############################################################################
+##
+#F  CollectGarbage( <full> )
+##
+##  <#GAPDoc Label="CollectGarbage">
+##  <ManSection>
+##  <Func Name="CollectGarbage" Arg='full'/>
+##
+##  <Returns>
+##  nothing.
+##  </Returns>
+##  <Description>
+##  This function forces a garbage collection.
+##  If <A>full</A> is <K>true</K> then it triggers a full garbage collection,
+##  otherwise a partial one.
+##  <P/>
+##  &GAP; invokes its garbage collector automatically, thus there is normally
+##  no need to call <Ref Func="CollectGarbage"/>.
+##  <P/>
+##  The function <Ref Func="CollectGarbage"/> was introduced in
+##  &GAP;&nbsp;4.12.
+##  In older &GAP; versions,
+##  one can use <C>GASMAN( "collect" )</C> (if <A>full</A> is <K>true</K>)
+##  or <C>GASMAN( "partial" )</C> (if <A>full</A> is not <K>true</K>)
+##  instead.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> CollectGarbage( false );
+##  gap> CollectGarbage( true );
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction("CollectGarbage");
+
+
 #############################################################################
 ##
 #F  GasmanStatistics( )

lib/gasman.gi

@@ -11,6 +11,22 @@
 ##  This file contains implementations of functions that report information from the
 ##  GASMAN garbage collector
 ##
+
+
+#############################################################################
+##
+#F  CollectGarbage( <full> )
+##
+##  This function works *not* only if GAP uses GASMAN.
+##
+InstallGlobalFunction( CollectGarbage, function( full )
+    if full then
+      GASMAN( "collect" );
+    else
+      GASMAN( "partial" );
+    fi;
+end );
+
 #############################################################################
 ##
 #F  GasmanStatistics( )

lib/init.g

@@ -352,6 +352,16 @@ if IsHPCGAP then
   ENABLE_AUTO_RETYPING();
 fi;
 
+
+#############################################################################
+##
+##  The command line option '-L' is supported only if GASMAN is used.
+##
+if "-L" in GAPInfo.SystemCommandLine and GAPInfo.KernelInfo.GC <> "GASMAN" then
+  Error( "workspaces (-L option) are supported only if GASMAN is used" );
+fi;
+
+
 # try to find terminal encoding
 CallAndInstallPostRestore( function()
   local env, pos, enc, a, PositionSublist;

lib/system.g

@@ -66,14 +66,14 @@ BIND_GLOBAL( "GAPInfo", rec(
       rec( short:= "y", long := "lines", default := "", arg := "<num>", help := ["set number of lines"] ),
       ,
       rec( short:= "g", long := "gasinfo", default := 0,
-           help := ["show GASMAN messages (full/all/no garbage","collections)", "(available only if GASMAN is running)"] ),
+           help := ["show GASMAN messages (full/all/no garbage","collections)", "(only available if GAP uses GASMAN)"] ),
       rec( short:= "m", long := "minworkspace", default := "128m", arg := "<mem>",
            help := ["set the initial workspace size"] ),
       rec( short:= "o", long := "maxworkspace", default := "2g", arg := "<mem>",
-           help := [ "set workspace size where GAP will warn about", "excessive memory usage (GAP may allocate more)", "(available only if GASMAN is running)"] ),
+           help := [ "set workspace size where GAP will warn about", "excessive memory usage (GAP may allocate more)", "(available only if GAP uses GASMAN)"] ),
       rec( short:= "K", long := "limitworkspace", default := "0", arg := "<mem>",
            help := [ "set maximal workspace size (GAP never", "allocates more)"] ),
-      rec( short:= "s", default := "4g", arg := "<mem>", help := [ "set the initially mapped virtual memory", "(available only if GASMAN is running)" ] ),
+      rec( short:= "s", default := "4g", arg := "<mem>", help := [ "set the initially mapped virtual memory", "(available only if GAP uses GASMAN)" ] ),
       rec( short:= "a", default := "0",  arg := "<mem>",help := [ "set amount to pre-malloc-ate",
              "postfix 'k' = *1024, 'm' = *1024*1024,", "'g' = *1024*1024*1024"] ),
       ,
@@ -93,7 +93,7 @@ BIND_GLOBAL( "GAPInfo", rec(
       rec( long := "alwaystrace", default := false, help := ["always print error traceback", "(overrides behaviour of -T)"] ),
       rec( long := "quitonbreak", default := false, help := ["quit GAP with non-zero return value instead", "of entering break loop"]),
       ,
-      rec( short:= "L", default := "", arg := "<file>", help := [ "restore a saved workspace", "(available only if GASMAN is running)"] ),
+      rec( short:= "L", default := "", arg := "<file>", help := [ "restore a saved workspace", "(available only if GAP uses GASMAN)"] ),
       rec( short:= "R", default := false, help := ["prevent restoring of workspace (ignoring -L)"] ),
       ,
       rec( short:= "p", default := false, help := ["enable/disable package output mode"] ),
@@ -390,7 +390,7 @@ CallAndInstallPostRestore( function()
     # use the same as the kernel
     CommandLineOptions.E:= GAPInfo.KernelInfo.HAVE_LIBREADLINE;
 
-    # -L is valid only if GASMAN is running.
+    # -L is valid only if GAP uses GASMAN.
     if GAPInfo.KernelInfo.GC <> "GASMAN" then
       CommandLineOptions.L:= "";
     fi;

lib/wpobj.gd

@@ -17,7 +17,7 @@
 ##  gap> w := WeakPointerObj([[1,2]]);;
 ##  gap> IsBound(w[1]);
 ##  true
-##  gap> GASMAN("collect");
+##  gap> CollectGarbage( true );
 ##  gap> w;
 ##  WeakPointerObj([ [ ] ]);
 ##