Lecture Homepages as of FS 2017 Andreas Steiger, Manuel Lüthi February 6, 2017 1 Introduction When ETH revised its complete online portfolio, the previous content management system (CMS) Silva was archived as per the Fall Term 2016. The new CMS of ETH however is not designed to handle dozens of new editors every semester as we would use it for our lecture homepages at D-MATH. It was thus necessary to create a new solution for setting up lecture homepages as it was possible with Silva. Over the past years, the group around Norbert Hungerbühler, Alexander Caspar and Heinz Rasched developed software solutions for the projects Nemesis and Echo which can replace some of the functionality of the old system. During the past few months, a new system was thus set up which combines the simplicity and the openness of Silva with existing components of Echo. The result is released on https://metaphor.ethz.ch/. This site delivers mainly simple static HMTL files which are placed there using the versioning software git. Advanced users can use the full power of web applications if they want, e.g. PHP scripts or hooks for git. At this point, usage of the new system is voluntary but encouraged. However it is planned that as of the Fall Term 2017, all lecture homepages will run on this system. This guarantees that our work remains openly accessible, becomes searchable and is consistent in presentation. 2 How do I start? 2.1 Set up and installation Write an e-mail to Heinz that you want to take part! Send a request to heinz.rasched@math.ethz.ch including the name of your lecture and he will set up a git repository and a first version of your homepage. The software will fill in as much data as it can. Then you need git. On computers at D-MATH, this software should be installed. To check this, open a command terminal and write git --version (see below). If git is installed, you should see which version you have, otherwise something like bash: git: command not found should appear. In this case, 1
either tell your administrator to install git or do it yourself. You can find the software at https://git-scm.com/downloads. 2.2 Using a local repository To use git you can either work on the command line (i.e. a terminal window) or use a graphical interface of your choice. If you are not familiar with the command line, an online search for UNIX commands will present you with lists of the most common commands. Once the master repository is created, you will receive an e-mail by Heinz containing an URL of the form https://metaphor.ethz.ch/xyz/courseid. This is the master repository which contains all resources of the homepage. You will not work directly in the master repository, buy instead create a local copy of it. You can then work on the local copy and submit your changes to the master repository. To create a local copy of the master repository, create a local directory at PATH and execute the following commands: $ cd PATH $ git clone https :// metaphor. ethz.ch/xyz / COURSEID $ cd COURSEID Using the last command we entered the local repository. Now we can work with it and periodically submit the changes to the master repository. Heinz will also give you the link for your lecture homepage. You can set this link as the main link for your course at edoz so that all enrolled students can find your lecture homepage easily. 3 How do I edit my homepage? 3.1 Changing the local copy The command git clone placed many files in the directory PATH/COURSEID examples for exercise sheets, lecture scripts, etc. You will also find the HTML file index.htm, the local copy of your homepage. It already contains all available information from other tools like edoz and HA-Tool, i.e. a list of teaching assistants and exercise classes. Some contents might still be missing, so you should check this file carefully. HTML is a markup language just as L A TEX and thus contains all actual content, but also references to additional resources which are necessary for the browser to display the page properly. This works very similarly to documentclass and the packages which you know from L A TEX. Just as with L A TEX you can edit index.htm with the text editor of your choice. The structure of this file is fairly logical and should not pose a problem for a mathematician. If it does, you can solve this problem just as a mathematical one by either looking up the right resources (like a book or using the 2
internet) or by asking somebody who knows it already most likely, the latter option will be the faster one. Your repository can contain additional files as the example exercise sheets show. These files can also be accessed through the homepage once you add them to the repository. To see the effects of your changes, open the file index.htm locally with a web browser. 3.2 Submitting changes All the changes you have made so far were only done on the local repository. You now have to use git to send the changes to the master repository, so that the visitors of your homepage can see your updated homepage. In general, the work flow using git looks as follows: 1. The local repository is synchronized with the master repository 2. One change is done within the local repository 3. The changes to the local repository are added to the index of the local repository 4. The new state of the index is committed, i.e. git saves this state for the index of the local repository 5. Steps 2-4 are repeated as often as needed 6. The committed changes are sent to the master repository, making them visible online. To execute these steps, the following commands are used: 0. Change directories to the path where you placed your local copy: $ cd PATH/COURSEID 1. Synchronize the local repository with the master repository: $ git pull 3. Add the n changed or added files to the index: $ git add./pathtofile1./pathtofile2..../pathtofilen 4. Commit the changes to the index: $ git commit After execution of this command, a text editor will open and prompt you to comment on your changes. This can be very helpful if done properly, as it is then possible to track when something was changed. If you commit relatively small steps separately, you can then easily revert single steps if needed. On most systems, the text editor vi will be opened to write the commit message. This editor takes some time to get used to, but it is very powerful. The key sequence 3
itext <ESC >:wq < ENTER > adds the text TEXT and executes the command. Here, <ESC> and <ENTER> mean that you press the Escape and Enter keys, respectively. 6. The changed index is sent to the master repository: $ git push Now the committed changes are in the master repository and thus visible on your homepage. In a more compact form: $ git pull $ git add./ PATHTOFILE1..../ PATHTOFILEn $ git commit $ git push An example for the work flow can be found at the end of this document. Be careful on what you add to the master repository! All files added in this way are open to everyone who knows the file name. 3.3 Remarks You will often make several changes at once and only commit everything later. In this case, steps 3 and 4 can be done at the end. This summarizes all changes which belong together into one new single step for the index. Of course, this can repeated for other changes. If you work with others on the same repository, step 1 should be invoked often to avoid conflicts. These conflicts can usually be resolved easily through merging the different changes, but it is still easier to keep your local repository synchronized often. git is a versioning software and is much more powerful than what is listed here. You can find a manual online at https://metaphor.ethz.ch/x/man/ git/. Many other useful commands like git revert, git rm, git mv are explained there. For example, the latter two are used to delete or rename files from the repository. Another useful command is git status which lists all files which were changed. 4 The Directory src Interested users can request a so called source repository. It contains more tools to work with documents for the lecture. For example you can save exercises, scripts and exams in this repository to keep them in a secure place on an ETH server. Also, you can submit your online MC questions directly through such a source repository, no need for writing emails anymore. 4
5 Further Comments If you want to know how Heinz Rasched automatically filled your HMTL page with data and are interested in expanding this software, you are welcome to contact us. Any improvement is for the good of all current and future lecture organizers! General feedback and requests can be sent to Andreas Steiger: andreas.steiger@math.ethz.ch 5
6 An Example We want to add exercise sheet 15 to the website of the lecture 401-1151-00L. Figure 1: Go to the local repository and synchronize Figure 2: Save sheet 15 locally in the right directory. (Here, the original file was located at./../../s15.pdf, but that depends on your set up, of course.) Figure 3: The homepage before changing it. 6
Figure 4: Open and edit index.htm to add the new sheet. Figure 5: The entry for sheet 15 was added and a typo got corrected. Figure 6: Using git status one can see which files were changed locally and thus should be added to the index. 7
Figure 7: Using git add serien/s15/* we add the directory serien/s15 and all of its contents to the index. Using git commit we save the new status of the index. Figure 8: The command line after executing git commit: Depending on the settings, another text editor opens (in this case, vi), with which we comment on the changes. Figure 9: In the next step we add the changes for index.htm to the index: The new sheet 15 was linked. 8
Figure 10: We write a corresponding commit message (with a typo in typo ). Figure 11: Using git push we submit the changes to the master repository. Figure 12: The section of the website after using git push. 9