  
  [1X1 [33X[0;0YIntroduction[133X[101X
  
  [33X[0;0YThe  [5XUtils[105X  package provides a space for utility functions from a variety of
  [5XGAP[105X  packages to be collected together into a single package. In this way it
  is  hoped  that they will become more visible to other package authors. This
  package was first distributed as part of the [5XGAP[105X 4.8.2 distribution.[133X
  
  [33X[0;0YThe package is loaded with the command[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XLoadPackage( "utils" );[127X[104X
    [4X[28Xtrue[128X[104X
  [4X[32X[104X
  
  [33X[0;0YFunctions have been transferred from the following packages:[133X
  
  [30X    [33X[0;6YConversion of a [5XGAP[105X group to a [22XMagma[122X output string, taken from various
        sources including [11Xother.gi[111X in the main library.[133X
  
  [33X[0;0YTransfer is complete (for now) for functions from the following packages:[133X
  
  [30X    [33X[0;6Y[5XAutoDoc[105X [GH16] (with function names changed);[133X
  
  [30X    [33X[0;6Y[5XResClasses[105X [Koh17b];[133X
  
  [30X    [33X[0;6Y[5XRCWA[105X [Koh17a];[133X
  
  [30X    [33X[0;6Y[5XXMod[105X [WAOU17].[133X
  
  [33X[0;0YThe  package  may  be obtained either as a compressed [10X.tar[110X file or as a [10X.zip[110X
  file, [11Xutils-version_number.tar.gz[111X, by ftp from one of the following sites:[133X
  
  [30X    [33X[0;6Ythe [5XUtils[105X GitHub release site: [7Xhttps://gap-packages.github.io/utils/[107X.[133X
  
  [30X    [33X[0;6Yany                  [5XGAP[105X                 archive,                 e.g.
        [7Xhttps://www.gap-system.org/Packages/packages.html[107X;[133X
  
  [33X[0;0YThe      package      also      has      a     GitHub     repository     at:
  [7Xhttps://github.com/gap-packages/utils[107X.[133X
  
  [33X[0;0YOnce  the  package  is loaded, the manual [10Xdoc/manual.pdf[110X can be found in the
  documentation  folder.  The  [10Xhtml[110X  versions, with or without [22XMathJax[122X, may be
  rebuilt as follows:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XReadPackage( "utils", "makedoc.g" ); [127X[104X
  [4X[32X[104X
  
  [33X[0;0YThis  package  now  uses  the [5XAutoDoc[105X package to extract test files from the
  examples  in  the  manual. Many of the original test files, which duplicated
  these examples, have now been deleted. The user can ensure that the full set
  of  test files exists on their system by rebuilding the manual, as described
  above.[133X
  
  [33X[0;0YIt  is  then possible to check that the package has been installed correctly
  by running the test suite (this terminates the [5XGAP[105X session):[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XReadPackage( "utils", "tst/testall.g" );[127X[104X
    [4X[28XArchitecture: . . . . . [128X[104X
    [4X[28Xtesting: . . . . . [128X[104X
    [4X[28X. . . [128X[104X
    [4X[28X#I  No errors detected while testing[128X[104X
  [4X[32X[104X
  
  [33X[0;0YNote  that functions listed in this manual that are currently in the process
  of  being  transferred are only read from the source package [5XHome[105X (say), and
  so  can  only  be  used  if  [5XHome[105X has already been loaded. There are no such
  functions in transition at present.[133X
  
  
  [1X1.1 [33X[0;0YInformation for package authors[133X[101X
  
  [33X[0;0YA  function  (or  collection  of  functions) is suitable for transfer from a
  package [5XHome[105X to [5XUtils[105X if the following conditions are satisfied.[133X
  
  [30X    [33X[0;6YThe  function  is  sufficiently non-specialised so that it might be of
        use to other authors.[133X
  
  [30X    [33X[0;6YThe function does not depend on the remaining functions in [5XHome[105X[133X
  
  [30X    [33X[0;6YThe  function  does not do what can already be done with a [5XGAP[105X library
        function.[133X
  
  [30X    [33X[0;6YDocumentation of the function and test examples are available.[133X
  
  [30X    [33X[0;6YWhen  there is more than one active author of [5XHome[105X, they should all be
        aware (and content) that the transfer is taking place.[133X
  
  [33X[0;0YAuthors  of  packages may be reluctant to let go of their utility functions.
  The  following  principles  may help to reassure them. (Suggestions for more
  items here are welcome.)[133X
  
  [30X    [33X[0;6YA  function  that  has  been  transferred to [5XUtils[105X will not be changed
        without the approval of the original author.[133X
  
  [30X    [33X[0;6YThe  current  package  maintainer has every intention of continuing to
        maintain  [5XUtils[105X.  In  the  event  that this proves impossible, the [5XGAP[105X
        development team will surely find someone to take over.[133X
  
  [30X    [33X[0;6YFunction  names  will  not be changed unless specifically requested by
        [5XHome[105X's author(s) or unless they have the form [10XHOME_FunctionName[110X.[133X
  
  [30X    [33X[0;6YIn  order  to  speed  up the transfer process, only functions from one
        package  will  be in transition at any given time. Hopefully a week or
        two will suffice for most packages.[133X
  
  [30X    [33X[0;6YAny  package  author  who transfers a function to [5XUtils[105X will become an
        author  of [5XUtils[105X. (In truth, [5XUtils[105X does not have [13Xauthors[113X, just a large
        number of [13Xcontributors[113X.)[133X
  
  [33X[0;0YThe  process  for  transferring  utility  functions  from  [5XHome[105X  to [5XUtils[105X is
  described in Chapter [14X13[114X.[133X
  
