<oXygen/> User Guide |
While editing a document is a simple procedure, there are some points of which you should be aware and which should make your editing more productive.
Unicode provides a unique number for every character, no matter what the platform, no matter what the program, no matter what the language. Unicode is an internationally recognized standard, adopted by industry leaders. The Unicode is required by modern standards such as XML, Java, ECMAScript (JavaScript), LDAP, CORBA 3.0, WML, etc., and is the official way to implement ISO/IEC 10646.
It is supported in many operating systems, all modern browsers, and many other products. The emergence of the Unicode Standard, and the availability of tools supporting it, are among the most significant recent global software technology trends. Incorporating Unicode into client-server or multi-tiered applications and websites offers significant cost savings over the use of legacy character sets.
As a modern XML Editor, Oxygen provides support for the Unicode standard. Enabling your XML application to be targeted across multiple platforms, languages and countries without re-engineering. Internally, the Oxygen Editor uses 16bit characters covering the Unicode Character set.
On loading documents of the type XML, XSL, XSD and DTD, Oxygen reads the document prolog to determine the specified encoding type. This is then used to instruct the Java Encoder to load support for and save using the code chart specified. In the event that the encoding type cannot be determined, Oxygen will prompt and display the "Available Java Encodings" dialog. The "Available Java Encodings" dialog provides a list of all encodings supported by the Java platform.
While in most cases you will use UTF-8, simply changing the encoding name will cause the file to be saved using the new encoding. The appendix Unicode Character Encoding provides a Matrix that matches common names with Java Names. It also explains what you should type in the XML prolog to cause the document to be saved as the required encoding.
To edit document written in Japanese or Chinese, you will need to change the font to one that supports the specific characters (a Unicode font). For the Windows platform, use of "Arial Unicode MS" or "MS Gothic" is recommended. Do not expect Wordpad or Notepad to handle these encodings. Use Explorer or Word to eventually examine XML documents.
![]() | Note |
---|---|
The naming convention used under Java does not always correspond with the common names used by the Unicode standard. For instance, while in XML you will use encoding="UTF-8", in Java the same encoding has the name "UTF8". |
Oxygen's intelligent Tag-Insight feature is an content assistant that enables rapid, in-line identification and insertion of structured language elements, attributes and in some cases their parameter options.
The Tag-Insight assistant is automatically displayed whenever the < character is entered into a document or by selecting CTRL+Space on a partial element or attribute name. Moving the focus to highlight an element and pressing the Enter key or the Tab key, inserts both the start and end parts of the highlighted element in to the document. If the feature Add Required Elements of Tag-Insight is enabled all the elements that the new element must contain, as specified in the DTD or XML Schema, are inserted automatically in the document. After inserting, the cursor is positioned directly before the > character of the start tag, if the element has attributes, in order to enable rapid insertion of any attributed supported by the element, or after the > char of the start tag if the element has no attributes. Pressing the space bar, directly after element insertion will again display the assistant. In this instance the attributes supported by that element will be displayed. If an attribute supports a fix set of parameters, the assistant will display the list of valid parameter. If the parameter setting is user defined and therefore variable, the assistant will be closed to enable manual insertion.
The content assistant can be invoked at any time by pressing CTRL+Space and the context-sensitive list of proposals will be shown in any position of the caret in the edited document in which element, attribute or attribute value insertion makes sense. Such positions are: anywhere within a tag name or at the beginning of a tag name in an XML document, XML Schema, DTD or Relax NG (full or compact syntax) schema, anywhere within an attribute name or at the beginning of an attribute name in any XML document with an associated grammar, and within attribute values or at the beginning of attribute values in XML documents where lists of possible values have been defined for that element in the grammar associated with the document.
The content of the Tag-Insight assistant is dependent on the element structure given in a given DTD, XML Schema, Relax NG (full or compact syntax) schema or NRL schema.
The number and type of elements displayed by the assistant is sensitive to the current position of the cursor in the structured document . The child elements displayed within a given element are defined by the structure of the specified DTD, XML Schema, Relax NG (full or compact syntax) schema or NRL schema. All elements that are not child elements of the current element are filtered out. This behavior is continued to element attributes and their parameters. For Relax NG schemas, all the elements are offered in any position of the document and inside a tag all the attributes possible for that tag are displayed by the Tag-Insight assistant (this will be improved in a future version).
The DTD, XML Schema, Relax NG schema or NRL schema used to populate the Tag-Insight assistant is specified in the following methods, in order of precedence:
From the file specified in the external subset of the document prolog. In this case Oxygen reads the prolog and resolves the location of the DTD, XML Schema, Relax NG schema or NRL schema.
From the file specified in the Oxygen Tag-Insight dialog. Oxygen will read the Tag-Insight settings when the prolog fails to provide or resolve the location of a DTD, XML Schema or Relax NG schema.
When working with documents that do not specify a DTD, or for which the DTD is not known or does not exist, Oxygen is able to learn and translate it to a DTD, which in turn can be saved to a file in order to provide a DTD. In addition to being useful for quick creation of a DTD that will be capable of providing an initialization source for the Tag-Insight assistant. This feature can also be used to produce DTDs for documents containing personal or custom element types.
Procedure 4.8. To create a DTD:
Open the structured document from which a DTD will be created.
Select Ctrl+Shift+L). Oxygen will learn the document structure, when finished displaying words "Learn Complete" in the Message Pane of the Editor Status bar.
-> (Select Ctrl+Shift+S) to save the DTD currently stored in memory to file.
-> (![]() | Note |
---|---|
The resulting DTD is only valid for documents containing the elements and structures defined by the document used as the input for creating the DTD. If new element types or structures are defined in a document, they must be added to the DTD in order for successful validation. |
When Internet access is not available one or more XML catalogs can be added to the list in the dialog below and the local copies of the DTD, XML Schema, Relax NG schema and/or NRL schema files will be used. When you add or delete an XML catalog to the list of XML catalogs in the Options -> Preferences -> XML Catalog pane you must restart the application so that the changes take effect.
The Prefer option is used to specify whether Oxygen will try to resolve first the PUBLIC or SYSTEM reference using the specified XML catalogs. If a PUBLIC reference is not mapped in any of the catalogs then a SYSTEM reference is looked up. The verbosity level specifies the types of output messages displayed and can have one of the values: debug, warn, info, error and fatal.
If the user has added no XML catalogs to this list then Oxygen will add by default the built-in catalogs for DocBook and TEI documents located in the docbook and tei subdirectories of the installation directory.
In structured markup languages, the whitespace between elements that is created by use of the Space bar, Tab or multiple line breaks insertion from use of the Enter, is not recognized by the parsing tools. Often this means that when structured markup documents are opened, they are arranged as one long, unbroken line, what seems to be a single paragraph.
While this is perfectly acceptable practice, it makes editing difficult and increases the likelihood of errors being introduced. It also makes the identification of exact error positions difficult. Formatting and Indenting, also called "Pretty Print", enables such documents to be neatly arranged, in a manner that is consistent and promotes easier reading on screen and in print output.
Pretty print is in no way associated with the layout or formatting that will be used in the transformed document. This layout and formatting is supplied by the XSL style sheet specified at time of transformation.
Procedure 4.9. To format and indent a document:
Open or focus on the document that is to be formatted and indented.
Selecting Ctrl+Shift+P). While in progress the Status Panel will indicate "Pretty print in progress". On completion, this will read "Pretty print successful" and the document will be arranged.
-> (![]() | Note |
---|---|
Pretty Print can format empty elements as an auto-closing markup tag (ex. <a/>) or as a regular tag (ex. <a></a> ). It can preserve the order or attributes or order them alphabetically. Also the user may specify a list of elements for which white spaces are preserved exactly as before Pretty print and a one with elements for which white space is stripped. These can be configured from -> -> Editor -> Format. |
Pretty Print requires that the structured document is "Well Formed". If the document is not "Well Formed" an error message is displayed. The message will usually indicate that a problem has been found in the form and will hint to the problem type. It will not highlight the general position of the error, to do this run "Well Formed" function by selecting Ctrl+Shift+W).
-> (XPath is a language for addressing specific parts of an XML document. XPath, like the Document Object Model (DOM), models an XML document as a tree of nodes. An XPath expression is a mechanism for navigating through and selecting nodes from the XML document. An XPath expression is in a way analogous to a Structured Query Language (SQL) query used to select records from a database.
XPath models an XML document as a tree of nodes. There are different types of nodes, including element nodes, attribute nodes and text nodes. XPath defines a way to compute a string-value for each type of node.
XPath defines a library of standard functions for working with strings, numbers and Boolean expressions.
Examples:
child: : * Select all children of the root node.
.//name Select all elements having the name "name", descendants of the current node.
/catalog/cd[price>10.80]Selects all the cd elements that have a price element with a value larger than 10.80
To use XPath effectively requires, at least an understanding of the XPath Core Function Library. Once you have this knowledge the Oxygen XPath expression field part of the Editor toolbar can be used to aid you in XML document development.
To find out more about XPath, the following URL is recommended: http://www.w3.org/TR/xpath
In Oxygen the results of an XPath query are returned in the Message Panel. Clicking a record in the result list highlights the nodes within the editing panel.
Results are returned in a format that itself is a valid XPath expression:
- [FileName.xml] /node[value]/node[value]/node[value] -
Example 4.3. XPath Utilization with DocBook DTD
Our example is taken from a DocBook book based on the DocBook XML DTD. The book contains a number of chapters. DocBook defines that chapters as have a <chapter> start tag and matching </chapter> end tag to close the element. To return all the chapter nodes of the book enter //chapter into the XPath expression field, then Enter. This will return all the chapter nodes of the DocBook book, in the Message Panel. If your book has six chapters, their will be six records in the result list. Each record when clicked will locate and highlight the chapter and all sibling nodes contained between the start and end tags of the chapter.
If we used XPath to query for all example nodes contained in the section 2 node of a DocBook XML document we would use the following XPath expression //chapter/sect1/sect2/example. If an example node is found in any section 2 node, a result will be returned to the message panel. For each occurrence of the element node a record will be created in the result list.
In our example an XPath query on the file oxygen.xml determined that:
- [oxygen.xml] /chapter[1]/sect1[3]/sect2[7]/example[1]
Which means:
In the file oxygen.xml, first chapter, third section level 1, seventh section level 2, the example node found is the first in the section.
![]() | Tip |
---|---|
If your project is comprised of a main file with ENTITY references to other files, you can use XPath to return all the name elements of a certain type by querying the main file. The result list will query all referenced files. |
The Check Spelling option enables you to perform the check spelling on the current document:
Complete the dialog as follows:
Contains the word that cannot be found in any of the existing dictionaries. The word is also highlighted in the XML document.
The character string with which suggest to replace the unrecognized word.
Displays a list of words suggested to replace the unknown word. Double clicking a word in this list automatically inserts it in the document and continues the spell checking process.
Displays a list with the available dictionaries.
Replaces the currently highlighted word in the XML document, with the selected word in the Guess list box.
Replaces all occurrences of the currently highlighted word in the XML document, with the selected word in the Suggestions list box.
Allows you to continue checking the document while ignoring the first occurrence of the unknown word. The same word will be flagged again if it appears in the document.
Ignores all instances of the unknown word in the whole document.
Includes the unrecognized word in the list of valid words so that the spell checker will no longer consider it for correction.
Sets the configuration options of the Spell Checker.
Closes the Spell Checker dialog.
The Options dialog contains the global check spelling options:
When checked, operations ignore capitalization errors.
When checked, operations do not check words containing case mixing (e.g. "SpellChecker").
When checked, the Spell Checker do not check words containing digits (e.g. "b2b").
When checked, the Spell Checker do not signal two successive identical words as an error.
When checked, ignores words looking like URL or file names (e.g. "www.xxx.com" or "c:\boot.ini") .
When checked, punctuation checking is enabled: misplaced white space and wrong sequences, like a dot following a comma, are detected.
Enables the "Replace Always" feature.
When checked, all words formed by concatenating two legal words with an hyphen are accepted. If the language allows it, two words concatenated without hyphen are also accepted.
When checked, a word formed by concatenating a registered prefix and a legal word is accepted. For example if "mini-" is a registered prefix, accepts "mini-computer".
When checked, accepts any word ending with registered file extensions (e.g. "myfile.txt", "index.html" etc.).
This option indicates the type of spell checker accuracy, which may be: "Favour speed over quality", "Normal" and "Favour quality over speed".
The Search and Replace option enables you to perform the following operations on the current document:
find occurrences of a word or string of characters including white spaces and highlight the position in the editor.
replace occurrences of target defined in the "Find" field with a word or string of characters, including white spaces, defined in the "Replace" field.
find all occurrences of a word or string of characters including white spaces and return a result list to the Message Panel.
replace all occurrences of a word or string of characters including white spaces.
Complete the dialog as follows:
The target character string to search for.
The character string with which to replace the target. It may contain '{$ENTER}' which at the replace time will insert a new line character.
Execute a find operation for the next occurrence of the target and stop.
Execute a replace operation for the target and stop.
Executes a find operation and returns all results to the Message Panel.
When checked, operations are case sensitive.
When checked only whole occurrences of a word will be included in the operation.
When checked, operation will include content of the start and end tags of the XML elements.
When checked allows using any regular expression in PERL syntax.
Commences the operation from start of file, position 0:0.
Continues the find from the start of the document after reaching the end.
The Search and Replace in Files option enables you to perform the same operations as the Search/Replace option on any number of files located in a given path.
Complete the dialog as follows:
The target character string to search for.
When checked, operations are case sensitive.
When checked only whole occurrences of a word will be included in the operation.
When checked, operation will include content of the start and end tags of the XML elements.
When checked allows using any regular expression in PERL syntax.
The character string with which to replace the target. It may contain '{$ENTER}' which at the replace time will insert a new line character.
In the replace process Oxygen make backup files of the modified files. The default extension is *bak, but you can change extension as you prefer.
Choose the search path
Use the path of the current file
Search the files from the current project using the specified file filter.
Search only in the selected files of the current opened project
![]() | Note |
---|---|
The search is performed only on local files. If you have added to the project remote files from an FTP or Webdav server these will be skipped from the search. |
Executes a find operation and returns the result list to the Message Pane
Replaces all occurrences of the target containing in the specified files.
![]() | Use this option with caution. |
---|---|
Global search and replace across all project files does not open the files containing the targets, nor does it prompt on a per occurrence basis, to confirm that a replace operation must be performed. As the operation simply matches the string defined in the find field, this may result in replacement of matching strings that were not originally intended to be replaced. |