# How to create an XML language and its XML editor in 5 minutes

## Introduction

This tutorial explains how to create a configuration file for Jaxe including the XML language, the menu to insert the XML elements, and the way XML elements are displayed. It also gives an example of an XSLT stylesheet. The example has been used to create the file you are just reading.

## Creation of the configuration file

Configuration files are located in Jaxe's `config` folder, and their names end with `_config.xml`. For instance, the configuration file for configuration files (whose root element is CONFIG_JAXE), has the name CONFIG_JAXE_config.xml. We start this tutorial by launching Jaxe, choosing the button "New", and selecting "CONFIG_JAXE - Jaxe configuration".

There are two ways of creating a configuration file for Jaxe :

- Using an XML schema to define the XML language to use, and defining just the menus and the method to display elements in the configuration file. In this case it is possible to create automatically a basic configuration file from the schema, by opening the schema file and using the export menu.
- Defining an XML language with a simplified syntax within the configuration file.

We will use in this tutorial the simplified syntax, which only allows to define elements, their attributes, the sub-elements, and which elements can contain text. If we were using an XML schema, we would instead simply link to the schema file.

## Definition of the XML language

We start the definition of the configuration's XML language by inserting an element `Language` under `Jaxe Configuration`. Inside the `Language` element, we choose to insert a `Simple schema` element to define the XML language within the config file.

All the elements in the XML language have then to be defined. Let's start with the root element, which we will call `TUTORIAL`. We insert an `Element` element under `Simple schema`, and give its name and specify it cannot contain text (other elements inside will contain text, but not the root element) (be careful not to use spaces in element names).

We then specify which elements will be authorized under `TUTORIAL`. In this case, we are planning to add the elements `TITLE` and `SECTION`, so we add a reference to them as sub-elements.

These elements `TITLE` and `SECTION` now have to be defined. We proceed in the same way, and authorize text under `TITLE` but not `SECTION`.

Here is the list of the elements we will define, with the possible sub-element :

- `TUTORIAL`
  - `TITLE`
  - `SECTION`
- `TITLE`
- `SECTION`
  - `TITLE`
  - `PARAGRAPH`
  - `LIST`
  - `IMAGE`
- `PARAGRAPH`
  - `TITLE`
  - `EMPHASIS`
  - `CODE`
  - `LINK`
- `LIST`
  - `LI`
- `LI`
  - `LIST`
  - `EMPHASIS`
  - `CODE`
  - `LINK`
- `IMAGE`
- `EMPHASIS`
- `CODE`
- `LINK`

Some elements will have attributes, which will will define with the `Attribute` element.

- `IMAGE` will have an attribute `file` (required) to specify the image file.
- `LINK` will have an attribute `href` (required) to specify the link URL

Text will be authorized under : `TITLE`, `PARAGRAPH`, `LI`, `EMPHASIS`, `CODE` and `LINK`.

To avoid repeating elements mixed with text in the sub-elements for `PARAGRAPH` and `LI`, we can define a set containing the elements `EMPHASIS`, `CODE` and `LINK`, and add this set instead of the 3 sub-elements in the elements `PARAGRAPH` and `LI`.

We can notice at this point that the `Language` element shows up in orange, which means it is not valid. Indeed, it is required to specify at least one possible root element for the language (this is required even when the language is specified with a WXS schema instead of the simplified schema). In our example, the root is `TUTORIAL`. So we add that with the `Root` element in the config file, just avec `Simple schema`.

Here is what the language definition looks like in Jaxe at this point :

## A rough editor...

Once the XML language is defined, it is already possible to edit documents with it in Jaxe... but the edition interface is not great : there is no menu for the language, all the elements are displayed in the same way, etc...

The difference between Jaxe and a random editor is that it is possible to configure the interface for the chosen XML language. This is what is coming up in the following steps.

It you've reached this point in the tutorial, you can still do a little test : choose the menu "Open configuration..." in Jaxe, and select your new configuration file (another way to do it is to move the configuration file to the `config` folder, to choose "New...", and to select the root `TUTORIAL`). The 3 left side panels are already working : we can see the list of the elements that can be inserted at a given position, the tree of the document, and the current element's attributes. It is also possible to insert elements with the contextual menu.

## Definition of the menus

When an XML language has many elements, it becomes important to organize them, so as to insert them more easily than with a list of 100 elements in alphabetical order : this is the objective of the insertion menus in Jaxe.

We will prepare insertion menus for all the elements in the language (except the root which is automatically added to new documents), by organizing them into 3 menus : Structure, for the organization in the document, Blocks for block elements (that are not mixed with text), and Text for the elements that can be mixed with text. We can use the occasion to specify keyboard shortcuts to quickly insert frequently used elements : p for `PARAGRAPH`, and t for `TITLE`.

This is what we get :

## Elements display

This section might be the most important one for Jaxe : it relates to the definition of the way elements will be displayed and edited in Jaxe. There are a number of display types, defined in detail in the syntax documentation. The default display type is `string` : it just displays a start tag and an end tag to surround the content of the element, without any automatic indentation.

Here are some display types we can choose for the tutorial :

- `TUTORIAL` : `division`
- `TITLE` : `string`
- `SECTION` : `division`
- `PARAGRAPH` : `area`
- `LIST` : `list`
- `LI` : `item`
- `IMAGE` : `file`
- `EMPHASIS` : `string`
- `CODE` : `string`
- `LINK` : `string`

The `file` type, for instance, will automatically display the image linked by the `IMAGE` element. In order for Jaxe to know which attribute is linking to the file, we have to add a parameter to the element display : in this case, we have to use a parameter with the name `srcAtt` and the value `file` (the name of the attribute linking to the file).

Other parameters can be used to get a pleasant editing interface : "`style`" "`GRAS`" (bold) for the `TITLE` element, "`style`" "`ITALIQUE`" (italic) for the `EMPHASIS` element, and "`police`" (font) "`MONOSPACED`" for the `CODE` element.

Here is how this part of the configuration looks in Jaxe :

## Exports

All these things let us create beautiful XML files, but they are not very useful as such. We still have to export them to other languages, such as HTML to get web pages. To do that, we add to the config file an `Exports` element which contains an `Export` with the `HTML` output. Inside, we link to an XSL file defining the transform from our language to HTML. This XSL file can be created with Jaxe, with the "XSLT" configuration (see below to find how).

The addition of an HTML export in the config will provoke the activation of the HTML Window menu in Jaxe's Windows menu. The transform will occur every time the menu is called, and every time an update is asked by the user.

## Strings

The interface we get at this point is usable, but we can wish to go further with displayed texts, to :

- choose a text displayed in Jaxe's "New" dialog
- change the menu titles
- change the titles of the elements on the tags when they are displayed in Jaxe
- add a documentation for each element, easily available to users
- change the title of the attribute values
- do all this in several languages without having to change the schema (the language being automatically chosen for the user depending on the selected language in his operating system)

All of that can be done with the `Strings` element. In this tutorial, we will just define a little text displayed in the dialog for creating a new document, with `Configuration description`.

## Tutorial file

Here is the full configuration file for this tutorial : TUTORIAL_config.xml

If we had used an XML schema separate from Jaxe configuration file, we would have specified its path with the `XML schema file` element instead of using `Simple schema`. Here is the files we would get by doing it like that : TUTORIAL2_config.xml - TUTORIAL2.xsd.

## Creation of the stylesheet

An XSLT document is created by choosing the "New" menu and selecting "stylesheet - XSLT". XSLT files mix several XLM languages in a document, and we see here the menus for XSLT together with the menus for XHTML.

The XSLT version should be defined with the value "1.0" for the attribute `version` of the root element. The transformation output has also to be defined. For instance, to obtain XHTML, `xsl:output` is used with the attributes :

- `doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"`
- `doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"`
- `encoding="ISO-8859-1"`
- `indent="yes"`
- `method="xml"`

In general, an HTML equivalent can be defined for every element. For instance, to display `CODE` as with `tt` in HTML, we use an XSLT `template` element with the value "CODE" for the `match` attribute, we insert inside the HTML `tt` element, and we apply the other rules recursively inside with the XSLT element `apply-templates` :

Here is the finished XSL file.

## Top chrono!

Finally, we just need to choose the "Open configuration..." menu and to select our configuration file, `TUTORIAL_config.xml`, to create a new document with it. We could also move the configuration file to Jaxe's `config` folder, so that it appears in the list when a new document is created with the "New" menu.