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 WinMergeTM or Beyond CompareTM to help you sychronize these files.

The main files are:

FilenameDescription
AutoDocTagDictionary.txtContains all the tag definitions.
AutoDocFileExtensionDefaults.txtContains the settings for the file extensions / programming languages.
AutoDocGroupings.txtContains the grouping definitions for the navigation tree on the left side of the TreeView.
AutoDocUserGroupDefs.txtContains user defined group definitions to be used in "@ingroup" tags..

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:

FilenameDescription
lang/TagTexts.txtContains the texts for all AutoDoc tags.
lang/AutoDocMessages.txtContains the messages of the AutoDoc program.

 

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:

ColumnDescription
1ID: Contains the unique key of an AutoDoc tag (e.g. "L4_AUTHOR").
2Tag name: Contains the tag name (e.g. "author").
3Level: Contains the tag level (1 = file, 2 = structural, 3 = functional, 4 = sub, 5 = inline).
4Number of parameters the tag is expecting.
5Sort Index, only relevant for functional tags.
6Special type flags (see below).

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

Type FlagUsable forDescription
overwriteAny TagOverwrites a previously defined AutoDoc Tag Dictionary entry.
excludeFile TagsExclude file from output.
classStructural TagsMarks a Class.
classtypeStructural TagsMarks a type similar to a Class (works as modifier for class, interface).
includeStructural TagsMarks an include.
interfaceStructural TagsMarks an interface.
sectionStructural TagsMarks a program section.
varFunctional TagsMarks a variable.
funcFunctional TagsMarks a function.
libnameFunctional TagsMarks a libname.
keeppreFunctional TagsMarks a pre-formatted element (works as modifier).
remoteFunctional TagsMarks a remote libname (works as modifier to the libname flag).
beginsrcquoteSub-TagsMarks the @beginsrcquote tag.
briefSub-TagsMarks a brief description tag.
callSub-TagsMarks a function / macro call.
commentSub-TagsMarks comment, output to the generated documentation is suppressed.
detailsSub-TagsMarks a detailed description tag.
directorySub-TagsMarks the @directory tag.
endsrcquoteSub-TagsMarks the @endsrcquote tag.
entitySub-TagsMarks a organizational entity tag (see Groupings Definitions file).
groupSub-TagsMarks a group tag (see Groupings Definitions file).
packageSub-TagsMarks a package / namespace / module like tag (see Groupings Definitions file).
personSub-TagsMarks a person (see Groupings Definitions file).
propertiesSub-TagsMarks a file properties tag (see Groupings Definitions file).
usectionSub-TagsMarks a user section (@section) tag.
boldInline TagsMarks a bold tag (works as modifier).
codeInline TagsMarks a code tag (works as modifier).
doublequoteInline TagsMarks a double quote tag (works as modifier).
emphasizedInline TagsMarks an emphasized tag (works as modifier).
extlinkInline TagsMarks a @extlink tag (works as modifier).
imageInline TagsMarks an @image tag (works as modifier).
italicInline TagsMarks a italic tag (works as modifier).
linkInline TagsMarks a @link tag (works as modifier).
newlineInline TagsMarks the a @newline tag (works as modifier).
singlequoteInline TagsMarks a single quote tag (works as modifier).
strikeInline TagsMarks a strike through tag (works as modifier).
typewriterInline TagsMarks a typewriter tag (works as modifier).
underlineInline TagsMarks an underline tag (works as modifier).

 

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:

ColumnDescription
1ID: Contains the unique key of an AutoDoc tag as in the Tag Dictionary.
2Text / Label for output.

 

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:

ColumnDescription
1Message ID.
2Text for output.

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:

ColumnDescription
1Name of the grouping (currently ignored).
2Key of the grouping in the AutoDoc Tag Dictionary file.
3Character used to split sub-groups.
4Processing type ("Group", "Simple", or "Complex").
5Force to a certain tag level (0 = all levels, 1 = file tags only).
6Clean trailing word delimiters (0 = no, 1 = yes).
7Message ID of the header text (refering to AutoDoc Message Texts file).

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:

ValueDescription
GroupReserved for the @group tag and it's aliasses.
SimpleA simple grouping, like "Package / Namespace / Module", or "Programming Language".
ComplexA more complex grouping, like "Persons", "File Properties", or "Organizational Entities".

 

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:

ColumnDescription
1Unique group ID.
2Replacement group definition.

 

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:

ColumnDescription
1List of file extensions, separated by commas, * as default.
2Block begin marker.
3Block end marker.
4Quote character.
5Description.

 

This is how they are currently defined:

ExtensionsBlock BeginBlock EndQuote CharDescription
* /*! */ "Default
asp '*! *!' "Active Server Pages
au3 ;*! !*; "AutoIt
bat rem ! *! "DOS / Win Batch File
c, cpp, cxx, h, hpp, hxx, cc /*! */ "C/C++
cs /*! */ "C#
cobol, cob, cbl, ovd 07 ! !! "Cobol
c02 *>! !<* "Cobol 2002
css /*! */ "Cascading Stylesheets CSS
d /*! */ "D
f, for, f90, f95, f2k C !* *! "Fortran
htm, html, xhtml, xhtm <!--! --> "HTML
java /*! */ "Java
js /*! */ "Javascript
jsp /*! */ "Java Server Pages
lisp ;*! !*; "Lisp
nsi #*! *# "NSIS Installer Script
pas (*! !*) "Pascal
php /*! */ "PHP
py #* *# "Python
r #*! *# "R
sas /*! */ "SAS
sh, csh, ksh, bsh #*! *# "Unix Shell Script
sm "*! *!" 'Smalltalk
tex %*! *%" 'TeX / LaTeX
vba, bas, vb, vbs '*! *!' "Visual Basic
xml <!--! --> "XML

 

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.
*/