Setting up a Ximera course

Now that you can create a course. A Ximera course consists of a directory (anExampleCourse) containing a set of directories (theFirstActivity, theSecondActivity) that all contain LATEX files using the ximera document class. This directory also contains one or more LATEX files using the xourse document class, each of which is a launch page for the activities in the course(s). This section describes how to create a course.

(a)

In this example, we will create a directory called anExampleCourse that contains a directory called theFirstActivity. We will also create the anExampleCourse.tex file. Open a terminal session and type the following commands to do that.

     mkdir anExampleCourse
      
cd anExampleCourse
      
mkdir theFirstActivity
      
touch anExampleCourse.tex
     

(b)

Next we will modify the anExampleCourse.tex file in the (anExampleCourse) directory. Click “Files,” click on the (xandbox) directory and click on the (anExampleCourse) directory, then click the file anExampleCourse.tex. Copy and paste the following in the left-hand side of the window and click “Save.” It may complain that you haven’t created the theFirstActivity.tex file yet, but that’s fine.

    \documentclass{xourse}
      

      
\title{An example course}
      
%% This is the Name of your course
                                                                  

                                                                  
      
%% personalize it
      

      
\begin{document}
      
\begin{abstract} %% This describes your course
      
This is a Ximera activity explaining how to get
      
started with Ximera for course instructors.
      
\end{abstract}
      
\maketitle
      

      
%% Here we have a listing of the activities.
      
\activity{theFirstActivity/theFirstActivity}
      

      
\end{document}
     

Now return to the terminal window, which should still be in the directory theExampleCourse. You need to add the file (and the directory containing it) to git and commit your changes, and also tell it who you are.

      
git add anExampleCourse.tex
      
git commit -m "this is my first course"
     

Every time you add or change files, you will need to run git add and git commit -m "short description of changes" to commit the changes to the server. The description of changes is necessary to commit, as is the  -m. If you are changing multiple files, you can use git add *.

In general the file with the xourse document class specifies course information such as the name of the course, a description of the course, and the names of all LATEX activity files comprising the course, in the order they should be presented to students. In addition to a name and a description, anExampleCourse.tex above specifies that there is one activity file theFirstActivity.tex, written with or without the extension .tex, and located in a directory called theFirstActivity. We will create this file and directory in the following step.

Generally courses should contain more than one activity. We recommend placing each activity in a directory of the same name. This facilitates sharing activities among collaborators and makes reusing existing activities easier. We also recommend that the directory and the LATEX file have exactly the same name as the title of the activity, with all spaces removed and all words other than the first word capitalized. So for example, if the title of the activity were Plants native to Ohio the LATEX file plantsNativeToOhio.tex would be located in a directory called plantsNativeToOhio.

(c)

Now create your first activity. In your terminal, move to the theFirstActivity directory and create a file called theFirstActivity.tex. This can be accomplished by executing the commands below.

      
cd theFirstActivity
      
touch theFirstActivity.tex
     

(d)

Click “Files” again and navigate to the (theFirstActivity) folder, open theFirstActivity.tex, and paste in the following text. Then save the file.

    \documentclass{ximera}
      
\title{The First Activity}
      
\begin{document}
      
\begin{abstract}
      
This activity deals with Ximera activities.
      
\end{abstract}
      
\maketitle
      
\end{document}
     

An activity should be composed as a regular LATEX file in the document class ximera. It should contain the title of the activity and an abstract. These will both appear on the course website in the navigation area, so the abstract should be short. At this stage your activity contains a title and an abstract, but is otherwise blank.

(e)

Now add this file to git and commit your changes. Back in the terminal, change to the directory anExampleCourse and execute the following commands

                                                                  

                                                                  
     git add theFirstActivity.tex
      
git commit -m "Added first activity file"
     

(f)

Type xake bake to compile the tex documents, then xake frost to create a publication commit on top of your source commit. Finally type xake serve to share your content with the world. For instance, my content will appear at https://ximera.osu.edu/turnloon/anExampleCourse

(g)

This is a good point to add some further content in the form of a simple exercise. Update the file theFirstActivity.tex you created above so that it looks like the following.

    \documentclass{ximera}
      
\title{The First Activity}
      
\begin{document}
      
\begin{abstract}
      
This activity deals with Ximera activities.
      
\end{abstract}
      
\maketitle
      
This activity is about creative work.
      
\begin{exercise}
      
  Choose the best place to work on mathematics.
      
  \begin{multipleChoice}
      
    \choice{At the library}
      
    \choice[correct]{At the caf\’e}
      
    \choice{In your office}
      
  \end{multipleChoice}
      
\end{exercise}
      
\end{document}
     

The edits above insert a multiple-choice question into the theFirstActivity activity. See the Question and answer types activity later in this tutorial for more information on creating exercises.

(h)

Change to the directory anExampleCourse and execute the following commands.

                                                                  

                                                                  
     git add theFirstActivity.tex
      
git commit -m "Added an exercise"
      
git push
      
xake bake
      
xake frost
      
xake serve
     

If everything went well, you should see a URL printed on the terminal. If not, see the Troubleshooting activity in this tutorial or send your questions to ximera@math.osu.edu.

The commands above inform git that changes have been made to your repository and communicates them to github.com which in turn communicates them to ximera.osu.ed. You should execute similar commands whenever you change files in your repository.

Creating further activities

From here you can create further Ximera activities as in step ??. You should issue a git add command after creating a new file or directory and a git commit command followed by a git push command periodically to transmit your most recent changes to github.com. You should also add the name of your activity file to the xourse file in the position relative to other activities where you want the activity to appear. Observe however that once the filename appears in the xourse file the corresponding activity will appear to students. It might therefore be preferable to create a separate branch on GitHub until the activity is ready for students. During the editing phase you still view the activity by processing it with LATEX and inspecting the resulting PDF file, which might be helpful in any case for finding and correcting mistakes.

Other ways to set up a Ximera repository

There are other ways to create a Ximera course. One possibility is to begin by creating the repository on github.com. Then instead of executing the commands to initialize the local copy of the repository, you could clone the copy on github.com using a git clone command. Alternately you could fork an existing repository, either your own or someone else’s. See the git manual for more information about the clone and fork commands. Both possibilities above obviate step ?? since cloning or forking a git repository creates a local directory and initializes it as a git repository.