| | 1 | === Command-Line Usage === |
| | 2 | |
| | 3 | T3D is used as follows: |
| | 4 | {{{ |
| | 5 | t3d [options] ((--html | --xml-only) | --local-dependencies)+ |
| | 6 | (filename | path)+ |
| | 7 | }}} |
| | 8 | |
| | 9 | This seemingly complicated syntax indicates several peculiarities of the command line usage of the tool: |
| | 10 | |
| | 11 | 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. |
| | 12 | |
| | 13 | - 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. |
| | 14 | - If an individual file is provided as input, then only that file will be processed and documented. |
| | 15 | - 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. |
| | 16 | - If a list of individual files and/or paths are provided as input, these will be combined and processed together. |
| | 17 | - If wildcards are used, these will be expanded by the command-line environment into a list and subsequently analyzed as such. |
| | 18 | |
| | 19 | The other mandatory parameter is the output format, which may (currently) be one of three possible options: |
| | 20 | |
| | 21 | * {{{--html}}} is probably the most likely option. It will cause the generation of the complete HTML documentation, including intermediate XML files. |
| | 22 | * {{{--xml-only}}} will result in the generation of the intermediate XML files only, without the HTML files. |
| | 23 | * {{{--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. |
| | 24 | |
| | 25 | 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). |
| | 26 | |
| | 27 | A summary of the available options is provided below: |
| | 28 | {{{ |
| | 29 | --generate-config <FILE NAME> Generate a new default configuration |
| | 30 | file at the specified location |
| | 31 | --config <FILE NAME> Configuration file location |
| | 32 | |
| | 33 | --profile <PROFILE NAME> Configuration profile |
| | 34 | |
| | 35 | --html Generate HTML documentation, including |
| | 36 | intermediate XML files |
| | 37 | --xml-only Generate intermediate XML files only |
| | 38 | --local-dependencies Generate local dependencies XML file |
| | 39 | |
| | 40 | --verbosity <LOG LEVEL> Verbosity level (currently supports ERROR, |
| | 41 | WARNING and INFORMATION values) |
| | 42 | --output-path <PATH> Destination path for the output (if |
| | 43 | applicable, otherwise ignored). |
| | 44 | Overrides the profile setting. |
| | 45 | --help Show this usage information screen |
| | 46 | }}} |
| | 47 | |
| | 48 | The options not discussed so far are: |
| | 49 | |
| | 50 | * {{{--help}}} will provide brief usage information. T3D will stop and document no files when the help screen is called. |
| | 51 | * 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. |
| | 52 | * 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. [[BR]] |
| | 53 | {{{ |
| | 54 | t3d --config ~/.t3d/t3d.xml |
| | 55 | }}} |
| | 56 | on a UNIX based system or [[BR]] |
| | 57 | {{{ |
| | 58 | t3d --config %APPDATA%\T3D}\t3d.xml |
| | 59 | }}} |
| | 60 | 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. |
| | 61 | |
| | 62 | * 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. |
| | 63 | |
| | 64 | * 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. |
| | 65 | |
| | 66 | * 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. |
| | 67 | |
| | 68 | 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. |
