Common XML for Requirements and Solutions

Simon Ambler.

Version: 0.1
Date: 9th October 2002

Introduction

Documentation based on the DTD.

XML elements

<title> The document title.

Contents: Text

<author> The name of one of the authors of the document.

Contents: Text

Where a document has several authors then put each one in a separate author element.

Attribute	Sort	Value	Description
email	optional	Text	The e-mail address of the author.
webpage	optional	Text	The web-page of the author.

<introduction> An introduction to the document.

Contents: (para+)

Several paragraphs of text to set out the context of the document and to give overview of the contents.

<summary> A brief description of the requirement or solution idea.

Contents: Text (incl. bold, italic, and link)

No more than a sentence or two.

<details> A more detailed description of the requirement or solution idea.

Contents: (para+)

This may run to several paragraphs. It should say enough to make it entirely clear what is meant. It may also contain some discussion or justification of the analysis.

Note that each paragraph must be contained in a para element.

<para> A paragraph of text.

Contents: Text (incl. bold, italic, and link)

<bold> Used within text elements to mark where the text should be in boldface.

Contents: Text

Note that bold, italic and link tags cannot be nested.

<italic> Used within text elements to mark where the text should be in italics.

Contents: Text

Note that bold, italic and link tags cannot be nested.

<link> A hyper-text link.

Contents: Text

Note that bold, italic and link tags cannot be nested.

Attribute	Sort	Value	Description
url	required	Text	The URL of the target document.

<crossref> Cross reference to an element within a requirements or solutions hierachy.

Contents: Text

Use crossref rather than link where the target element lies within the same document. This ensures that JavaScript high-lighting works.

Attribute	Sort	Value	Description
document	optional	Text	URL of the document being cross-referenced (if the document is not the current one).
section	required	(hierachy \| listing)	Section being referenced.
path	required	Text	Path of requirement or solution element within the hierachy.

<figure> The measurement of a quality or resource element or the impact of some solution.

Contents: None

Attribute	Sort	Value	Description
quantity	required	Text	Number or level on the scale of measurement.
error-margin	optional	Text	If the actual value of quantity is uncertain then error-margin gives a magnitude for the likely error. The actual value should lie between quantity - error-margin and quantity + error-margin.
suffix-unit	optional	Text	Prefix symbol or abbreviation for the unit of measurement.
suffix-unit	optional	Text	Suffix symbol or abbreviation for the unit of measurement.

<justify> A short paragraph to justify the value of a particular figure.

Contents: Text (incl. bold, italic, and link)