Command-Line Usage

T3D is used as follows:

t3d [options] ((--html | --xml-only) | --local-dependencies)+ 
    (filename | path)+

This seemingly complicated syntax indicates several peculiarities of the command line usage of the tool:

Apart from any required options (see below), there always have to be at very least two other parameters that needs to be specified. One of these is the input parameter, which can be either a path that contains the TTCN-3 files that should be analyzed, the name of an individual file, or any combination of these (a mixed list), including wildcards.

• If a path provided as input (and recursive processing is enabled in the configuration, which is the default setting), T3D will recursively parse and analyze all files in this directory that match the provided file extensions (which are specified in the configuration file) and generate documentation for all of them. For the current path a simple '.' is sufficient. If no files match these extensions, T3D will output a corresponding message and quit.
• If an individual file is provided as input, then only that file will be processed and documented.
• If the path or filename contains spaces, you need to put the path into quotation marks or use the auto-completion feature of the environment (provided there is one), which should take care of escaping spaces or enclosing the complete path in quotation marks.
• If a list of individual files and/or paths are provided as input, these will be combined and processed together.
• If wildcards are used, these will be expanded by the command-line environment into a list and subsequently analyzed as such.

The other mandatory parameter is the output format, which may (currently) be one of three possible options:

• --html is probably the most likely option. It will cause the generation of the complete HTML documentation, including intermediate XML files.
• --xml-only will result in the generation of the intermediate XML files only, without the HTML files.
• --local-dependencies will result in the generation of an intermediate XML file containing the local dependencies as described below. The other intermediate XML files and the HTML documentation will not be generated if only this output option is selected.

The local dependencies intermediate XML file may be generated in addition to either the other intermediate XML files or the complete HTML documentation, including the intermediate XML files by using two output format parameters together (e.g. --local-dependencies --html, the order is irrelevant; --html supersedes --xml-only, meaning it makes no sense to use both).

A summary of the available options is provided below:

    --generate-config <FILE NAME>   Generate a new default configuration
                                    file at the specified location
    --config <FILE NAME>            Configuration file location

    --profile <PROFILE NAME>        Configuration profile
                               
    --html                          Generate HTML documentation, including
                                    intermediate XML files
    --xml-only                      Generate intermediate XML files only
    --local-dependencies            Generate local dependencies XML file
                               
    --verbosity <LOG LEVEL>         Verbosity level (currently supports ERROR,
                                    WARNING and INFORMATION values)
    --output-path <PATH>            Destination path for the output (if
                                    applicable, otherwise ignored).
                                    Overrides the profile setting.
    --help                          Show this usage information screen

The options not discussed so far are:

• --help will provide brief usage information. T3D will stop and document no files when the help screen is called.
• The --generate-config option (new as of v1.0.1) allows the generation of new default configuration files at the location specified. T3D will then quit.
• The --config option (new as of v1.0.0) is mandatory and has to be specified every time T3D is run (except when --help or --generate-config are used). It specifies the location of the configuration file. Starting with v1.0.1, if no configuration file is found at the specified location, the user will be prompted to use the appropriate option (--generate-config) to produce a new default configuration. To use the default location from previous versions one will have to specify it manually, e.g.
  

  t3d --config ~/.t3d/t3d.xml 
  

  on a UNIX based system or
  

  t3d --config %APPDATA%\T3D}\t3d.xml 
  

  on a Windows based system. The --generate-config and the --config options are mutually exclusive, with --generate-config having precedence, meaning that if both are specified, T3Q will still only generate the new default configuration and quit. Please not that if the location of the configuration file contains spaces, it has to be either enclosed in quotation marks or the auto-completion feature of the environment has to be used to take care of escaping the spaces.

• The --profile option overrides the defaultConfigurationProfile in the XML configuration. This means that you can specify multiple profiles in the XML configuration and run T3D using another existing profile without the need to change the XML configuration. If the profile specified on the command-line does not exist, T3D will automatically fall back to the default profile provided in the main section of XML configuration. In turn, if this default profile does not exist as well, T3D will fall back to the implicit all profile. If the configuration profile name contains any empty spaces, they need to be escaped or the profile name needs to be enclosed in quotation marks, depending on the environment.

• The --verbosity option (newly introduced in v1.0.0) regulates the verbosity level of the output messages based on their type. The possible values are ERROR, WARNING and INFORMATION (in an ascending inclusive order, meaning that when INFORMATION is selected, the output will include both ERROR and WARNING verbosity level messages as well). INFORMATION is the default setting. More information about the message types is available in the next section.

• The --output-path option (newly introduced in v1.0.1) makes it possible to supply the output path at the command line interface (overriding the profile setting). It is added purely for convenience in case the same profile has to be used on different projects with different destination paths.

The native binary executable for Windows supplied with v1.0.1 is discarded again as of v1.0.2, due to the fact that it does not grant the desired advantages. Thus, the basic usage is reverted to the batch scripts. Starting with v1.0.2, the batch scripts include a "hidden" --echo option, which simply outputs the deployment specific call to the Java virtual machine, without any command line arguments, meaning that it makes no sense to provide any further command line parameters besides the --echo option. The sole purpose of this option is to output the full command line necessary for starting the tool, which may be necessary for embedding into third party tools. This is why this option is considered hidden (it also does not show in the standard help screen). It should not affect the general usage of the tool. If, for whatever reason, other command line arguments are supplied together with the --echo option, then the --echo option needs to be the first command line argument.