Generating Documentation

This transaction is used to generate HTML documentation from TradeDesign sources. A distinction is made between user documentation and developer documentation. It is possible to generate documents using the UTF-8 or the ISO-8859-1 character set.

This transaction works similarly to the transaction GENWIK, which generates documentation in DokuWiki format.

Starting with release 5.06, the developer documentation will be generated in Wiki format, starting with release 5.06 SP2 also the user documentation. Older Releases had been provided in .html format.

The following types of documentation can be generated using GENDOC:

Documents for

• Codetables
• Database tables
• Transactions
• Mappings of incoming messages
• Party models

As well as using the sources of the transactions and database tables, this transaction also uses content from various database tables.
The section Sources of texts in generated documentation below describes which parts of the documentation are generated from which source.

It is therefore important that the database used as a source contains the up-to-date version of the information required:

• the ATP and ETP entries for the transactions to be generated
• the codetables
• the mappings for the incoming messages
• the help texts for the database fields and the roles
• if applicable, the documentation help texts for the transactions to be generated

In addition, the source files for the database tables and transactions are used in accordance with the given environment.

Generating the documentation further requires the programs “mod2txt.exe” and “Tidy”.

Tidy is a tool provided as part of W3C framework that checks HTML documents for conformity, for example, and automatically carries out various normalization processes. The version of Tidy.exe we used at the release date is included in our product. (HTML Tidy for Windows, released on 1 September 2005, is a utility to clean up and pretty print HTML/XHTML/XML – see http://tidy.sourceforge.net/).

Tdtidy.dll should be located in the BIN directory of the application. We do not accept any liability for the correct functioning of Tidy.

Manually written texts can be added to generated documents. To ensure that these texts are retained when a document is re-generated,
generated passages are to be contained within special html tags. Anything bracketed by a <a id=“TD_Start_ ….> entry and a <a id=“TD_End_…> entry was generated by GENDOC. Manually added texts are only retained if they are written between a <a id=“TD_End_…> and a <a id=“TD_Start_…> entry.

If changes to a document result when it is re-generated, GENDOC tries to check out this document. The Log records the processing options set and and the processes carried out. Warnings and error messages are highlighted so that the Log can be used as a check list for further processing. GENDOC also indicates if there are links pointing to documents that do not exist.

The documentation generated in this way is written to directory “X:/Workenvironment/DOKUHTM/yy/xxx/GENDOC”, with:

yy = User language (e.g. 'DE' for German and 'EN' for English)
xxx = Type of documentation ('APP' for user documentation and 'DEV' for developer documentation)

All files that are not in a GENDOC directory are documentation files that have been created manually.

If a table, transaction or codetable is removed, the corresponding html documents have to be deleted manually. Any existing index entries must also be deleted manually.

The current environment and system variables are displayed in the upper part of the 'Generation' panel.

The output language can be selected from the 'Language' field. The character set to be used is determined in the 'Character Set' field.

The documentation type is defined under 'Type of Documentation'. The available options are:

• 'Application' for user documentation (in path “X:/Workenvironment/DOKUHTM/userlanguage/APP/GENDOC”)
• 'Developer' for developer documentation (in path “X:/Workenvironment/DOKUHTM/userlanguage/DEV/GENDOC”)

The output path for documentation generation is displayed in the field 'Path of Documents'. By default, this is located in the work environment currently used.

The level of detail written to the Log during the generation of the documentation is defined in 'Log Details'. The default value is 'Errors', i.e., only errors are written to the log file. The 'Info' option is used for normalization (in the 'Document Handling' panel).

In the lower part of the panel, several checkboxes and comboboxes are available to determine which parts of the documentation are to be generated.

The documentation is generated by clicking the [Generate] button. Click the [View Log] button to view the log for this transaction.

Once a document has been generated, it is normalized using the 'Tidy' program.

A document is generated for each codetable stored in the database. The filename consists of the name of the codetable and a 2-digit language code. In addition, an index file 'indexct.htm' is created covering all codetables.

A document is generated for each database table. The filename is the same as the name of the table.

In addition, an index file 'indexdbf.htm' is created covering all database tables.

If this checkbox is checked, additional entries will be required.

It allows the user to define for which transactions the documentation is to be generated:

• All Transactions - all transactions stored in the frame directory of the current environment, or in its sub-environments
• File List - all transactions listed in the panel accessed by clicking the [Handle List] button
• Single Transaction - the transaction indicated in the field that appears alongside
• All TRNs in Workenv. - the transactions for which frame files exist in the work environment

On top of this, a selection can be made of what exactly is to be generated for the selected transactions:

• Display Files - a display file contains copies of the panels of the transaction, as they are described according to the definitions in the source. The files are created in the display/<Language> directory of the current environment, with the filename consisting of the transaction abbreviation and the file extension .dsp.
• GIF Files - the GIF files are screenshots of the transaction panels, as generated from the proprietary display files. If manually generated display files are stored in the current/production environment (in the display\mandsp\<language> directory), these will be used, otherwise the files generated from the display\<language> directory are used. The GIF files generated in this way are stored in /images, below the /gendoc directory. The filename consists of the transaction code, a 2-digit sequential number and the extension .gif. The GIF files are later embedded as images in the documentation for the transaction.
• Documents - the documentation for the transaction
• Use English Maps / GIFs for GENxxx Transactions - This option is only enabled if a language other than 'English' is selected under 'Language'. As GENxxx transactions are only available in English, it is possible to define here whether the English screenshots should nevertheless be generated for documentation in another language.

A document is generated for each transaction selected. The filename corresponds to the transaction code.

In addition, an index file 'indextrn.htm' is created, or updated, which covers all the transactions.

Many panels, such as the 'Settlement' panel or the panel for a Liability, are used in many transactions independent of the business sector. To avoid duplication/multiplication of the required documentation, when the list of the transaction panels is populated, GENDOC checks whether a file called ''<modulename>.htm' already exists in the parent directory for the module to which the panel belongs. If this is the case, a link from the entry in the list of panels is established to this module (plus the name of the panel), and the image of the panel, including the list of fields, is not included in the transaction documentation.

when generating panels and lists of fields:

• When generating display files, the static visible/invisible status of fields and panels is used in generating the documentation. Thus, the panel shown in the documentation may appear different from the way the panel appears at the start of the transaction.
• With grids, field information is not stored, and it is therefore not possible to allocate help texts.
• Fields used on multiple occasions will not be listed in the list of fields.
• XML templates cannot be recognized and are not visible.
• The field list uses the internal field descriptions, rather than the field labels appearing on the panels.

Sometimes it is appropriate to use display files that are created manually for specific panels; this would be the case with panels where several labels overlap, panels where panel names are allocated dynamically, or panels containing important grids that are not filled in in the generated display files. This process is described under 'Manually created hardcopies in the documentation'. If there are such manually created display files, these are automatically taken into account when creating the GIF files.

For each business sector, a document is generated that identifies the defined rolls in that sector. The filename consists of the constant 'bro' and the 2-digit code for the business sector. In addition, an index file called 'indexbro.htm' is created covering all party models.

An umbrella document is generated for each business sector that lists transaction mappings for the sector. The filename consists of the constant 'swm' and the 2-digit code for the business sector. In addition, an index file called 'indexswmbus.htm' is created that lists such umbrella documents.

A document is generated for each incoming message containing at least one defined mapping. This document identifies the target transactions and the individual field mapping. The filename consists of the constant 'swm', the single-digit channel code and the 3-digit message type. In addition, an index file called 'indexswm.htm' is created that lists all defined mappings.

If checked, this option prompts the 'TDView' viewer to refresh/create the whole index for the documentation once the documentation has been generated.

-gendoc (Generate documents)
-normalize (Normalize documents)

Sources for generated documentation include sources (source code and specific comments, so-called doku-tags) and entries in the database of the environment from which the documentation generation is started.
Entries in the ATP, ETP, HLP, SWM, STH and STB tables are used.

Help texts for data base fields are stored under the key DOK.DBF.<Table>.<Field>.

Help texts for database fields are stored under the key DOK.DBF.<Table>.<Field>.

Depending on the type of transaction, different headings/sections are generated.

A distinction is made between

• selection transactions of the business sectors xxTSEL
• business transactions - marked as such in ATP
• other transactions

Table of parties:

Description of parties:

Help text for the corresponding role in this business sector.
Help texts for database fields are stored under the key DOK.TRN.\<Sector>DGRP\<Role>\PTS.

Generation
Document Handling

The 'Document Handling' panel is used to normalize a single documents or all documents in a given directory.

The normalization process converts all backslashes (“\”) to normal slashes (”/”) so that they are easily recognized on both Linux and Windows systems. Files to be normalized can be selected via the displayed directory window and the [Dir Up] and [Dir Down] buttons (directory up or down). Clicking the [Norm. File] button normalizes the selected file, and clicking the [Norm.Dir.] button normalizes all files in the displayed directory.

The [Chk.Dir] and [Check.File] buttons can be used to check whether all the links work, independent of the generation. [Chk.Dir] checks all the documents in the selected directory, [Chk.File] only checks the selected file. Links that do not work are listed in the log.

The HTML source code for a selected file can be displayed by clicking the [View] button.