Table of Contents
authors - List a module's authorsdescription - description of some aspect of a moduledeveloper - Documentation intended for module developersgui - Documents the use of a module's graphical user interfaceimplementation - A list of a module's c++, c, and fortran source fileslabel - A label (text) associated with a GUI
widget.modref - Cross-reference to a module specification document.outputs - Documents a module's outputsio - Specifies a module's inputs and outputsnets - Documents the use of a module via one or more simple networksoverview - Lists a module's authors and describes a module's
purpose.section - A titled section sub-divisionsummary - summarizes a module's purposetesting - Documents a plan for testing a moduleulink - A URL-based link.xref - An intra-document cross-referenceTable of Contents
Table of Contents
This section introduces the SCIRun module specification language.
Writing a module specification should be one of the first steps in the design and implementation of a module.
A module specification documents the use, design, implementation, and testing of a SCIRun module.
HTML and PDF documention for a module are generated from a module specification. A module's source code can be partially generated from its module specification.
A module specification is written in an XML-based mark-up language. The rest of this document describes the grammer and semantics of the module specificition language.
An XML formulation of the module specification is used to achieve the following goals:
Represent the module specification as a set of data to be used in several contexts.
Specify all modules the same way
Validate (check for correctness and completeness) module specifications.
The module specification mark-up language is similar in concept to HTML, but has a different, smaller set of tags, and a simpler, more regular set of document composition rules.
An XML Schema defines a set of elements, element attributes, and the way they may be used in order to produce a valid document. The module specification language definition is available as a DTD and as a RELAX NG schema.
The module specification DTD can be found, relative to the top of the SCIRun tree, here:
src/Dataflow/XML/component.dtd
. The RELAX NG schema can be found here:
src/Dataflow/XML/component.rnc
Table of Contents
Any text editor can be used to create a module specification document's content. However, because it is easy to get lost in the “noise” of XML syntax, it is best to use an XML/Schema (e.g. DTD, Relax NG) aware editor. This type of editor will help construct a valid module specification document. Emacs is one such editor.
Emacs supports editing environments PSGML mode and nxml mode. These modes highlight XML syntax, indent nested elements and their content, and suggest elements based on the position of the insertion point. Nxml mode performs on-the-fly validation (PSGML does not).
Nxml mode can be downloaded from:
http://www.thaiopensource.com/download/
Information on the use of nxml mode can be found here:
http://www.xmlhack.com/read.php?item=2061
PSGML mode can be downloaded from:
http://sourceforge.net/projects/psgml/
Information on the use of psgml mode can be found here:
http://www.lysator.liu.se/~lenst/about_psgml/
It is strongly recommended that content is created with one of these editing modes in emacs. Note also that these modes are excellent for composing any xml (e.g. xhtml, DocBook, etc) content.
This author recommends nxml mode because it is simpler to use than psgml mode, performs on-the-fly content validation, and is actively supported.
Nxml mode is commonly installed in a sub-directory of
emacs'site-lisp directory, typically
/usr/share/emacs/sitelisp/nxml.
After installing nxml, file
component.rnc must be copied to
nxml/schema.
The following lines must be added to file
nxml/schema/schemas.xml:
<documentElement prefix="" localName="component" typeId="Component"/> <typeId id="Component" uri="component.rnc"/>
The following lisp code should be inserted into Emacs'
.emacs initialization file prior to using
nxml mode:
(load "nxml/rng-auto")
(setq auto-mode-alist
(append
'(("\\.xml" . nxml-mode)
("\\.html" . nxml-mode))
auto-mode-alist))
(make-face 'nxml-delimited-data-face)
(make-face 'nxml-name-face)
(make-face 'nxml-ref-face)
(make-face 'nxml-delimiter-face)
(make-face 'nxml-comment-content-face)
(make-face 'nxml-comment-delimiter-face)
(set-face-foreground 'nxml-delimited-data-face "grey55")
(set-face-foreground 'nxml-name-face "#257A25")
(set-face-foreground 'nxml-ref-face "#9292C9")
(set-face-foreground 'nxml-delimiter-face "#9292C9")
(set-face-foreground 'nxml-comment-content-face "orange")
(set-face-foreground 'nxml-comment-delimiter-face "orange")
The following lisp code should be inserted into Emacs'
.emacs initialization file prior to using
SGML mode:
;; Setup autoloading
(require 'psgml)
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files" t)
(autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
(setq auto-mode-alist
(append
'(("\\.xml" . xml-mode)
("\\.html" . sgml-mode))
auto-mode-alist))
;; Indent tags but not content.
(setq sgml-indent-step 2)
(setq sgml-indent-data nil)
;; Create appropriate "faces"
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)
(make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face)
(make-face 'sgml-comment-face)
;; Assign colors to faces
(set-face-foreground 'sgml-start-tag-face "grey55")
(set-face-foreground 'sgml-end-tag-face "seagreen")
(set-face-foreground 'sgml-entity-face "yellow2")
(set-face-foreground 'sgml-doctype-face "orange3")
(set-face-foreground 'sgml-comment-face "lightblue")
;; Assign faces to sgml objects
(setq sgml-set-face t)
(setq sgml-markup-faces
'((comment . sgml-comment-face)
(start-tag . sgml-start-tag-face)
(end-tag . sgml-end-tag-face)
(doctype . sgml-doctype-face)
(entity . sgml-entity-face)))
To create a new module specification (using nxml mode) follow these steps:
Create a new file and insert the following:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE component SYSTEM "path-to/component.dtd"> <component name="component-name" category="category-name"> </component>
Save, close, and re-open the file (this will force nxml/sgml mode to load the proper schema when the file is re-opened).
Insert remaining content using features of nxml or psgml mode.
A validation service for module specification xml files can be found here:
Each element reference is organized as follows:
The first part of each element reference provides the name of an element and a short summary of its purpose.
The synopsis consists of two parts. The first part of the synopsis presents an element's content model using a DTD-like syntax. The second part of the synopsis lists the name, type, and default value of each of the element's attributes.
Describes the element's purpose and use.
Describes the purpose and use of each attribute.
Lists the element's parents.
An element's content model is the DTD fragment describing the element's structure. The content model lists an element's children and the number and order of their occurrence. A content model may contain keywords (e.g., #PCDATA), element names, and tokens that indicate child grouping (“(” and “) ”), sequencing (“,” separates children occuring in sequence), repetition (“*”, zero or more; “+”, one or more; “?”, zero or one), and alternation (“|” separates choices) of children.
Attribute values are one of five types:
A choice of one or more string literals.
A string containing any characters except “<” and “&”
A string uniquely identifying an element. An ID string must start with a letter, underscore, or colon and may then contain any combination of letters, digits, and the characters “.”, “-”, “_”, “:”
A string matching the value of one element's id attribute.
A string consisting of any combination of letters, digits, and the characters “.”, “-”, “_”, “:”
Table of Contents
authors - List a module's authorsdescription - description of some aspect of a moduledeveloper - Documentation intended for module developersgui - Documents the use of a module's graphical user interfaceimplementation - A list of a module's c++, c, and fortran source fileslabel - A label (text) associated with a GUI
widget.modref - Cross-reference to a module specification document.outputs - Documents a module's outputsio - Specifies a module's inputs and outputsnets - Documents the use of a module via one or more simple networksoverview - Lists a module's authors and describes a module's
purpose.section - A titled section sub-divisionsummary - summarizes a module's purposetesting - Documents a plan for testing a moduleulink - A URL-based link.xref - An intra-document cross-referenceTable of Contents
authors - List a module's authorsdescription - description of some aspect of a moduledeveloper - Documentation intended for module developersgui - Documents the use of a module's graphical user interfaceimplementation - A list of a module's c++, c, and fortran source fileslabel - A label (text) associated with a GUI
widget.modref - Cross-reference to a module specification document.outputs - Documents a module's outputsio - Specifies a module's inputs and outputsnets - Documents the use of a module via one or more simple networksoverview - Lists a module's authors and describes a module's
purpose.section - A titled section sub-divisionsummary - summarizes a module's purposetesting - Documents a plan for testing a moduleulink - A URL-based link.xref - An intra-document cross-referencecaption — A description of an image
component — Module description top-level element.
description — description of some aspect of a module
Element description
is a small documentation environment. It is used in several places to
document a particular aspect of a module. It offers many markup
tags equivalent to those found in xhtml. A number of tags are
unique to the task of writing module descriptions.
idId is an
identifying string for a description element. It must be unique
within a module description and must begin with a letter.
Attribute id
is used with element xref to create cross-references
within a module description document.
developer — Documentation intended for module developers
developer::= (p|latex|figure|pre|orderedlist|unorderedlist|desclist|note|tip|warning)
Element developer
presents information intended for module developers. Developer's content model is
similar to element description's content
model, but may not be divided into sections.
examplesr — Specifies the path of a SCIRun network file which demonstrates the use of a module. Deprecated
Specifies the path of a SCIRun network file which
demonstrates the use of a module. Element examplesr is deprecated. Element nets
is now used to demonstrate the use of a module in a network.
figure — A captioned image
idId is an
identifying string for a figure
element. Id must be unique within
a module specification and must begin with a letter.
Attribute id
is used with element xref to create cross-references
within a module specification document.
The following elements contain figure: description,desclistdef,developer,listitem,net,note,section,step,tip,warning
gui — Documents the use of a module's graphical user interface
Element gui
documents the use of a module's graphical user interface.
Use of content model fragment
(img,caption?)*
is deprecated.
Instead, screenshots of a module's GUI should be
presented within the description element using figures and xrefs.
img — The pathname of an image file
inputs — Documents a module's inputs
Element inputs
specifies and documents a module's inputs. An input may come
from a port, file, or device.
modref — Cross-reference to a module specification document.
Element modref is a
cross-reference to another module specification. Attributes
name and package uniquely specify the
referenced module. Modref
may be empty or may contain cross-reference text. If
modref is empty, suitable
cross-refence text will be generated.
outputs — Documents a module's outputs
io — Specifies a module's inputs and outputs
net — Demonstrates the use of a module within a small network
Element net
is an environment for documenting the use of a
module within a SCIRun network. Element net's content model is identical to
element description's content model.
idId is an
identifying string for a description element. It must be unique
within a module description and must begin with a letter.
Attribute id
is used with element xref to create cross-references
within a module description document.
p — A paragraph
plan — A testing plan for a module
Element plan
outlines one plan for testing a module. Plan consists of a general test plan description followed by one or more
specfic test plan steps.
section — A titled section sub-division
Element section is
a titled sub-division of the documentation elements description, net, step. Section elements may be
nested.
idId is an
identifying string for a section element. It must be unique
within a module description and must begin with a letter.
Attribute id
is used with element xref to create cross-references
within a module description document.
step — Describes one step in a module testing process
Element step
describes one step in a module's test plan.
Step's content
model is identical to description's content model.
summary — summarizes a module's purpose
ulink — A URL-based link.