Instructions for setting up a course.
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} - (h)
- Change to the directory anExampleCourse and execute the following
commands.
git add theFirstActivity.tex
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.
git commit -m "Added an exercise"
git push
xake bake
xake frost
xake serveThe 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.