Document Properties, History and Outline

Documents have a set of properties which can be read and/or set in the Document Editor. A complete history of every Document is automatically maintained. A new revision is created in the repository each time a Document is modified and saved. Revisions can be easily compared.

Document Properties

Documents have the following properties which are displayed in the Properties panel of the Document Sidebar:

  • Name - the name of the document

  • Author - the user name of the person who created the Document.

  • Revision - the current repository revision number of the Document.

  • Auto-Suspect - flag that determines if new Work Items created in the Document are automatically marked as Suspect.

Auto-Suspect Property

If this Document property is enabled in the Document, the Suspect attribute will be applied automatically to child Work Item links, if the parent Work Item is modified. (This setting takes effect when you Save the Document.) The Auto-Suspect works for Document Work Items even if Auto-Suspect is not enabled in Administration. The Suspect flag set on Work Items can be useful for change impact analysis. For more information, see Administrator's Guide: Configuring Work Items: Suspect Default State and User Guide: Suspect Links.

Not Applied to Parents or Structural Document Links

The Suspect attribute is only applied to links to Child Work Items. (Not to Parents or Structural links within a document.)

See Suspect Links for details.

On-demand Work Item Loading

On-demand Work Item Loading is a new feature that dramatically increases the response time when editing large documents. Because it only loads the Work Items that are scrolled into view, it makes editing large documents more fluid and user friendly.

With 17 On-demand Work Item Loading is now enabled by default, for documents containing 200 or more Work Items.

It can still be turned ON or OFF for any document in its Document Sidebar.

Administrators can set system-wide behavior by editing the following property in the polarion.properties file.

On-demand Work Item Loading Property

com.siemens.polarion.ui.document.lazyLoad.enabledByDefault=200

Possible Values:

200 - The default setting. Enabled for all documents containing 200+ Work Items. (Administrators can set any numerical value.)

true - Will enable it by default for all documents.

false - Will disable it by default for all documents.

There are currently some limitations that occur with On-demand Work Item Loading ON :

  • When On-demand Work Item Loading is turned ON, make sure that all the Work Items you wish to copy have finished loading before pasting them somewhere else within the same document.

    (This limitation does not apply when copying them to a different document.)

  • Caption numbers are sometimes replaced with "#" while viewing the document in Polarion. The "#" are replaced with the correct numbers when the document is exported. See the Caption section for details.

Turn ON/OFF On-demand Work Item Loading

On-demand Work Item Loading can be set to ON/OFF for a document in the Document Properties Sidebar.

  1. Select the target document in the Naviagtion bar.

  2. Click on the top right.

  3. Click Document Properties.

    (The Document Properties sidebar appears on the right.)

  4. Click the ON or OFF button in the On-demand Work Item Loading Section.

Figure 15.32. Turn "ON/OFF" On-demand Work Item Loading

Turn "ON/OFF" On-demand Work Item Loading

Document History

Polarion automatically maintains a history of each Document. Every time you save the Document, a new entry, or revision, is created in the history. You can easily review any revision, and you can compare any two revisions to understand what changes took place between the older and the newer revision.

TIP

History is maintained in the underlying Subversion repository. Although developed as a version control (a.k.a. source code control) system, Polarion uses Subversion's history capability to maintain a history of many types of development artifacts, including Documents.

Viewing Document History

Each revision of the Document is automatically assigned a unique numerical ID, and is stamped with the date and time the revision was written to the repository. If you know the revision number you want to see, you can use your browser's Find feature to locate it on the Document history page. In addition to the date and time, the Document history page shows how long ago each revision took place.

To access a Document's history, click on the Document Editor toolbar. (You can also access the Document history via the View History link in the Document Properties panel of the Document Sidebar.)

In the history page, you can browse the table of revisions until you find one you want to view. Then click Show in the Actions column. The document loads in the editor in the state it was when the revision was saved, but the content is read-only and cannot be changed.

Note

If a document revision is opened that contains a block of Wiki syntax, but a historical index of the database is currently in progress, then the block’s content will not be displayed until the indexing is complete. While the historical indexing is in progress, the following warning message appears:

Figure 15.33. Historical Index In Progress Warning

Historical Index In Progress Warning

You can use the Current Revision button to return to the current state of the Document in the editor.

Note

Baseline revisions that do not match will have the revision number and name rendered in italics in all link states (normal, hover, selected).

Comparing Document Revisions

You can compare any two revisions in the Document history page. You cannot compare more than two revisions at once.

To compare Document revisions:

  1. Open the Document history page (see Viewing Document History).

  2. In the Revision # column, check the boxes on the rows of the two revisions you want to compare and then click the Compare button.

There are two content states that can be compared:

  • Document: compare the state of textual content in the two revisions

  • Work Item: compare the state of Work Items defined in the document in the two revisions.

You can jump between changed elements or Work Items using the Changes buttons at the right side of the history page header. Return to the history page using the History button.

Comparing table changes when cells have been merged

When cells that contain text are merged then compared with a previous version, the layout will appear a little strange in the comparison view.

That's because it's more important to view the actual changes than display the layout correctly in comparison view.

(This only affects the comparison view. When exporting or viewing the most recent, merged cell revision, or the historical revision before the merge, both layouts will appear as expected.)
Exporting Comparison to PDF

After comparing two revisions, you can export the comparison result to PDF. You can only export the Document (content) view.

To export Document comparison results to PDF:

  1. Compare 2 revisions as described earlier.

  2. If you are in the Work Items view, click the Document button on the toolbar to return to the Document view.

  3. In the Document view, locate the Actions Menu button on the toolbar, click it, and choose Export to PDF.

  4. In the Export to PDF dialog, set the export options as desired and click Export.

Document Outline

The Outline panel of the Document Sidebar displays a hierarchical tree of the Document's headings, including titles of contained Work Items. The Document outline can help you browse the Document structure to some specific part of a Document. Every node is "live" - clicking a node scrolls the Document content to the respective heading or Work Item. When you are editing content in the Document body, the nearest parent heading or title is selected in the Outline panel.

If the outline is large you can enter some text in the edit control provided to filter the outline for the input text. If you add or remove content in the Document, you can use the Update button to refresh the outline tree.

For more information see User Reference: Documents: Documents Reference: Document Sidebar: Document Outline Panel.