Context Navigation

T3D Technical Documentation

This documentation serves as a technical and development reference for maintenance and further development.

Functioning

The HTML documentation is created in 2 steps:

First, the TTCN-3 files are parsed and the information required for step two is written into XML files. These files are then used to generate the HTML files via XSL-Stylesheets. The XSL-Transformations are done by the Saxon XSLT Processor.

Creating the XML Files

TTCN-3 trees are generated by TRex and are then traversed by Visitors which gather all relevant information to be written into the XML files. The Visitors are instantiated for every TTCN-3 file:

Visitors

There are currently 3 Visitors:

T3DVisior - gathers information used to generate the project.xml
DependencyVisitor - gathers information used to generate the dependencies.xml
ImportVisitor - gathers information used to generate the imports.xml

Creating new Visitors

To create a new Visitor to implement new functionalities or to gather new information from the TTCN-3 files, the following code can be used.

Basic structure of the new Visitor:

package org.etsi.t3d.visitor;

import de.ugoe.cs.swe.trex.core.analyzer.rfparser.LocationAST;

public class NewVisitor extends AbstractVisitor {
	@Override
	public void finish() {
	}

	@Override
	public void init() {
	}

	/*
		visitNodeType(LocationAST node) functions
	*/
}

visitNodeType(LocationAST node) functions are called when nodes of certain types are traversed. For example, visitFunctionDef(LocationAST node) is called when a FunctionDef node is found. This node is represented by the node parameter. See AbstractVisitor.java for a full list of those functions.

Adding the new Visitor to T3D.java

The following code shows where to implement the new Visitor in T3D.java, so it will function properly.

T3D.java:

/* ... */
public void run(String[] args) {
	/* ... */
	for (int i = 0; i < ttcn3Resources.size(); i++) {
		analyzer = analyzerFactory.getTTCN3Analyzer(ttcn3Resources.get(i));
		T3DVisitor visitor = new T3DVisitor(xmlPrinter);
		DependencyVisitor dependencyVisitor = new DependencyVisitor(depPrinter);
		ImportVisitor importVisitor = new ImportVisitor(importPrinter);

		NewVisitor newVisitor = new NewVisitor();
		// ...
		newVisitor.acceptDFS((LocationAST) analyzer.getParser().getAST());
		// ...
	}
	/* ... */
}
/* ... */

Structure of the generated XML files

project.xml

This file contains the most comprehensive information and represents an abstracted version of the source TTCN-3 files, including module structure, the individual elements, their bodies (if configured so), and T3Doc comments for every module, group, and element of the processed TTCN-3 files. It serves as a basis for the main and the module parameter / test case views.

DTD:

<!ELEMENT project (module, element, group)*>
<!ELEMENT module (name, comment?, behaviour, modulename, import*)>
<!ELEMENT group (name, location, comment?, behaviour, modulename, path)>
<!ELEMENT element (name, location, comment?, behaviour, modulename, mpview_ModuleParDef?, path)>
 <!ATTLIST element type CDATA #REQUIRED> 
 
<!ELEMENT path (path_group)>
<!ELEMENT path_group (path_group)>
 <!ATTLIST path_group loc CDATA #REQUIRED name CDATA #REQUIRED>
<!--
Contains information on which groups an element or group belongs to
<path>
 <path_group loc="..." name="subsubgroup"> 
  <path_group loc="..." name="subgroup"> 
   <path_group loc="..." name="group">
   </path_group>
  </path_group>
 </path_group>
<path>
-->

<!ELEMENT mpview_ModuleParDef((mpview_TestcaseDef | mpview_FunctionDef | mpview_AltstepDef)*)
<!ELEMENT mpview_FunctionDef((mpview_TestcaseDef | mpview_FunctionDef | mpview_AltstepDef)*)
<!ELEMENT mpview_TestcaseDef((mpview_TestcaseDef | mpview_FunctionDef | mpview_AltstepDef)*)
<!ELEMENT mpview_AltstepDef((mpview_TestcaseDef | mpview_FunctionDef | mpview_AltstepDef)*)
 <!ATTLIST mpview_ModuleParDef loc CDATA #REQUIRED name CDATA #REQUIRED>
 <!ATTLIST mpview_FunctionDef loc CDATA #REQUIRED name CDATA #REQUIRED>
 <!ATTLIST mpview_TestcaseDef loc CDATA #REQUIRED name CDATA #REQUIRED>
 <!ATTLIST mpview_AltstepDef loc CDATA #REQUIRED name CDATA #REQUIRED>
<!-- contains information on how module parameters are connected to testcases -->
 
<!ELEMENT behaviour (#PCDATA | keyword | constructbody | link)*>
<!ELEMENT constructbody (#PCDATA | keyword | link)*>
 <!ATTLIST constructbody id CDATA #REQUIRED>
<!ELEMENT keyword (#PCDATA)>
<!-- <keyword> elements are used around keywords of TTCN3 like "function" -->
<!-- <link> elements are used to identifiy crossreferences -->
<!-- the <constructbody> tag surrounds the parts of the behaviour which can be toggled in the HTML documentation -->

<!ELEMENT link (#PCDATA)>
 <!ATTLIST link loc CDATA #REQUIRED>

<!ELEMENT newline EMPTY>
<!ELEMENT tab EMPTY>

<!ELEMENT name (#PCDATA)>
<!ELEMENT location (#PCDATA)>

<!ELEMENT comment (author | config | desc | exception | member | param | purpose | remark
                 | return | see | since | status | url | verdict | version)*>
 <!-- @version 2.0.1 ist stored as <version>2.0.1</version> -->

<!ELEMENT author (#PCDATA | esee | eurl)*>
<!ELEMENT config (#PCDATA | esee | eurl)*>
<!ELEMENT desc (#PCDATA | esee | eurl)*>
<!ELEMENT exception (#PCDATA | esee | eurl)*>
<!ELEMENT purpose (#PCDATA | esee | eurl)*>
<!ELEMENT param (#PCDATA | esee | eurl)*>
<!ELEMENT remark (#PCDATA | esee | eurl)*>
<!ELEMENT return (#PCDATA | esee | eurl)*>
<!ELEMENT see (#PCDATA)>
<!ELEMENT since (#PCDATA | esee | eurl)*>
<!ELEMENT status (#PCDATA | esee | eurl)*>
<!ELEMENT url (#PCDATA | esee | eurl)*>
<!ELEMENT verdict (#PCDATA | esee | eurl)*>
<!ELEMENT version (#PCDATA | esee | eurl)*>
<!ELEMENT member (#PCDATA | esee | eurl)*>

<!ELEMENT esee (#PCDATA)>
<!ELEMENT eurl (#PCDATA)>

Examples

TTCN-3

XML

Behaviour

testcase tc2() runs on sampleComponent1 system sampleComponent3{
	map(mtc:p1, system:p1)
	var sampleComponent2 component2, component3;
	component2 := sampleComponent2.create;
	component3 := sampleComponent2.create;
	component2.start(f3());
	component3.start(f4(1, "a"));
	unmap(mtc:p1, system:p1)
}

<behaviour><keyword>testcase</keyword> <link loc="testcases-tc2-328.html">tc2</link> ()
     <keyword>runs</keyword> <keyword>on</keyword> <link loc="configuration-sampleComponent1-235.html">sampleComponent1</link>
     <keyword>system</keyword> <link loc="configuration-sampleComponent3-365.html">sampleComponent3</link> <constructbody id="id319">{
       <keyword>map</keyword> ( mtc:p1, system:p1 )
       <keyword>var</keyword> <link loc="configuration-sampleComponent2-455.html">sampleComponent2</link> component2, component3;
       component2 := sampleComponent2.create;
       component3 := sampleComponent2.create;
       component2.start ( <link loc="functions-f3-1119.html">f3</link> () );
       component3.start ( <link loc="functions-f4-1347.html">f4</link> ( 1, "a" ) );
       <keyword>unmap</keyword> ( mtc:p1, system:p1 )
}</constructbody>
</behaviour>

Path

group group1{
	group group1_1{
		group group1_1_1{
			//...
		}
	}
}

<path>
 <path_group loc="groupTest-group1_1_1-341.html" name="group1_1_1">
  <path_group loc="groupTest-group1_1-321.html" name="group1_1">
   <path_group loc="groupTest-group1-304.html" name="group1">
   </path_group>
  </path_group>
 </path_group>
</path>

import.xml

This file contains information about the imports and dependency relations of the processed TTCN-3 modules. It serves as a basis for the import / module dependency view.

DTD:

<!ELEMENT imports module*>
<!ELEMENT module import*>
<!ELEMENT import (import_behaviour, import*) | EMPTY>
 <!ATTLIST import name CDATA #REQUIRED>
<!ELEMENT import_behaviour (#PCDATA | link)*>
<!ELEMENT link (#PCDATA)>
 <!ATTLIST link loc CDATA #REQUIRED>

dependencies.xml

This file can be thought of as a blend between an abstracted version of the main project.xml file and a low-level version of the import.xml file, featuring a compact representation of the low-level dependencies at the module definition (element) level - it contains all the module definitions and all the known elements referenced directly within each module definition. There is no separate view associated to this file, since it is basically a compact representation of the main view and its main intent is the use with third-party tools to perform custom tasks, such as slicing or markup of definitions related to a particular module definition (e.g. approved / locked definitions, etc.).

DTD:

<!ELEMENT dependencies element*>
<!ELEMENT element reflist>
 <!ATTLIST element id ID #REQUIRED,
                   type CDATA #REQUIRED
                   line CDATA #REQUIRED
                   module CDATA #REQUIRED>
<!ELEMENT reflist ref*>
<!ELEMENT ref EMPTY>
 <!ATTLIST ref id IDREF #REQUIRED>

log.xml

This file contains all informations, warnings and errors for each TTCN-3 module that are logged by T3D.

DTD:

<!ELEMENT t3dlog file*>
 <!ATTLIST t3dlog t3dversion CDATA #REQUIRED>
 
<!ELEMENT file (warning | error )*>
 <!ATTLIST file path CDATA #REQUIRED>
 
<!ELEMENT warning #PCDATA>
 <!ATTLIST warning level CDATA #REQUIRED
                   lines CDATA #REQUIRED>
                   
<!ELEMENT error #PCDATA>
 <!ATTLIST error level CDATA #REQUIRED
                   lines CDATA #REQUIRED>

Generation of HTML files

The HTML documentation is generated with the project.xml and the imports.xml:

The Main View and Module Parameter/Testcase? View of the documentation are generated with the html.xsl stylesheet using the project.xml and the Import View is generated with the html_import.xsl stylesheet using the imports.xml .

Structure of the XSL-stylesheets

Below, the structure and templates of the XSL-Stylesheets are described to simplify making modifications. See {$T3D_HOME}/css/doc.css for descriptions of the HTML elements.

html.xsl

Structure of the html.xsl:

<xsl:stylesheet>
 <xsl:template match="/">
  <xsl:result-document href="..." format="html">
   <!-- generates index.html -->
  </xsl:result-document>

  <xsl:result-document href="..." format="html">
   <!-- generates import_index.html -->
  </xsl:result-document>

  <xsl:result-document href="..." format="html">
   <!-- generates mp_index.html -->
  </xsl:result-document>

  <xsl:for-each select="//module">
   <xsl:variable name="currentmodule" select="name/text()"/>
   <xsl:variable name="currentindex">
    <!--...-->
   </xsl:variable>
   <xsl:variable name="currentmp_index">
    <!--...-->
   </xsl:variable>

   <xsl:result-document href="..." format="html">
    <!-- generates Main View Documentation of modules -->
   </xsl:result-document>

   <xsl:result-document href="..." format="html">
    <!-- generates MP/TC View Documentation of modules -->
   </xsl:result-document>

   <xsl:for-each select="//element[modulename/text() eq $currentmodule]">
    <xsl:result-document href="..." format="html">
     <!-- generates Main View Documentation of elements -->
    </xsl:result-document>

    <xsl:if test="@type eq 'testcase'">
     <xsl:result-document href="..." format="html">
      <!-- generates MP/TC View Documentation of testcases -->
     </xsl:result-document>
    </xsl:if>

    <xsl:if test="@type eq 'parameter'">
     <xsl:result-document href="..." format="html">
      <!-- generates MP/TC View Documentation of module parameters -->
     </xsl:result-document>
    </xsl:if>
   </xsl:for-each>
  </xsl:for-each>  

  <xsl:for-each select="//group">
   <xsl:result-document href="..." format="html">
    <!-- generates Main View Documentation of groups -->
   </xsl:result-document>

   <xsl:result-document href="..." format="html">
    <!-- generates MP/TC View Documentation of groups -->
   </xsl:result-document>
  </xsl:for-each>
 </xsl:template>

 <!--
    Templates
   -->

</xsl:stylesheet

The following table contains descriptions of parameters and function of the used XSLT templates in html.xsl .

Template	Parameters	Function
main_allElements	$this = module\|group\|element $currentindex = complete construct index	calls views template inserts $currentindex calls header template calls element_withcomment template
mp_allTables	$testcases = testcases $parameters = parameters	generates div_mp element for groups, modules and the MP/TC index
html_head	$title = title of page	generates head element
views	$main = location of Main View documentation of the current element $mp = location of MP/TC View documentation of the current element $import = location of Import View documentation of the current element $togglemode	generates div_views element and T3D Generation Stamp
main_index	$modulename = name of the current module	generates div_modules element generates div_index element of the Main View of modules, elements and the index
main_groupindex	$grouplocation = location of the current group	generates div_modules element generates div_index of the Main View of groups
index_grouplist	$this = groups $prefix = '' or 'mp_'	generates list of hyperlinks to all groups given in parameter $this
index_elementlist	$this = elements $prefix = '' or 'mp_' $type = type of elements	generates list of hyperlinks to all elements given in parameter $this
mp_index	$modulename = name of the current module	generates div_modules element generates div_index of the MP/TC View
index_modulelist	$prefix = '', 'mp_' or 'import_'	generates list of hyperlinks to all modules
header	$this = module\|group\|element $prefix = '', 'mp_' or 'import_'	generates p_header element
element_withcomment	$this = module\|group\|element	generates div_content element generates div_comment element generates div_element element
path	$this = module\|group\|element $prefix = '', 'mp_' or 'import_'	calls path_group template
path_group	$this = module\|group\|element $prefix = '', 'mp_' or 'import_'	generates the group part of the path navigation
mp_testcase_table	$this = testcases	generates the MP/TC View table of testcase elements
mpview_path_testcase	$this = mpview_TestcaseDefs $first = true\|false	generates Path part of the MP/TC View table of testcase elements
match mpview_ModuleParDef		generates the MP/TC View table of module parameter elements
mpview_path_modulepar	$this = module\|group\|element $first = true\|false	generates Path part of the MP/TC View table of module parameter elements

html_import.xsl

The following table contains descriptions of parameters and function of the used XSLT templates in html_import.xsl .

Template	Parameters	Function
import	$module = name of the current module $importname = name of imported module	generates a list of imports by $module from $importname
importby	$imports = list of indirect imports	generates a list of $imports
show_imports	$module = module $currentmodule = currently selected module	selects a color for $currentmodule and calls the colored_module template
colored_module	$module = module $color = class of $module	generates a colored hyperlink to $currentmodule (used for list of modules in the middle column)

html_head $title = title of page generates head element legend generates Import View Legend

Using new XSL-Stylesheets and/or XML files

New XSL-Transformations can be executed by using the following code.
XSL-Transformation:

String foldername = getProperOutputPath() + "/" + getSubPath();
String xmlFileName = "name.xml";
String xsltFileName = "name.xsl";
String outputFileName = "outputName";
    	
System.setProperty("javax.xml.transform.TransformerFactory", "net.sf.saxon.TransformerFactoryImpl");
TransformerFactory tfactory = TransformerFactory.newInstance();
Transformer transformer;
try {
	transformer = tfactory.newTransformer(new StreamSource(new File(xsltFileName)));
	//transformer.setParameter("parameterName", <parameterValue>);

	transformer.transform(new StreamSource(new File(foldername + "/" + xmlFileName)),
	    	    	new StreamResult(new FileOutputStream(foldername + "/" + outputFileName)));
} catch (TransformerConfigurationException e) {
	e.printStackTrace();
} catch (TransformerException e) {
	e.printStackTrace();
} catch (FileNotFoundException e) {
	e.printStackTrace();
}

Javascript

To toggle the visibility of certain elements in the HTMl documentation (e.g. navigation items), a Javascript file called doc.js is used. It can be found in {$T3D_HOME}/js.

Functions

The Javascript file consists of the following functions:

getElementsByClass(searchClass,node,tag) : returns all HTML elements of a certain class
toggleConstructbodies(hide) : toggles visibility of all construct bodies in the Main View of elements/groups/modules if hide == true
toggleImportDetails() : toggles visibility of all details in the Import View of a module
togglePaths(hide) : toggles visibility of all Path columns in the MP/TC View of module parameters/test cases/groups/modules if hide == true
toggleHideNotes() : toggles visibility of all (toggle) notes in the Main View of elements/groups/modules
toggleElement(element) : toggles the visibility of element
toggle(elementName) : calls toggleElement() with the element with the Id elementName
mp_init(listName) : collapses all construct lists in the construct index of the MP/TC View, except listName
init(listName) : calls toggleHideNotes() and collapses all construct lists in the construct index of the Main View, except listName

Context Navigation

T3D Technical Documentation

Functioning

Creating the XML Files

Visitors

Creating new Visitors

Adding the new Visitor to T3D.java

Structure of the generated XML files

project.xml

Examples

import.xml

dependencies.xml

log.xml

Generation of HTML files

Structure of the XSL-stylesheets

html.xsl

html_import.xsl

Using new XSL-Stylesheets and/or XML files

Javascript

Functions

Attachments (3)

Download in other formats: