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