Oxygen XML Editor Eclipse Plugin 18.1

Writing Your First Document

Depending on the type of document you choose, the Oxygen XML Editor plugin interface changes to support editing that document type. This may include new menus, toolbar buttons, and items in the contextual menus.

Also, depending on the type of document you choose, Oxygen XML Editor plugin may open your document in Text or Author mode. Text mode shows the raw XML source file, while Author mode shows a graphical view of the document.

The availability of Author mode for your document type depends on the type you choose and if there is a CSS stylesheet available to create the Author mode. Oxygen XML Editor plugin includes default Author mode views for most of the document types it supports. If your company has created its own document types, Author mode stylesheets may have also been created for that type. However, if you create a plain XML file, or one based on a schema that is not included in the Oxygen XML Editor plugin built-in support, you need to edit it in Text mode or create your own Author mode style sheet for it.

You can switch back and forth between Author mode and Text mode at any time by clicking the buttons at the bottom left of the editor window. You do not lose any formatting when switching from Author to Text mode. Text and Author modes are just different views for the same XML document. There is also a Grid mode available, which is useful for certain kinds of documents, particularly those that are structured like databases. You can also use it to sort things such as list items and table rows.

If you use Author mode, you might find that it is similar to word processors that you are used to. Likewise, the Text mode is similar to many typical text editors. If you are new to XML, the biggest difference is that XML documents have a particular structure that you have to follow. Oxygen XML Editor plugin assists you with a continuous validation of the XML markup.

Structuring Your First Document

Each XML document type has a particular structure that you have to follow as you write and edit the document. Some document types give you a lot of choices, while others give you very few. In either case, you need to make sure that your document follows the particular structure for the document type you are creating. This means:

• At any given location in the document, there are only certain XML elements allowed. Oxygen XML Editor plugin helps you determine which elements are allowed. In Author mode, when you press Enter, Oxygen XML Editor plugin assumes that you want to enter a new element and shows you a list of elements that can be created in this location. Keep typing until the element you want is highlighted and press Enter to insert the element. If you want to view the overall structure of a document and see what is allowed (and where), you can use the Model view ( Window ⇒ Show View ⇒ Model ).
• When you create certain elements, you may find that your text gets a jagged red underline and you get a warning that your content is invalid. This is usually because the element you have just created requires certain other elements inside of it. Your document will be invalid until you create those elements. Oxygen XML Editor plugin does its best to help you with this. If there is only one possible element that can go inside the element you just created, Oxygen XML Editor plugin creates it for you. However, if there is more than one possibility, you have to create the appropriate elements yourself. In many cases, Oxygen XML Editor plugin presents XML Quick Fixes that help you resolve errors by offering proposals to quickly fix problems such as missing required attributes or invalid elements.

Editing Your First Document

Once you have completed the first draft of your document, you may need to edit it. As with any editor, Oxygen XML Editor plugin provides the normal cut, copy, and paste options as well as drag and drop editing. However, when you are editing an XML document, you have to make sure that your edits respect the structure of the XML document type. In fact, you are often editing the structure as well as the content of your document.

Oxygen XML Editor plugin provides many tools to help you edit your structure and to keep your structure valid while editing text.

The Document Breadcrumbs

Across the top of the editor window (in Text mode), there is a set of breadcrumbs that shows you exactly were the insertion point is in the structure of the document. You can click any element in the breadcrumbs to select that entire element in the document.

Showing Tags

To see exactly where you are in the structure of the document, you can show the tags graphically in the Author view. There are several levels of tag visibility that you can choose using the Display tags mode drop-down menu on the toolbar (the button may look a little different than this, as it changes to reflect the level of tags currently displayed).

Outline View

The Outline view shows you the structure of your document in outline format. You can use it to select elements, or to move elements around in the document.

Outline View

You can configure the Outline view to determine what is shown, such as element names, attributes, and comments. Certain choices may work better for particular document types. You can also filter the Outline view to show only elements with a certain name.

Outline View Filtered to only Show Element Names

Cut and Paste, Drag and Drop

You can cut and paste or drag and drop text, just as you would in any other editor. However, when you do this in Author view, it is important to remember that you are actually moving blocks of XML. When you cut and paste or drag and drop a block of XML, the result has to be valid both where the content is inserted, and where it is removed from.

A big part of doing this correctly is to make sure that you pick up the right block of text in the first place. Using the breadcrumbs or Outline view, or showing tags and using them to select content, can help ensure that you are selecting the right chunk of XML.

If you do try to paste or drop a chunk of XML somewhere that is not valid, Oxygen XML Editor plugin warns you and tries to suggest actions that make it valid (such as by removing surrounding elements from the chunk you are moving, by creating a new element at the destination, or by inserting it in a nearby location).

If you are using Author mode, you can also switch to Text mode to see exactly which bits of XML you are selecting and moving.

Refactoring actions

You can perform many common structure edits, such as renaming an element or wrapping text in an element, using the actions in the Refactoring menu of the contextual menu. More advanced refactoring operations are also available using the XML Refactoring tool that is available in the XML Tools menu.

Validating Your First Document

Validation is the process of making sure that an XML document abides by the rules of its schema. If Oxygen XML Editor plugin knows how to find the schema, it validates the document for you as you type. Oxygen XML Editor plugin finds the schema automatically for most of the document types created from templates. However, in some cases you may have to tell it how to find the schema.

When Oxygen XML Editor plugin validates as you type, there is a small bar at the right edge of the editor that shows you if the document is invalid and where errors are found. If the indicator at the top of that bar is green, your document is valid. If the document is invalid, the indicator turns red and a red flag shows you where the errors are found. Click that flag to jump to the error. Remember that sometimes your document is invalid simply because the structure you are creating is not yet complete.

In addition to problems with the validity of the XML document itself, Oxygen XML Editor plugin also reports warnings for a number of conditions, such as if your document contains a cross reference that cannot be resolved, or if Oxygen XML Editor plugin cannot find the schema specified by the document. The location of these warnings is marked in yellow on the validation bar. If the document contains warnings, but no errors, the validity indicator turns yellow.

You can also validate your document at any time by selecting the Validate action from the Validation toolbar drop-down menu or the XML menu.. When you validate in this manner, if errors are found, the validation result opens in a new pane at the bottom of the editor that shows each validation error on a separate line. Clicking the error takes you to the location in your document where the error was detected.

Proofing Your First Document

Oxygen XML Editor plugin includes an automatic (as-you-type) spell checking feature, as well as a manual spell checking action. To check the spelling of your document manually, use the Check Spelling action on the toolbar.

Transforming Your First Document

An XML document must be transformed to be published. Transformations are specific to the particular type of document you have created. For example, a DITA transformation cannot be used on a DocBook file, or vice versa. A single document type may have many multiple transformations that produce different kinds of outputs. For some document types, such a DITA, many different content files may be combined together by a transformation. You need to locate and launch a transformation that is appropriate for your document type and the kind of output you want to generate.

Oxygen XML Editor plugin uses transformation scenarios to control the transformation process. Depending on the document type you have created, there may be several transformation scenarios already configured for your use. This may include the default transformation scenarios supplied by Oxygen XML Editor plugin or ones created by your organization.

To see the list of transformations available for your document, select the Apply Transformation Scenario(s) action from the toolbar or the XML menu. A list of available transformation scenarios are displayed. Choose one or more scenarios to apply, and click Apply associated. Exactly how your transformed content appears depends on how the transformation scenario is configured.

Understanding DITA Topics

It is important to understand the role that a DITA topic plays in a DITA project. A DITA topic is not associated with a single published document. It is a separate entity that can potentially be included in many different books, help systems, or websites. Therefore, when you write a DITA topic you are not writing a book, a help system, or a website. You are writing an individual piece of content. This affects how you approach the writing task and how Oxygen XML Editor plugin works to support you as you write.

Most of your topics are actually related to other topics, and those relationships can affect how you write and handle things such as links and content reuse. Oxygen XML Editor plugin helps you manage those relationships. Depending on how your topics are related, you can use the tools provided in Oxygen XML Editor plugin, along with the features of DITA, in a variety of ways.

Role of Maps

The basic method that DITA uses to express the relationship between topics is through a DITA map. Other relationships between topics, such as cross references, generally need to be made between topics in the same map. DITA uses maps to determine which topics are part of any output that you create. While customized DITA solutions can use other mechanisms, generally DITA is not used as a way to publish individual topics. Output is created from a map and includes all the topics referenced by the map.

A publication is not always represented by a single map. For instance, if you are writing a book, you might use a map to create each chapter and then organize the chapters in another map to create the book. If you are writing help topics, you might use a map to combine several DITA topics to create a single help topic and then create another map to organize your help topics in a help system. This allows you to reuse the content of a map in multiple projects.

Creating a Map

To add topics to a map, you must first create the map. A map is an XML document, similar to a topic. To create a map, select File ⇒ New ⇒ Other ⇒ Oxygen XML Editor plugin , or click the New button on the toolbar, select New from Templates, go to Framework templates ⇒ DITA Map ⇒ map and select the type of map you want to create. Oxygen XML Editor plugin asks if you want to open your map in the editor or in the DITA Maps Manager. Usually, opening it in the DITA Maps Manager is the best choice, but you can also open the map in the editor from the DITA Maps Manager. The DITA Maps Manager presents a view of the DITA map that is similar to a table of contents.

DITA Maps Manager View

Adding Topics to a Map

To add a topic to a map, add a topic reference to the map using a topicref element. The easiest way to do this is to open the topic in the editor, then right-click the DITA map in the DITA Maps Manager view and choose Reference to the currently edited file from the Append child or Insert After submenus. This opens the Insert Reference dialog box with all of the required fields already filled in for you. You can fill in additional information in the various tabs in this dialog box or add it to the map later. When you select Insert and close, a reference to your topic is added to the map.

Insert Reference Dialog Box

If you want to see what the resulting map looks like in XML, save your map and then double-click the DITA map in the DITA Maps Manager view. The XML version of the map opens in the editor.

As you add topics to your map, you may want to make a topic the child or sibling of another topic. This is usually done at the map level. To create a child topic reference, right-click the parent topic in the DITA Maps Manager view and choose Append child. To create a sibling topic reference, right-click a topic in the DITA Maps Manager view and choose Insert After. From either of these submenus you can then choose one of the following options:

• New - Opens the New file wizard for creating a new topic.

• Reference - Opens the Insert Reference dialog box that allows you to create a reference to an existing topic.

• Reference to the currently edited file - Opens the Insert Reference dialog box that helps you to easily create a reference to the file that is currently opened in the editor.

You can also change the order and nesting of topics in the DITA Maps Manager view by doing either of the following:

• Select the topic to move while holding down the Alt key and use the arrow keys to move it around.
• Use the mouse to drag and drop the topic to the desired location.

The way your parent and child topics are organized in any particular output depends on both the configuration of those topics in the map and the rules of the output transformation that is applied to them. Do not assume that your topics must have the same organization for all output types. The map defines the organization of the topics, not the topics themselves. It is possible to create a variety of maps, each with different organization and configuration options to produce a variety of outputs.

Child Maps

If you have a large set of information, such as a long book or extensive help system, a single map can become long and difficult to manage. To make it easier to manage, you can break up the content into smaller submaps. A submap might represent a chapter of a book, a section of a user manual, or a page on a website.

To build a publication out of these smaller maps, you must add them to a map that represents the overall publication. To add a child map to the current map, right-click the parent DITA map and choose Append child ⇒ Map reference .

Validating a Map

Just as it is with your individual topics, it is important to validate your maps. Oxygen XML Editor plugin provides a validation function for DITA maps that does more than simply validating that the XML is well formed. It also does the following:

• Validates all of the relationships defined in the maps.
• Validates all of the files that are included in the map.
• Validates all of the links that are expressed in the files.

Validate and Check for Completeness

Publishing Your Topics

As noted previously, in DITA standards you usually do not publish output from an individual topic. Instead, you create published output by running a DITA transformation on a map. This collects all the topics that are referenced in the map, organizes them, and produces output in a particular format. By default, Oxygen XML Editor plugin uses the transformations provided by the DITA Open Toolkit for publishing to various output formats (such as PDF, WebHelp or EPUB). Your organization may have created various custom transformations or modified the built-in DITA Open Toolkit transformations. In either case, Oxygen XML Editor plugin manages them by using transformation scenarios.

To publish output for a map, select the transformation scenario you want to run and set any of the parameters it requires. To select a transformation, click the Configure Transformation Scenario(s) button in the DITA Maps Manager view. This opens the Configure Transformation Scenario(s) dialog box.

Configure Transformation Scenarios Dialog Box

Creating a New Project

To create a new project, select New ⇒ XML Project or New ⇒ Sample XML Project from the contextual menu or File menu. This opens a dialog box that allows you to create and customize a new project and adds it to the structure of the project in the Navigator view.

Adding Items to the Project

To add items to the project, select the desired document type or folder from the New menu of the contextual menu, when invoked from the Navigator view (or from the File menu). You can also create a document from a template by selecting New ⇒ New from Templates from the contextual menu.

Using Linked Folders (Shortcuts)

Another easy way to organize your XML working files is to place them in a directory and then to create a corresponding linked folder in you project. If you add new files to that folder, you can simply use the Refresh (F5) action from the toolbar or contextual menu and the Navigator view will display the existing files and subdirectories. If your files are scattered amongst several folders, but represent the same class of files, you might find it useful to combine them in a logical folder.

You can create linked folders (shortcuts) by dragging and dropping folders from the Windows Explorer (Mac OS X Finder) to the project tree, or by using the contextual menu from the location in the project tree where you want it added and selecting New ⇒ Folder ⇒ Advanced . The linked folders presented in the Navigator view are marked with a special icon. To create a file inside a linked folder, use the contextual menu and select New ⇒ File (you can use the Advanced button to link to a file in the local file system).

Installation Steps for the HTTP License Server Installer Distribution for Windows

1. Download the HTTP license server installer from the Oxygen XML Editor plugin website.
2. Run the installer and follow the on-screen instructions.
3. You need to configure two sets of credentials:
   1. Administrator credentials - used for accessing the Oxygen XML Editor plugin license server administrative interface. Optionally you can choose to change the standard 8080 port.
   2. Standard user credentials - used by an Oxygen XML Editor plugin application to connect to the license server.
4. Optionally you can choose to install the server as a Windows service. In this case, you can choose the name of the Windows service.

Installation Steps for the HTTP License Server All-Platform Distribution

1. Download the HTTP license server all-platform archive from the Oxygen XML Editor plugin website.
2. Unpack the archive.
3. Run the license server scripts suitable for your operating system (licenseServer.bat for Windows or licenseServer.sh for Linux and Mac).

   Note

   To specify a different port (other than the default 8080), you can pass the new port number as an argument to the scripts (for example, licenseServer.bat 8082).
4. On the first run, you will be prompted to set two sets of credentials:
   1. Administrator credentials - used for accessing the Oxygen XML Editor plugin license server administrative interface.
   2. Standard user credentials - used by an Oxygen XML Editor plugin application to connect to the license server.

Installation Steps for the HTTP License Server WAR Distribution

1. Make sure that Apache Tomcat 5.5 or higher is running on the machine you have selected to be the license server. To get it, go to http://tomcat.apache.org.
2. Download the HTTP license server Web ARchive (.war) from the Oxygen XML Editor plugin website.
3. Configure two Tomcat users:
   1. One user with the role user, used by an Oxygen XML Editor plugin application to connect to the license server. In the subsequent example, this user name is John.
   2. Another user with the roles admin and manager-gui, used for accessing the Oxygen XML Editor plugin license server administrative interface and the Tomcat management interface. In the subsequent example, this user name is Mary.
   A typical way to achieve this is to edit the tomcat-users.xml file from your Tomcat installation (if using a Tomcat zip/tar.gz distribution, by default this configuration file is found in the /TomcatInstallFolder/conf/ directory). After adding the two users, the configuration file might look like this:

   <tomcat-users xmlns="http://tomcat.apache.org/xml"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
                 version="1.0">
     <!-- ... other user and role definitions ... -->
     <role rolename="user"/>
     <role rolename="admin"/>
     <role rolename="manager-gui"/>
     <user username="John" password="user_pass" roles="user"/>
     <user username="Mary" password="admin_pass" roles="admin,manager-gui"/>
   </tomcat-users>

4. Go to the Tomcat Web Application Manager page and log-in with the user you configured with the manager-gui role (Mary in the example above). In the WAR file to deploy section, choose the WAR file and click the Deploy button. The oXygenLicenseServlet application is now up and running, but the license key is not yet registered.
5. Go to the oXygen license server administration page by clicking the oXygenLicenseServlet link in the manager page. You will need to authenticate with the user configured with the admin role (Mary in our example).
6. Activate the floating license key. This process involves binding your license key to your license server deployment. Once the process is completed you cannot activate the floating license with another license server. Follow these steps to activate the license:
   1. Access the HTTP license server by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the credentials configured for the admin or manager users.

      Result: A page is displayed that prompts for a license key.

   2. Paste your floating license key into the form and press Submit. The browser used in the activation process needs to have Internet access.

      Result: You will be redirected to an online form hosted on the Oxygen XML Editor plugin website. This form is pre-filled with an activation code that uniquely identifies your license server deployment, and your license key.

      Note

      If, for some reason, your browser does not take you to this activation form, refer to the Manual Activation Procedure.

   3. Press Activate.

      If the activation process is successfully completed, your license server is running. Follow the on-screen instructions to configure the Oxygen XML Editor plugin client applications.

7. By default, the license server logs its activity in the TomcatInstallDir/logs/oxygenLicenseServlet.log file. To change the log file location, edit the log4j.appender.R2.File property from the TomcatInstallDir/webapps/oXygenLicenseServlet/WEB-INF/lib/log4j.properties configuration file.

Manual License Activation Procedure

1. Access the HTTP license server by following the link provided by the Tomcat Web Application Manager page. You will be taken to the license registration page.
2. Copy the license server activation code.
3. Go to the activation page at http://www.oxygenxml.com/activation/.
4. Paste the license server activation code and floating license key in the displayed form, then click Activate.
5. The activated license key is displayed on-screen. Copy the activated license key and paste it in the license registration page of the HTTP server.

Automatic Subscription Renewal

If the HTTP license server is configured with a subscription license, then the license server will automatically check to see if a new subscription license was purchased and will automatically download and install it for you.

If the automatic renewal process fails, you can try either of the following possible solutions:

• If your server uses a proxy to connect to the Internet, go to the main management page of the license server and configure the proxy settings by clicking the Proxy settings link in the Management tasks section.
• Manually replace the floating license key.