Ximera documents can be glued together using the xourse document class. A xourse file is basically a list of other ximera files and even other xourse files. These are included via the commands \activity (for Ximera files with \maketitle) or \practice (for Ximera files without \maketitle). The xourse file for A First Step in Ximera can be found at the top level of the GitHub repository ximeraFirstSteps here

The xourse document class specifies information such as the name of the document, the names of the authors, a description of the content, a license, and the names of all Ximera LaTeX files comprising the whole document via \activity and \practice.

You may have multiple xourse files per repository. They may be nested inside folders. However, the xourse document will only be easily accessible online if it contains a title, abstract, and ∖maketitle command.

If a xourse does not contain a title, abstract, and ∖maketitle it will still be deployed but you will need to know the path to the file. It will be something like:

It is important that there is no trailing ‘/’ as

• https://ximera.osu.edu/moooculus is correct but
• https://ximera.osu.edu/moooculus/ is not.

1 File structure

While one can write a Ximera document without the use of folders, this quickly turns into a mess that is difficult to understand and should only be used for the most basic Ximera content. To help others (including your future-self) work with larger projects, you should have a file structure that helps developers understand where content is stored. We recommend the following:

Group by concept

by having all documents that are closely related in idea or scope in the same folder. If someone else wants to use your content, this will be a one-stop destination for them.

Descriptive file names

will help you and others understand the structure of your repository. Give you documents descriptive file names like: completeTheSquare.tex or derivativeRules.tex rather than generic names like: chapter1.tex, or math872ch2sec3.tex. Authors find themselves reordering their content and generic names are useless for other users.

A consistent and well thought out set up will allow you and others to easily understand and modify your content for years to come. Ideally a document’s parent folder would contain everything that document needs to compile.

For the repository ximeraFirstSteps we have the following structure:

We’ve left some files out of this diagram; regardless, you should be able to go to

and witness this file structure. At the top level of the repository, we have the documents xmPreamble.tex and aFirstStepInXimera.tex along with the folders aFirstFolder and aListOfExercisesFolder. Inside aFirstFolder, we show two activities. Inside aListOfExercisesFolder we have all the practice exercises.

2 Including with ∖activity and ∖practice

Once you have some files and a basic directory structure, you can add them to the xourse document.

There are two different commands we use to add ximera documents to a xourse file:

∖activity

is for including Ximera documents that include a title, abstract, and ∖maketitle. They will be represented by their title online. This command is typically used for worksheets and sections of textbooks.

∖practice

is for including Ximera documents that do not include a title, abstract, and \maketitle. They will be represented by a number based on their order in xourse file. This command is used for lists of exercises and problem banks.

In aFirstStepInXimera.tex we write

\documentclass{xourse}
\author{Wim Obbels \and Bart Snapp}
\title{A First Ximera Xourse}
\begin{document}
\begin{abstract}
    A very simple collection of Ximera activities,
    to be deployed online.
\end{abstract}
\maketitle
\part{The First Topic of This Course}
\chapterstyle
\activity{aFirstFolder/aFirstActivity}
\sectionstyle
\activity{aFirstFolder/exercises/someExercises}
\chapterstyle
\activity{aFirstFolder/aGraphicsActivity}
\end{document}

Note, no preamble is required, since xmPreamble.tex is automatically loaded. Also note how we give the paths to the exercises, it’s the folder name, followed by the document name. The .tex can be left on if you like.

2024-12-23 16:29:47