Introduction

Layout

The XMLFlow layout comprises a header bar, a side bar and the main document view. Its dimensions and panels are arranged specifically for the IPad tablet, but it is designed also to adapt for larger displays.

The side bar includes three tabbed panels: the Files Panel, the Content Panel and the Attributes Panel, buttons on the tab-bar at the top of the sidebar are used to switch between each of these sub panels.

The header bar is organised in a upper and lower section. The upper section holds general control buttons, whils the lower section contains the Labels Panel (showing 'base', 'anna' and 'ben' labels in the adjacent screenshot) on the left and a multi-purpose Status Panel to the right.

XMLFlow comprises a header bar, a side bar and the document view.

Workflow

XMLFlow's 'working merge' is designed to fit in with the various types of workflow that might arise in the DITA publishing process. The following steps assume the working merge is finalized in the same session, even though this will not always be the case:

  • Load the 'common ancestor' file
  • Load several different versions of the common ancestor
  • Add meaningful labels for each version
  • If required, sort the different versions
  • Begin the Merge operation to produce a 'working merge'
  • Accept/reject content and attribute changes in the working merge
  • Finalize the working merge to produce a 'finalized DITA' document
  • Store the finalized DITA and working merge files
  • Externally process the stored files

The working merge can be updated, stored and reloaded in XMLFlow any number of times, either in the current review session in XMLFlow or in a later session. Conversely, the finalized DITA file is more restrictive as review information is removed in the Finalize process.

If the working merge file is selected and updated after a Finalize operation, then a new finalized DITA file is created automatically when it is re-selected. Any updated files should be stored again, previously stored files are never updated.

A typical document review workflow.

Managing Files

You manage files in XMLFlow with the Files Panel (see screenshot), the first of three tabbed pages in the side bar. Files are represented as buttons with a short label at the top and the full filename below.

Loading

Before merging files, you first need to upload the different versions. For this, the top part of the Files Panel (above the Console) serves as a drop zone, so you can drag and drop files from your desktop into this area.

Alternatively you can upload documents already in the cloud by pressing the Upload button in the console at the bottom of the Files Panel. A popup box will be shown, prompting you for the URL of a file, enter the URL for each file, pressing the Load button for each URL, when all files are loaded, press the Cancel button.

Working merge files (still containing change data) previously stored using XMLFlow can also be loaded using either method described above. When such files are loaded, any other files are removed from the panel.

Only valid DITA files or an XMLFlow Working Merge may be uploaded, invalid files are marked with a red diamond.

Sorting and Labelling

It is important for the 'common ancestor' of a merge to be the first listed file. You can change the order of input files by selecting them and then using the left and right arrow buttons on the main toolbar to change their position.

The labels for each file are used to identify the origin of changes in the merge. They appear at the top of each file button and they are also shown in the Labels Bar immediately above the Files Panel. Labels are given an initial value, but these can be edited in the Labels Bar to be more meaningful.

Manage files in the Labels Bar and Files Panel

Merging

Once you have loaded three or more source files (including the common ancestor), sorted and labelled them, you are ready to merge. To begin a merge, press the Merge button in the lower Button Panel.

The merge may take 30 seconds or so (host resources are currently restricted), a timer in the Message Bar at the top of the Button Panel provides a rough indication of progress. Once the merge completes, a Working Merge button is added to the Files Panel and the merged document is shown in the Document View (see screenshot).

Once a working merge is created, you can review all changes in the Document View, the Content Panel, or the Attributes Panel, as described in the Working Merge section below.

Storing and Downloading

To store any file in the Files Panel, first select it and then press the Store button. The selected file is stored (non-permanently) on the XMLFlow Server and a URL for this is shown in the Status Panel on the toolbar, the URL can be copied and pasted to another application, or emailed to someone else for review purposes.

Unless you're working on an IPad (that doesn't expose the file system), you can also download the stored file to your local machine. In Chrome you just press the Download button, but in other browsers the button will behave as a link, so you will need to 'right-click' and select the 'Save As' option.

Finalizing

The Working Merge keeps a record of changes and their review state (accepted/rejected) embedded in the file. This is useful for records keeping, sharing with others, or if you need to alter the review state of recorded changes. However, the additional embedded data, means that this is no longer a valid DITA file.

The Finalize action, requires that all changes (including attribute changes) have been accepted or rejected and applies or removes the changes respectively from the Working Merge. Provided that there are no 'undecided' changes, all change information is removedfrom the Working Merge and you are left with a valid DITA file that can be processed in the usual way.


Changes are highlighted in the document view

Review and Approval

The working merge is created by the Merge operation (see the Merging section above) and is used to review and approve all document changes.

Content and attribute changes are numbered and listed in their respective Content and Attribute panels in the side bar. When a change is selected in the side bar, the associated document part is highlighted in the document view. Likewise, a change selected in the document view will also be highlighted in the the side bar.

Review and approval is performed on the working merge

The 'accept/reject' mode is set in the header bar

Content Change

Changes to document content may either be at the element or text level. Text-level changes have circular icons in the side bar and rounded borders in the document view, element-level changes have square icons in the side bar and squared borders in the document view.

Changes can be adds or deletes at the element or the text level, in the side bar these are shown with the '-' and '+' characters and are colored red and green respectively. In the document view, element additions are shown with shadows, whilst deletions are shown with a dashed border.

Text-level changes may also be of type 'replace' or 'modify', these are colored blue and are represented in the side bar icons with '|' and '*' characters respectively.

When approving changes, you should first set the required 'accept' or 'reject' mode using the option button in the header bar. When the change type is 'replace' or 'modify', only the 'accept' mode can be used.

Once the approval mode is set, you just need to select changes in either the side bar or the document view, buttons in the side bar will expand when selected for 'replace' or 'modify' change types. To undo an approval action, simply select the same change again.

Content changes highlighted in the side bar and document view

Attribute Change

Changes to attributes are managed in a very similar way to text-level changes, with the same types of: 'add', 'delete', 'replace' and 'modify'.

The buttons in the side bar (Attributes Panel) show the attribute name and current attribute value for each attribute change. The same 'accept' or 'reject' mode is used for approval of attribute changes.

Attribute changes highlighted in the 'Attributes' panel of the side bar/p>

Additional Features

Extra features are provided to help you work with revisions more effectively, these are outlined in this section.

Origin of change

Each time you select a change, all labels associated with the change will be underlined in the labels bar.

Highlight changes for a single revision

To highlight just the changes for a particular revision, select the associated label in the label bar, with the red or green highlighter background color indicating a delete or add.

Reveal element structure

The element paths for the more structure DITA elements can be shown immediately above their content. Press the 'filter' button in the header bar to hide or reveal these paths. The 'reveal' mode also shows content such as DITA comments and keywords that would not normally be rendered in the output.

Previous/next change

Use the Previous and Next buttons (shown as left and right arrows) in the header bar to move to the previous or next change. If you have a keyboard, the up and down cursor keys have the same effect.

Font sizing

An enlarged font size can be set for the document view contents by pressing the 'magnifier' button in the header bar.

Select a label to highlight its changes

The 'reveal' and 'magnifier' butttons in the header bar

The 'previous', 'next' and 'collapse' buttons in the header bar

The type of the currently selected element is displayed in the header bar

Changes can be highlighted for a single label