This is the xmloperator user guide. It aims to help you in using the tool or in deciding if it could be useful to you. First section "Getting started" gives an introduction to the tool and some entry points to this guide. Second one "How to do that" is a list of question / answer for using the tool, in an arbitrary order. Third one "Tool description" is a description of the tool, in a hierarchical order.
xmloperator is an XML editor, a tool that allows you to create, read, and modify documents in XML format. Main characteristics of the tool are the following :
According to these characteristics, it is suited for editing very small to very large, data oriented documents, using a large variety of schemas.
At this point, you can start learning the tool use from one of the following links
about documents :
about schemas :
about (reversible) operations :
This section is a list of question and answer about using the tool.
A document is loaded by an instance of the tool. You can open several documents in the same time by opening several instances of the tool.
A distinction is done between small documents, which can sit in memory, and large documents, which cannot stay into memory or which are preferably not entirely loaded into memory. Typically, documents whose size is greater than may be 100 Ko, may be more, should be considered as large documents.
The two menus propose to load the document from your local disk or from a standard URL. In the first case, use the Browse... menu item (shortkey is Alt-O for a small document, Ctrl-O for a large one). In the second case, use the Enter... menu item.
You will have to enter or select the identifier of the XML document and, if it is a large document, you will have also to validate a path name for the intermediary binary file, so called BRXI file.
After these validations, document loading will start and you will be able to follow the following steps of the loading process in the message bar :
Step 1 doesn't exist for large documents because the BRXI format doesn't support entities. Step 4 may, for a large document, use a too long time or use too much memory. There is an option for skiping this step.
You obtain a tree view of the opened document. This view corresponds to the Document Object Model of the W3C. At one time, you can select one or more nodes. When only one node is selected (this is the most common case), information relative to the selected node is displayed in the detail view.
There may be a lot of nodes in your document, then you need some mechanisms for finding them. The most common method to find a node is by content : you know some fragment of a text node or an attribute value. You can then use the "View / Search..." menu item (shortkey is Ctrl+F) to find the node(s) from its (or their) content. For a more sophisticated criterion, you can use the "View / Evaluate..." menu item (shortkey is Ctrl+Shift+E) which uses an XPath expression.
This tool supports also ID navigation, based on any DTD or any RELAG NG schema that conforms to the DTD compatibility specification. Suppose you have selected an element that has a non-empty IDREF attribute. You can double-click on the attribute or use the goto menu item from the contextual menu (obtained by right mouse click on the element in the tree view) to select the target element, which has an ID attribute with the same value.
Another thing is to remember some nodes you have selected before. You can do that by double clicking on nodes that you want remember. Their are added on the navigation list, accessible through the "View / Browsing" menu item.
Once your document loaded, you can modify text and attribute values after selecting them.
For a text node, the text value is display both as a line in the tree view and as an editing area in the detail view. The tree view line is truncated and doesn't support editing. Editing occurs in the editing area where the text is fully accessible. You place your cursor at the location you desire and write your text. Your change is stored without you need to do an action for that. The text on the tree view is continually updated.
For an attribute, you have to select it in the attribute table of the element detail view. Then, if it is CDATA, you edit it, like for a text node, by placing your cursor somewhere in the value field and writing your value. No validation is required in this case. This is different for an ID, IDREF or IDREFS attribute. A button then occupies the value field. The button action opens a dialog window. For an ID, you enter the value and validate. For an IDREF or IDREFS attributes, you select the referenced element(s). For an enumeration, the value selection occurs directly in the attribute value field. Using ID, IDREF, IDREFS and enumeration works as well with a RELAX NG schema than with a DTD.
Once you have realized some changes on your document, you should save it. You can use the File / Save document menu item. Shortkey is Ctrl+S. If you forget to do that and close the document or the tool without saving the document, there will be no message to prevent you to do so. When you will reload the document, may be by re-launching the tool, you will have the surprise, after the loading of your document, to be proposed the execution of some operations. They correspond to the changes you forgot to save before closing the document. By accepting the operations, you apply your changes. By rejecting them you cancel your changes and will not be able any more to recover them. So, if you don't know what to do, the best is to accept the changes since you will be able to undo them later.
For adding or removing a node in your document you can use the contextual menu (right click on the context node in the tree view), the Edit menu, or a shortkey.
You can select a node (the context node) for inserting a node before it (shortkey is Ctrl+P) or after it (shortkey is Ctrl+N). The choice of the context node is not indifferent since it is generally used as pattern for the new node. If the context node is a text node then a text node will be inserted. It would be the same for cdata section node, comment node or processing instruction node. If the context node is an element and if the schema of the document allows the element to be repeated then an element with the same name than the context element is inserted elsewhere a list of possible names for the new element is proposed. If the list contains an only name then an element with that name is immediately inserted.
You can also add a descendant to an element. The shortkey is Ctrl+D. If the element has already descendants then it will be the last. If the element accept text node as descendant then a text node will be added else an element will be added. You will select the element name from a list of possible names or an element will be immediately added if there is only one possible element name.
Adding an element (from sibling or parent) may require adding more elements in order to maintain the document validity. The tool manages this aspect by proposing recursively to insert an element at each place where it is missing. At each time, you have to select an element name if there are several possible element names. When only one element name is possible then the element is inserted immediately. If you cancel some element name selection then the document will be kept in an invalid state. It's not a problem since you can save an invalid document and make corrections later.
Removing a node requires selecting it and asks for remove. The shortkey is Ctrl+Delete. The operation is not allowed if the element removing would make the element sequence invalid. In that case, you could have to select several nodes or to use the "Lazy" mode. By using the lazy mode you make the choice to make temporally the document invalid.
Replacing a node is equivalent to removing the node and inserting another node at the same place. If you want to change the node type of your node to another node type than element type then select this node type in the node type field of the detail view. Elsewhere, for changing to element type then use the Edit / Replace menu item. The shortkey is Ctrl+R. If an element is replaced by another element then the descendants, if any, are kept.
For adding an attribute to a selected document of your document you can use the New attribute menu item of the context menu (right click on the table attribute header) or the one of the Edit menu or the shortkey Ctrl+U. This action opens a dialog window for selecting an attribute name. Names of attribute already in the element are excluded.
For removing an attribute from an element that you have selected in your document you have to select the attribute and ask for removing. You can either use the Remove attribute menu item of the contextual menu (right click on the attribute name or value in the attribute table) or the one of the Edit menu or the shortkey Alt+Delete. The operation will be not allowed if the attribute is required.
You can move one or more nodes at a time. Moving several nodes require they have the same parent node. Once you have selected your node(s) you can execute moves using one or two step(s).
A one step move is a local move. The following operations are proposed by the Move menu and the contextual menu (right click on one selected node).
| Menu item | Shortkey | Action |
|---|---|---|
| Move previous | Ctrl+Shift+Up | The selected nodes are moved before the previous sibling node. |
| Move next | Ctrl+Shift+Down | The selected nodes are moved after the next sibling node. |
| Move child | Ctrl+Shift+D | The selected nodes are moved to the place of last descendant of the previous element. |
| Move parent | Ctrl+Shift+T | The selected nodes are moved after their parent element. |
The two steps move works as follows :
You select the node(s) to move and action the To be moved menu item of the Move menu or the contextual menu. Sortkey is Ctrl+Shift+M. Then the first node and the last node (if several nodes are selected) of the selected nodes interval are displayed in the detail view. There is also a "Cancel" button for canceling the operation.
You select a node in your document for using as a mark for the move. Then you execute one of the commands already examined for a local move.
For copying a node (or a sequence of nodes from the same parent node) from one document to the same document or to another document, the tool uses "fragments". There is one fragment by opened document, i.e. tool instance. A fragment is a container for a node or a sequence of nodes. The nodes are not in the document but are always attached to the document. Fragment relatives operations are the following :
| Menu item | Shortkey | Action |
|---|---|---|
| Cut | Ctrl+X | The selected nodes are removed from the document and put into the fragment attached to the document. |
| Copy | Ctrl+G | The selected nodes are copied into the fragment attached to the document. |
| Import | Ctrl+Shift+F | The nodes selected in another opened document are copied into the fragment attached to the current document. |
| Paste before | Ctrl+V | The node(s) contained in the fragment attached to the document are copied before the first selected node of the document. |
| Paste after | Ctrl+W | The node(s) contained in the fragment attached to the document are copied after the last selected node of the document. |
| Paste under | Ctrl+Y | The node(s) contained in the fragment attached to the document are copied as last descendant of the selected element of the document. |
| Replace | Ctrl+Shift+R | The selected node(s) are replaced by the ones of the fragment. |
| Copy to clipboard | Alt+G | The selected node(s) are copied into the fragment attached to the document and into the system clipboard. Entities (if any) are expanded for the system clipboard. |
| Copy fragment to clipboard | Ctrl+T | The node(s) contained in the fragment attached to the document are copied into the system clipboard. Entities (if any) are expanded for the system clipboard. |
| Copy clipboard to fragment | Alt+T | The system clipboard is parsed as a fragment, which is copied to the fragment attached to the document. |
| Paste clipboard before | Alt+V | The system clipboard is parsed as a fragment, which is copied to the fragment attached to the document and copied before the first selected node of the document. |
| Paste clipboard after | Alt+W | The system clipboard is parsed as a fragment, which is copied to the fragment attached to the document and copied after the last selected node of the document. |
| Paste clipboard under | Alt+Y | The system clipboard is parsed as a fragment, which is copied to the fragment attached to the document and copied as last descendant of the selected element of the document. |
Copying elements is not equivalent to moving elements since they contain IDs, because IDs cannot be duplicated in the document. The tool takes care of changing the IDs of duplicated elements and keeping consistence of their references, if any.
For creating a new document, use the Document / new document menu item. This action opens a dialog window, titled "New document", asking you for a document type and a file name.
If the document type of your future document is already defined then select it in the list. If it is not then click the New button at the right of the document type field. This action opens a dialog window for defining a new document type. You have to set the following information :
The name is the name of the document element. It is not required but you should type it if there is only one possible document element name.
The additional key is useful for distinguishing two document types using the same document element name. It is optional but greatly recommended.
You may have to set DTD information or/and RELAX NG information. RELAX NG is more flexible and should be preferred for editing. But you may need to reference a DTD from your document because, as an example, the document references external entities. When DTD and RELAX NG schema are set in the document type it is assumed that this is the RELAX NG schema which drives editing. See details on using DTDs and using RELAX NG.
The namespace identifier is optional. If it is set then an "xmlns" attribute with that value will be added to the document element.
The "shortcut used for empty elements" flag has only an effect on writing out the document. The only justification of this flag is the bad interpretation of xhtml documents by old browsers.
The "default transformer" field allows setting a default transformer for the document.
You enter the file name end validates. A minimal document conforming to the document type is created, saved using the file name and reloaded.
The following DTD relative information is (optionally) attached to a document type :
The DTD Public Id is destined to the DOCTYPE node of a new document.
The Document relative System Id is destined to the DOCTYPE node of a new document.
The HTTP DTD System Id is an absolute URI for referencing the document.
The User relative DTD System Id is an URI where the DTD will be accessed for editing.
In your documents with DTD, you have to choose between a DTD internal subset and a DTD external subset. The reason is this one. Suppose you load a document which has a document type declaration with an internal subset and a reference to an external subset. The tool read a monolithic DTD, making no difference between the DTD internal subset and the external subset. It's cool for editing but when you will save your document the DTD internal subset will be lost.
So you have to choose between the two following cases :
Your document refers to an external DTD and contains no internal subset. You have defined the document relative System Id information consistently. You may have defined the DTD Public Id. You may have defined the user relative DTD System Id in order to access it.
The document type declaration of your document contains a DTD internal subset and doesn't refer to an external subset. The DTD relative document type information is not set. In this case the DTD will be saved with the document, as DTD internal subset.
If your document has or refers to a DTD and you want to remove completely the document type declaration from it, you can do that by clearing the saving option "DOCTYPE if DTD".
You can use a DTD to edit a document without document type declaration. You have simply to set the User relative DTD System Id and not set the Document relative DTD System Id. The DTD will be loaded after the document. At some time you might be asked for associating the document to a document type.
If your document type information includes the user relative DTD System Id then you have two methods for modifying the DTD : you can edit it as text by using the Selected type / Edit DTD / as DTD menu item of the Document types window, ) or you can use DTDXML.
The tool offers some RELAX NG support. RELAX NG is used for guiding editing. The tool helps you to make your document valid but it doesn't verify all the constraints that a document must conform to be valid. Also you need an external RELAX NG validation tool for validating your document after editing with this tool.
The following RELAX NG relative information is (optionally) attached to a document type :
The RNG full syntax System Id is an URI where the RELAX NG schema will be accessed for editing.
The RNG simple syntax System Id is an URI where should be available the RELAX NG schema in its simplified form.
The tool contains a full syntax to simple syntax translator. You can launch the translator by using the Build button in the RELAG NG panel of the document type dialog (see the Document types window). The input is the schema referenced by the RNG full syntax System Id. The output will be referenced by the RNG simple syntax System Id.
Another way to simplify a RELAX NG schema is to load it in a tool window and using the File / Simplify RELAX NG schema menu. There are three menu items that map to three possible modes of simplification :
Simple syntax. This mode produces the simple syntax as defined by the RELAX NG specification.
Group with more than two children. Using this mode, all the simplification steps are executed except the §4.12 one that reduces the number of child elements. This is the mode used by the document type dialog.
Ref resolution only. This mode executes minimal simplification. Its purpose is only to resolve the externalRef and include elements before transforming the schema to HTML for being browsed by the user.
If you load a document associated to a document type whose the RNG simple syntax System Id is set then the RELAX NG schema will be loaded immediately after and you will be allowed to edit your document using this schema.
DTDXML is an XML dialect for representing DTDs. By editing a DTDXML document then compiling it to a DTD, you have a best control of the production of DTD. However there is no DTDXML specification, only a DTD. It's not a standard.
You want yet use it ? OK, we continue.
The pathname of the DTD that you have to produce is given as document type information. You can attach a DTDXML document to the document type by setting the DTDXML System Id. Then you can use the Document types window in two steps :
For editing the DTDXML document, use the Selected type / Edit DTD / As DTDXML menu item. The document will be loaded in a free tool instance. You will be guided by its DTD for editing.
For producing the DTD, use the Selected type / Build DTD / DTDXML -> DTD menu item. The DTD is written out to the User relative DTD System Id (which must refer to a file).
For transforming a document, you can use the File / Transform document as menu item. You enter a pathname for the destination file. If several transformers are available for this type of document then you will be asked for selecting one. The transformation is launched. Once this task finishes, you can open the resulting document. It is proposed at first position in the Reopen list.
But what is a transformer ?
A transformer is used for translating documents from an XML format to another XML format or to text format. This section considers particularly XSLT transformers. For defining a transformer you have to proceed as follows. First you opens the Transformers window by using the Document / Transformers menu item. Then you use the "New" menu item on this window. This action will open a dialog window titled "Transformer" whose you will set the fields in that way :
You have to give a Name to the transformer.
You set the Document type name, which is the name of the source document element. This is used for transformer selecting.
By clicking the XSLT button you will set the transformer Class name to "org.xmloperator.transform.XSLTTransformer", which is the adapter Java class to the Xalan XSLT processor, included to the tool.
You enter the Style sheet System Id or action the Choose button for selecting it by browsing.
You may have to give the list of Param names if any. They must be separated by spaces.
Check the XML Result box if the transformer must produce an XML document. Don't check for a text output format.
You enter the destination DTD Public Id and DTD System Id of your destination document only if you want to include a document type declaration to it.
You select the destination document Encoding name.
You can specify "Standalone document" and/or "Shortcut use for empty element" for the destination document.
Your transformer is based on a style sheet. For writing such a style sheet by using the tool, you can use the xsl:stylesheet or the xsl:transform document type. They use a RELAX NG schema.
For debugging your style sheet, there is some XSLT options available. After modifying your style sheet document, you can re-transform your source document by using the File / Transform document (shortkey is Ctrlr+Shift+V), which uses the same destination document System Id than previously.
The tool proposes the comparison of documents. The used method consists of associating comparable elements of the two documents. The comparison result doesn't depend on the order of elements. More precisely, elements with the same content but in another order are considered equal. This kind of comparison is usefull and suitable to the tool but you may need an ordered kind of comparison. If so then you should search for an "XML diff" tool on the web.
For comparing two documents, you must first loading each document in a separate tool instance, then using the Compare / Associate menu item on one of the two instances. The look of each document is changed in that way :
An element identical to an element of the other document keeps its normal font.
An element that has no mapping element in the other document takes a bold font.
An element associated to an element of the other document because one or more of its children are associated to children of the other element takes an italic font.
For selecting in the other document the element associated to an element (rendered by normal or italic font), you can use the Compare / Associated element menu item or its shortkey Ctrl+Shift+A.
You can edit one or the two documents but the comparison will be updated only if you re-launch it (shortkey is Ctrl+Shift+C).
By the Disassociate menu item, you disassociates the two documents. They take again their usual look. Disassociation is automatic if you close one of the two documents.
This section is a description of the tool by using a hierarchical decomposition.
An instance of the tool has capability for managing one document. The document is displayed on the main instance window.
Several tool instances can be opened simultaneously. This allows transfers and comparison between documents.
A new instance is opened by using the Document / New instance menu item on the main instance window. Do not re-launch the tool from the operating system, the tool instances would be isolated and could not communicate.
There may be secondary windows attached to the main instance window. They are closed when the main instance window is closed.
There may be global windows attached to no particular instance. They are closed when the last main instance window is closed.
When you start the tool, the first opening window is a main instance window.
The tool instance main window is composed of a menu bar, a central area and a status bar.
The menu bar is composed of the File menu, the Document menu, the Edit menu, the Move menu, the Fragment menu, the View menu, the Compare menu and the Options menu. All of these menus are invariant. All of them are enabled except during the execution of a task, such as loading a document.
The central area is splited to a tree view of the document and a detail view of the selected node, if any. The separation between the two can be moved with the mouse.
The File menu is composed of the following, file or resource related, menu items.
The Open document / Browse menu item leads to opening a document after browsing a file system. It opens a dialog window for selecting a file. You select an XML document and validate. The document file is loaded.
The Open document / Enter menu item opens a document directly on the Web for consultation (or editing after it is saved in a file). A dialog window is opened for entering a URL. You enter the URL and validate. The document is loaded. It is read only.
The Open large document / Browse menu item leads to opening a large document after browsing a file system. It opens a dialog window for selecting a file. You select an XML document and validate. You have also to validate the path name of an intermediary BRXI file. The XML document is first translated to the BRXI format then the BRXI document is loaded.
The Open large document / Enter menu item get a document directly on the Web for translating to the BRXI format. A dialog window is opened for entering an URL. You enter the URL and validate. You validate also a path name for the BRXI file. The document is translated to BRXI and the BRXI document is loaded.
The Re-open document menu item opens a previously opened document. A dialog window proposes to select a document given by its URI. A reduced path is displayed for each document located in the current directory.
The Close document menu item closes the opened document. It empties the main window space and closes the windows linked to the document, such as the fragment window or the operations window.
The Save document menu item saves the opened document. If the opened document is maped to a BRXI file then you will be asked for saving either the BRXI file only either both the BRXI file and the XML file. The index of the BRXI file path name will be systematically incremented. Incrementing the XML file path name index is an option. After saving, the change indicator displays "Ready".
The Save document as menu item saves the opened document under a new name. It opens a dialog window for entering the file name. Enter a file name and validate. If you don't enter a suffix, ".xml" will be automatically added. After saving, the change indicator displays "Ready".
The Transform document as menu item transforms the current document into another document. It opens a first dialog window for entering the name of the file receiving the destination document, and a second dialog window for specifying the parameter values. After the transformation, the destination file is at the top of the <re-open> list.
The Retransform document menu item transforms the current document into the last destination document. It opens a dialog window for specifying the parameter values. After the transformation, the destination file is at the top of the <re-open> list.
The Process batch menu item opens a dialog for selecting a batch file and processing it. A batch file is built using the xmloperator/batch document type. The batch document is a list of transformations to do.
The Open DTD / Browse menu item is used to open a DTD by browsing a file system. It opens a selection window. You select a DTD file and validate. This option has no effect if no document is opened. If a document is opened then the new DTD replaces the one attached to the document.
The Open DTD / Enter menu item enables the opening of a DTD directly on the Web. A dialog window is opened for entering a URL. You enter the URL and validate. The behavior of this command is the same as the previous one.
The Close DTD menu item closes the currently used DTD and reuse the original one (which was attached to the document). The option has no effect if no DTD has been loaded. If the document-node is selected then the detail view indicates that the used DTD is not the original one.
The Open RELAX NG schema / Browse menu item is used to open a RELAX NG schema by browsing a file system. It opens a selection window. You select an RNG file and validate. This option has no effect if no document is opened. If a document is opened then the new schema replaces the one attached to the document.
The Open RELAX NG schema / Enter menu item enables the opening of a RELAX NG schema directly on the Web. A dialog window is opened for entering a URL. You enter the URL and validate. The behavior of this command is the same as the previous one.
The Simplify RELAX NG schema menu has three menu item. Any of them opens a dialog for entering the pathname of a file, which will receive the result of simplifying. The input schema is the currently loaded document. Each menu item maps to a particular simplification mode. The first one produces the simple syntax as specified in the RELAX NG specification. The second one keeps more than 2 children in group, interleave and choice elements. The third one applies a ligth simplification for browsing by user (after transformation to HTML).
The Exit menu item closes the instance of the tool. It is the equivalent of using the close button located in the frame. The application is closed when the last window is closed.
The Document menu is composed of the following, document or tool instance related, menu items.
The New document menu item creates a new document. A dialog window is opened for entering the type and name of the document. You enter the desired information, and validate. A confirmation window appears if a file with the same name already exists. Confirm if necessary. The document is created and displayed. The document element may be completed if the schema attached to the document type requires it.
The New instance menu item activates the opening of a new tool instance main window.
The Document types menu item gives the user access to the document types by opening the document types window.
The Document type menu item opens a dialog box for reading or modifying the information relative to the type of the current document (if a document is opened).
The Transformers menu item gives the user access to the transformers by opening the transformers window.
The Add namespace menu item adds a namespace declaration to the document root element. The user has been first asked for selecting the namespace URI in a dialog box. The prefix used is the usual prefix for that namespace.
The Remove empty texts menu item deletes the text nodes that only contain blanks and empty lines. This action is only authorized if the document is not modified. It is not reversible.
The Indent the elements menu item indents all the elements. Texts and mixed contents are left unchanged. This action is only authorized if the document is not modified. It is not reversible.
The Edit source menu item enables editing of the XML document as ordinary text. It opens the document as text in a new editing window. Direct editing of an XML document is not recommended because of the risk of incorrect formatting, which would prevent a user from opening it as an XML document.
The Edit menu executes operations on nodes of the opened document. All these operations are reversible.
The Undo menu item allows you to reverse an operation. The last "positive" operation to be completed is "reversed". The resulting "negative" operation is run and kept in memory, in case it is called to be "redone". No action is undertaken if there is no Undo operation. If several successive operations are linked (for the validity of the document), then the operations in question are all undone.
The Redo menu item enables you to redo an operation previously undone. The last "negative" operation to be run is "reversed". The resulting "positive" operation is run and saved in memory, in case it is called to be "undone". No action is undertaken if there is no operation to redo. If several successive operations are linked (for the validity of the document), then the operations in question are all redone.
The New previous menu item creates a new node and inserts it immediately before the selected node. If several nodes are selected, the first one is considered. The node type created is the same as that of the selected node. If an element has to be created then its name might have to be selected in a list of possible names. If the insertion makes the document invalid because not complete then new inserts will be generated automatically.
The New next menu item works like last one with this difference that insert occurs after the selected node.
The New child menu item works like the two last ones with the difference that the new node will be the last descendant of the selected node. If the new node will be the first child node and if a text node can go there then the new node will be a text node.
The Replace menu item operates if one node is selected. Operation consists of replacing the node by an element. You might have to select the element name from a list of possible names. If an element is replaced by another element then the descendants, if any, are kept. If the new element requires descendants then they will be created except those for which you would cancel the element name selection.
The Remove menu item deletes the selected node(s). If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. Similarly, if the deletion would make the document invalid, then the operation is not allowed.
The Pack menu item creates a new element, inserts it in the place of the selected node(s) and makes the selected node(s) descendants of this new element. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. If the action would make the document invalid then the operation is not allowed.
The New Attribute menu item creates a new attribute for the selected element. You select an attribute name in a list of possible attribute name, excluding the attribute the element has already.
The Remove attribute menu item removes the selected attribute of the selected element. The operation is not allowed if the attribute is required.
The Unpack menu item replaces the selected element with the group of its descendants. No action is undertaken if a node other than an element is selected, or if several nodes are selected. If the action would make the document invalid then the operation is not allowed.
The Join next menu item joins the selected node and the one immediately following it into one text node. Only one node must be selected, and both it and the one that follows it must be of the type "TEXT". If not, no action will be undertaken. The pieces of text are put end to end.
The Split menu item divides the text of the selected node into two text nodes, each one receiving part of the original text. The place where the text is split is defined by the current position of the cursor in the field of the detail view. No action is undertaken if several nodes are selected or if the node type selected is not "TEXT".
The Special menu item opens a window for selecting an operator [Operators] defined for the current document type. Nothing happens if no operator is defined for the current document type of if no document is opened.
The Move menu executes nodes move operations into the opened document. All these operations are reversible.
The Move previous menu item moves the selected node(s) (or to be moved) before the preceding node. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. If the move would make the document invalid then the operation is not allowed. No action is undertaken if the first node selected has no preceding node.
The Move next menu item moves the selected node(s) (or to be moved) after the node following the last one. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. If the move would make the document invalid then the operation is not allowed. No action is undertaken if the last node selected has no following node.
The Move child menu item moves the selected node(s) (or to be moved) to the last descendants from the node which precedes the first one. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. If the move would make the document invalid then the operation is not allowed. No action is undertaken if the first node selected has no preceding node or if this node preceding is not an element.
The Move parent menu item moves the node(s) selected (or to be moved) immediately after their parent node and at the same hierarchical level. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. If the move would make the document invalid then the operation is not allowed. No action is undertaken if the grandparent of the node(s) selected does not accept such descendants.
The To be moved menu item notes the selected node(s) as those to be moved. The first and last node of the interval (in the case of several nodes) are represented in the detail area, with an abandon button above (or to the left). If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken.
The Reorder ascending menu item puts the selected elements in increasing order according to their attribute values. No action occurs if the selected nodes are not all elements with the same name.
The Reorder descending menu item puts the selected elements in decreasing order according to their attribute values. No action occurs if the selected nodes are not all elements with the same name.
The Fragment menu executes fragment operations into the opened document. All these operations are reversible (but some nuance explained in the text).
The Cut menu item has two actions: First a copy of the selected node(s) is realized to make up a fragment. Secondly the selected node(s) is/are deleted (the same as using the "Remove" option). If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. Similarly if the deletion would make the document invalid then the operation is not allowed. Note that only the second action is an operation. In particular, this deletion is reversible, while the one producing a fragment (possibly replacing an existing fragment) is not.
The Copy menu item realizes a copy of the selected node(s) to make up a fragment. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. This action has no effect on the document and is therefore not considered as an operation.
The Import menu item imports the selected nodes of an opened document in another instance into this one. When several other instances are open, a dialog window opens to allow the selection of an instance. Each instance is represented by its number. This number appears in the title bar of the main window, after the tool name .
The Paste before menu item inserts the node(s) contained in the fragment immediately before the selected node. If the insertion would make the document invalid (because it is incomplete) then the operation is not allowed. If several nodes are selected, the first one is considered.
The Paste after menu item inserts the node(s) contained in the fragment immediately after the selected node. If the insertion makes the document invalid (because it is incomplete) then the operation is not allowed. If several nodes are selected, the last one is considered.
The Paste under menu item inserts the node(s) contained in the fragment as last descendants of the selected node. If the insertion makes the document invalid (because it is incomplete) then the operation is not allowed. No action is undertaken if several nodes are selected.
The Replace menu item replaces the selected node(s) by the content of the fragment.
The Copy to clipboard menu item realizes a copy of the selected node(s) to make up a fragment and copies it into the system clipboard. For the system clipboard, the entities, if any, are expanded. If several nodes are selected, they must follow each other and belong to the same hierarchical level. If not, no action is undertaken. This action has no effect on the document and is therefore not considered as an operation.
The Copy fragment to clipboard menu item copies the fragment into the system clipboard. For the system clipboard, the entities, if any, are expanded. This action has no effect on the document and is therefore not considered as an operation.
The Copy fragment to clipboard menu item parses the system clipboard for getting a fragment. This action has no effect on the document and is therefore not considered as an operation.
The Paste clipboard before menu item parses the clipboard for getting a fragment and inserts the node(s) contained in the fragment immediately before the selected node. If the insertion would make the document invalid (because it is incomplete) then the operation is not allowed. If several nodes are selected, the first one is considered.
The Paste clipboard after menu item parses the clipboard for getting a fragment and inserts the node(s) contained in the fragment immediately after the selected node. If the insertion makes the document invalid (because it is incomplete) then the operation is not allowed. If several nodes are selected, the last one is considered.
The Paste clipboard under menu item parses the clipboard for getting a fragment and inserts the node(s) contained in the fragment as last descendants of the selected node. If the insertion makes the document invalid (because it is incomplete) then the operation is not allowed. No action is undertaken if several nodes are selected.
The View menu is dedicated to opening views.
The Browsing menu item opens the navigation window.
The Operations menu item opens the operations window.
The Fragment menu item opens the fragment window.
The Content model menu item opens the content model window.
The Element labelling menu item opens a dialog window for selecting a different labelling for the elements with the same name than the currently selected element (if any). Labelling may use child text for a leaf element, all attributes (default), all single child elements, an attribute with a given name, or a single child element with a given name. Automatic element labelling at document loading is optional (display option), true by default.
The Referencing elements menu item opens a referencing elements window. No action is undertaken in the following cases: the selected element does not have an ID type attribute, the selected node is not an element, several nodes are selected. Several windows of this type can be opened at the same time. They focus on different referenced elements. The attribute ID value of the reference element appears in the title of the window.
The Invalid element menu item searchs an invalid element content from the currently selected element. If such an element is found then it is selected otherwise the content of the initial element is given as deeply valid.
The Errors menu item opens the errors on loading window that could have appeared during the loading of the document. The window is empty if no warnings or errors appeared during the loading. The information provided does not take into account the changes made to the document since the loading of the document.
The Element at location menu item opens a dialog for entering a line number and a column number. On validating this dialog, the most deeply element that contains this location will be selected.
The Exception trace menu item displays the trace of an anomaly that would have occurred. The window is empty if no anomaly has occurred.
The Search menu item opens a dialog window allowing the entry of text (the object of the search). You can specify if the search should be or not case-sensitive. The text field is initially filled with the text used for the last search. You can enter a new text or select a previous searched text. You validate. A window entitled "Search results" opens. It contains the list of nodes that contain the search text. If a search results window is already open, then it is requisitioned to present the results of the new search. The search focuses on the whole document. It is independent of the selected node(s).
The Evaluate menu item opens a dialog window allowing the entry of XPath Expression for evaluation. The dialog window contains two parts : an entry field for the XPath expression and a wizard frame for building a location path. The context node is the document element. Enter an expression or use the wizard and validate. If the expression is a location path then the result will be given in the same window than used for searching text. The wizard proposes to build a location path by a sequence of steps beginning from the document element. Each step specifies either an element name or the text node type or the any node type, as child or a descendant, with zero or more predicates. An element name is selected using a combo-box. A predicate is entered using a text field. Select a radio-button and press the Next button until the wizard terminates.
The Statistics menu item opens a dialog window that provides a statistic of the document elements. Opposite each element name is the corresponding element count. Click on name header or on count header for sorting by element name or by element count.
The Expand deeply menu item expands deeply the selected node(s). When the action takes a long time because a lot of elements are expanded, you can stop the process by pressing the cancel button.
The Change layout menu item changes the internal layout of the tool instance. The tree and detail views are placed left and right or top and below. The internal layout of the detail view is also adapted.
The Rebuild menu item rebuilds "as is" the graphic interface of the tool instance. It can be useful if some peculiarities appear on the display. The secondary windows are not rebuilt. The information (document, fragment, operations, options, ...) is not affected.
The Compare menu is dedicated to document comparison.
The Associate menu item compares two open documents and associates them, element by element. If several other instances are open, a dialog window opens for the selection of the instance containing the document to be compared. For a comparison, the font attributes used to represent each element are modified in the following way. A normal font signifies full accord between the corresponding elements (without considering the order of the child elements). An italic font signifies partial accord between the corresponding elements (some child elements have no associated element). A bold font signifies that the element has no associated element.
The Associated element menu item selects, in the second document, the element corresponding to that selected in the first. The action has no effect if the selected element in the first document does not have a corresponding one in the second, or if several nodes are selected.
The Disassociate menu item destroys the established association between two documents. They take on their normal traits.
The Merge as menu item merges two documents currently associated, and saves the resulting document under a new name.
The Options menu is dedicated to managing the settings.
The Settings / Modify menu item opens the settings dialog window. This window allows easy modification of the most current settings. The window is organized in sections, selectable by tab. Not all the settings are represented in this window. The absent settings must be edited in the options document.
The Settings / Save menu item saves the current settings in the options file. This action is not required since it is automatically executed at tool closing.
The Settings / Reload menu item reloads the saved settings. This action is useful after a modification is made to the options file. This modification would actually be lost after the automatic saving of the settings when the tool is closed.
The Settings / Edit menu item opens a new instance of the tool if the current one is not free and loads the settings document in that new instance for editing purposes.
The About menu item opens a dialog window displaying the tool version, the copyright and acknowledgement of outside contributions.
The tree view takes up the left part (or upper, depending on the orientation selected) of the central area in a tool instance window. This view displays the document while editing. The document is decomposed using the Document Object Model (DOM) of the W3C. The nodes that have descendants are represented by a folder. The nodes without descendant are represented by a bullet. The nodes with descendant(s) can be expanded by clicking on the "+" icon in front of the folder icon.
The detail view takes up the right part or the lower part of the central area in a tool instance window. This is the detail view of the selected node in the tree view. You can modify the selected node through it.
The detail view content depends on the type of the selected node but the node type always appears on top of it. The node type can or cannot be modifiable, depending of context, as explained in the following paragraphs. If the document is read-only then nothing in the document is modifiable.
The DOCUMENT node view contains the document system identifier, the encoding name, the standalone indicator, the document type and its additional key. The node type, document system identifier and document type cannot be changed. The encoding name and standalone indicator can be changed. The additional key can be changed. Each proposed additional key comes with the same document type name or with no specified document type name.
The DOCTYPE node view contains the DTD public identifier, and the DTD System Identifier. The node type, DTD public identifier and DTD system identifier cannot be changed.
The ELEMENT node view contains the element name, a field about (superficial) content validity and either a table of its attributes either a text area for the value of one of its attributes. The node type cannot be changed if the element has descendants. Neither the node type nor the element name can be changed if the element is the document element or if the element is required for the content validity of its parent element. Otherwise node type or element name can be changed.
The attribute table contains the attribute names and values. The selection of an attribute (by clicking on its name or value, or using the up and down arrow keys), displays the line in reverse video and shows the location of the attribute value an editing field adapted to the type of this attribute.
A popup list is displayed for an enumeration.
A button is displayed for ID, IDREF or IDREFS type of attribute. Action of this button opens a dialog window whose purpose is to entry the ID value in the case of ID type, to select an existing ID in the case of IDREF type, to select zero or more existing IDs in the case of IDREFS type.
An entry field is displayed for all other types of attribute.
By a rigth clic on the attribute table heading, a contextual menu popups with the following item :
By a rigth clic on an attribute name, a contextual menu popups with the following items :
The TEXT node view contains an editing area. The node type is modifiable except if the document is read-only. The editing area keeps the text between its vertical limits by going to the line if necessary, and preferably to spaces so as not to cut words. These line jumps do not make up part of the text (only those that are entered are part of the text).
The CDATA SECTION node and the COMMENT node view content are the same as the text node view content.
The ENTITY REFERENCE node view contains the name of the entity. You can select the entity from a list of declared or predefined entities.
The PROCESSING INSTRUCTION node view is similar to that of the text node view, except it includes a supplementary "Target" field.
A special case is when one or several nodes have been selected to be moved. In this case, the detail view displays the first and the last node (or only the first if there is only one). It also displays a button that can be used to cancel the move.
The status bar, located on the bottom of the window, is made up of the following fields (from left to right): a document status indicator, an edit mode indicator and a message line. All indicators can be removed, see the options dialog, Status bar tab.
The document status indicator is a combo-box that can show the following: empty (grayed out), "Ready" (accessible), "Read-only" (accessible or grayed out), and "Modified" (grayed out). The indicator is empty when no document is open. The indicator is in "Ready" state if the open document can be edited and was not yet modified. The indicator shows "Read-only" if the open document is read-only. The status is "Modified" if the document was modified and has not been saved since.
The edit mode indicator is a check-box called "Lazy". In the regular mode (not "lazy"), all of the realized operations (without breaking down the linked operations) should respect the schema or DTD. In "lazy" mode, they can make the document not valid. Clearing the check-box while the content including the selected node is not valid has the effect of adding as many elements as necessary in order to make the content (superficially) valid.
Certain actions conclude with a message displayed in the message bar. Such a message is a simple reminder. An important and unexpected message such as an error always appears in a modal dialog window, because it must be accepted. The message is erased with each new action or at the end of a fixed amount of time.
An instance secondary window depends on the instance main window. In particular it is automatically closed when the instance main window is closed. They are listed in the following lines. Some of them are unique for the instance, some others are multiple.
This window displays the list of nodes that were selected by double clicking.
This window displays the list of operations realized with the tool since the document was loaded. It also allows the undoing or redoing of a group of operations.
The operations list is built from top to the bottom. When there are no operations to undo, the last operation in the list is the last operation to be realized. When there are operations to redo, but also to undo, they appear in the following order: the operations to undo, a separation line, and the operations to redo. When all of the operations are to be redone, the first operation is preceded by a separation line.
Each operation is always expressed as having been realized or to be realized. The reverse operation is never expressed this way. The operation wording generally consists of: a verb (Insert, Set value, ...), an object (element, TEXT, ...), and a context (within <...>, ...). A special operation, named "and", has no effect on the document. It links operations of which the indissociable execution ensures that the validity of the document is maintained.
The Undo all menu item undoes all the operations that can be undone.
The Redo all menu item redoes all the operations that can be redone.
The Clear undo menu item clears all the operations that can be undone. All that is left are possible operations to redo.
The Clear redo menu item clears all the operations that can be redone. All that is left are possible operations to undo.
The Load menu item opens an operations file selection window. If an operations file is actually open, its operations are run and added to the operations to be undone, with the possible operations to be redone being cleared.
The Save menu item opens a window for the entry of the name of the operations file. If the entry is validated, the operations that can be undone are saved in this operation file.
This window displays the fragment resulting from a cut or copy. It also enables the importing of a fragment from another document. A checkbox allows you to choice between erasure of the fragment or not, after paste.
The Clear menu item clears the fragment.
The Import menu item allows you to import selected nodes from another opened document in the current one. If several other instances are open, a dialog window opens so that you can select the instance from which to import. The action is abandoned if no other instances are open. The imported fragment replaces the current fragment, if there is one.
This window displays the content model of the selected element when an element is selected. The notation is a mixed of DTD syntax and RELAX NG compact syntax. Attributes are present, prefixed by the '@' character. A default namespace of an nsName is represented by the 'D' character if no prefix is available for this namespace. This notation is destined to be interpreted by human, not by machine.
An help is provided for localizing parenthesis : When you clic at some position within the content model string, the text area between the corresponding left parenthesis and the corresponding rigth parenthesis is selected.
This window displays the list of elements for which an IDREF or IDREFS points to this element, considered as the target. Clicking on one of the referencing elements selects it in the tree view of the instance main window. Using the Target menu item, the target element is again selected in the tree view of the instance main window.
One can open as many referencing element windows as there are elements with ID in the document. The windows are updated according to the changes made to the document. A window from which the target element is deleted disappears by its own.
The loading error window opens during document loading if errors or warnings are triggered. Subsequently, this window can be re-opened using the Errors menu item of the instance main window. The window displays the list of errors and warnings. By selecting a line, the element in which the error appears is selected in the tree view of the main window. Double clicking on a line opens a source text editing window for the document (if it is not already open) and the line in the source text is selected.
The search results window opens at the conclusion of a search for a text extract in the document that is being edited. This search is launched by the Search menu item of the instance main window. This window displays the list of nodes containing the text extract being searched for. The extract can be in the text of a node, or in an attribute value. The selection of a node in this list selects this node in the tree view of the main window. If this node includes an edit field (TEXT, PROCESSING INSTRUCTION and CDATA SECTION) then the first occurrence of the required text is selected. If this node is an element then the attribute containing the required text is selected.
A new search reopens the same results window, and erases the preceding search. The position and dimensions of the window are maintained.
There are two global windows : the document types window and the transformers window. They are unique, can be opened from any instance main window and are closed when the last instance main window is closed.
This window defines the document types as well as their associated files. The window displays a table with a menu bar on top.
The document types table contains the following columns: Document type, additional key, and schema type (nothing, DTD, RNG or DTD + RNG). Select a line by clicking on it or by pressing the up or down arrow button. Double clicking on a line has the same effect as the Modify menu item.
The New menu item opens a dialog window for entering the new document type characteristics. That includes the document type name, the additional key, the DTD public identifier, the DTD reference HTTP URL, the DTD URL as it should appear in the "DOCTYPE" node of the document, the DTD user path, the DTDXML user path, the RELAX NG full syntax schema URL, the RELAX NG simplified schema URL, the namespace identifier, the flag for using shortcut for empty elements, and the reference transformer name. All the fields are optional, including the document type name.
The Modify menu item opens a dialog window allowing the modification of the document type selected. The dialog window is the same as that which defines a new document type.
The Duplicate menu item has the same effect than the New menu item with this difference that the entry fields get the values corresponding to the currently selected document type.
The Remove menu item removes the selected document type.
The DTDXML -> DTD menu is about building a DTD from DTDXML. The first menu item translates each pattern element of the DTDXML document by a parameter entity declaration in the DTD. The second one applies these patterns without using parameter entities. Nothing is done if there is no DTDXML system Id in the document type information.
The Edit DTD / As DTD menu item opens an editing window for the DTD content. The window title is the user DTD System id. The text is read-only if the DTD is not in a file.
The Edit DTD / As DTDXML menu item opens a new tool instance or uses the current instance if it is free, for loading the DTDXML document. Nothing is done if the document type information contains no DTDXML system Id.
The Edit RNG / Full syntax menu item opens a new tool instance or uses the current instance if it is free, for loading the RELAX NG full syntax document. Nothing is done if the document type information contains no RELAX NG full syntax System Id.
The Edit RNG / Simple syntax menu item opens a new tool instance or uses the current instance if it is free, for loading the RELAX NG simple syntax document. Nothing is done if the document type information contains no RELAX NG simple syntax System Id.
This window defines the document transformers. The window displays a table with a menu bar on top.
The transformers table contains the following columns: transformer name, full name of implementation Java class, and System Id of its style sheet if it is an XSL Transformation. Select a line by clicking on it or by pressing the up or down arrow button. Double clicking on the line has the same effect than the Modify menu item.
The New menu item opens a dialog window for entering a new transformer. That includes the transformer name, the full Java class name, the System Id of the style sheet for an XSL Transformation, the destination DTD public identifier, the destination DTD System Id, the encoding name, a check box for standalone document and a check box for using or not the empty element shortcut. It is only possible to validate if the transformer name is entered.
The Duplicate menu item has the same effect than the New menu item with this difference that the entry fields get the values corresponding to the currently selected transformer.
The Modify menu item opens a dialog window allowing the modification of the transformer selected. The dialog window is the same as that which defines a new transformer.
The Remove menu item removes the selected transformer.
The tool keeps, for each document type, some relative information.
A document type is identified by the document element name and an additional key. If you want use different document element names with the same document type then keep the document element name empty. You can have several document types with the same document element name but with different additional keys. An additional key represents nothing by itself when creating a document.
The information attached to a document type includes: the DTD public identifier, the reference HTTP URL of the DTD, the URL of the DTD as it appears in the "DOCTYPE" node of the document, the path to the user DTD, the path to the XML version of the DTD, the RELAX NG full syntax System Id, the RELAX NG simple syntax System Id, the namespace identifier, the flag about using shortcut for empty elements, and the reference transformer name.
This information is that which is used during a document save. When the Document relative DTD System Id is absent then, the document DTD, if any, is inserted directly into the document.
An action that could use some time is managed as a task. Examples of tasks are : loading a document, saving a document or transforms a document. During a task, all the menus are disabled and the indicators in the status bar are replaced by a Cancel button.
An <operation> is any atomic alteration made to a document, realized with the help of the tool. With each action of the tool that results in a change to the document in memory, an operation is created, run and added to a stack of operations. The operations already run can be cancelled. You can undo or redo any operation. The stack of operations can be consulted in the operations window. The operations can be kept for being rerun later in operations files. A special operation, labeled "and", has no effect on the document. This operation joins two operations. It signifies that the operations linked in this way must be considered indissociable, in order to maintain the validity of the document.
A sequence of operation can be saved in an operations file to be rerun later, in an equivalent context. An operations file has the suffix ".ope". The operations file relative to a document file carry the name of the document file in which the suffix is replaced by ".ope". For this reason, an operations file cannot be attached to an operations file. Editing an operations file uses a schema called xmloperator_x_y_operations.rng where x and y map to the release x.y.z of the tool.
At the conclusion of loading a document, if it exists an operations file attached to it then you will be prompted to rerun the operations it contains. An operation that cannot be run in a given document context will be rejected. You should to choose whether or not to run the subsequent operations.
An operator is an additional code, linked at run-time, implementing a given Java interface and realizing a special (and generally complex) sequence of operations.
A transformer is used for producing a document from another document. The documents generally have not the same schema or DTD. The tool uses a standard transformer interface. You can create a Java class that implements this interface and dynamically link this class to the tool. You can also write an XSLT stylesheet. The XSLT engine is provided by the Xalan-J software of the Apache Software Foundation.
The information attached to a transformer includes : the transformer name, the full Java class name, the style sheet path name for an XSL Transformation and the output format depending information. The output format is either XML document or text. For an XML output, the public identifier and the system identifier of a destination DTD can be defined with the encoding names, the standalone flag and the shortcut enabling flag.
All the settings of the tool are designated by <options>. Certain options may be modified by using the options dialog, the others can be modified by editing the options document. Options are loaded at tool launching and saved at tool closing.
The tool options file is named "xmloperator.xin". The path can be specified as parameter in the command line. If the path is not specified then the file is created in the tool's launch directory. Editing this document uses a schema called "xmloperator_x_y_options.rng" where x and y map to the release x.y.z of the tool.
The tool defines a processing instruction target, named xmloperator, but without case distinction. An xmloperator processing instruction is supposed to be only interpreted by the xmloperator tool. All other document-processing tools are supposed to ignore this instruction. The tool uses these instructions to attach certain processing options to document instances. An instruction is made up of one or more space separated commands. Only the processing instructions whose parent node is the document element are interpreted. There is only one instruction currently defined : the "ReadOnly" instruction. The "ReadOnly" instruction opens a document in read only mode. This doesn't prevent you from switching immediately to the "Ready" mode and editing the document.
There will be always bugs. We have simply to reduce their effects and manage their fixing.
A bug appears on an unexpected case and generally raises an exception. The exception is intercepted by the tool (but some ones are not) and is reported to you by a persistent message "SEE EXCEPTION TRACE" in the message bar. Then you have to use the View / Exception trace menu item for reading and accepting the exception. Accepting the exception means only that the "SEE EXCEPTION TRACE" message will be cleared.
The exception trace contains the date, the tool version, and the exception(s) that have arisen. Each exception appears as a call stack. For bug fixing, you should send a copy of this trace to the tool developer (info@xmloperator.net). Additional comments would be welcome.
| Last update : 2003-08-25 | Copyright (c) 2000 - 2003 The_xmloperator_project |