This chapter describes how the information accessible on www.gap-system.org is stored and collected, and how it is transformed into web pages.
The GAP website (in the following just called website
) 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.
All the sources for the web pages are kept in the git repository https://github.com/gap-system/GapWWW. So you can clone this repository using
git clone https://github.com/gap-system/GapWWW
The web server in St Andrews also uses its clone, updates it to the latest revision of the master branch, runs the Jekyll tool and then serves the pages. Another named branch is called testing and it is served on the password protected version of the GAP website at https://test.gap-system.org where work in progress may be published to be reviewed internally.
The GAP website has some pages that are treated specially such as the GAP manuals, the pages for the GAP packages, the pages for the GAP bibliography, and the (old) GAP forum archive. The setup for these special pages is described in Sections 8.6 to 8.8 in this chapter.
There are several possible workflows dependently on how much efforts you would like to commit to the website maintenance.
A minimalistic scenario for small improvements (e.g. correcting details and fixing typos) only requires to install git and then:
Clone the Website repository: git clone https://github.com/gap-system/GapWWW
Make changes in a feature branch
Submit your changes as GitHub pull request so that website administrator(s) can review and merge this update.
If you are one of website administrator(s), then you will also need to be able to access the web server in St Andrews via ssh to run certain update scripts and copy necessary data.
We assume here that you are familiar with the standard git commands git clone, git pull, git push, git update, git commit etc.
The source files for the web site are kept in the git repository https://github.com/gap-system/GapWWW. You may clone it by doing
git clone https://github.com/gap-system/GapWWW
This command creates in your current directory a directory GapWWW with the complete source tree of the web site.
Source files are treated like any other source file in the git repository, that is you can update, modify, commit, add, remove them as usual.
The 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:
Changes in the master 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 8.4 to make them available online.
Changes in feature branches (which you may create to keep some work in progress) will not be visible anywhere.
A 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.
Currently, the actually published version of the web site is contained in the directory /gap/GapWWW on the following machine in St Andrews:
gap-web.host.cs.st-andrews.ac.uk
To get access to this data the easiest and most secure way is probably to create an RSA key pair, append the public key to /gap/.ssh/authorized_keys and to keep the private key in the .ssh subdirectory of the user's home directory.
Before performing an update on gap-web, it is wise to check first whether jekyll runs without an error message in your own checked out version of the website.
The next step then is to test it on the online test version of the website. To do so, ssh into gap-web and the enter these commands:
cd ~/test.gap-system.org git pull jekyll build
Assuming this worked without error message, you can review the results at https://test.gap-system.org.
Finally, to update the actual website, use the following:
cd ~/www.gap-system.org git pull jekyll build
This section describes the procedure to install the GAP web site on a machine from scratch. Thus, this section is usually not needed because all this is already done on the machine gap-web.host.cs.st-andrews.ac.uk. However, if one wants to have an exact copy of the web site or have to install it somewhere anew, this section is needed.
standard tools: git, tar, gzip, make, sh
jekyll
a web server if pages shall be published
a copy of the full doc directory from a GAP installation for references into the manual (this can reside on some web site)
setup for automatic creation of the pages for packages
Clone the git repository GapWWW:
git clone https://github.com/gap-system/GapWWW
This creates a subdirectory GapWWW in the current directory.
Unpack some (frozen) subtrees, which are in archives:
cd GapWWW
gzip -dc ForumArchive.tar.gz | tar xvf -
cd Gap3
gzip -dc Manual3.tar.gz | tar xvf -
cd ..
TODO/FIXME/WARNING: everything after this is outdated!!!
Edit GapWWW/lib/config, see that file for instructions:
vi lib/config
In this file a few variables have to be defined to adapt the web pages to the local conditions.
Copy a whole doc directory of a GAP distribution to the place mentioned in GapWWW/lib/config (see step 4.) in the variable GAPManualLink (this is GapWWW/Manuals in the current setup).
The files for the GAP bibliography have been included into this directory tree in the repository.
Create the html and PDF versions by:
cd Doc/Bib
gap4 convbib.g
cd ../..
Some more information about this is in GapWWW/Doc/Bib/INFO which is unchanges since 2010 and may be somewhat outdated.
Install package manuals:
Copy the result of Frank's scripts to the place mentioned in GapWWW/lib/config (in the variable pkgmixerpath). (currently, this is GapWWW/Manuals, copy the whole pkg directory)
To update the package pages, copy all .mixer files and pkgconf.py to GapWWW/Packages and rerun the Mixer.
Make sure that the file GapWWW/lib/AllLinksOfAllHelpSections.data is always up-to-date (this has to be adjusted whenever the released manuals change).
In the development version of GAP there is a file dev/LinksOfAllHelpSections.g. Read this with a current GAP version with all currently released packages installed and call WriteAllLinksOfAllHelpSections(), this writes the file AllLinksOfAllHelpSections.data. It has then to be checked in to its place under the GapWWW tree. Do not forget to publish the latest revision.
Run Jekyll:
jekyll build
If things are changed in the repository, all that has to be done to update the pages locally is:
git pull
in the GapWWW directory, followed by a
jekyll build
All GAP manuals are available in HTML format via the web pages. This works by simply copying the doc directory of a complete GAP installation to the place specified by the variable GAPManualLink in GapWWW/lib/config (which is GapWWW/Manuals in the current setup). Note that those files are not under version control there, they are only copied to checked out working copies, like for example on the web server in St Andrews.
The single remaining point to explain is how one can specify links to manual sections on the web pages. This is done with a special Mixer tag like the following:
<mixer manual="Reference: Lists">Chapter about lists</mixer>
This element creates a link to the manual section which would appear in the GAP help system when called with
, which happens to be the chapter in the reference manual about lists. The text of the link would be ?Reference: ListsChapter about lists
.
This works, because the Mixer has access to a file containing the links to all manual sections. This file resides in GapWWW/lib/AllLinksOfAllHelpSections.data, which is created using dev/LinksOfAllHelpSections.g in the development version of GAP as described in Section 8.5.
The value of the attribute manual
in the mixer
tag must be the complete text of the section heading the link should point to.
The archives and web pages for the GAP packages are generated by yet another set of tools described in Chapter 7. These generate for every package a .mixer-file and for all packages together a file pkgconf.py. All these files have to be put under version control in the directory GapWWW/Packages. These nodes then only have to be put into the tree by mentioning them in the tree file there.
Until December 2003 the GAP forum archive was handled by a tool written especially for this task. At that point it was switched to mailman, 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 GapWWW/ForumArchive.tar.gz.
To install those pages in a checked out working copy one just has to extract this archive by doing
gzip -dc ForumArchive.tar.gz | tar xf -
in the GapWWW directory as explained in Section 8.5.
generated by GAPDoc2HTML