Oxygen XML Author 18.1

Writing Your First Document

Depending on the type of document you choose, the Oxygen XML Author 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 Author 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 Author 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 Author 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 Author 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 Author helps you determine which elements are allowed. In Author mode, when you press Enter, Oxygen XML Author 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 Author 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 Author 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 Author 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 Author 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 Author 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, 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 Author 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 (or the Document ⇒ Markup menu). More advanced refactoring operations are also available using the XML Refactoring tool that is available in the 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 Author knows how to find the schema, it validates the document for you as you type. Oxygen XML Author 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 Author 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 Author 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 Author 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 Document ⇒ Validate 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 Author 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 or from the Edit menu.

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 Author 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 Author 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 Document ⇒ Transformation 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 Author 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 Author helps you manage those relationships. Depending on how your topics are related, you can use the tools provided in Oxygen XML Author, 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 or click the New button on the toolbar, go to Framework templates ⇒ DITA Map ⇒ map and select the type of map you want to create. Oxygen XML Author 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 Author 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 Author 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 Author 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 Project from the Project menu, the New menu in the contextual menu, or the drop-down menu at the top-left of the Project view. This opens a dialog box that allows you to assign a name to the new project and adds it to the structure of the project in the Project view.

Adding Items to the Project

To add items to the project, select any of the following actions that are available when invoking the contextual menu in the Project view:

New ⇒ File

Opens a New file dialog box that helps you create a new file and adds it to the project structure.

New ⇒ Folder

Opens a New Folder dialog box that allows you to specify a name for a new folder and adds it to the structure of the project.

New ⇒ Logical Folder

Creates a logical folder in the tree structure (the icon is a magenta folder on Mac OS X - ).

New ⇒ Logical Folders from Web

Replicates the structure of a remote folder accessible over FTP/SFTP/WebDAV, as a structure of logical folders. The newly created logical folders contain the file structure of the folder it points to.

Add Folder

Adds a link to a physical folder, whose name and content mirror a real folder that exists in the local file system (the icon of this action is different on Mac OS X ).

Add Files

Adds links to files on the local file system.

Add Edited File

Adds a link to the currently edited file in the project.

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 Project 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 selecting Add Folder in the contextual menu from the project root. Linked folders are displayed in the Project view with bold text. To create a file inside a linked folder, select the New ⇒ File action from the contextual menu. The linked files presented in the Project view are marked with a special icon.