# The XPAGES language

Author: Damien Guillaume

- Introduction
- Documents structure
- Informations
- Block elements
- Elements mixed with text
- Exercises

# Introduction

XPAGES provides a way to create websites quickly and easily. XPAGES is based on the principle of separation between content and presentation : with XPAGES, the content (text, images, animations) is entered, and is structured with a meaning associated to each part. An author does not worry about the way content will be displayed later on, which saves time and avoids mixing meaning with presentation. The way content will be displayed is specified separately, with stylesheets. Thus, it is possible to change the display independently from the edition.

XPAGES is an XML language, i.e. a set of elements and rules designed to structure a text. Associated stylesheets can automatically transform XPAGES documents into HTML files so that they can be viewed on the web. XPAGES documents can be edited with Jaxe and WebJaxe thanks to a configuration file describing the edition user interface.

XPAGES is a very simple language, easy to learn : it features only 59 elements (46 without the exercises), to compare for instance to the 91 elements in HTML, 390 elements in DocBook, or 526 elements in OpenDocument.

# Documents structure

XPAGES documents have a root element, `XPAGES set`, that is used in all the documents as a first level element. Under this element, the following elements can be found : `Informations`, `Page`, `Ref. XPAGES document` and `XPAGES set`.

- `Informations` is a metadata block, i.e. informations about the document. It is described later on.
- `Page` represents a web page, and has a title and a label used to create links to the page.
- `Ref. XPAGES document` is a reference (via the label) to another XPAGES document, that will be included in place of the `Ref. XPAGES document` element. This is used to create a website with several levels : for instance, one can create a website with a home page, and several sets of pages. To do that, an XPAGES document is created for the website, containing the home page and `Ref. XPAGES document` references to the different sets of pages in the website.
- `XPAGES set` under `XPAGES set` can be used to add another level to the tree, as with `REFXPAGES`, but without creating a new document.

Inside a page, sections can be created with the `Section` element. This element has a title, a role that specifies the meaning of the section and can result in a different display for each function, and an importance that can be used to highlight the section if it is important.

The text is added inside paragraphs, with the `Paragraph` element. It is easy to insert a new paragraph with the command-P or control-P shortcut in Jaxe.

It is possible to create several contributions, each one containing an XPAGES XML file and the associated files (images, Java applets, ...). Each contribution corresponds to a folder whose name is the same as the label given in the `Informations` block in the XML file. This folder contains the XML file and the associated files.

# Informations

The information block provides information about the document, and is also used to choose a skin for the generated website. It is required, and is located at the beginning of the document. It has the following children :

- `Label` : a name used later to reference the document with the `Ref. XPAGES document` element, to include the content of the document in a larger one. The label is required, and must match the name of the XML file without the ".xml" extension. In WebJaxe, this label must simply be the name of the contribution.
- `Title` : the document title (required).
- `Author` : an author of the document. It is of course possible to specify several authors.
- `Author` : the creation date of the document, with the syntax `DD/MM/YYYY`.
- `Update date` : the update date of the document, with the syntax `DD/MM/YYYY`.
- `Logo` : path to an image file with a logo to use on the website. The image must be in a standard format for the web (JPEG, PNG or GIF). It is possible to specify a link to use when the logo is clicked.
- `Interface` : choice of a skin for the pages.
- `Menubar` : to choose whether or not to display the buttons on top of web pages to navigate to the subsets referenced with `REFXPAGES`.
- `Language` : the code for the document language (`en` for English).

# Block elements

Block elements are XML elements that can be directly inserted inside a `Page` element. They are used to structure the document, but are not mixed with text : it is not possible to insert text directly under `Page`, because text must necessarily be inside a block element.

XPAGES has the following block elements :

- `Section` : used to identify an area inside a page, with a title, a semantic role, and an importance. The role is optional, but is important to give meaning to the different parts of the document. It can also be used later to display sections with the same role in a similar way, to visually distinguish them from other sections.
- `Paragraph` : a paragraph is one or several sentences. To do a "line break" (this idea is quoted because it is related to presentation instead of content), it is necessary to create a new paragraph.
- `List` : a list of `List item` elements. Items can contain text, but also paragraphs or sublists.
- `Table` : a table is formed with a given number of lines and columns. It is possible to specify a line of titles (the first line of the table). Also, cells can be merged, and an alignment can be specified inside the cells.
- `Image environment` : an element grouping the informations related to an image (copyright and legend), and a link to the image file. It is also possible to create a link on the image, so that a click on it redirects to another part of the site or an external page.
- `Java applet` : a Java applet, for instance for interactive simulations.
- `Flash object` : a Flash object, that can also be used to add interactivity to the website.
- `Comment` : a comment of the author, that will not be displayed on the website. Very useful for instance to mark parts to develop or correct at the time of writing.
- `Code` : a block of computer code whose formatting must be preserved.
- `Exercise` : an exercise (see later).
- `Quiz` : a quiz (see later).
- `Bibliography` : a list of bibliographic and webographic references.

# Elements mixed with text

Some XPAGES elements can be mixed with text, for instance inside a paragraph. They are the following elements :

- `Link to internal page` : link to a page on the same website. To identify the page to link to, the label of the contribution and the label of the page have to be entered. If only the label of the page is given, it is assumed to be in the same contribution. If only the label of the contribution is given, the link directs to the first page in this contribution.
- `External link` : link to a web page external to the website. The address (URL) must start with "`http://`".
- `File` : an image or animation file. Normally used inside an `Image environment` element, so that a legend can be specified, but it can also be used within the text (for instance to include a symbol that could not be created with an equation).
- `Symbol` : greek letter or mathematical symbol.
- `Equation` : equation based on Jaxe's equation editor syntax.
- `TeX Equation` : equation based on the TeX syntax.
- `Glossary word` : word to include in the glossary. The word to display is specified with the `word` attribute, and the definition for the word is given within the `Glossary word` tags.
- `Emphasis` : emphasis (to highlight one or several words).
- `Superscript` : superscript text
- `Subscript` : subscript text
- `Code` : computer science code (usually displayed with a monospaced font)
- `Non-breaking space` : non-breaking space

# Exercises

XPAGES can be used for many applications, but it is especially handy to create online courses, and was created in this context. For these reasons, the language contains elements specific to the definition of exercises, even though these elements might not be useful outside of the context of online courses.

There are two types of exercises : the question-answer type (`Exercise` element), and the quiz type (`Quiz` element). In both cases, an exercise can have a title (`title` attribute), an indication of the difficulty (`Difficulty` element), an indication of the time necessary to complete the exercise (`Time` element), and questions (`Question` and `Quiz question` elements).

Each question can have terms (`Terms` element) and one or more helps (`Help` element). Questions of type question-answer have a solution (`Solution` element) and a number of points that can be granted if the answer is correct (`Points` element). Questions of the quiz type have possible answers (`Quiz answer` element), each answer being either right or wrong (`correct` attribute), with the text of the answer (`Answer text` element) and a comment which will be displayed to the user should he choose this answer, for instance to explain why the answer is wrong (`Answer comment` element).

In Jaxe, solutions for evaluation exercises are not added to HTML when the "public website" is generated. They are added when the "production website" is created. WebJaxe always creates the production website. To create a public website from a contribution in WebJaxe, the contribution has to be exported and opened with Jaxe. In this way, it is possible to create, from the same XML files, a website for students, and another one for tutors for an elearning program.