DE AutoDoc - Part IV   Extending AutoDoc for Experts

Contents

1. Introduction
2. Documentation of Parameter Files
   1. AutoDoc Tag Dictionary
   2. AutoDoc Tag Texts
   3. AutoDoc Message Texts
   4. Groupings Definitions
   5. Standardized User Grouping Definitions
   6. File Extensions Defaults
3. How to Accomplish Tasks
   1. Adding an Alias for an Existing Tag
   2. Overwriting an Exisiting Tag
   3. Adding a New Simple Tag
   4. Creating a new Grouping for the TreeView

Introduction

AutoDoc has a few parameter files in the "res" sub-directory, which control the behavior of the program. With these files, it is possible to extend AutoDoc by adding new tags, groupings, and texts.

However, changing these files is potentially dangerous and may lead to AutoDoc not working properly. Therefore, it is strongly recomended, that you don't change these files directly, but rather make a copy of the whole directory (e.g. to a directory named "my_res") and apply your changes to this copy. You can then use the "-res" parameter to point to this changed copy.

Please note, that these files are subject to permanent changes. So, it is your responsibilty, to synchronize the original files with your changed files after every AutoDoc update. Since those are normal text files, you can use a file comparison program, like WinMerge^TM or Beyond Compare^TM to help you sychronize these files.

The main files are:

The language specific files are stored in sub-directories "en" for English and "de" for German. These files are selected by the "-locale" parameter. You can add you own translations by creating an own sub-directory with the language code of your preferred language, copy the files to it and translating all the texts to this language. The files are:

Documentation of Parameter Files

AutoDoc Tag Dictionary

The file "res/AutoDocTagDictionary.txt" contains the definitions for all Tags, which AutoDoc understands. It is a text file, containing a row for every tag definition and the columns are separated by commas (","). The columns are:

In the sixth column, one or more type flags can be defined. This is a list of the currently used flags:

AutoDoc Tag Texts

The file "res/lang/TagTexts.txt" contains the texts for the output of the tags, where lang is the language selected by the "-locale" parameter. It is a text file, containing a row for every tag definition and the columns are separated by commas (","). The columns are:

AutoDoc Message Texts

The file "res/lang/AutoDocMessages.txt" contains the texts for the program output of AutoDoc, where lang is the language selected by the "-locale" parameter. It is a text file, containing a row for every message and the columns are separated by commas (","). The columns are:

Some of the message texts may contain parameter placeholders "%1%", "%2%", etc.

Groupings Definitions

The file "res/AutoDocGroupings.txt" contain the definition of the groupings shown on the left side of the TreeView output. It is a text file, containing a row for every grouping and the columns are separated by commas (","). The columns are:

The groupings are output in the TreeView on the left side of the output in the order they appear in this file. The key in the second column must be identical to a Type Flag in the AutoDoc Tag Dictionary file.

The 7th column contains the Message ID in the AutoDoc Message Texts file containing the Header of the TreeView segment. Alternatively you can specify the heading as text, but then the heading cannot be localized to your output language specified by the "-locale" parameter.

The 4th column contains the processing type for this grouping. There are 3 possible values:

Standardized User Grouping Definitions

In this file the user can define standardized groups to be used with the "@group" tag. They are stored in the file "res/AutoDocFileExtensionDefaults.txt" and is a text file, containing a row for every file extension definition and the columns are separated by commas (","). The file has 2 columns:

File Extensions Defaults

The current file extension defaults for the block makers are stored in the file "res/AutoDocFileExtensionDefaults.txt". It is a text file, containing a row for every file extension definition and the columns are separated by commas (","). The columns are:

This is how they are currently defined:

How to Accomplish Tasks

Adding an Alias for an Existing Tag

The simplest way to extend AutoDoc is to define an alias for an existing tag. You can accomplish this by perfoming these steps:

1. Search the original entry in the file AutoDocTagDictionary.txt in the res sub-directory for which you want to create the alias.
2. Copy the entry to the end of the file.
3. Change the tag name of the copy to the alias name.

For example, if you want to create an alias for the "@saslibname" tag and want to use the new tag "@libname", add the following line to the end of the file:

L3_LIBNAME,    "libname", 3,  3,   0, "libname"

Now, you can use "@libname" and it works exactly as "@saslibname".

Overwriting an Exisiting Tag

Sometimes you want to change the behaviour of an exsiting tag slightly, for example when you want to add it to a grouping.

Rather than changing existing tags directly in the AutoDoc Tag Dictionary file in the res sub-directory, it is recomended to copy the respecting entry for the tag to the end of the file and to use the overwrite flag. This way it is easier to synchronize the settings, when a new AutoDoc version is available, because all of your changes are at the bottom of the AutoDoc Tag Dictionary file. The steps are:

1. Search the original entry in the file AutoDocTagDictionary.txt in the res sub-directory for which you want to create the alias.
2. Copy the entry to the end of the file.
3. Change the tag settings of the copy.
4. Add the flag "overwrite" to the type flag column to indicate that the previous definition is to be overwritten.

For example, if you want entries for the "@freq" tag to appear in the "File properties" grouping in the TreeView on the left side, normally you only need to add the groupings key "properties" to the type flags column. So first copy the entry of the "@freq" tag to the bottom of the file and add the flags "properties" and "overwrite" as shown below.

L4_FREQ,       "freq",     4,  1,   0, "properties, overwrite"

Adding a New Simple Tag

Simple tags can be added easily, especially if they are Sub-Tags (Level = 4). You can accomplish this by perfoming these steps:

1. Create a new entry in the file AutoDocTagDictionary.txt in the res sub-directory with a unique key.
2. Create a new entry all of the language specific files lang/TagTexts.txt with the same key as in the previous step.

For example, when you want to add the new sub-tag "@clientaddress", you can add the following line to the end of your AutoDocTagDictionary.txt file:

L4_MYCLIENTADDRESS,    "clientaddress",   4,  1,   0, ""

The level is 4 (for Sub-Tag), the tag has 1 parameter, sort index 0 is not relevant here, and there are no special flags.

Then you add the text to the end of your TagTexts files in all locale directories, e.g. for English:

L4_MYCLIENTADDRESS,    "Client's Adress"

Creating a new Grouping for the TreeView

If you want to create a new grouping for the TreeView on the left side of the output, you have to follow these steps with the files in the res sub-directory:

1. Create a new entry in all of the language specific files lang/AutoDocMessages.txt with a unique Message ID and the header text for your new grouping.
2. Create a new entry in the file AutoDocGroupings.txt with a unique key and the same Message ID as in the previous step. Set the other parameters as you need it for the output.
3. Modify the file AutoDocTagDictionary.txt to create or modify tags you want to show up in this grouping, adding the unique key from the previous step to it's type flag field.
4. If you created new tags in the previous step, make sure you have not forgotten to create new entries to all of the language specific files lang/TagTexts.txt with the same keys as in the AutoDocTagDictionary.txt file.

For example, you want add a new Sub-Tag "@project" expecting one parameter and want to show it in a separate grouping "Project" in the TreeView. First, you have to create the Header text for the grouping in lang/AutoDocMessages.txt for each language, for example for English:

MSG_OUTMYPROJECT, "Project"

Next, you add an entry to AutoDocGroupings.txt:

"Project",       "myproject",       ";",              "Simple",      1,     1,                "MSG_OUTMYPROJECT"

The key of this grouping is "myproject" and for the delimiter we can use the same as in the Persons grouping. The processing type is "Simple", because we want to create a simple list for this grouping, like in "Programming Language". The 1 in the next parameter makes sure, only Sub-Tags of File Tags are to be considered, and the next 1 tells AutoDoc to clean word delimiters at the end. The last parameter refers to the Header message ID you created in the lang/AutoDocMessages.txt files. Next we create a the Sub-Tag in the AutoDocTagDictionary.txt file:

L4_MYPROJECT,      "project",   4,  1,   0, "myproject"

The unique key is "L4_MYPROJECT" and the tag name is "project". The level of the tag is 4 for Sub-Tag, it requries 1 parameter and the sorting order is irrelevant for Sub-Tags. The grouping key defined in the AutoDocGroupings.txt file is set as special type flag in the last column. Now, you have to add the Tag text to the lang/TagTexts.txt files for each language using the same unique key as in the AutoDocTagDictionary.txt file. For English, this could be:

L4_MYPROJECT, "Project"

Now, you can use "@project Description" as a new Sub-Tag inside a File Tag and then a new Grouping in the TreeView is generated. For example:

/*!
* @program Test Program.
*
* @author  Daniel Enache
* @version 1.0
* @date    30.01.2016
* @project Test.
*/