# Jaxe, your XML editor

Author: Damien Guillaume

- Documentation for end users
  - XML principles
  - Definition of an XML language
  - Launching Jaxe
  - Using Jaxe
  - Jaxe equations syntax
  - Preferences
- Jaxe configuration files
  - Introduction
  - Definition of the XML language
  - File saving options
  - Menus
  - Node display
  - Display types
  - Exports
  - Strings
- Developer Guide
  - Introduction
  - Using Jaxe within another application
  - Creation of new Jaxe elements
  - Adding a function
- The XPAGES language
  - Introduction
  - Documents structure
  - Informations
  - Block elements
  - Elements mixed with text
  - Exercises

# Jaxe, your XML editor

En français

Jaxe on SourceForge

## Features

You're looking for a free XML editor adaptable to your XML language ? Jaxe is the solution. The latest version includes the following features :

- configurable with an XML schema and a configuration file for the graphical user interface
- adapted to structured narrative XML documents
- validation at elements insertion
- multi-platform (Java 1.5+)
- free open-source software
- possible addition of Java modules to add customised graphical interfaces
- exports to HTML, XML and PDF with XSLT and XSL-FO stylesheets
- side panels with a tree view, with the allowed elements at the insertion point, and with the current element attributes
- contextual menu
- multiple undo/redo
- source code display
- complete document validation
- configuration file examples for XML schemas, XHTML strict, Docbook, DITA, XPAGES, and a schema for online presentations
- French, English, German, Russian, Brazilian Portuguese and Spanish localisations (the system language is used by default)
- spell checking with English, French and German dictionaries
- equation editor
- online help based on the XML schema
- XPath search

What Jaxe doesn't do (that is a topic you won't find on commercial websites, but that could save you time!) :

- Jaxe does not let you edit XML files without a configuration file for the language.
- Jaxe is not "WYSIWYG" (What You See Is What You Get), it is "WYSIWYM" (What You See Is What You Mean). As with all good XML editor, display is an operation independant from data input.
- Jaxe is not a Java applet: it cannot be used in a web browser. It is however possible to include the XML edition pane within a Java applet. This solution is used by WebJaxe, a CMS written in PHP and based on XML document edition with Jaxe in a Java applet.
- Jaxe does not support all the features of XML schemas. To know exactly what Jaxe supports, look at the file config/SimplerSchema.xsd: it's a subset of the schema for schemas including what Jaxe understands. In the latest version, nearly all features are there. One example of a missing feature is real-time validation for `xs:all`.
- Jaxe does not handle well very large XML documents. The reason is that it uses Java Swing components in memory to display XML elements, in order to facilitate the creation of new displays for XML elements. The trouble is, these components use a lot of memory.

## Required configuration

An OS (Mac, UNIX, Windows or other) with a recent Java version (at least 1.5). To test your OS Java version, you can type "`java -version`" under the command line.

## Installation

- Download Jaxe (there are versions for Mac, Windows, and UNIX/Linux)
- Extract the Jaxe folder. This usually just requires double-clicking on it on MacOS X, or right-clicking on it and choosing "extract here" on Windows, but it could be necessary to use for instance Stuffit Expander, or the command "`tar xvzf jaxe.tar.gz`" on UNIX, or 7-Zip on Windows.
- Move the resulting folder on the hard disk, for instance in `/Applications` on MacOS X, or `Program Files` on Windows.
- In the jaxe folder, type "`./jaxe.sh`" on UNIX, or double-click on the application on MacOS X or Windows.

## How to use Jaxe

Jaxe can be used as an administrator, to define a configuration file for a given XML language, or as an end user with the administrator's configuration files. Developers can also add Swing components to display elements, or use Jaxe within other applications.

- user's guide
- administrators: configuration files syntax, short example
- developer's guide

## Screenshots

Jaxe

This screenshot shows the insertion panel on the left, the language menubar on top, and the XML area. XML elements are displayed in different ways, depending on what they represent: for instance, an element representing an image is displayed as the image itself.

An application using Jaxe, by Bodo Tasche

This second example shows Jaxe integrated inside another Java appliation, with custom element displays.

## Public Forums

Help - Open Discussion

## Licence

GPL

## Authors

- Damien Guillaume
- Bodo Tasche
- Oliver Kykal
- Cyril Dedieu
- Léa Guillon
- Bertrand Delacretaz
- Sven Kitschke

## Official tester

- Gilles Bessou

## Packages used by Jaxe

- Xerces (until Jaxe 2.3, and also starting with Jaxe 3.4)
- Xalan (until Jaxe 2.3, and also starting with Jaxe 3.0)
- Jazzy
- Oro or Regexp (until Jaxe 2.3)
- PngEncoder (until Jaxe 2.4)
- JEuclid
- JSmooth or launch4j
- FOP (starting with Jaxe 3.0)
- Jing (starting with Jaxe 3.2)
- Saxon (starting with Jaxe 3.4)
- XSLTC (starting with Jaxe 3.4)

## New versions

Release notifications no longer exist on sourceforge. It is no longer possible to be informed by email of new versions of Jaxe. Instead, it is possible to use an RSS feed.

## Contributions

Jaxe is progressing with everybody's help. If you have enhanced Jaxe (for instance by localising it for another language, or by creating a plugin to edit certain data types), please don't hesitate to make your files available.

This website has been created with Jaxe and XPAGES.

# Documentation for end users

Author: Damien Guillaume

# XML principles

XML is a syntax, but it is mostly a philosophy in writing documents, which consists of describing the meaning in an explicit way as opposed to the presentation. One would write, for instance:

    <TITLE>XML</TITLE>

instead of:

    <BOLD><ITALIC><CENTER>XML</CENTER></ITALIC></BOLD>

This principle allows both automatic data processing (like the extraction of all the titles to build a table of contents), and the possibility to define several displays for the same content (like a web display and a paper display).

Since the content is well separated from the presentation, XML editors like Jaxe are not WYSIWYG ("What you see is what you get"). People used to word processors like Word have to be careful not to use styles such as bold or italic when it is possible to convey the meaning of the content instead. It is also important to not rely on the preview because there can be several ways of displaying the content. It is better to use elements corresponding to paragraphs or sections rather than line break elements, because the space between paragraphs can depend on the display and be a little less or a little more than a line.

# Definition of an XML language

An XML language is defined formally, so that an automatic syntax check is possible. This formal description includes the names of the elements in the language, the allowed element nesting, the order of the elements and their attributes (attributes being optional or required).

Jaxe makes the creation of XML documents easier by using the language rules to suggest elements to insert wherever possible. This makes the creation of valid documents (i.e. conforming to the language rules) much easier than with a simple text editor. This introduction is general for all XML languages, but each end user has to learn one or more specific XML languages which are not detailed here.

On top of the files describing XML languages (the schemas), Jaxe uses configuration files to define the menubar and the way to display elements. These files are located in the `config` directory, and their names end with `_config.xml`.

# Launching Jaxe

Jaxe requires Java 1.5 or later. To know what version of Java is installed, type `java -version` in the command line.

Jaxe is launched in different ways depending on the OS. On MacOS, it is done with a double-click on the application, which is located in the Jaxe directory. On Windows, Jaxe is launched with the Jaxe.exe executable or with the run.bat script, and on UNIX with the run.sh script. These scripts can be modified to define a default configuration file.

On Windows it is possible to run the script `assocXMLJaxe.bat` to associate the "`.xml`" extension to Jaxe. This lets you open XML files directly by double-clicking on them. This script only works if you have the rights to change file associations, so you have to be an administrator.

On MacOS X you can choose Jaxe rather than another program to open an XML file with a double-click by choosing the "Get Info" menu for an XML file, choosing Jaxe in "Open with", and clicking on "Change all" so that all XML files open with it.

It is also possible to launch Jaxe with the scripts `jaxe.bat` and `jaxe.sh`, by adding the name of a file to open, for instance by typing `./jaxe.sh test.xml`.

Jaxe loads XML files in memory, and it can be difficult when they contain lots of large images. It is possible to increase the memory alloted to Jaxe, depending on the OS:

- on Windows and UNIX, by modifying the file run.bat or run.sh: replace `java` by `java -Xms128m -Xmx512m` to specify 128 Mb of initial memory and allow a maximum of 512 Mb.
- on MacOS, edit Jaxe/Jaxe.app/Contents/Info.plist, and add the lines `<key>VMOptions</key>` and `<string>-Xms=128m -Xmx=512m</string>` after the lines `<key>Java</key>` and `<dict>`.

Jaxe uses by default the OS language, but in Jaxe 3.4 only French, English, German, Brazilian Portuguese, Russian and Spanish have been defined. If the OS is using another language, Jaxe is using French. To change the language used, just add the option `-Duser.language=xx` after the command `java` in the scripts, or as the value for the Info.plist key `VMOptions` on MacOS X. `xx` is a code corresponding to the language, for instance `en` for English.

# Using Jaxe

## Configuration files

At startup, Jaxe opens a new XML document with the default configuration if there is only one configuration file. If there is more than one, a dialog is displayed to choose a configuration file corresponding to an XML language. To check that the XML language in an opened document is the one you want to use, just look at the menus: the elements menubar is located under Jaxe menus (which are on top of the screen on MacOS). If it is not the right language, choose a configuration file with the Open configuration... menu. When an XML file is opened, Jaxe is automatically using the configuration file corresponding to its XML language (when it exists).

Jaxe includes example configuration files for XHTML strict, Docbook, simplified Docbook, XPAGES, and an XML language for presentations. Your administrator has normally prepared another configuration file for the XML language you will use.

## Elements display

XML elements can be displayed in many different ways in Jaxe, and it is even possible to create new display types. The way elements are displayed is defined in Jaxe's configuration file for the chosen XML language. However, some display types are more popular than others. A classic display type consists in a start tag, followed by the element content, and finishing with an end tag. For instance, a date can be displayed like that :

With this display type, when an element has attributes, buttons appear on the tags to allow their modification in a dialog. If validation icons are activated in the preferences, the tags also contain an icon indicating if the element is valid or not (an element can for instance be invalid if required sub-elements are missing inside). These icons are however not indispensable, because the tags also change of color when an element is invalid.

Other display types are for instance lists, tables, images (for elements linking to image files), or forms.

## Elements insertion

When a configuration file is opened, Jaxe prepares a new document, and automatically inserts the root element (when XML documents have only one root element), displaying a dialog for its attributes if it has attributes. The menubar corresponds to the elements in the XML language, and can be used to insert elements. Another way to insert elements is the insertion panel, which appears on the left of the text area. It gives a list of the elements that can be inserted in the text where the cursor is. This list can also be obtained with the contextual menu, which is opened on the Mac with a control-click, or with a right click with a multi-button mouse. It can also be displayed by typing cmd-D (on a Mac) or ctrl-D (Linux/Windows), in order to avoid moving the hands off the keyboard.

It is also possible to insert an element around a text or a set of elements already entered. This is done by selecting this set, and inserting the element as would be done normally.

## Elements removing

To remove an element, place the cursor after one of the tags (or another graphic object if the element is not displayed with start and end tags) and press the delete key. Be careful, this deletes the whole element, with everything inside ! In case of catastrophe, do not forget the cancel menu.

## Attributes

Some elements have attributes (i.e. a set of name/value strings). When a new element with attributes is inserted, a dialogue is displayed to choose the attribute values. To change them later, just click on the start tag's attribute button, or place the cursor within the element and look at the Attributes panel. Optional attributes have a name in green, while required attributes are in red.

## Images

Many XML languages have elements corresponding to images. With these XML languages, it is possible to paste an image in Jaxe, which creates automatically the image file in the same directory as the XML file, and creates an XML element with the reference to the new image file. The attributes dialogue for image elements has two more buttons, Select a file... and Copy a file.... These buttons are used to select a file and (with the copy button) to copy the image file near the XML file. It is better in general to avoid absolute references to files, such as `/Users/toto/x.gif`, and to use paths relative to the directory containing the XML file instead. It is good to create a directory for each XML file, and to create a directory inside to contain the image files referenced by the XML file. The reference to the image file then becomes `images/x.gif`.

## Equations

Jaxe features a simple equation editor, to easily insert and modify equations. It opens with elements corresponding to equations. The editor has two areas: one at the bottom, where the equation is written as simple text, and one at the top, where the the graphic representation is displayed bit by bit.

For instance, when `sqrt(2)/3` is typed, the equation's image is displayed : . The editor syntax is described in the next page.

## Search and replace

Words in the text can be found and replaced with the Find menu in the Edit menu. It is possible to do advanced searches with the XPath syntax to select XML element with their name and their attribute values. It is not necessary to know XPath to use this feature: a sub-dialog can be used to build simple requests. It is for instance easy to search for a `SECTION` element with a given `title` attribute.

## Spell checking

Jaxe includes the Jazzy spell checker. Before using it, make sure you have downloaded a dictionary and moved it in the dicos directory. The British English dictionary is made up of two files, `British.dico` and `British.phon`. Then, select a dictionary with the preferences by choosing the `.dico` file. You can then use the Spelling... menu in the Edition menu.

## Displaying source code

It is possible to display the XML file source code, as it will be saved, with the XML source menu. The XML source window is not editable so as to avoid update problems.

## Validation

Jaxe creates valid XML files, but it is possible to prepare an XML file that is not yet valid (because a required element has not yet been added, in which case the parent element is displayed in orange), or to open an invalid file. In this case, it is possible to start a validation, which is done based on the XML schema (the validation is not useful when the simplified syntax has been used to define the language). This can be done with the Validation menu. When there are errors, they are displayed in a list, and a click on an error shows the location in the XML window.

## HTML preview

An HTML preview can be created if a stylesheet has been created for the XML language. The preview is generated with the HTML Window menu. It is displayed within Jaxe, but not necessarily well if CSS is used (Java Swing is only able to display HTML 3 so far !). So, it may be necessary to open the HTML file with a web browser, which is done easily with a button on the HTML window after the web browser has been selected in the preferences. In the latest version of Jaxe, the HTML window directly opens in the web brower chosen in the preferences.

# Jaxe equations syntax

Jaxe has a specific equation editor, to add and change equations. An equation is edited in a text area, while the corresponding image is displayed above in real time. The equation images are saved in a folder called equations_myfile within the folder of the XML file myfile.xml.

This editor does not pretend to be exhaustive. Complex equations can be created with another editor and added in Jaxe with a copy-paste.

Here are some rules to follow in order to make the best use of the editor :

- Do not use spaces (they are ignored in the best case).
- Write the equation as if it would be interpreted mathematically and a numerical result would be calculated. As a consequence, always specify the operators, even when they should not be displayed.
- Use parenthesis to specify the order of the operations if it does not match the mathematical evaluation order.

As opposed to many equation editors, this editor analyses the mathematical meaning of the equation. It then builds the image from there. This makes it possible to get uniform graphical results for all equations. On the other hand, it is not possible to specify display constraints, for instance to obtain a little more space between two characters : the user gives the meaning for the equation, and the editor is in charge of finding the best display for it.

- Addition and subtraction

  Operators '`+`' and '`-`'.

- Multiplication

  Operator '`*`', displayed only when two numbers are multiplied.

  Example : `2*3*sin(1.5*pi)` is displayed :

- Division

  Operator '`/`' (displayed as a fraction) and functions '`slash`' and '`fraction`'

  Example : `slash(a;b)/c` is displayed :

- Function

  The parameter separator is the semicolon, to distinguish it from the coma, sometimes used in numbers : `functionname(arg1;arg2;...)`

  Example : `f(x;y)` is displayed :

- Power

  Operator '`^`'.

  Example : `x^y` is displayed :

- Subscript

  Operator '`_`'.

  Example : `x_(ab)` is displayed :

- Subscript superscript

  Function '`subsup`' with the first term, and the elements to display as subscript and superscript.

  Example : `subsup(A;1;2)` is displayed :

- Square root

  Function '`sqrt`'.

  Example : `sqrt(x/2)` is displayed :

- Root

  Function '`root`' with the degree of the root as the second parameter.

  Example : `root(x;3)` is displayed :

- Absolute values

  Function '`abs`'.

  Example : `abs(x^3)` is displayed :

- Power of e

  Function '`exp`'.

  Example : `exp(x^2)` is displayed :

- Integral

  Function '`int`', with 4 parameters: the function to integrate, the integration variable, and the minimum and maximum bounds.

  Example : `int(f(x);x;0;infty)` is displayed :

- Sum and product

  Functions '`sum`' and '`prod`', with 3 parameters: the function to sum up, and the minimum and maximum bounds.

  Example : `sum(ln(k)/k;k=1;10)` is displayed :

- Matrix

  Function '`matrix`', with the lines as parameter as a function '`line`'.

  Example : `matrix(line(1;2;3);line(4;5;6))` is displayed :

- Greek letters

  Variables with the letter name, with an uppercase to the first character of the name to get an uppercase Greek letter.

  Example : `alpha*Delta*thetasym*upsih*piv` is displayed :

- Special characters

  Variable with the name of the special character.

  `sun|star|earth|planck|infin|angstrom|ell|hat|bar|asterisk|bigg|...`

  Example : `M_sun/M_earth=3.329*10^5` is displayed :

- Special operators

  Special code with no space.

  `!=|~=|<=|>=|<<|>>|->|forall|exists|part|nabla|prop|cross|plusminus|cap|cup`

  Example : `forall a exists b<<c~=d>=e!=f` is displayed :

- Accents

  Function '`accent`' with the letter and the accent to add above.

  Example : `accent(AB;->)+accent(ABC;hat)+accent(x;bar)` is displayed :

- Time derivatives

  Function '`timed`' with the variable and the number of dots to display above.

  Example : `timed(theta;2)` is displayed :

- Vectors

  Function '`vector`' with the name of the vector.

  Example : `vector(u_theta)` is displayed :

- Scalar product

  Function '`scalarp`' with the two vectors as parameters.

  Example : `scalarp(vector(AB);vector(CD))` is displayed :

- Norm

  Function '`norm`' with the vector as a parameter.

  Example : `norm(vector(AB))` is displayed :

- Functions with no parenthesis

  Some functions are displayed without parenthesis when they have a single parameter with a variable.

  Example : `sin(a)*sin(b)` is displayed :

- Equation system

  Function '`system`', with the lines as parameters.

  Example : `system(x+y=2;x-2*y=3)` is displayed :

- Units

  Function '`unit`', with the unit as the second parameter.

  Example : `bigg=unit(6.67259*10^(-11);m^3*kg^(-1)*s^(-2))` is displayed :

  Note that units are displayed with a plain font, while a variable like is displayed with an italic font.

- Factorials

  Function '`fact`'.

  Example : `fact(x)` is displayed :

- Mean

  Function '`mean`'.

  Example : `mean(M_B)` is displayed :

# Preferences

## Default panels

It is possible to choose which panel will be visible on the left of the XML window.

- The tree displays the structure of the document. A clic on an element brings the XML window to its location.
- The insert panel lists the elements that can be inserted at the location of the cursor, and gives an easy access to online help for elements.
- The attribute panel is used to edit the attributes of the element containing the cursor in the XML window.

## Web browser

It is the browser launched when the "Browser" button is clicked on in the HTML preview window. When the Select button is clicked, or when the "Browser" button is clicked for the first time, a dialog opens to ask for the location of the browser program on the hard disk. It is for instance usually in the "Applications" folder on MacOS X, or in the "Program Files" folder on Windows.

## Perserve indentations

This option can be used to preserve all spaces in the XML document, and in particular indentations for XML elements. By default, Jaxe automatically deletes all the spaces used for indentation, which is not a problem when a document is always edited with Jaxe (because indentations are displayed in the XML window), but can be a problem when a document can also be edited with a different XML editor.

## Validation icon

This option displays an icon on tags to show if an element is valid or not. An element can be invalid when it requires for instance several sub-elements and not all of them have been inserted.

## Always display the attribute dialog when creating an element

This option can be used to always display the attribute dialog when elements with no required attribute are created. The attribute dialog is always displayed when there is at least one required attribute. It can be useful to uncheck this option, for instance, when using languages with rarely used optional attributes on all elements.

## Dictionary

A certain number of dictionaries can be downloaded for Jaxe. They should be placed in the `dicos` directory in Jaxe's directory. The file with the `.dico` extension corresponding to the dictionary to use can then be selected.

## XSLT processor

Choice of the XSLT processor :

- by default : uses the default Java Virtual Machine XSLT processor (usually XSLTC, but another one can be defined with the system property `javax.xml.transform.TransformerFactory`, which can be specified in the file `lib/jaxp.properties` in the JVM folder)
- Xalan
- XSLTC
- Saxon, the only one to support XSLT 2.0

# Jaxe configuration files

Author: Damien Guillaume

# Introduction

When creating a new document with Jaxe, it is necessary to choose a config file.

Jaxe's config files are used to specify the GUI to edit XML documents with Jaxe, for a given XML language. This covers informations about the XML language, saving options, menus (especially to insert the elements), display types for the elements, possible exports, and all the strings used in the interface, depending on the user language.

Config files are located in Jaxe's `config` directory, and their names end with "_config.xml". Old Jaxe config files (before Jaxe 3.0) had a name ending with "_Jaxe_cfg.xml". They can be converted to the new version with an export menu in the File menu.

It is possible to open an XML schema with Jaxe and to "export" to a config file. This automatically creates a config file that will make edition in Jaxe possible for the schema, but the automatic guesses for the display types are often bad or insufficient : this export should not be considered a method to create config files, but it could be used to start the creation of a config file from a particularly complex schema.

# Definition of the XML language

## Element definition

- `XML schema file`

  When creating a new config file, the first thing to do is to define the corresponding XML language. This is usually done by specifying an existing XML schema. Schemas must use the W3C syntax (WXS), or the Relax NG one (in XML).

- `Simple schema`

  WXS schemas being rather complex, there exists an alternative to define a very simple language in Jaxe, within the config file. The element `Simple schema` is used to define the XML elements, their attributes, and the relationships between the elements. It is not possible with these schemas to specify for instance an order for sub-elements in a given element, or to specify types for elements and attributes. But this could be used to quickly create a prototype, or when the needs are very basic.

  - `Element`

    Definition of an XML element.

  - `Sub-element`

    A possible sub-element (which must be defined elsewhere).

  - `Sub-set`

    A set of possible sub-elements (the set must be defined elsewhere).

  - `Attribute`

    Element attribute.

  - `Value`

    A possible value

  - `Set`

    Definition of an element set (which can be used to avoid repeating the same sub-elements for many elements).

- `Root`

  After defining the XML language, it is necessary to give Jaxe one or several possible root elements to use for new documents. The name of the element is specified for each possible root element.

- `Other configuration`

  Finally, it is possible to specify other config files to use in parallel with the current one, with the element `Other configuration`, so as to mix 2 XML languages in a document. This is used for instance to create XSLT documents.

## Element tree

Element tree under `Language` :

- `Language (XML schema file | Simple schema, Root+, Other configuration*)`
  - `XML schema file @name`
  - `Simple schema (Element | Set)+`
    - `Element @name @text (Sub-element | Sub-set | Attribute)*`
      - `Sub-element @element`
      - `Sub-set @set`
      - `Attribute @name @presence (Value*)`
        - `Value`
    - `Set @name (Sub-element | Sub-set)+`
      - `Sub-element @element`
      - `Sub-set @set`
  - `Root @element`
  - `Other configuration @name`

# File saving options

## Element definition

- `Encoding`

  Character encoding to use for new documents. Jaxe uses ISO-8859-1 by default if nothing is specified.

- `Doctype`

  Document type definition, if a DTD must be specified in the document headers.

- `Namespace prefix`

  Prefix to use for a given namespace. It is possible to specify several namespace prefixes.

## Element tree

Element tree under `Saving` :

- `Saving (Encoding?, Doctype?, Namespace prefix*)`
  - `Encoding`
  - `Doctype @publicid @systemid`
  - `Namespace prefix @uri @prefix`

# Menus

Menus defined in config files are displayed above Jaxe's text area. They are not mixed with Jaxe's menubar, which is above (on top of the screen on Macs).

## Element definition

- `Menu`

  A main menu, possibly containing sub-menus.

- `Insertion menu`

  A menu to insert an XML node at the cursor position. The node name and the node type (element by default) must be specified. It is also possible to specify a keyboard shortcut, with the corresponding key.

- `Function menu`

  Menu to execute a function with its Java class. The only predefined function in Jaxe is `jaxe.FonctionNormal`, which is used to remove all the styles in a text area. Other functions can be added as plugins.

- `Parameter`

  A parameter to pass to the function.

- `Separator`

  Menu separator.

## Element tree

Element tree under `Menus` :

- `Menus (Menu+)`
  - `Menu @nom (Menu | Insertion menu | Function menu | Separator)+`
    - `Insertion menu @name @node type (element|instruction|comment) @shortcut`
    - `Function menu @name @class @shortcut`
      - `Parameter @name @value`
    - `Separator`
    - `Menu`

# Node display

An essential feature in Jaxe is the possibility to display and edit XML element in different ways, whatever their types in the XML schema. For instance, a table element can be displayed as a table, and an element linking to an image can be displayed as an image. The objective is to ease document editing, without losing of sight their semantics : elements will not be displayed as they will be seen in web pages or PDF documents, but simply with a user interface making edition easier and highlighting the meaning of the elements.

## Element definition

- `Element display`

  Specifies how an element will be displayed in Jaxe

- `Parameter`

  A display parameter, depending on the display type (see below for a list).

- `Suggested value`

  Value suggested to the user when the schema does not limit authorized values.

- `Attribute display`

  Can be used to suggest attribute values.

- `PI plugin`

  Plugin to use to display processing instructions.

- `XML comment plugin`

  Plugin to use to display XML comments.

## Element tree

Element tree under `Display` :

- `Display (Element display | PI plugin | XML comment plugin)+`
  - `Element display @element @type (Parameter | Suggested value | Attribute display)*`
    - `Parameter @name @value`
    - `Suggested value`
    - `Attribute display @attribute (Suggested value+)`
      - `Suggested value`
  - `PI plugin @target (Parameter+)`
    - `Parameter @name @value`
  - `XML comment plugin (Parameter+)`
    - `Parameter @name @value`

# Display types

Type | Description | Display
--- | --- | ---
`division` | Two bars extending to the window's right side, clearly separating large areas in the document. |
`area` | Two tags and carriage returns, to separate areas smaller than with `division`. |
`string` | Two tags to identify a small string, without any carriage return. |
`empty` | A single tag, typically for an empty element. |
`table` | Spreadsheet style table display (with the Swing component JTable). Handy for tables of numbers, but does not allow the use of XML elements inside the cells (use `text table` to do that). |
`text table` | Table display allowing the use of XML elements inside the cells. Also handles the rowspan and colspan attributes to gather cells vertically and horizontally. |
`style` | For use in the case (very rare if the XML language encodes the meaning as opposed to the presentation) where an XML element only conveys a style information. Displays the characters in the chosen style (bold, italic, ...), without any tag. An alternative is to use the `string` type, which can also use a style, but displays the tags. |
`file` | Displays an image based on its path on the disk coming from an attribute of the XML element (to be defined). It is possible to copy/paste images and Jaxe will automatically create the XML element and the image file on the disk, using the first element of type `file`. |
`symbol` | Displays an image chosen within a set of images in an image folder. |
`list` | For an element representing a bulleted or ordered list. The sub-element must use the `item` type. The tags are displayed as for `area`, with a '+' button to create new items. |
`item` | List item in a list displayed with the `list` type. Displayed with bullets or numbers, depending on the list type. |
`simple type` | Displays an element having a simple value, in a small panel. Usable only for the elements with a simple type in the XML schema. The precise display (text field, menu or checkbox) and the validation are done based on the XML schema constraints. |
`equation` | Displays the image of an equation. The equation can be edited by a simple click on the image, with a dialog showing at the same time the text of the equation (using a very simple syntax specific to Jaxe) and the corresponding image. |
`form` | Displays an element and all its sub-elements as a form, with a field for each sub-element. Beware not to use this type with elements that could have an infinitely deep subtree ! |
`plugin` | If you want to define your own Jaxe element, it is possible ! See the section "Creation of new Jaxe elements" in the developer guide for more information. |

Parameters can be specified for some display types, with the `Parameter` element under `Element display`.

Display types `division` and `area` can have a parameter specifying the name of the attribute to use as a title for the element display.

Display types `file` and `symbol` must have a parameter specifying the attribute with the file name.

Display types `table` and `text table` must have parameters specifying the elements for the rows and the cells.

Display types `style` must have a parameter specifying the style.

Display types `area` and `string` can have a parameter specifying the style, a parameter with the font family, and a parameter with the font size.

Display types `equation` must have parameters specifying the attributes to use for the equation text and the image filename.

Here is a list of all the parameters:

type | parameter name | description
--- | --- | ---
division and area | titreAtt | attribute for the title
division, area, string and empty | attributsVisibles | displays all the attributes on the start tag (true|false)
table and text table | trTag | element for a line
table and text table | tdTag | element for a cell
table and text table | thTag | element for a header cell
text table | colspanAttr | attribute to merge columns
text table | rowspanAttr | attribute to merge rows
text table | alignAttr | attribute to align text
list | typeListe | type of list (`POINTS|NUMEROS`) (bulleted/ordered)
style, area and string | style | `GRAS` (bold) | `ITALIQUE` (italic) | `EXPOSANT` (superscript) | `INDICE` (subscript) | `SOULIGNE` (underlined) | `BARRE` (strikethrough)
area and string | police | font family
area and string | taille | font size
file and symbol | srcAtt | attribute with the file name
plugin | classe | Java class derived from JaxeElement
item | image1 | first bullet image
item | image2 | second bullet image
equation | srcAtt | attribute with the image filename
equation | texteAtt | attribute with the equation text

# Exports

## Element definition

- `Export`

  A possible export for the documents, using one or several successive XSLT transforms. An export to an HTML file will make an "HTML preview" menu appear in Jaxe's `Windows` menu. The other exports are available in Jaxe's `File` menu.

- `XSL file`

  An XSL file to use for the transform (XSLT 1.0). Must generate XHTML or HTML for the `HTML` output, and XSL-FO for the `PDF` output.

- `Parameter`

  A stylesheet parameter. There are magic names that make Jaxe automatically fill up values before the transform (these values cannot otherwise be obtained from XSLT) :

  - `jaxe-fichier-xml`

    The path to the XML file

  - `jaxe-uri-xml`

    The URI to the XML file

  - `jaxe-fichier-xsl`

    The path to the XSL file

  - `jaxe-uri-xsl`

    The URI to the XSL file

## Element tree

Element tree under `Exports` :

- `Exports (Export+)`
  - `Export @name @output (XSL file+)`
    - `XSL file @name (Parameter+)`
      - `Parameter @name @value`

# Strings

All the texts (also called strings) may have to be changed in the interface created with the configuration. Either to improve readability without having to change the schema, or to provide an interface in another natural language for the same schema. Texts may also have to be provided for a set of languages, so that users can edit the same documents, with the same Jaxe configuration, but with an interface entirely in their native language.

For these reasons, the `Strings` element represents a set of strings for a given language and country, and it is possible to specify several in the same config file. On can use for instance `language="pt" country="BR"` for Brazilian Portuguese, or just `language="en"` so specify English without any precision about the country.

You may have noticed that the real config file XML elements have French names, even though you see them in English in Jaxe and in this documentation. This is because the config file for config files is using these `Strings` elements to define titles to use for elements when the user's system language is English.

## Element definition

- `Configuration description`

  Short line to describe the configuration, displayed in the dialog to create new documents with Jaxe.

- `Menu strings`

  Strings associated to a menu, identified with its name

- `Title`

  A title

- `Documentation`

  A documentation

- `Element strings`

  Strings associated to an XML element. Used to display the element, but also for this element's insertion menu if no string was defined for the menu.

- `Title for value`

  A title to use for an element or attribute value

- `Attribute strings`

  Strings associated to an attributes

- `Export strings`

  Strings associated to an export

## Element tree

Element tree under `Strings` :

- `Strings @language @country (Configuration description | Menu strings | Element strings | Export strings)+`
  - `Configuration description`
  - `Menu strings @menu (Title?, Documentation?, Menu strings*)`
    - `Title`
    - `Documentation`
    - `Menu strings @menu`
  - `Element strings @element (Title?, Documentation?, Title for value*, Attribute strings*)`
    - `Title`
    - `Documentation`
    - `Title for value @valeur`
    - `Attribute strings @attribut (Title?, Documentation?, Title for value*)`
      - `Title`
      - `Documentation`
      - `Title for value @valeur`
  - `Export strings @export (Title?, Documentation?)`
    - `Title`
    - `Documentation`

# Developer Guide

Author: Damien Guillaume

# Introduction

Although Jaxe has been localised to English, most of the source code is using French, and most comments, variables, methods, and classes are in French. So, knowing French can be useful to develop with Jaxe, but it is not necessary in most cases, since you can just follow the following recipes. Also, most CVS update comments on sourceforge are in English, so it's also useful to know English. But the language you really have to know is of course Java !

It will be assumed that the reader has already read the documentations for users, administrators and the syntax for configuration files.

This documentation explains how to use Jaxe within another application, and how to add plugins to display elements.

# Using Jaxe within another application

Jaxe's startup class is (unsurprisingly) `jaxe.Jaxe`. This class gathers external events handling (file opening, closing, etc...), so it can be useful to take a look at it to see how a new Jaxe document is created or opened.

Another important class is `jaxe.JaxeFrame`. This class relates to an XML document window. It is using the class `jaxe.JaxeMenuBar` to handle the menubar, this one being unfortunately (because of a shortcoming of Java) linked to the window.

The easiest way to include Jaxe in another application is probably to use the class `jaxe.JaxeTextPane`, which represents the text area in the XML window. Since this class is derived from `java.swing.JTextPane`, it can easily be added wherever required, according to the host application layout. The constructor requires a `JaxeDocument` (linked to the DOM) and a `JFrame` (the parent window).

The object of class `jaxe.JaxeDocument` has to be initialised with a Jaxe configuration file (handled by the class `jaxe.Config`) and possibly with an XML file or with a DOM object.

To sum up, here is a list of instructions to include a Jaxe text area in a `parent` `Container` located in a given `frame`:

    JaxeDocument jaxeDoc = new JaxeDocument("mylanguage_config.xml");
    JaxeTextPane jaxeTextPane = new JaxeTextPane(jaxeDoc, frame);
    jaxeDoc.lire(xmlFileURL);
    // or jaxeDoc.setDOMDoc(domDocument);
    parent.add(jaxeTextPane);

Elements can be inserted with the contextual menu, or with `jaxe.ActionInsertionBalise` actions. The constructor for `ActionInsertionBalise` requires the Jaxe document, and the DOM element corresponding to the definition of the element in the Jaxe configuration file.

The document can later be saved with the method `JaxeDocument.ecrire(File f)`.

# Creation of new Jaxe elements

A Jaxe element is a class derived from `jaxe.JaxeElement`, describing a display for a given XML element. Standard Jaxe elements are gathered in the `jaxe.elements` package. They correspond to display types in the configuration files (for instance, the type `string` corresponds to the Jaxe element `jaxe.elements.JEString`).

A new Jaxe element can be created by deriving a new class from `jaxe.JaxeElement`. It can then be used in a configuration file with the `plugin` type, with the class to be used:

    <AFFICHAGE_ELEMENT element="aBooleanElement" type="plugin">
      <PARAMETRE nom="classe" valeur="JEBoolean"/>
    </AFFICHAGE_ELEMENT>

Two methods must be defined in the Jaxe element: `init` and `nouvelElement`. Two other ones are only useful if starting and ending tags are used (as explained later): `insPosition`, and (if the element has attributes) `majAffichage`.

`init` is used for initialisation and to insert the Swing component in the text area. The parameters are the position where the element has to be inserted in the text, and the DOM node. Using these parameters, the component has to be inserted with the method `JaxeElement.insertComponent(Position pos, JComponent comp)`.

It gets trickier if we want to use a component as a start tag and a component as an end tag, letting Jaxe handle recursively the descendants. The position in the text after the insertion of the start tag has to be obtained (it is returned by `insertComponent`), descendants have to be added with `creerEnfants(Position)`, and the end tag has to be inserted with a new call to `insertComponent` (with the `Position` objects passed as a parameter to `creerEnfants`. The character style has then to be updated for the tags and the descendants, which means the start position had to be kept before the first `insertComponent`. Here is an example:

    int startOffset = pos.getOffset();
    Position newpos = insertComponent(pos, startTagComponent);
    creerEnfants(newpos);
    insertComponent(newpos, endTagComponent);
    if (newpos.getOffset() - startOffset - 1 > 0) {
      SimpleAttributeSet style = attStyle(null);
      if (style != null)
        doc.setCharacterAttributes(startOffset, newpos.getOffset() - startOffset - 1, style, false);
    }

The method `nouvelElement` is called when the user inserts a new element. It might have to ask for informations to the user (such as the attributes), and has to return the new DOM element. The dialog `jaxe.DialogueAttributs` can be used to ask for attribute values.

`insPosition` can be called to get the position where the cursor will be placed after the insertion of a new element. By default, the cursor is placed after the element, but it can be useful to place it between the start and end tags when they are used.

Finally, `majAffichage` is called to update the display when the attributes values have been changed in the attribute panel.

## Example

The following file is a Jaxe element for a boolean, using a checkbox as a display: JEBoolean.java. It can be compiled and put into a jar file to become a new plugin for Jaxe.

# Adding a function

It is easy to add a menu launching a particular function instead of inserting an element. For this, one just needs to derive a class from `jaxe.Fonction` and implement the method `appliquer`, which provides the working Jaxe document, and the starting and ending positions of the text selection.

    public void appliquer(JaxeDocument doc, int start, int end)

The DOM document can be obtained from the Jaxe document with `doc.DOMdoc`. A Jaxe element can be obtained from a position in the text with `doc.elementA(int pos)`. All the elements in the interval [start,end] can be obtained with `rootJE.elementsDans(start, end)`. The corresponding DOM node is obtained with `JaxeElement.noeud`.

## Example

The following example adds a menu giving statistics about the document.

- Download StatisticsFunction.java.
- Put it in a folder named `pluginsjaxe` (it's the name of the package).
- Compile it. From the location of the pluginsjaxe folder, type on the command line : `javac -encoding ISO-8859-1 -classpath .:lib/Jaxe.jar pluginsjaxe/StatisticsFunction.java` (assuming `Jaxe.jar` is in a `lib` directory under the working directory). This should create a file `StatisticsFunction.class` in the folder `pluginsjaxe`.
- Create a jar file with the folder `pluginsjaxe`, and add it to the `plugins` folder.
- Update the configuration file to add a menu calling the function:

    <MENU nom="plugins">
      <MENU_FONCTION classe="pluginsjaxe.StatisticsFunction" nom="Statistics"/>
    </MENU>

# The XPAGES language

Author: Damien Guillaume

# 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.