  
  [1X9 [33X[0;0YMaintaining the [5XGAP[105X[101X[1X website[133X[101X
  
  [33X[0;0YThis  chapter describes how the information accessible on www.gap-system.org
  ([7Xhttps://www.gap-system.org/[107X)  is  stored  and  collected,  and  how  it  is
  transformed into web pages.[133X
  
  
  [1X9.1 [33X[0;0YOverview[133X[101X
  
  [33X[0;0YThe  [5XGAP[105X website (in the following just called [21Xwebsite[121X) has a tree structure
  for easier navigation and overview. Each node and each leaf of the tree is a
  web page. Every single page resides somewhere in this tree. This position is
  shown in the navigation bar on the left hand side, and the user can navigate
  through the tree using this navigation bar. However, pages can still link to
  other pages that reside in some other branch of the tree.[133X
  
  [33X[0;0YWith  very few exceptions, all pages are static HTML pages conforming to the
  XHTML  1.0  standard  (see Section [14X9.4[114X). However, these pages are not edited
  directly by the maintainer, but they are produced by a tool called [21Xthe [5XMixer[105X[121X
  (see  [14X9.3[114X),  which  takes  so called [21X[11X.mixer[111X-files[121X as source and produces the
  final  HTML  files.  During  this process, the navigation bar and some other
  parts  of  the page are created automatically, such that the maintainer does
  not  have  to worry about technicalities. A [11X.mixer[111X file essentially contains
  the  content  of  the  page in form of a well-formed XML document (see again
  Section [14X9.4[114X for an explanation) and the [5XMixer[105X handles the technical details.[133X
  
  [33X[0;0YAll  the  sources  for  the  web  pages  are  kept  in  the  git  repository
  [10Xhttps://github.com/gap-system/GapWWW[110X. So you can clone this repository using[133X
  
  git clone https://github.com/gap-system/GapWWW
  
  [33X[0;0YThe  web  server in St Andrews also uses its clone, updates it to the latest
  revision  of  the  [9Xmaster[109X  branch, runs the [5XMixer[105X and then serves the pages.
  Another  named  branch  is  called  [9Xtesting[109X and it is served on the password
  protected version of the [5XGAP[105X website at [7Xhttp://devel.gap-system.org/testsite[107X
  where work in progress may be published to be reviewed internally.[133X
  
  [33X[0;0YThe  [5XGAP[105X  website  has some pages that are treated specially such as the [5XGAP[105X
  manuals,  the  pages  for  the  [5XGAP[105X  packages,  the  pages  providing search
  facilities,  the  pages for the [5XGAP[105X bibliography, the sitemap, and the (old)
  [5XGAP[105X  forum  archive.  The  setup  for  these  special  pages is described in
  Sections [14X9.8[114X to [14X9.13[114X in this chapter.[133X
  
  [33X[0;0YIn  the  following sections we first cover the [5XMixer[105X, the web standard XHTML
  1.0,  the  usage  of  git for the web pages, and the installation of the web
  site on the web server.[133X
  
  
  [1X9.2 [33X[0;0YGetting started[133X[101X
  
  [33X[0;0YThere  are  several  possible  workflows dependently on how much efforts you
  would like to commit to the website maintenance.[133X
  
  [33X[0;0YA  minimalistic scenario for small improvements (e.g. correcting details and
  fixing typos) only requires to install git ([7Xhttps://git-scm.com/[107X) and then:[133X
  
  [31X1[131X   [33X[0;6YClone        the       Website       repository:       [10Xgit       clone
        https://github.com/gap-system/GapWWW[110X[133X
  
  [31X2[131X   [33X[0;6YMake changes in the [9Xmaster[109X branch[133X
  
  [31X3[131X   [33X[0;6YCommit   and   push   changes   to  trigger  notification  to  website
        admininstrator(s) to check and approve this update.[133X
  
  [33X[0;0YA more robust scenario, especially for changes that are more likely to break
  the [5XMixer[105X syntax, is to clone also the [5XMixer[105X repository with[133X
  
  git clone https://github.com/gap-system/Mixer
  
  [33X[0;0Yan  build  the  [5XMixer[105X as described in the [11Xmixer.README[111X file (see Section [14X9.3[114X
  for  further  details).  For  this  step,  you  will  need a C compiler (for
  compiling  parts  of  the  [5XMixer[105X)  and  a  Python  ([7Xhttps://www.python.org/[107X)
  interpreter (for running the [5XMixer[105X).[133X
  
  [33X[0;0YWith  [5XMixer[105X,  you  may  run  the [11Xmixer.py[111X script (probably with [10X-f[110X option to
  rebuild  everything  regardless  the  timestamps)  inside the [11XGapWWW[111X working
  directory  to check how produced html pages look like in your browser before
  committing and pushing the changes.[133X
  
  [33X[0;0YFinally,  while  changes in the [9Xmaster[109X branches will trigger notification to
  website  admininstrator(s)  to  check and approve them, for changes that you
  want to be internally reviewed prior to publication, you may use the [9Xtesting[109X
  branch  which is served on the password protected version of the [5XGAP[105X website
  at  [7Xhttp://devel.gap-system.org/testsite[107X. Changes in the [9Xtesting[109X branch will
  appear  at  the  testing  site  immediately after pushing them to the master
  repository.  This workflow is useful if you want to show your suggestions to
  a wider group of people who may not have an opportunity to install [5XMixer[105X and
  have a local version of the [5XGAP[105X website to review your changes.[133X
  
  [33X[0;0YIf  you  are one of website admininstrator(s), then you will also need to be
  able  to  access  the web server in St Andrews via [10Xssh[110X to run certain update
  scripts and copy necessary data.[133X
  
  
  [1X9.3 [33X[0;0YThe Mixer[133X[101X
  
  [33X[0;0YThe  [5XMixer[105X  is  a Python script that uses a C-library to parse XML documents
  (see  Section  [14X9.4[114X). Therefore this library (which comes with the [5XMixer[105X) has
  to be compiled first.[133X
  
  [33X[0;0YThe [5XMixer[105X is kept in the git repository [10Xhttps://github.com/gap-system/Mixer[110X.
  To clone this repository, use[133X
  
  git clone https://github.com/gap-system/Mixer
  
  [33X[0;0YThe  above command creates a clone of this repository in the directory [11XMixer[111X
  of the current directory. In that directory you can create the manual of the
  [5XMixer[105X  by  calling [10Xmake mixer.pdf[110X provided you have an installation of LaTeX
  on your machine. In that manual the [5XMixer[105X and its installation are described
  in details.[133X
  
  [33X[0;0YAlternatively  you  can  download  a copy of the [5XMixer[105X and its documentation
  from                                this                                page
  (
  http://www.math.rwth-aachen.de/~Max.Neunhoeffer/Computer/Software/mixer.html
  ).[133X
  
  [33X[0;0YA  small  comment  on  the rationale behind the [5XMixer[105X might be in order. The
  fact  that  the  input  of  the  [5XMixer[105X,  that is the [11X.mixer[111X-files have to be
  well-formed  XML  documents  (see  Section  [14X9.4[114X)  might  at  first  sight be
  considered  inconvenient  and  a  bit  awkward.  However,  this fact greatly
  improves  the chances that the resulting HTML files conform to the XHTML 1.0
  standard  and  at  the  same time lead to the fact that the [5XMixer[105X is able to
  give  very concise and usable error message during parsing in case something
  is   not   well-formed.  This  together  with  the  automatically  generated
  navigation  bar  makes  the  [5XMixer[105X  a  valuable tool for the creation of web
  pages.[133X
  
  [33X[0;0YNote  in  particular  that  the  tree  structure  of  the  whole web site is
  controlled  by  the [11Xtree[111X files in each subdirectory, exactly as described in
  the manual of the [5XMixer[105X.[133X
  
  
  [1X9.4 [33X[0;0YXHTML[133X[101X
  
  [33X[0;0YThe  HTML  language has undergone a series of revision and standardizations.
  One  major  step  was  to  make  an  HTML  standard that conforms to the XML
  standard  which  happened  with the revision [21XXHTML 1.0[121X of the HTML standard.
  This  step  was  important because the XML framework makes it much easier to
  parse  such documents automatically and check for [21Xwell-formedness[121X. Here, the
  term  [21Xwell-formed[121X  means that the document fulfils a set of syntactic rules.
  That  is,  a document might be well-formed and at the same time not make any
  sense.  See  this  page ([7Xhttps://www.w3.org/TR/xhtml1/[107X) for details. A short
  introduction  to  the  XML standard can be found in Section [14X'GAPDoc: XML'[114X in
  the [5XGAPDoc[105X manual.[133X
  
  [33X[0;0YThe  [5XGAP[105X  web  pages should conform to the standard XHTML 1.0. To cut a long
  story  short,  this  means  a few restrictions on the markup to use. Here we
  quickly cover the most important things, which should enable anybody who has
  ever seen an HTML document of any version to get started.[133X
  
  [31X1[131X   [33X[0;6YAll tags must be written with lower case letters in the element names.[133X
  
  [31X2[131X   [33X[0;6YAll  non-empty  elements must have a start- and end-tag, in particular
        enclose paragraphs in [10X<p>[110X and [10X</p>[110X or list entries in [10X<li>[110X and [10X</li>[110X.[133X
  
  [31X3[131X   [33X[0;6YElements  must  be  properly nested like brackets, that is things like
        [10X<a><b></a></b>[110X are not allowed.[133X
  
  [31X4[131X   [33X[0;6YAttributes  always  must  have an assigned value and the value must be
        enclosed   by   either   double  or  single  quotes;  for  example  [10X<a
        href="https://www.gap-system.org">GAP site</a>[110X.[133X
  
  [31X5[131X   [33X[0;6YWrite  empty  elements  like  [10X<br  />[110X,  the  space before the [10X/[110X is not
        necessary  according  to  the  specification  but  it  helps  some old
        browsers to interpret it correctly.[133X
  
  [31X6[131X   [33X[0;6YDo  not  put information on colors or fonts in the XHTML file. Instead
        use  the  [10X.css[110X  style sheet file. (For complicated cases use the [10Xclass[110X
        attribute  to  mark  elements  for  which  you  want  to  give special
        formating rules in the style sheet.[133X
  
  [31X7[131X   [33X[0;6YThe  XML markup characters [21X[10X<[110X[121X, [21X[10X&[110X[121X, and [21X[10X>[110X[121X must be entered as [21X[10X&lt;[110X[121X, [21X[10X&amp;[110X[121X,
        and  [21X[10X&gt;[110X[121X  respectively. There are quite a few such [21Xentities[121X which are
        defined    to    enter    special    characters.    See    this   page
        ([7Xhttps://www.w3.org/TR/xhtml1/Overview.html#h-A2[107X) for details.[133X
  
  [33X[0;0YUsing  the  W3C  ([7Xhttps://www.w3.org/TR/html401/[107X)  specification  HTML  4.01
  ([7Xhttps://www.w3.org/TR/html401/[107X)  - this includes a nice [13Xelements[113X overview -
  together  with  the  above  rules  and the general rule to avoid complicated
  looking  constructs  when possible, we found it not too difficult to produce
  sets of valid web pages.[133X
  
  
  [1X9.5 [33X[0;0YGit usage[133X[101X
  
  [33X[0;0YWe  assume  here  that  you  are familiar with the standard git commands [10Xgit
  clone[110X, [10Xgit pull[110X, [10Xgit push[110X, [10Xgit update[110X, [10Xgit commit[110X etc.[133X
  
  [33X[0;0YThe  source  files  for  the  web  site  are  kept  in  the  git  repository
  [10Xhttps://github.com/gap-system/GapWWW[110X. You may clone it by doing[133X
  
  git clone https://github.com/gap-system/GapWWW 
  
  [33X[0;0YThis  command  creates in your current directory a directory [11XGapWWW[111X with the
  complete source tree of the web site.[133X
  
  [33X[0;0YSource  files  are treated like any other source file in the git repository,
  that is you can update, modify, commit, add, remove them as usual.[133X
  
  [33X[0;0YThe  only  thing  one  has  to  understand  with  respect  to  git  is which
  implications  the  branch  in which the change has appeared will have on the
  process of its publication:[133X
  
  [30X    [33X[0;6YChanges  in  the  [9Xmaster[109X branch will not be automatically published on
        the web server. They will be reviewed by the website administrator who
        will then have to run the update script on the server in St Andrews as
        described in Section [14X9.6[114X to make them available online.[133X
  
  [30X    [33X[0;6YChanges  in the [9Xtesting[109X branch will immediately appear on the password
        protected       version      of      the      [5XGAP[105X      website      at
        [7Xhttp://devel.gap-system.org/testsite[107X  where  they  may  be reviewed by
        others.[133X
  
  [30X    [33X[0;6YChanges in feature branches (which you may create to keep some work in
        progress) will not be visible anywhere.[133X
  
  [33X[0;0YA  little  comment  on the rationale behind this setup might be in order. It
  allows  that  more  than  one  person works independently on the website and
  those people exchange versions via git, without publishing them immediately.
  The  actual  guidelines  who  does  what in this process should be agreed on
  separately.[133X
  
  
  [1X9.6 [33X[0;0YThe web server in St Andrews[133X[101X
  
  [33X[0;0YCurrently,  the  actually  published version of the web site is contained in
  the directory [11X/gap/GapWWW[111X on the following machine in St Andrews:[133X
  
      yin.mcs.st-andrews.ac.uk
  
  [33X[0;0YThis  machine is not really a web server, but the real web server mounts and
  serves the directory [11X/gap/GapWWW[111X from [11Xyin[111X via NFS.[133X
  
  [33X[0;0YThe  [5XMixer[105X  is  checked  out (still old CVS version, it has not been changed
  since  it  remained  unchanged  over  several  years)  and  installed in the
  directory [11X/gap/Mixer[111X. It can be called with the command[133X
  
      /gap/Mixer/mixer.py
  
  [33X[0;0YThe  files  are  checked  out with ownership [11Xgapchron[111X which is a user on [11Xyin[111X
  with  the  same numerical user ID than the [11Xgap[111X user. In other words, one has
  to  be  the user [11Xgap[111X to manipulate the data. Note that the home directory of
  the user [11Xgap[111X is in fact [11X/gap[111X.[133X
  
  [33X[0;0YTo  get  access  to this data the easiest and most secure way is probably to
  create  an  RSA key pair, append the public key to [11X/gap/.ssh/authorized_keys[111X
  and  to  keep  the  private  key in the [11X.ssh[111X subdirectory of the user's home
  directory.[133X
  
  [33X[0;0YThere  is one shell script which is run by a website administrator to update
  the  website.  This script is in [11Xbin/updateGapWWW.sh[111X. It basically pulls the
  latest  version  from  the  master  repository  and  runs the [5XMixer[105X. You can
  trigger the update manually by doing[133X
  
     ssh gap@yin.mcs.st-andrews.ac.uk bin/updateGapWWW.sh
  
  [33X[0;0Yonce you have [10Xssh[110X access to [11Xyin[111X.[133X
  
  [33X[0;0YBefore  performing  an  update on [11Xyin[111X, it is wise to check first whether the
  [5XMixer[105X  runs  without an error message in your own checked out version of the
  website.[133X
  
  
  [1X9.7 [33X[0;0YInstallation on the web server[133X[101X
  
  [33X[0;0YThis  section  describes  the  procedure  to  install  the [5XGAP[105X web site on a
  machine  from  scratch. Thus, this section is usually not needed because all
  this  is  already  done on the machine [11Xyin.mcs.st-andrews.ac.uk[111X. However, if
  one  wants  to  have  an  exact  copy  of the web site or have to install it
  somewhere  anew,  this  section is needed. This section was derived from the
  ASCII  document  [11XGapWWW/INSTALL[111X  long time ago when it was under CVS control
  (so [11XGapWWW/INSTALL[111X is likely heavily outdated).[133X
  
  
  [1X9.7-1 [33X[0;0YNeeded ingredients[133X[101X
  
  [30X    [33X[0;6Ystandard tools: [10Xgit[110X, [10Xtar[110X, [10Xgzip[110X, [10Xmake[110X, [10Xsh[110X[133X
  
  [30X    [33X[0;6Ya C-compiler, preferably [10Xgcc[110X[133X
  
  [30X    [33X[0;6Y[5XPython[105X version 2.2 or later (for running the [5XMixer[105X)[133X
  
  [30X    [33X[0;6YyEd graph editor ([7Xhttp://www.yworks.com/en/products_yed_about.html[107X) if
        you want to edit the sitemap[133X
  
  [30X    [33X[0;6Ya web server if pages shall be published[133X
  
  [30X    [33X[0;6Ya  copy  of  the  full  [11Xdoc[111X  directory  from  a  [5XGAP[105X  installation for
        references into the manual (this can reside on some web site)[133X
  
  [30X    [33X[0;6Yfacility  to  run  CGI-scripts  for  feedback pages (TODO: check if we
        still use them)[133X
  
  [30X    [33X[0;6Ysetup for automatic creation of the pages for packages[133X
  
  [30X    [33X[0;6Ythe [10Xswish[110X utility for the creation of the search indices (TODO: may be
        better to switch to Google search)[133X
  
  
  [1X9.7-2 [33X[0;0YInstallation procedure[133X[101X
  
  [31X1[131X   [33X[0;6YClone the git repository GapWWW:[133X
  
  git clone https://github.com/gap-system/GapWWW 
  
        [33X[0;6YThis creates a subdirectory [11XGapWWW[111X in the current directory.[133X
  
  [31X2[131X   [33X[0;6YClone the git repository Mixer:[133X
  
  git clone https://github.com/gap-system/Mixer
  
        [33X[0;6YThis creates a subdirectory [11XMixer[111X in the current directory.[133X
  
  [31X3[131X   [33X[0;6YUnpack some (frozen) subtrees, which are in archives:[133X
  
      cd GapWWW  
      gzip -dc ForumArchive.tar.gz | tar xvf -
      cd Gap3  
      gzip -dc Manual3.tar.gz | tar xvf -
      cd ..    
  
  [31X4[131X   [33X[0;6YEdit [11XGapWWW/lib/config[111X, see that file for instructions:[133X
  
      vi lib/config
  
        [33X[0;6YIn this file a few variables have to be defined to adapt the web pages
        to the local conditions.[133X
  
  [31X5[131X   [33X[0;6YCopy  a  whole  [11Xdoc[111X  directory  of  a  [5XGAP[105X  distribution  to the place
        mentioned   in   [11XGapWWW/lib/config[111X  (see  step  4.)  in  the  variable
        [10XGAPManualLink[110X (this is [11XGapWWW/Manuals[111X in the current setup).[133X
  
  [31X6[131X   [33X[0;6YThe  files  for  the  [5XGAP[105X  bibliography  have  been included into this
        directory tree in the repository.[133X
  
        [33X[0;6YCreate the html and PDF versions by:[133X
  
      cd Doc/Bib
      gap4 convbib.g
      cd ../.. 
  
        [33X[0;6YSome  more  information  about this is in [11XGapWWW/Doc/Bib/INFO[111X which is
        unchanges since 2010 and may be somewhat outdated.[133X
  
  [31X7[131X   [33X[0;6YInstall search facility:[133X
  
        [33X[0;6YThings  are  in [11XGapWWW/Search[111X. You need the [10Xswish[110X utility installed to
        create  the  index  files  for  searching. Create a link in the [11XSearch[111X
        directory to the swish executable. Then create index files by:[133X
  
      cd Search
      ln -s PATHTOSWISH swish
      make
      cd ..
  
        [33X[0;6Y([11XPATHTOSWISH[111X has to be replaced by the path to the swish executable.)[133X
  
        [33X[0;6YThe CGI script [11XGapWWW/Search/search.cgi[111X will take care of the rest.[133X
  
  [31X8[131X   [33X[0;6YInstall package manuals:[133X
  
        [33X[0;6YCopy  the  result  of  Frank's  scripts  to  the  place  mentioned  in
        [11XGapWWW/lib/config[111X  (in the variable [11Xpkgmixerpath[111X). (currently, this is
        [11XGapWWW/Manuals[111X, copy the whole [11Xpkg[111X directory)[133X
  
        [33X[0;6YTo  update  the package pages, copy all [11X.mixer[111X files and [11Xpkgconf.py[111X to
        [11XGapWWW/Packages[111X and rerun the [5XMixer[105X.[133X
  
  [31X9[131X   [33X[0;6YMake  sure  that the file [11XGapWWW/lib/AllLinksOfAllHelpSections.data[111X is
        always  up-to-date  (this  has  to  be  adjusted whenever the released
        manuals change).[133X
  
        [33X[0;6YIn    the    development    version   of   [5XGAP[105X   there   is   a   file
        [11Xdev/LinksOfAllHelpSections.g[111X.  Read  this  with  a current [5XGAP[105X version
        with    all   currently   released   packages   installed   and   call
        [10XWriteAllLinksOfAllHelpSections()[110X,     this     writes     the     file
        [11XAllLinksOfAllHelpSections.data[111X.  It  has  then to be checked in to its
        place  under  the  [11XGapWWW[111X  tree.  Do  not forget to publish the latest
        revision.[133X
  
  [31X10[131X  [33X[0;6YRun the mixer:[133X
  
      ../Mixer/mixer.py -f
  
        [33X[0;6Y(the [10X-f[110X forces creation regardless of timestamps)[133X
  
  
  [1X9.7-3 [33X[0;0YInstalling updated versions[133X[101X
  
  [33X[0;0YIf  things  are changed in the repository, all that has to be done to update
  the pages locally is:[133X
  
  git pull
  
  [33X[0;0Yin the [11XGapWWW[111X directory, followed by a[133X
  
    ../Mixer/mixer.py
  
  [33X[0;0YThe  mixer  has  an  option  [10X-f[110X  to  force  recreation of all pages. This is
  necessary  if  some general files like the address database [11Xlib/addresses[111X or
  templates changes.[133X
  
  [33X[0;0YTo  change the sitemap, use [5XyEd[105X graph editor to modify [11Xsitemap.graphml[111X file,
  then  used  [5XyEd[105X export menu to create [11Xsitemap.html[111X file with associated [11X.png[111X
  image.[133X
  
  
  [1X9.8 [33X[0;0YThe [5XGAP[105X[101X[1X manuals on the web pages[133X[101X
  
  [33X[0;0YAll  [5XGAP[105X  manuals are available in HTML format via the web pages. This works
  by  simply  copying  the [11Xdoc[111X directory of a complete [5XGAP[105X installation to the
  place specified by the variable [11XGAPManualLink[111X in [11XGapWWW/lib/config[111X (which is
  [11XGapWWW/Manuals[111X  in  the  current setup). Note that those files are [13Xnot[113X under
  version  control  there, they are only copied to checked out working copies,
  like for example on the web server in St Andrews.[133X
  
  [33X[0;0YThe single remaining point to explain is how one can specify links to manual
  sections  on  the  web pages. This is done with a special [5XMixer[105X tag like the
  following:[133X
  
      <mixer manual="Reference: Lists">Chapter about lists</mixer>
  
  [33X[0;0YThis  element creates a link to the manual section which would appear in the
  [5XGAP[105X  help system when called with [21X[10X?Reference: Lists[110X[121X, which happens to be the
  chapter  in  the reference manual about lists. The text of the link would be
  [21XChapter about lists[121X.[133X
  
  [33X[0;0YThis  works,  because the [5XMixer[105X has access to a file containing the links to
  all       manual       sections.       This       file       resides      in
  [11XGapWWW/lib/AllLinksOfAllHelpSections.data[111X,    which    is    created   using
  [11Xdev/LinksOfAllHelpSections.g[111X  in the development version of [5XGAP[105X as described
  in Section [14X9.7[114X.[133X
  
  [33X[0;0YThe value of the attribute [21Xmanual[121X in the [21Xmixer[121X tag must be the complete text
  of the section heading the link should point to.[133X
  
  
  [1X9.9 [33X[0;0YThe [5XGAP[105X[101X[1X packages on the web pages[133X[101X
  
  [33X[0;0YThe archives and web pages for the [5XGAP[105X packages are generated by yet another
  set  of  tools  described  in  Chapter [14X8[114X. These generate for every package a
  [11X.mixer[111X-file and for all packages together a file [11Xpkgconf.py[111X. All these files
  have to be put under version control in the directory [11XGapWWW/Packages[111X. These
  nodes  then only have to be put into the tree by mentioning them in the [11Xtree[111X
  file there.[133X
  
  
  [1X9.10 [33X[0;0YThe search engine on the web pages[133X[101X
  
  [33X[0;0YThe  search  engine  on  the web pages internally uses the [10Xswish[110X tool. It is
  used  to create an index of all pages which allows very fast searches when a
  user  submits  a  query.  All  files  for  this  setup  are in the directory
  [11XGapWWW/Search[111X.[133X
  
  [33X[0;0YThe indices are regenerated by doing[133X
  
      touch everything.conf
      make
  
  [33X[0;0Yin that directory. This is done automatically every night, such that usually
  nothing has to be done after installation.[133X
  
  [33X[0;0YTo  make  this  work,  one needs a [10Xswish[110X executable and has to create a link
  [11XGapWWW/Search/swish[111X to that executable.[133X
  
  
  [1X9.11 [33X[0;0YThe [5XGAP[105X[101X[1X bibliography[133X[101X
  
  [33X[0;0YThe [5XGAP[105X bibliography resides in the directory [11XGapWWW/Doc/Bib[111X.[133X
  
  [33X[0;0YThe source files are:[133X
  
  [8X [11XGapCite.MR[111X [108X
        [33X[0;6YThis  file  contains  just  MR numbers of papers that cite or refer to
        (one   of  the  versions  of)  GAP  (here  and  below  [21XMR[121X  stands  for
        [21XMathematical  Reviews[121X.).  The  format is alternatingly one line of the
        form  [10X1stAuthorSurname  Paper[110X (not starting with a blank) and one line
        [10XMR-Number[110X (starting with a blank). MR numbers will be used to get full
        bibliographic  info  from MathSciNet, and the textual description only
        helps  when  adding papers to the file (in particular, to keep entries
        sorted by the first author).[133X
  
  [8X [11XGapCite.notyet[111X [108X
        [33X[0;6Y[10XBiBTeX[110X  entries  for  papers that are not yet in MR but likely will be
        there in a few months[133X
  
  [8X [11XGapNonMR.bib[111X [108X
        [33X[0;6Y[10XBiBTeX[110X entries for papers that will not be in MR (e.g. theses)[133X
  
  [8X [11XNonVerif.MR[111X [108X
        [33X[0;6YThings not yet verified, same format as [11XGapCite.MR[111X[133X
  
  [8X [11XNonVerif.NonMR[111X [108X
        [33X[0;6YThings not yet verified, same format as [11XGapCite.notyet[111X[133X
  
  [8X [11XGapIgnore.MR[111X [108X
        [33X[0;6YThis  file  contains a list of [5XGAP[105X strings corresponding to MR numbers
        of  papers  that  may  be falsely reported by MathSciNet as citing [5XGAP[105X
        (for  example,  if  they  refer  to the History of Mathematics Archive
        website  wrongly  stating  its  address  in  the  [5XGAP[105X domain as may be
        returned by some search systems). If necessary, add new items there in
        an obvious way.[133X
  
  [33X[0;0YIt  is  possible  to  check MathSciNet for new references to [5XGAP[105X reading the
  file [11Xupdatebib.g[111X into [5XGAP[105X. It will produce two files:[133X
  
  [8X [11Xtobeadded.txt[111X [108X
        [33X[0;6YThis  file  has  the  same format as [11XGapCite.MR[111X and lists publications
        citing  [5XGAP[105X  which  should  be examined and after that added either to
        [11XGapCite.MR[111X or to [11XGapIgnore.MR[111X.[133X
  
  [8X [11Xsuggested.txt[111X [108X
        [33X[0;6YThis   file   contains   suggestions  to  [21Xmove[121X  certain  entries  from
        [11XGapCite.notyet[111X   and  [11XGapNonMR.bib[111X  to  [11XGapCite.MR[111X.  All  suggestions,
        including  those  which do not match the publication listed in the [5XGAP[105X
        bibliography, should be carefully examined before any changes.[133X
  
  [33X[0;0YNote   that  [11Xupdatebib.g[111X  is  not  a  complete  solution  for  updating  [5XGAP[105X
  bibliography.  It  searches  for  occurrences  of  the  substring [10Xwww.gap[110X in
  citations  (this  covers both old and current addresses of the [5XGAP[105X website),
  but  it  does  not  cover  publications  citing  [5XGAP[105X  without its website or
  referring  to  it  only  in the text; finally, it covers only MathSciNet and
  does  not  look  into other bibliography databases. Therefore, manual search
  still   should  be  used  to  discover  more  [5XGAP[105X  citations.  The  function
  [10XSearchMathSciNetForUpdates[110X from [11Xupdatebib.g[111X may be helpful in this direction
  since  it  performs  more broad search in the MathSciNet, dropping some more
  strict limitations.[133X
  
  [33X[0;0YAfter  the  source  files  of  the  [5XGAP[105X bibliography are updated, the script
  [11Xnewmakegapbib[111X  uses  [11XGapCite.MR[111X,  [11XGapCite.notyet[111X  and [11XGapNonMR.bib[111X (and also
  [11XHEADER[111X  and  [11XMRBIB[111X) to produce [11Xgap-published.bib[111X (this requires subscription
  to MathSciNet, which St Andrews has). The advantage of this approach is that
  MathSciNet gives us good [10XBiBTeX[110X entries (no need to look up journal names or
  diacritic  characters)  and their updates, and MR numbers we can link to. It
  also makes it easier to add entries as only the MR number is needed.[133X
  
  [33X[0;0YAt  the  end  of  its  work  [11Xnewmakegapbib[111X  will also display error messages
  reporting  MR numbers whose BibTeX record it failed to fetch from MathSciNet
  --   these  should  be  investigated  since  they  may  point  out  on  some
  inconsistencies in our data.[133X
  
  [33X[0;0Y(There  is  also  a  script  [10XGETMR[110X that will return MR numbers for papers --
  convenient  to  look  up  a large number of papers one found in the citation
  index.)[133X
  
  [33X[0;0YFinally  [5XGAP[105X  itself  called with [11Xconvbib.g[111X produces the web page and a nice
  PDF   bibliography   from  [11Xgap-published.bib[111X  (using  further  helper  files
  [11Xgapbib.tex[111X and [11Xgap-head.bib[111X). The resulting files are [11Xgap-published.html[111X and
  [11Xgap-published.pdf[111X  which  are  linked  from the main web page [11Xbib.html[111X. [13XNOTE[113X
  that  [11Xgap-published.html[111X and [11Xgap-published.pdf[111X are [13Xnot[113X under version control
  because  they can be generated automatically by [11Xconvbib.g[111X rather quickly. In
  addition,  [11Xconvbib.g[111X creates [11Xstatistics.generated[111X and [11Xstatistics.mscreport[111X -
  two  pages  with  tables  which  are  used  in  [11Xstatistics.mixer[111X  to  create
  [11Xstatistics.html[111X.[133X
  
  [33X[0;0YThe  output  of  [11Xconvbib.g[111X  should  be  also checked for errors and warnings
  reporting  repeated  entries,  incomplete  BibTeX  records  (mostly  may  be
  ignored), etc.[133X
  
  [33X[0;0Y[13XNOTE[113X:  The  current  setup  does  not run [5XGAP[105X on [11Xconvbib.g[111X every night. This
  means  that  everybody  who  changes  the  [5XGAP[105X  bibliography  has to do this
  manually on [10Xyin[110X after every change.[133X
  
  
  [1X9.12 [33X[0;0YThe sitemap[133X[101X
  
  [33X[0;0YThe  sitemap  picture  is  generated  and  edited  in the following way: The
  original  source  is  the file [11Xsitemap.graphml[111X which is generated and edited
  with  the  [5XyEd[105X  program. [5XyEd[105X functionality allows to export the sitemap as a
  clickable   HTML   image   map,   producing   two   files  [11Xsitemap.html[111X  and
  [11Xsitemap1_1.png[111X. Because the sitemap usually does not change very much, these
  two files are also kept under the version control.[133X
  
  
  [1X9.13 [33X[0;0YThe [5XGAP[105X[101X[1X forum archive[133X[101X
  
  [33X[0;0YUntil  December  2003  the  [5XGAP[105X  forum archive was handled by a tool written
  especially  for  this  task.  At  that  point  it was switched to [10Xmailman[110X, a
  generic  tool for mailing list, which also does the archiving. Therefore the
  old  forum archives are frozen in form of a huge amount of HTML pages. These
  are  not  kept  under  version control as single files but as one big binary
  archive under [11XGapWWW/ForumArchive.tar.gz[111X.[133X
  
  [33X[0;0YTo install those pages in a checked out working copy one just has to extract
  this archive by doing[133X
  
      gzip -dc ForumArchive.tar.gz | tar xf -
  
  [33X[0;0Yin the [11XGapWWW[111X directory as explained in Section [14X9.7[114X.[133X
  
