<oXygen/> User Guide

Chapter 3. Getting Started

This section provides an overview of the Oxygen Graphic User Interface (GUI). It provides you with an explanation for each of the interface components and a short description of its purpose or usage. The Oxygen work area is split in three panes:

Preferences

Once Oxygen is installed you may want to use the following preferences to customize Oxygen for your requirements and network environment.

Global

Figure 3.1. The Global preferences

The Global preferences
Change Interface Language

Oxygen supports a number of languages for localization of the GUI. Select Options->Preferences->Global+Language droplist to display the language choices.

Changing Look and Feel

Use this option to change graphic style (look and feel) of the GUI.

Automatic Version Checking

When enabled, checks the availability of new Oxygen versions at http://www.oxygenxml.com.

Encoding for non XML files

This option defines the default encoding to be used when opening non XML documents.

BOM handling

This option defines how to handle the BOM( Byte Order Mark) on document save.

The available options are:

  • Don't Write - Don't write the BOM bytes, the loaded BOM bytes are ignored;

  • Write - Write the BOM bytes accordingly with choosed encoding;

  • Keep - If the loaded document has BOM then write them accordingly with choosed encoding. This is the default option.

Line separator

This option defines line separator to be used.System Default choice sets the line separator from the platform.

Default Internet browser

The path to a web browser executable. The browser is used to open XSLT or PDF transformation results, to open the Oxygen homepage or to point to specific paragraphs in the W3C recommendation of XML Schema grammars on the W3C website in case of validation errors.

Editor

Use these options to configure the visual aspect, formatting parameters, and behaviour of the content assistant.

Aspect

Figure 3.2. The Aspect pane

The Aspect pane
Font

Use this option to select the font family and size used to display text in the editor.

Editor background color

Use this option to set the background color of the editor.

Editor caret color

Use this option to set the background color of the editor.

Selection foreground color

Use this option to set the text color of selected text.

Selection background color

Use this option to set the background color of selected text.

Same font for the GUI

When checked the editor will use the font from the GUI.

Text antialiasing

This option indicates whether text strings should be drawn with antialiased rendering.

Line Wrap

This option will automatically wrap lines in edited documents.

Show EOL/EOF marks

Marks the EOL/EOF using small icons, for a better visualisation of the document.

Show line numbers

This option enables the line numbers column located in the left part of the editing space. When unchecked, line numbers option is disabled.

Format

Figure 3.3. The Format pane

The Format pane
Indent size

Sets the number of spaces or the tab size that will equal a single indent. The Indent can be spaces or a tab, select the preference using the Indent With Tabs option. If set to 4 one tab will equal 4 white spaces or 1 tab with size of 4 characters depending on which option was set in the Indent With Tabs option.

Indent with tabs

When checked enables 'Indent with tabs' to sets the indent to a tab unit. When unchecked, 'Indent with tabs' is disabled and the indent will measure as many spaces as defined by the 'Indent size' option.

Smart indent

Smart Indent attempts to indent mark-up in accordance to the tag/text and its position/ context within the body of a document. This option either enables or disables the use of smart indenting.

Line width - pretty print

Defines the point at which the "Format and Indent" (Pretty-Print) function will perform line wrapping. So if set to 100 Pretty-Print will wrap lines at the 100th space inclusive of white spaces, tags and elements.

Expand empty elements

When checked the Format and Indent operation will output empty elements with a separate closing tag, ex. <a atr1="v1"></a>. When not checked the same operation will represent an empty element in a more compact form: <a atr1="v1"/>

Sort attributes

When checked the Format and Indent operation will sort the attributes of an element alphabetically. When not checked the same operation will leave them in the same order as before applying the operation.

Preserve space elements

This list contains the names of the elements for which the contained white spaces like blanks, tabs and newlines are preserved by the Format and Indent operation exactly as before applying the operation.

Strip space elements

This list contains the names of the elements for which contiguous white spaces like blanks, tabs and newlines are merged by the Format and Indent operation into one blank.

Save

Figure 3.4. The Save pane

The Save pane
Make backup copy on save

When checked, on saving the edited document a backup copy is made.

Enable automatic save

Automatic save is a useful and time saving feature that ensures your work is being saved in the background. You can specify the time intervals between automatic saves. When checked enables Automatic Save to use the value specified. When unchecked, Automatic Save is disabled.

Automatic save interval (minutes)

Select the period in minutes for Auto Save intervals.

Tag-Insight

The Tag-Insight feature enables in line syntax lookup and Auto Completion of mark-up elements and attributes to streamline mark-up and reduce errors while editing.

Features

These settings define the operating mode of the content assistant.

Figure 3.5. The Tag Insight Features pane

The Tag Insight Features pane
Use Tag-Insight

This option enables Tag-Insight feature. When unchecked, all Tag-Insight features are disabled.

Close the inserted element

When inserting elements from the Tag-Insight assistant, both start and end tags are inserted.

Add required elements

When checked, Oxygen will insert automatically the required elements from the DTD or XML Schema.

End tag autocompletion

Having manually typed the start tag of an element, Oxygen will automatically insert the after tag when </ is typed.

Insert the required attributes

When checked, Oxygen will insert automatically the required attributes from the DTD or XML Schema for an element inserted with the help of the Tag-Insight assistant.

Insert the fixed attributes

When checked, Oxygen will insert automatically any FIXED attributes from the DTD for an element inserted with the help of the Tag-Insight assistant.

Show all entities

When checked, Oxygen will display a list with all the internal and external entities declared in the current document when the user types the start character of an entity reference (i.e. &).

Cursor position between tags

When checked, Oxygen, will set the cursor automatically beetween tags even if the auto-inserted elements have attributes, that are not required, the position of cursor can be forced between tags.

Learn attributes values

When checked, Oxygen will display a list with all attributes values learned from the current document.

Default

The URL of the default DTD / XML Schema to be used when no grammar is specified in the edited document.

Figure 3.6. The Tag Insight Default pane

The Tag Insight Default pane
DTD

Used to specify the full path location of the DTD file that will be used to initialize the Tag-Insight assistant when a document does not define a DTD, XML Schema, Relax NG or NRL schema.

XML Schema

Used to specify the full path location of the XML Schema file that will be used to initialize the Tag-Insight assistant when a document does not define a DTD, XML Schema, Relax NG or NRL schema.

XSL

These settings define what elements are suggested by the content assistant in addition to the XSL ones.

Figure 3.7. The Tag Insight XSL pane

The Tag Insight XSL pane
None

The Tag-Insight will offer only the XSL information.

XHTML transitional

Includes XHTML Transitional elements as substitute for xsl:element.

Formating objects

Includes Formating Objects elements as substitute for xsl:element.

Other

Includes elements from a DTD file or a XML Schema file specified from a URL as substitute for xsl:element.

XML Catalog

An XML catalog is a set of mappings between remote DTD and/or XML Schema and/or Relax NG files and local copies of these files. When Internet access is not available or is slow one or more XML catalogs can be added to the list in the dialog below and the local copies of the DTD and/or XML Schema and/or Relax NG files will be used during validation. 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.

Figure 3.8. The XML Catalog pane

The XML Catalog pane

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 to standard output 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.

XML Parser Options

Figure 3.9. The XML Parser Options pane

The XML Parser Options pane

http://apache.org/xml/features/validation/schema - This option sets the 'schema' feature to true.

http://apache.org/xml/features/validation/schema-full-checking - This option sets the 'schema-full-checking' feature to true.

Validate against a XML Schema even if a DTD is specified - This option forces validation against a referred XML Schema even if the document includes a DTD declaration.

XSLT Options

Figure 3.10. The JAXP XSLT Transformer option

The JAXP XSLT Transformer option

If you want to use an XSLT transformer different than the ones that ship with Oxygen namely Apache Xalan and Saxon all you have to do is to specify the name of the transformer's factory class which Oxygen will set as the value of the Java property "javax.xml.transform.TransformerFactory". To perform an XSLT transformation with Saxon 7 for instance you have to place the Saxon 7 jar file in the Oxygen libraries directory (the lib subdirectory of the installation directory), set "net.sf.saxon.TransformerFactoryImpl" as the property value and select JAXP as the XSLT processor in the transformation scenario associated to the transformed XML document.

Value

Allows the user to enter the name of the transformer factory Java class.

Validate with

Allows the user to set the XSLT Engine used for validation of XSL documents.

Debugger Settings

This section explains the settings available for Debugger mode. To display settings select Options->Preferences+Debugger Options (see Figure 3.11, “Debugger Settings”).

Figure 3.11. Debugger Settings

Debugger Settings

The following settings are available:

Enable XHTML output

Enable or disable rendering of output to the XHTML Output document view during the transformation process. For performance issues, it is advisable to disable XHTML output for large jobs. Also, the XHTML area is only able to render XHTML documents. In order to view the output result of other formats, such as HTML, save the Text output area to a file and use the required external browser for viewing.

Infinite loop detection

Set this option to receive notifications when an infinite loop occurs during transformation.

Maximum depth in templates stack

How many templates (<xsl:templates>) instructions can appear on the current stack. This setting is used by the infinite loop detection.

FO processors

Besides the built-in formatting objects processor (Apache FOP) the user can use other external processors. Oxygen has implemented an easy way to add XEP as external FO processor if the user has the XEP installed.

Figure 3.12. The FO processors pane

The FO processors pane
Enable the output of the built-in FOP

When checked all FOP output will be displayed in a results pane at the bottom of the editor window including annoying messages about FO instructions not supported by FOP.

Memory available to the built-in FOP

If your FOP transformations fail with an "Out of Memory" error select from this combo box a larger value for the amount of memory reserved for FOP transformations.

Configuration file for the built-in FOP

You should specify here the path to a FOP configuration file, necessary for example to render to PDF using a special true type font a document containing Unicode content.

The users can configure the external processors for use with Oxygen in the following dialog.

Figure 3.13. Configure the external processors

Configure the external processors
Name

The name that will be displayed in the list of available FOP processors on the FOP tab of the Transforming Configuration dialog.

Description

The description of the FO processor displayed in the Preferences->FO Processors option.

Working directory

The directory in which the intermediate and final results of the processing will be stored.

Command line

The command line that will start the FO processor, specific to each processor.

Plugins

Oxygen provides the ability to add plugins that extend the functionality of the application. The plugins are shipped as separate packages; check for new plugins on Oxygen site: http://www.oxygenxml.com.

One plugin consists of a separate sub-folder in the Plugins folder in the Oxygen installation folder. This sub-folder must contain a valid plugin.xml in accordance with the plugin.dtd file from the Plugins folder.

Oxygen automatically detects and loads plugins correctly installed in the Plugins folder and displays them in the Plugin option from the Preferences dialog.

Figure 3.14. The Plugins pane

The Plugins pane

A short description of the plugin can be obtained with a click on the plugin name.

External Tools

The user can run within Oxygen other tools as if from the command line of the operating system shell. The configuration of such a tool is done in the following dialog.

Figure 3.15. Configure External Tools

Configure External Tools
Name

The name of the menu entry corresponding to this tool that will be displayed in the External Tools menu and in the external tools combo box on the toolbar.

Description

The description of the tool displayed in the Preferences->External Tools option.

Shortcut key

The keyboard shortcut that launches the external tool.

Working directory

The directory the external tool will use to store intermediate and final results.

Command line

The command line that will start the external tool.

Menu shortcut keys

The user can configure in one place all the keyboard shortcuts of the menu items available in Oxygen. The current shortcuts assigned to menu items are displayed in the following table.

Figure 3.16. The Menu shortcut keys pane

The Menu shortcut keys pane
Description

A short description of the menu item operation.

Category

The shortcuts are classified in categories for easier management. For example the "Cut" operation for the source view is distinguished from the tree view one by assigning it to a separate category.

Shortcut key

The keyboard shortcut that launches the operation. Double-clicking on a table row or pressing the "Edit" button allows the user to register a new shortcut for the operation displayed on that row.

File Types

Oxygen offers support for a wide variety of file types, but users are free to add new file types specified by extension and associate them with the editor type which fits better.

Figure 3.17. The File Types

The File Types
Extension

The new file types.

Editor

The type of editor which the extensions will be associated with. Some editors provide easy access to frequent operations via toolbars (e.g. XML editor, XSL editor, DTD editor) while other provide just a syntax highlight scheme (e.g. Java editor, SQL editor, Shell editor, etc.)

Proxy Configuration

Some networks use Proxy servers to provide Internet Services to LAN Clients. Clients behind the Proxy may therefore, only connect to the Internet via the Proxy Service. The Proxy Configuration dialog enables this configuration. If you are not sure whether your computer is required to use a Proxy server to connect to the Internet or the values required by the Proxy Configuration dialog, please consult your Network Administrator.

Open the Proxy Configuration dialog by selecting Options->Preferences->Proxy Configuration.

Figure 3.18. The Proxy Configuration Dialog

The Proxy Configuration Dialog

Complete the dialog as follows:

Use proxy server

When checked enables Oxygen to use the specified Proxy Server. When unchecked, Proxy Server is disabled.

Web Proxy (HTTP)

The IP address or Fully Qualified Domain Name (FQDN) of the Proxy Server.

Port

The TCP Port Number, normally set to 80 or 8080.

User

The Name of the user if required. Can be empty.

Password

The Password for authentication. Can be empty.

Specify domains for which no proxy should be used.

SOCKS

When checked enables SOCKS using the specified host and port for the server. When unchecked, SOCKS is disabled.

Host

The SOCKS host you wish to connect to.

Port

The SOCKS port you wish to connect to.

Results / Output

Figure 3.19. The Results/Output option

The Results/Output option
Maximum number of lines

This option sets the maximum number of lines of the output console where the external tools place their output.

Print

Figure 3.20. The Printing Scale option

The Printing Scale option

It is sometimes useful to print out the contents of a document on paper. Oxygen allows you to adjust the scale of the print output to make it easier to read on a page.

Printing Scale

Displays a slide allowing the user to adjust the printing scale between 40% and 100%.

Colors

Oxygen support Syntax Highlight for XML, DTD, Relax NG (XML and Compact Syntax), Java, C++, C, PHP,CSS, Perl, Properties, SQL, Shell and Batch documents. While Oxygen provides a default color configuration for highlighting the tokens, you may choose to customize, as required, using the Colors dialog.

Figure 3.21. The Colors pane

The Colors pane

Open the Colors dialog by selecting Options->Preferences->Colors and choose one of the supported Document Types. Each document type contains a set of Tokens. When the Document Type is selected the associated tokens are listed. Selecting a token displays the current color properties and enables you to modify them.

Use Swatch, HSB or RGB models from the Color Dialog to define the color properties.

Modifications are saved when the OK button is clicked. Cancel discards changes. Reset button change the color to the default value.

Swatches

Displays a color pallet containing a variety of colors from across the color spectrum and shades thereof. Select a color.

HSB

Hue, Saturation and Brightness (HSB) enables you to specify a color by describing it using hue, saturation and brightness.

RGB

Red, Green and Blue (RGB) enables you to specify a color using triplets of red, green and blue numbers.

Preview

Displays the color properties of the current token and results of customization.