Xuse User Guide: Common Concepts

Within Xuse common concepts are used throughout the model XML files. These are described below.

Annotations

Annotations are similar in concept as annotations in MS Word documents. They can be used however you like, but are typically expected to capture thoughts that need to be revisited, inline review comments, outstanding issues or for internal team communication that should not be part of formal documentation.

Unlike MS Word annotations cannot be attached to any text, however they are used fairly extensively within the data model and can thus be associated with requirements, use-cases, use-case steps etc. The image below shows a typical annotation in XML.

annotation xml format

Annotation is normally displayed on right hand side of the associated item in similar way to MS Word.

example requirement HTML view annotation

Note: In general annotations are likely to become more sophisticated in future versions of Xuse.

Annotation XML reference

The following table explains the XML structure for an annotation.

Location/XPath Cdn. Description
[root-path]/xuse:annotation 1 Container element for the annotation.
[root-path]/xuse:annotation/xuse:description 1 Description text for the annotation.
[root-path]/xuse:annotation/xuse:author. 1 Author that created the annotation.
[root-path]/xuse:annotation/xuse:intended-audience 1 Who the annotation is intended to be viewed by. Permissible values are:
  • all
  • internal
  • client
  • requirements
  • development
  • design
[root-path]/xuse:annotation/xuse:creation-date 0..1 Date the annotation was created in the xs:date format.
[root-path]/xuse:annotation/xuse:comments 0..1 Container element for one or more (response) comments associated with this annotation.
[root-path]/xuse:annotation/xuse:comments/xuse:comment 1..* Container element for a (response) comment associated with this annotation. As the discussion around the original annotation progresses there may be many of these blocks.
[root-path]/xuse:annotation/xuse:comments/xuse:comment/xuse:description 1 Description text for the response. Typically useful where the original annotation raised a query.
[root-path]/xuse:annotation/xuse:comments/xuse:comment/xuse:comment-author 0..1 Name of the author of the response.
[root-path]/xuse:annotation/xuse:comments/xuse:comment/xuse:comment-date 0..1 Name of the author of the response.

Description-text

Description text is used in many places within Xuse. This is a fairly flexible construct that allows normal text to be inter-woven with cross-references to requirements and use-cases.

An example XML fragment is shown below showing how to link to specific requirements. This is particularly useful for Use-case steps.

example description text XML fragment

This is rendered as:

example description text HTML fragment

This example shows how to link a another use-case. Note: the container element for description text is not always <xuse:description/>.

example description text XML fragment

This is rendered as:

example description text HTML fragment

Description text XML reference

The following table explains the XML structure for a description.

Location/XPath Cdn. Description
[root-path]/text() 0..* The description XML Schema type is a mixed typed meaning that text and structure can be freely mixed together.
[root-path]/xuse:req-ref/@refId 0..* Link to a requirement. Note the HTML will link to the requirement, however the link text will be the text contained within the <xuse:req-ref/> element. If no such text is provided the title of the requirement will be shown as the link text. In other words both the following forms of link are allowed:
  • <xuse:req-ref refId="RQ4">your text here</xuse:req-ref>
  • <xuse:req-ref refId="RQ4" />
[root-path]/xuse:uc-ref/@refId 0..* Link to a use-case. Note the HTML will link to the use-case, however the link text will be the text contained within the <xuse:uc-ref/> element. If no such text is provided the name of the use-case will be shown as the link text. In other words both the following forms are valid:
  • <xuse:uc-ref refId="UC2">your text here</xuse:uc-ref>
  • <xuse:uc-ref refId="UC2" />

Replacement text

Xuse has the concept of comment (keyword) replacement text such that you do not have to edit multiple files when some terms change for example <xuse:project/> would be replaced by the actual project name in the output files.

TODO - this section needs completing.

XHTML subset

Xuse will render a subset of comment XHTML formatting elements.

TODO - this section needs completing.