# Jaxe configuration files

Author: Damien Guillaume

- Introduction
- Definition of the XML language
- File saving options
- Menus
- Node display
- Display types
- Exports
- Strings

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