Improve the documentation concerning GASMAN, add CollectGarbage

[ThomasBreuer]

GAP can use several garbage collectors (GASMAN, the Julia garbage collector, and the Boehm garbage collector).
Up to now, the GAP documentation mentions only GASMAN.
Several GAP functions make sense only if GASMAN is running, and several command line options make sense only in this case.

The proposed changes try to adjust the documentation to situations where GASMAN is not used.
(More changes in this direction will be needed, below is a list of open questions.)

Details of the changes:

• In debug.xml, section "Global Memory Information",
  moved the introductory part to a new subsection "Garbage Collection"
  that can be cross-referenced from places where garbage collection
  is mentioned;
  mention in this subsection that several garbage collectors
  can be used by GAP.

• In the functions GasmanStatistics, GasmanMessageStatus,
  GasmanLimits, mention that they work only if GASMAN is running.

• In run.xml, section "Saving and Loading a Workspace",
  mention that workspaces can be saved/loaded only if GASMAN is running.

• Added a cross-reference from SaveOnExitFile to SaveWorkspace.

• Changed the description of GAP's command line options:

  • In run.xml, mention that the options -g, -L, -o, -s
    are available only if GASMAN is used.
  • Do the same in system.g, variable GAPInfo.CommandLineOptionData.
    (I had thought about omitting the not supported options from the
    list, but such a filtered list might confuse users who want to
    understand why their options did not work as expected.)

• Call GASMAN( "message" ) in SetGasmanMessageStatus
  only if GASMAN is running, in order to avoid an error message.

• In chapter "Weak Pointers", removed the word GASMAN in the introduction
  and added a reference to "Garbage Collection".
  (Weak pointer objects work also with other garbage collectors than
  GASMAN.)

Open questions:

• The command line options -K and -m are evaluated also when the
  Julia GC is running, but are their values really used?

• The introduction of the section "Command Line Options" refers to a file
  https://www.gap-system.org/Download/INSTALL which exists but seems to
  be outdated --which URL should be given here?
  (The corresponding file in the GAP distribution is INSTALL.md.)

• If GASMAN is not running, a file given with the -L command line option
  is currently ignored, because LoadWorkspace is not called when
  GAP_ENABLE_SAVELOAD is not defined.
  Should we better show an error message telling that no workspace
  could be loaded?
  (In earlier versions, there was such a message.)

• The function GASMAN is undocumented.
  (The Development manual contains a section "Garbage collection in GAP",
  where GASMAN is said to be "the GAP memory manager".
  This seems to be the right place to add documentation for alternative
  garbage collectors.
  On the other hand, this manual is not part of the GAP distribution.)

  Calling GASMAN( "collect" ) and GASMAN( "partial" ) work also
  with the Julia GC; if this is intentional then we should choose
  a better name for the function.
  (GASMAN( "message" ) works only with the GASMAN GC.)

  The function GASMAN is shown in manual examples about weak pointer
  objects. Thus a function for forcing a garbage collection should be
  documented.

• The section "The GASMAN Interface for Weak Pointer Objects"
  in chapter "Weak Pointers" looks GASMAN specific (not only the title).
  How to reformulate it?

[fingolfin]

Thanks, that's a great improvement! A few minor remarks

[fingolfin]

• The command line options -K and -m are evaluated also when the
  Julia GC is running, but are their values really used?

These set the C kernel variables SyStorKill resp. SyStorMin. The former is honored by GASMAN and Boehm GC, but not but by Julia GC. The latter is only honored by GASMAN.

The main reason I didn't limit them further in the GAP kernel is that their values are returned by GASMAN_LIMITS, which in turn is used by GasmanLimits. Perhaps they should simply be changed to return infinity when not used. Then we could disable them also in Julia GC resp. Boehm GC, on the kernel level...

• The introduction of the section "Command Line Options" refers to a file
  https://www.gap-system.org/Download/INSTALL which exists but seems to
  be outdated --which URL should be given here?
  (The corresponding file in the GAP distribution is INSTALL.md.)

I left an inline comment on this.

• If GASMAN is not running, a file given with the -L command line option
  is currently ignored, because LoadWorkspace is not called when
  GAP_ENABLE_SAVELOAD is not defined.
  Should we better show an error message telling that no workspace
  could be loaded?
  (In earlier versions, there was such a message.)

Agreed, showing an error message would be better.

• The function GASMAN is undocumented.
  (The Development manual contains a section "Garbage collection in GAP",
  where GASMAN is said to be "the GAP memory manager".
  This seems to be the right place to add documentation for alternative
  garbage collectors.
  On the other hand, this manual is not part of the GAP distribution.)
  Calling GASMAN( "collect" ) and GASMAN( "partial" ) work also
  with the Julia GC; if this is intentional then we should choose
  a better name for the function.
  (GASMAN( "message" ) works only with the GASMAN GC.)
  The function GASMAN is shown in manual examples about weak pointer
  objects. Thus a function for forcing a garbage collection should be
  documented.

Indeed, there should be a function for garbage collection, with a neutral name, say CollectGarbage() which takes a boolean as argument. However, we should make it clear that in normal situation, there should be no need to invoke it.

Also, we still might want to mention something like "in older GAP versions, one can use GASMA("collect") for this"; or even something like:

The function CollectGarbage was introduced in GAP 4.12. If your code needs to be compatible with older GAP versions as well, you can use helper code like this:

if not CompareVersionNumbers( GAPInfo.Version, "4.12" ) then
  CollectGarbage := function(full)
   if full then
     GASMAN( "collect" );
   else
     GASMAN( "partial" );
   fi;
  end;

• The section "The GASMAN Interface for Weak Pointer Objects"
  in chapter "Weak Pointers" looks GASMAN specific (not only the title).
  How to reformulate it?

That section IMHO simply does not belong into the reference manual, it should be in the dev manual instead.

[fingolfin]

Looks good to me, but I'd appreciate if @ChrisJefferson could also have at least a quick peek at this.