=== Configuration === T3D uses an XML-based configuration format. Starting with version v1.0.0, the location of the configuration file must be supplied as a command line option during execution (the location was previously based in the default user's data location - depending on the system, a file {{{t3d.xml}}} was stored in {{{%APPDATA%\T3D}}} (Windows) or in {{{~/.t3d/}}} (Unix)). The location of the {{{%APPDATA%}}} directory depended on the username, the Windows version and possibly the localization. For example, for a user 'foobar' on a German Windows XP machine, the resulting configuration path would be {{{C:\Documents and Settings\foobar\Application Data\T3D}}}. In version v1.0.0 and onwards, the location of the configuration file has to be supplied every time T3D is called. Additionally, starting with version v1.0.1, if there is no existing configuration file in the selected location, the tool will prompt the user to use the appropriate option to generate a new configuration with the default settings. Thus, the tool has to be started with the appropriate parameter to generate a new configuration prior to actual usage. This way, it will be possible to modify the configuration file to accommodate the particular needs of the user prior to generating any output. By location here the path, filename, and extension of the configuration file are meant, which implies that any filename and any extension can be used. It is probably best to retain certain norms in naming the configuration files, at least in preserving the file extensions ({{{.xml}}}) to avoid confusion. If the fact that a new XML configuration is automatically generated if existing one is not found is too confusing, there may be a separate option available in the command line to generate new default configuration files in future releases. Please note that after an update, during the development stage, the configuration files will often be extended. Thus, it may be necessary to generate a new configuration file and transfer the custom settings from the old configuration file. The configuration file has two sections: - A configuration profiles section - A main section The '''!ConfigurationProfiles''' section contains a list of '''!DocumentationProfile''' elements. Its elements contain the tags '''profilename''' as well as elements with settings for the documentation generation, such as output path and paths to files needed for the generation among others. In the default {{{t3d.xml}}} that is created, there is a profile called ''defaultProfile'' that initializes all profile configuration values to the default values. This is also the configuration of an implicitly given profile called ''all''. The ''all'' profile is not part of the XML configuration, but it exists and is known to the tool. Since v0.4, configuration profiles also have a version ('''profileVersion''' element), that regulates the profile compatibility. If a profile from an older version is used, T3D will throw and error and recommend profile upgrade or the selection of another profile. Also, further robustness checks have been introduced to provide hints if the configuration profile is otherwise incompatible or corrupted. In case of a problem that can be localized, a corresponding error message is provided suggesting the location of the problem. Also, there are several generic options, that affect the overall behavior of the T3D tool. The known extensions for files that are to be processed can be specified by means of a regular expression in the '''resourceExtensionsRegExp''' option. By default, ''ttcn'',''ttcn3'' and ''3mp'' file extensions are recognized. Since v1.0.1, there is also support for supplying input by means of what will be referred to as ''project'' files. These files specify a list of input files and directories (including wildcards). The '''projectExtension''' option regulates what is to be considered a project file. Note that this is not a regular expression option, therefore only a single value is currently supported. Since v1.0.3, the '''ignoredResourceRegExp''' option enables the specification of regular expressions for resources within the set of input files that will be ignored during the processing steps. Note that all resources in the input set will be parsed and pre-processed so that definitions within ignored resources will be still be correctly resolved during the documentation generation phase. The ignored resources will be skipped during the documentation generation steps (annotated with '''(Skipped)''' in the output). Note also that currently this may lead to broken links in the HTML documentation output. The default setting for ignored resources is '''.*IGNORED.*''', meaning that resources which contain '''IGNORED''' in their full path will be skipped. There is an option to switch recursive processing on and off ('''settingRecursiveProcessing'''). There is an option to switch aborting on (parsing) errors on and off ('''settingAbortOnError'''). Both of these options are turned on by default. Turning them off may result in unreliable output. Files that contain syntax errors will be documented only up to the point of the first syntax error occurrence. Then there are the options regulating the documentation generation process and the logging output (further details are featured below), and the options defining the paths to dynamically linked files necessary for the documentation generation process (which do not concern the user in the usual usage scenarios). These files are described in more detail below. Starting with v1.0.1, it is possible to define custom names for the supported documentation tags in the '''commentTagsConfiguration''' section of the configuration. Finally, there are options regulating the output. Currently there is only one setting - the output directory ('''outputDirectory'''), where the output files will be placed. Other options regulating the output have been relegated to the command line interface. Note that this option can also be overridden by a corresponding command line option. In the ''main section'', there is currently one single configuration element '''defaultConfigurationProfile'''. It points to the implicit ''all'' profile by default. The '''all''' profile has all settings set to their default values. The '''defaultConfigurationProfile''' is the profile that will be used if no specific profile is provided as command-line parameter. If the specified '''defaultDocumentationProfile''' does not exist in the configuration, T3D will fall back to the implicit ''all'' profile. Some of the profile options may be moved to the ''main section'' in the future, as they are rather generic. A default newly generated configuration file currently looks like this: {{{ defaultProfile v1.0.2 ttcn|ttcn3|3mp .*IGNORED.* t3p true true false true true true true true desc author config exception member param purpose remark return see since status url verdict version true false false true false true true true $T3D_HOME/css/doc.css $T3D_HOME/js/doc.js $T3D_HOME/xslt/html.xsl $T3D_HOME/t3d/xslt/html_import.xsl DOCUMENTATION defaultProfile }}} where {{{{$T3D_HOME}}}} is substituted by the value of the {{{T3D_HOME}}} environment variable as specified in the setup when the configuration file is generated. This means that the same profile may not be directly usable on a different configuration, where the {{{T3D_HOME}}} environment variable has a different value. This will be subject to change in the future in that at least substitution with the environment variable is done at runtime in the default configuration. The options regulating the documentation generation process and logging output have the following effects: * '''includeConstructBody''' (by default ''true'') - The documentation will contain the bodies of module definitions. Leaving out the bodies contributes to a more abstract and concise documentation. However the details may often be necessary. * '''hideConstructBody''' (by default ''true'') - The module definition bodies are hidden by default when an HTML documentation page is loaded. This makes the initial presentation more compact. * '''showOriginalT3DocTags''' (by default ''true'') - The HTML documentation will use the original T3Doc tags (e.g. "@author John Doe" instead of "Author(s): John Doe"). * '''checkUndocumentedParameters''' (by default ''true'') - The T3D generation process log output will include warnings on undocumented formal parameters * '''checkFunctionDescTagsRequired''' (by default ''false'') - The T3D generation process log output will include warnings on missing @desc tags for function definitions * '''checkConsistentTagUsage''' (by default ''true'') - The T3D generation process log output will include warnings on incorrect tag usage in consistence with the TTCN-3 Documentation Specification Standard (for example: multiple version or other tags that may only be used once, etc.) * '''checkIdenticalDescriptionTags''' (by default ''true'') - The T3D generation process log output will include warnings identical description tags (defined by string equivalence currently, more sophisticated identity relation may be employed in future releases) * '''checkCyclicImports''' (by default ''true'') - T3D will check the project for cyclic imports (which may take up to several minutes on large and complex test suites) and report any occurrences in the documentation generation log output.