Tcl Library Source Code

> bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{  
>     set key \[aes::Init ecb $k $i\]  
> \} \-body \{  
>     aes::Encrypt $key $p  
> \} __\-post__ \{  
>     aes::Final $key  
> \}  
>   

## <a name='subsection4'></a>Advanced pre\- and postprocessing

Our last example again deals with initialization and cleanup code\. To see the
difference to the regular initialization and cleanup discussed in the last
section it is necessary to know a bit more about how bench actually measures the
speed of the the __\-body__\.
................................................................................
> bench \-desc "set include, missing <SC> x$times $n" __\-ipre__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;set A $sx\($times,$n\)  
> &nbsp;&nbsp;&nbsp;&nbsp;set B $A  
> \} \-body \{  
> &nbsp;&nbsp;&nbsp;&nbsp;struct::set include A x  
> \} __\-ipost__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;unset A B  
> \}  
>   

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of benchmarks, he should be fortified enough to be able to understand the formal
*bench language specfication*\. It will also serve as the detailed
specification and cheat sheet for all available commands and their syntax\.

> bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{  
>     set key \[aes::Init ecb $k $i\]  
> \} \-body \{  
>     aes::Encrypt $key $p  
> \} __\-post__ \{  
>     aes::Final $key  
> \}


## <a name='subsection4'></a>Advanced pre\- and postprocessing

Our last example again deals with initialization and cleanup code\. To see the
difference to the regular initialization and cleanup discussed in the last
section it is necessary to know a bit more about how bench actually measures the
speed of the the __\-body__\.
................................................................................
> bench \-desc "set include, missing <SC> x$times $n" __\-ipre__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;set A $sx\($times,$n\)  
> &nbsp;&nbsp;&nbsp;&nbsp;set B $A  
> \} \-body \{  
> &nbsp;&nbsp;&nbsp;&nbsp;struct::set include A x  
> \} __\-ipost__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;unset A B  
> \}


# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of benchmarks, he should be fortified enough to be able to understand the formal
*bench language specfication*\. It will also serve as the detailed
specification and cheat sheet for all available commands and their syntax\.

>    % \\iffalse  
> &nbsp;&nbsp;&nbsp;%<\*driver>  
> &nbsp;&nbsp;&nbsp;\\documentclass\{tclldoc\}  
> &nbsp;&nbsp;&nbsp;\\begin\{document\}  
> &nbsp;&nbsp;&nbsp;\\DocInput\{*filename\.dtx*\}  
> &nbsp;&nbsp;&nbsp;\\end\{document\}  
> &nbsp;&nbsp;&nbsp;%</driver>  
> &nbsp;&nbsp;&nbsp;% \\fi  
>   

or some variation thereof\. The trick is that the file gets read twice\. With
normal LaTeX reading rules, the first two lines are comments and therefore
ignored\. The third line is the document preamble, the fourth line begins the
document body, and the sixth line ends the document, so LaTeX stops there —
non\-comments below that point in the file are never subjected to the normal
LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth

>    % \\iffalse  
> &nbsp;&nbsp;&nbsp;%<\*driver>  
> &nbsp;&nbsp;&nbsp;\\documentclass\{tclldoc\}  
> &nbsp;&nbsp;&nbsp;\\begin\{document\}  
> &nbsp;&nbsp;&nbsp;\\DocInput\{*filename\.dtx*\}  
> &nbsp;&nbsp;&nbsp;\\end\{document\}  
> &nbsp;&nbsp;&nbsp;%</driver>  
> &nbsp;&nbsp;&nbsp;% \\fi


or some variation thereof\. The trick is that the file gets read twice\. With
normal LaTeX reading rules, the first two lines are comments and therefore
ignored\. The third line is the document preamble, the fourth line begins the
document body, and the sixth line ends the document, so LaTeX stops there —
non\-comments below that point in the file are never subjected to the normal
LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth

> \[index\_begin GROUPTITLE TITLE\]  
> \[__key markup__\]  
> \[__key \{semantic markup\}\]__\]  
> \[__key \{docidx markup\}__\]  
> \[__key \{docidx language\}__\]  
> \[__key \{docidx commands\}__\]  
> \[index\_end\]  
>   

In the above example the command __key__ is used to declare the keyword
phrases we wish to be part of the index\.

However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords\. Here is a
made\-up index for all the manpages in the module
................................................................................
> \[__manpage uuencode__\]  
> \[key yEnc\]  
> \[__manpage yencode__\]  
> \[key ydecode\]  
> \[__manpage yencode__\]  
> \[key yencode\]  
> \[__manpage yencode__\]  
> \[index\_end\]  
>   

In the above example the command
__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ is used to insert references
to documents, using symbolic file names, with each command belonging to the last
__key__ command coming before it\.

The other command to insert references is
................................................................................
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[index\_begin GROUPTITLE TITLE\]  
> \.\.\.  
> \[index\_end\]  
>   

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

> \[index\_begin GROUPTITLE TITLE\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \.\.\.  
> \[index\_end\]  
>   

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __index\_begin__ may contain only the templating commands __vset__
and __include__, a file included after a key may contain only manape or url
references, and other keys, etc\.

................................................................................
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

>   \.\.\.  
>   These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
>   because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
>   impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
>   \.\.\.  
>   

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\.
From here on out the *[docidx language command

> \[index\_begin GROUPTITLE TITLE\]  
> \[__key markup__\]  
> \[__key \{semantic markup\}\]__\]  
> \[__key \{docidx markup\}__\]  
> \[__key \{docidx language\}__\]  
> \[__key \{docidx commands\}__\]  
> \[index\_end\]


In the above example the command __key__ is used to declare the keyword
phrases we wish to be part of the index\.

However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords\. Here is a
made\-up index for all the manpages in the module
................................................................................
> \[__manpage uuencode__\]  
> \[key yEnc\]  
> \[__manpage yencode__\]  
> \[key ydecode\]  
> \[__manpage yencode__\]  
> \[key yencode\]  
> \[__manpage yencode__\]  
> \[index\_end\]


In the above example the command
__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ is used to insert references
to documents, using symbolic file names, with each command belonging to the last
__key__ command coming before it\.

The other command to insert references is
................................................................................
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[index\_begin GROUPTITLE TITLE\]  
> \.\.\.  
> \[index\_end\]


Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

> \[index\_begin GROUPTITLE TITLE\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \.\.\.  
> \[index\_end\]


The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __index\_begin__ may contain only the templating commands __vset__
and __include__, a file included after a key may contain only manape or url
references, and other keys, etc\.

................................................................................
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

>   \.\.\.  
>   These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
>   because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
>   impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
>   \.\.\.


# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\.
From here on out the *[docidx language command

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__item 1 DESCRIPTION__\]  
> \[__item 1\.1 \{Basic structure\}__\]  
> \[__item 1\.2 Items__\]  
> \[__item 1\.3 Divisions__\]  
> \[__item 2 \{FURTHER READING\}__\]  
> \[toc\_end\]  
>   

## <a name='subsection4'></a>Divisions

One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1\.
................................................................................
> \[__division\_start DESCRIPTION__\]  
> \[item 1 \{Basic structure\}\]  
> \[item 2 Items\]  
> \[item 3 Divisions\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]  
>   

Or, to demonstrate deeper nesting

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__division\_start DESCRIPTION__\]  
> \[__division\_start \{Basic structure\}__\]  
> \[item 1 Do\]  
................................................................................
> \[__division\_start Divisions__\]  
> \[item 1 Sub\]  
> \[item 1 Zero\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]  
>   

And do not forget, it is possible to freely mix items and divisions, and to have
empty divisions\.

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[item 1 Do\]  
> \[__division\_start DESCRIPTION__\]  
................................................................................
> \[item c Fa\]  
> \[__division\_end__\]  
> \[__division\_start Divisions__\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]  
>   

## <a name='subsection5'></a>Advanced structure

In all previous examples we fudged a bit regarding the markup actually allowed
to be used before the __toc\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
................................................................................
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[toc\_begin GROUPTITLE TITLE\]  
> \.\.\.  
> \[toc\_end\]  
>   

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

> \[toc\_begin GROUPTITLE TITLE\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \.\.\.  
> \[toc\_end\]  
>   

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __toc\_begin__ may contain only the templating commands __vset__
and __include__, a file included in a division may contain only items or
divisions commands, etc\.

................................................................................
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.  
>   

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\.
From here on out the *[doctoc language command

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__item 1 DESCRIPTION__\]  
> \[__item 1\.1 \{Basic structure\}__\]  
> \[__item 1\.2 Items__\]  
> \[__item 1\.3 Divisions__\]  
> \[__item 2 \{FURTHER READING\}__\]  
> \[toc\_end\]


## <a name='subsection4'></a>Divisions

One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1\.
................................................................................
> \[__division\_start DESCRIPTION__\]  
> \[item 1 \{Basic structure\}\]  
> \[item 2 Items\]  
> \[item 3 Divisions\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]


Or, to demonstrate deeper nesting

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__division\_start DESCRIPTION__\]  
> \[__division\_start \{Basic structure\}__\]  
> \[item 1 Do\]  
................................................................................
> \[__division\_start Divisions__\]  
> \[item 1 Sub\]  
> \[item 1 Zero\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]


And do not forget, it is possible to freely mix items and divisions, and to have
empty divisions\.

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[item 1 Do\]  
> \[__division\_start DESCRIPTION__\]  
................................................................................
> \[item c Fa\]  
> \[__division\_end__\]  
> \[__division\_start Divisions__\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]


## <a name='subsection5'></a>Advanced structure

In all previous examples we fudged a bit regarding the markup actually allowed
to be used before the __toc\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
................................................................................
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[toc\_begin GROUPTITLE TITLE\]  
> \.\.\.  
> \[toc\_end\]


Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

> \[toc\_begin GROUPTITLE TITLE\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \.\.\.  
> \[toc\_end\]


The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __toc\_begin__ may contain only the templating commands __vset__
and __include__, a file included in a division may contain only items or
divisions commands, etc\.

................................................................................
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.


# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\.
From here on out the *[doctoc language command

[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5\.4 tcllib "Documentation tools")

<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../../toc.md">Table Of Contents</a> &#124; <a
href="../../../../index.md">Keyword Index</a> &#124; <a
href="../../../../toc0.md">Categories</a> &#124; <a
href="../../../../toc1.md">Modules</a> &#124; <a
href="../../../../toc2.md">Applications</a> ] <hr>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

# <a name='synopsis'></a>SYNOPSIS

package require Tcl 8\.2  
package require doctools ?1\.5\.4?  

[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1)  
[__::doctools::help__](#2)  
[__::doctools::search__ *path*](#3)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#4)  
[*objectName* __configure__](#5)  
[*objectName* __configure__ *option*](#6)  

[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5\.5 tcllib "Documentation tools")

<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../../toc.md">Table Of Contents</a> &#124; <a
href="../../../../index.md">Keyword Index</a> &#124; <a
href="../../../../toc0.md">Categories</a> &#124; <a
href="../../../../toc1.md">Modules</a> &#124; <a
href="../../../../toc2.md">Applications</a> ] <hr>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

# <a name='synopsis'></a>SYNOPSIS

package require Tcl 8\.2  
package require doctools ?1\.5\.5?  

[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1)  
[__::doctools::help__](#2)  
[__::doctools::search__ *path*](#3)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#4)  
[*objectName* __configure__](#5)  
[*objectName* __configure__ *option*](#6)  

> \[manpage\_begin NAME SECTION VERSION\]  
> \[__copyright \{YEAR AUTHOR\}__\]  
> \[__titledesc TITLE__\]  
> \[__moddesc   MODULE\_TITLE__\]  
> \[__require   PACKAGE VERSION__\]  
> \[__require   PACKAGE__\]  
> \[description\]  
> \[manpage\_end\]  
>   

Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
................................................................................
> \[copyright \{YEAR AUTHOR\}\]  
> \[titledesc TITLE\]  
> \[moddesc   MODULE\_TITLE\]\[__comment \{ \.\.\. \}__\]  
> \[require   PACKAGE VERSION\]  
> \[require   PACKAGE\]  
> \[description\]  
> \[manpage\_end\]  
> \[__comment \{ \.\.\. \}__\]  
>   

## <a name='subsection3'></a>Advanced structure

In the simple examples of the last section we fudged a bit regarding the markup
actually allowed to be used before the __manpage\_begin__ command opening the
document\.

................................................................................
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the document\. I\.e\. it is possible to write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> \[manpage\_end\]  
>   

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\. I\.e\. for example in
the header as well\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[description\]  
> \[manpage\_end\]  
>   

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __manpage\_begin__ may contain only the templating commands
__vset__ and __include__, a file included in the header may contain only
header commands, etc\.

................................................................................
> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> &nbsp;\.\.\.  
> \[__para__\]  
> &nbsp;\.\.\.  
> \[__para__\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]  
>   

Empty paragraphs are ignored\.

A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces\. The command for doing so is
__section__\. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph\. The first section
................................................................................
> &nbsp;\.\.\.  
> \[__section \{Section A\}__\]  
> &nbsp;\.\.\.  
> \[para\]  
> &nbsp;\.\.\.  
> \[__section \{Section B\}__\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]  
>   

Between sections and paragraphs we have subsections, to split sections\. The
command for doing so is __subsection__\. Each occurrence of this command
closes the previous subsection and automatically opens the next, including its
first paragraph\. A subsection is automatically opened at the beginning of the
body, by __description__, and at the beginning of each section\. In the same
manner the last subsection automatically ends at __manpage\_end__\.
................................................................................
> &nbsp;\.\.\.  
> \[para\]  
> &nbsp;\.\.\.  
> \[__subsection \{Sub 2\}__\]  
> &nbsp;\.\.\.  
> \[section \{Section B\}\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]  
>   

## <a name='subsection5'></a>Text markup

Having handled the overall structure a writer can impose on the document we now
take a closer at the text in a paragraph\.

While most often this is just the unadorned content of the document we do have
................................................................................
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\]  
>   
> &nbsp;&nbsp;Text structure\. List element\. Argument list\. Automatically closes the  
> &nbsp;&nbsp;previous list element\. Specifies the data\-\[__arg type__\] of the described  
> &nbsp;&nbsp;argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The  
> &nbsp;&nbsp;latter is optional\.  
> &nbsp;&nbsp;\.\.\.  
>   

## <a name='subsection6'></a>Escapes

Beyond the 20 commands for simple markup shown in the previous section we have
two more available which are technically simple markup\. However their function
is not the marking up of phrases as specific types of things, but the insertion
of characters, namely __\[__ and __\]__\. These commands, __lb__ and
................................................................................
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.  
>   

## <a name='subsection7'></a>Cross\-references

The last two commands we have to discuss are for the declaration of
cross\-references between documents, explicit and implicit\. They are
__[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both
take an arbitrary number of arguments, all of which have to be plain unmarked
................................................................................
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__see\_also doctools\_intro__\]  
> &nbsp;&nbsp;\[__see\_also doctools\_lang\_syntax__\]  
> &nbsp;&nbsp;\[__see\_also doctools\_lang\_cmdref__\]  
> &nbsp;&nbsp;\[__keywords markup \{semantic markup\}__\]  
> &nbsp;&nbsp;\[__keywords \{doctools markup\} \{doctools language\}__\]  
> &nbsp;&nbsp;\[__keywords \{doctools syntax\} \{doctools commands\}__\]  
> &nbsp;&nbsp;\[manpage\_end\]  
>   

## <a name='subsection8'></a>Examples

Where ever we can write plain text we can write examples too\. For simple
examples we have the command __example__ which takes a single argument, the
text of the argument\. The example text must not contain markup\. If we wish to
have markup within an example we have to use the 2\-command combination
................................................................................
\(Remember section [Advanced structure](#subsection3)\)\.

The source for the very first example in this document \(see section
[Fundamentals](#subsection1)\), with some highlighting added, is

> \[__example__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;\.\.\. \[list\_begin enumerated\] \.\.\.  
> &nbsp;&nbsp;\}\]  
>   

Using __example\_begin__ / __example\_end__ this would look like

> \[__example\_begin__\]  
> &nbsp;&nbsp;&nbsp;&nbsp;\.\.\. \[list\_begin enumerated\] \.\.\.  
> &nbsp;&nbsp;\[__example\_end__\]  
>   

## <a name='subsection9'></a>Lists

Where ever we can write plain text we can write lists too\. The main commands are
__list\_begin__ to start a list, and __list\_end__ to close one\. The
opening command takes an argument specifying the type of list started it, and
this in turn determines which of the eight existing list item commands are
................................................................................
>   
> &nbsp;&nbsp;\(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It  
> &nbsp;&nbsp;is a specialized form of a definition list where the term is the name  
> &nbsp;&nbsp;of a configuration option for a widget, with its name and class in the  
> &nbsp;&nbsp;option database\.  
>   
> &nbsp;&nbsp;\[__list\_end__\]  
> &nbsp;&nbsp;\.\.\.  
>   

Note that a list cannot begin in one \(sub\)section and end in another\.
Differently said, \(sub\)section breaks are not allowed within lists and list
items\. An example of this *illegal* construct is

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[list\_begin itemized\]  
> &nbsp;&nbsp;\[item\]  
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__section \{ILLEGAL WITHIN THE LIST\}__\]  
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[list\_end\]  
> &nbsp;&nbsp;\.\.\.  
>   

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctools language syntax](doctools\_lang\_syntax\.md)* specification as
well\. From here on out the *[doctools language command

> \[manpage\_begin NAME SECTION VERSION\]  
> \[__copyright \{YEAR AUTHOR\}__\]  
> \[__titledesc TITLE__\]  
> \[__moddesc   MODULE\_TITLE__\]  
> \[__require   PACKAGE VERSION__\]  
> \[__require   PACKAGE__\]  
> \[description\]  
> \[manpage\_end\]


Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
................................................................................
> \[copyright \{YEAR AUTHOR\}\]  
> \[titledesc TITLE\]  
> \[moddesc   MODULE\_TITLE\]\[__comment \{ \.\.\. \}__\]  
> \[require   PACKAGE VERSION\]  
> \[require   PACKAGE\]  
> \[description\]  
> \[manpage\_end\]  
> \[__comment \{ \.\.\. \}__\]


## <a name='subsection3'></a>Advanced structure

In the simple examples of the last section we fudged a bit regarding the markup
actually allowed to be used before the __manpage\_begin__ command opening the
document\.

................................................................................
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the document\. I\.e\. it is possible to write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> \[manpage\_end\]


Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\. I\.e\. for example in
the header as well\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[description\]  
> \[manpage\_end\]


The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __manpage\_begin__ may contain only the templating commands
__vset__ and __include__, a file included in the header may contain only
header commands, etc\.

................................................................................
> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> &nbsp;\.\.\.  
> \[__para__\]  
> &nbsp;\.\.\.  
> \[__para__\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]


Empty paragraphs are ignored\.

A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces\. The command for doing so is
__section__\. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph\. The first section
................................................................................
> &nbsp;\.\.\.  
> \[__section \{Section A\}__\]  
> &nbsp;\.\.\.  
> \[para\]  
> &nbsp;\.\.\.  
> \[__section \{Section B\}__\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]


Between sections and paragraphs we have subsections, to split sections\. The
command for doing so is __subsection__\. Each occurrence of this command
closes the previous subsection and automatically opens the next, including its
first paragraph\. A subsection is automatically opened at the beginning of the
body, by __description__, and at the beginning of each section\. In the same
manner the last subsection automatically ends at __manpage\_end__\.
................................................................................
> &nbsp;\.\.\.  
> \[para\]  
> &nbsp;\.\.\.  
> \[__subsection \{Sub 2\}__\]  
> &nbsp;\.\.\.  
> \[section \{Section B\}\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]


## <a name='subsection5'></a>Text markup

Having handled the overall structure a writer can impose on the document we now
take a closer at the text in a paragraph\.

While most often this is just the unadorned content of the document we do have
................................................................................
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\]  
>   
> &nbsp;&nbsp;Text structure\. List element\. Argument list\. Automatically closes the  
> &nbsp;&nbsp;previous list element\. Specifies the data\-\[__arg type__\] of the described  
> &nbsp;&nbsp;argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The  
> &nbsp;&nbsp;latter is optional\.  
> &nbsp;&nbsp;\.\.\.


## <a name='subsection6'></a>Escapes

Beyond the 20 commands for simple markup shown in the previous section we have
two more available which are technically simple markup\. However their function
is not the marking up of phrases as specific types of things, but the insertion
of characters, namely __\[__ and __\]__\. These commands, __lb__ and
................................................................................
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.


## <a name='subsection7'></a>Cross\-references

The last two commands we have to discuss are for the declaration of
cross\-references between documents, explicit and implicit\. They are
__[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both
take an arbitrary number of arguments, all of which have to be plain unmarked
................................................................................
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__see\_also doctools\_intro__\]  
> &nbsp;&nbsp;\[__see\_also doctools\_lang\_syntax__\]  
> &nbsp;&nbsp;\[__see\_also doctools\_lang\_cmdref__\]  
> &nbsp;&nbsp;\[__keywords markup \{semantic markup\}__\]  
> &nbsp;&nbsp;\[__keywords \{doctools markup\} \{doctools language\}__\]  
> &nbsp;&nbsp;\[__keywords \{doctools syntax\} \{doctools commands\}__\]  
> &nbsp;&nbsp;\[manpage\_end\]


## <a name='subsection8'></a>Examples

Where ever we can write plain text we can write examples too\. For simple
examples we have the command __example__ which takes a single argument, the
text of the argument\. The example text must not contain markup\. If we wish to
have markup within an example we have to use the 2\-command combination
................................................................................
\(Remember section [Advanced structure](#subsection3)\)\.

The source for the very first example in this document \(see section
[Fundamentals](#subsection1)\), with some highlighting added, is

> \[__example__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;\.\.\. \[list\_begin enumerated\] \.\.\.  
> &nbsp;&nbsp;\}\]


Using __example\_begin__ / __example\_end__ this would look like

> \[__example\_begin__\]  
> &nbsp;&nbsp;&nbsp;&nbsp;\.\.\. \[list\_begin enumerated\] \.\.\.  
> &nbsp;&nbsp;\[__example\_end__\]


## <a name='subsection9'></a>Lists

Where ever we can write plain text we can write lists too\. The main commands are
__list\_begin__ to start a list, and __list\_end__ to close one\. The
opening command takes an argument specifying the type of list started it, and
this in turn determines which of the eight existing list item commands are
................................................................................
>   
> &nbsp;&nbsp;\(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It  
> &nbsp;&nbsp;is a specialized form of a definition list where the term is the name  
> &nbsp;&nbsp;of a configuration option for a widget, with its name and class in the  
> &nbsp;&nbsp;option database\.  
>   
> &nbsp;&nbsp;\[__list\_end__\]  
> &nbsp;&nbsp;\.\.\.


Note that a list cannot begin in one \(sub\)section and end in another\.
Differently said, \(sub\)section breaks are not allowed within lists and list
items\. An example of this *illegal* construct is

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[list\_begin itemized\]  
> &nbsp;&nbsp;\[item\]  
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__section \{ILLEGAL WITHIN THE LIST\}__\]  
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[list\_end\]  
> &nbsp;&nbsp;\.\.\.


# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctools language syntax](doctools\_lang\_syntax\.md)* specification as
well\. From here on out the *[doctools language command

    overwriting any existing definition\. This is the assignment operator for
    automatons\. It copies the automaton contained in the FA object *srcFA*
    over the automaton definition in *faName*\. The old contents of *faName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    > *faName* __deserialize__ \[*srcFA* __serialize__\]  
    >   

  - <a name='6'></a>*faName* __\-\->__ *dstFA*

    This is the reverse assignment operator for automatons\. It copies the
    automation contained in the object *faName* over the automaton definition
    in the object *dstFA*\. The old contents of *dstFA* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *dstFA* __deserialize__ \[*faName* __serialize__\]  
    >   

  - <a name='7'></a>*faName* __serialize__

    This method serializes the automaton stored in *faName*\. In other words it
    returns a tcl *value* completely describing that automaton\. This allows,
    for example, the transfer of automatons over arbitrary channels,
    persistence, etc\. This method is also the basis for both the copy

    overwriting any existing definition\. This is the assignment operator for
    automatons\. It copies the automaton contained in the FA object *srcFA*
    over the automaton definition in *faName*\. The old contents of *faName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    > *faName* __deserialize__ \[*srcFA* __serialize__\]


  - <a name='6'></a>*faName* __\-\->__ *dstFA*

    This is the reverse assignment operator for automatons\. It copies the
    automation contained in the object *faName* over the automaton definition
    in the object *dstFA*\. The old contents of *dstFA* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *dstFA* __deserialize__ \[*faName* __serialize__\]


  - <a name='7'></a>*faName* __serialize__

    This method serializes the automaton stored in *faName*\. In other words it
    returns a tcl *value* completely describing that automaton\. This allows,
    for example, the transfer of automatons over arbitrary channels,
    persistence, etc\. This method is also the basis for both the copy

    overwriting any existing definition\. This is the assignment operator for
    grammars\. It copies the grammar contained in the grammar object *srcPEG*
    over the grammar definition in *pegName*\. The old contents of *pegName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    > *pegName* __deserialize__ \[*srcPEG* __serialize__\]  
    >   

  - <a name='5'></a>*pegName* __\-\->__ *dstPEG*

    This is the reverse assignment operator for grammars\. It copies the
    automation contained in the object *pegName* over the grammar definition
    in the object *dstPEG*\. The old contents of *dstPEG* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *dstPEG* __deserialize__ \[*pegName* __serialize__\]  
    >   

  - <a name='6'></a>*pegName* __serialize__

    This method serializes the grammar stored in *pegName*\. In other words it
    returns a tcl *value* completely describing that grammar\. This allows, for
    example, the transfer of grammars over arbitrary channels, persistence, etc\.
    This method is also the basis for both the copy constructor and the

    overwriting any existing definition\. This is the assignment operator for
    grammars\. It copies the grammar contained in the grammar object *srcPEG*
    over the grammar definition in *pegName*\. The old contents of *pegName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    > *pegName* __deserialize__ \[*srcPEG* __serialize__\]


  - <a name='5'></a>*pegName* __\-\->__ *dstPEG*

    This is the reverse assignment operator for grammars\. It copies the
    automation contained in the object *pegName* over the grammar definition
    in the object *dstPEG*\. The old contents of *dstPEG* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *dstPEG* __deserialize__ \[*pegName* __serialize__\]


  - <a name='6'></a>*pegName* __serialize__

    This method serializes the grammar stored in *pegName*\. In other words it
    returns a tcl *value* completely describing that grammar\. This allows, for
    example, the transfer of grammars over arbitrary channels, persistence, etc\.
    This method is also the basis for both the copy constructor and the

events, and via callback options like the text widget's __\-yscrollcommand__
option\. Tk events are available only in Tk, and callback options require tight
coupling between the modules sending and receiving the notification\.

Loose coupling between sender and receiver is often desirable, however\. In
Model/View/Controller terms, a View can send a command \(stemming from user
input\) to the Controller, which updates the Model\. The Model can then call a
hook *to which all relevant Views subscribe\.* The Model is decoupled from the
Views, and indeed need not know whether any Views actually exist\. At present,
Tcl/Tk has no standard mechanism for implementing loose coupling of this kind\.
This package defines a new command, __hook__, which implements just such a
mechanism\.

## <a name='subsection2'></a>Bindings

The __hook__ command manages a collection of hook bindings\. A hook binding
has four elements:

  1. A *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*: the name of the entity

events, and via callback options like the text widget's __\-yscrollcommand__
option\. Tk events are available only in Tk, and callback options require tight
coupling between the modules sending and receiving the notification\.

Loose coupling between sender and receiver is often desirable, however\. In
Model/View/Controller terms, a View can send a command \(stemming from user
input\) to the Controller, which updates the Model\. The Model can then call a
hook *to which all relevant* *Views subscribe\.* The Model is decoupled from
the Views, and indeed need not know whether any Views actually exist\. At
present, Tcl/Tk has no standard mechanism for implementing loose coupling of
this kind\. This package defines a new command, __hook__, which implements
just such a mechanism\.

## <a name='subsection2'></a>Bindings

The __hook__ command manages a collection of hook bindings\. A hook binding
has four elements:

  1. A *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*: the name of the entity

    to specify as a boolean value whether or not we can be used a certificate
    authority \(CA\)\. The *caDepth* argument indicates how many children CAs can
    be children of this CA in a depth\-wise fashion\. A value of "0" for the
    *caDepth* argument means that this CA cannot sign a CA certificate and
    have the result be valid\. A value of "\-1" indicates infinite depth\.

# <a name='section3'></a>EXAMPLES





# <a name='section4'></a>REFERENCES

# <a name='section5'></a>AUTHORS

Roy Keene

    to specify as a boolean value whether or not we can be used a certificate
    authority \(CA\)\. The *caDepth* argument indicates how many children CAs can
    be children of this CA in a depth\-wise fashion\. A value of "0" for the
    *caDepth* argument means that this CA cannot sign a CA certificate and
    have the result be valid\. A value of "\-1" indicates infinite depth\.

# <a name='section3'></a>EXAMPLES





# <a name='section4'></a>REFERENCES

# <a name='section5'></a>AUTHORS

Roy Keene

    This method assigns the contents of the PEG object *source* to ourselves,
    overwriting the existing definition\. This is the assignment operator for
    grammars\.

    This operation is in effect equivalent to

    > *objectName* __deserialize =__ \[*source* __serialize__\]  
    >   

  - <a name='9'></a>*objectName* __\-\->__ *destination*

    This method assigns our contents to the PEG object *destination*,
    overwriting the existing definition\. This is the reverse assignment operator
    for grammars\.

    This operation is in effect equivalent to

    > *destination* __deserialize =__ \[*objectName* __serialize__\]  
    >   

  - <a name='10'></a>*objectName* __serialize__ ?*format*?

    This method returns our grammar in some textual form usable for transfer,
    persistent storage, etc\. If no *format* is not specified the returned
    result is the canonical serialization of the grammar, as specified in the
    section [PEG serialization format](#section2)\.

    This method assigns the contents of the PEG object *source* to ourselves,
    overwriting the existing definition\. This is the assignment operator for
    grammars\.

    This operation is in effect equivalent to

    > *objectName* __deserialize =__ \[*source* __serialize__\]


  - <a name='9'></a>*objectName* __\-\->__ *destination*

    This method assigns our contents to the PEG object *destination*,
    overwriting the existing definition\. This is the reverse assignment operator
    for grammars\.

    This operation is in effect equivalent to

    > *destination* __deserialize =__ \[*objectName* __serialize__\]


  - <a name='10'></a>*objectName* __serialize__ ?*format*?

    This method returns our grammar in some textual form usable for transfer,
    persistent storage, etc\. If no *format* is not specified the returned
    result is the canonical serialization of the grammar, as specified in the
    section [PEG serialization format](#section2)\.

    This is the *assignment* operator for graph objects\. It copies the graph
    contained in the graph object *sourcegraph* over the graph data in
    *graphName*\. The old contents of *graphName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *graphName* __deserialize__ \[*sourcegraph* __serialize__\]  
    >   

    The operation assumes that the *sourcegraph* provides the method
    __serialize__ and that this method returns a valid graph serialization\.

  - <a name='4'></a>*graphName* __\-\->__ *destgraph*

    This is the *reverse assignment* operator for graph objects\. It copies the
    graph contained in the graph object *graphName* over the graph data in the
    object *destgraph*\. The old contents of *destgraph* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *destgraph* __deserialize__ \[*graphName* __serialize__\]  
    >   

    The operation assumes that the *destgraph* provides the method
    __deserialize__ and that this method takes a graph serialization\.

  - <a name='5'></a>*graphName* __append__ *key* *value*

    Appends a *value* to one of the keyed values associated with the graph\.

    This is the *assignment* operator for graph objects\. It copies the graph
    contained in the graph object *sourcegraph* over the graph data in
    *graphName*\. The old contents of *graphName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *graphName* __deserialize__ \[*sourcegraph* __serialize__\]


    The operation assumes that the *sourcegraph* provides the method
    __serialize__ and that this method returns a valid graph serialization\.

  - <a name='4'></a>*graphName* __\-\->__ *destgraph*

    This is the *reverse assignment* operator for graph objects\. It copies the
    graph contained in the graph object *graphName* over the graph data in the
    object *destgraph*\. The old contents of *destgraph* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *destgraph* __deserialize__ \[*graphName* __serialize__\]


    The operation assumes that the *destgraph* provides the method
    __deserialize__ and that this method takes a graph serialization\.

  - <a name='5'></a>*graphName* __append__ *key* *value*

    Appends a *value* to one of the keyed values associated with the graph\.

    This is the assignment operator for matrix objects\. It copies the matrix
    contained in the matrix object *sourcematrix* over the matrix data in
    *matrixName*\. The old contents of *matrixName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *matrixName* __deserialize__ \[*sourcematrix* __serialize__\]  
    >   

  - <a name='4'></a>*matrixName* __\-\->__ *destmatrix*

    This is the reverse assignment operator for matrix objects\. It copies the
    matrix contained in the matrix object *matrixName* over the matrix data in
    the object *destmatrix*\. The old contents of *destmatrix* are deleted by
    this operation\.

    This operation is in effect equivalent to

    > *destmatrix* __deserialize__ \[*matrixName* __serialize__\]  
    >   

  - <a name='5'></a>*matrixName* __add column__ ?*values*?

    Extends the matrix by one column and then acts like __set column__ \(see
    below\) on this new column if there were *values* supplied\. Without
    *values* the new cells will be set to the empty string\. The new column is
    appended immediately behind the last existing column\.

    This is the assignment operator for matrix objects\. It copies the matrix
    contained in the matrix object *sourcematrix* over the matrix data in
    *matrixName*\. The old contents of *matrixName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *matrixName* __deserialize__ \[*sourcematrix* __serialize__\]


  - <a name='4'></a>*matrixName* __\-\->__ *destmatrix*

    This is the reverse assignment operator for matrix objects\. It copies the
    matrix contained in the matrix object *matrixName* over the matrix data in
    the object *destmatrix*\. The old contents of *destmatrix* are deleted by
    this operation\.

    This operation is in effect equivalent to

    > *destmatrix* __deserialize__ \[*matrixName* __serialize__\]


  - <a name='5'></a>*matrixName* __add column__ ?*values*?

    Extends the matrix by one column and then acts like __set column__ \(see
    below\) on this new column if there were *values* supplied\. Without
    *values* the new cells will be set to the empty string\. The new column is
    appended immediately behind the last existing column\.

    This is the assignment operator for tree objects\. It copies the tree
    contained in the tree object *sourcetree* over the tree data in
    *treeName*\. The old contents of *treeName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *treeName* __deserialize__ \[*sourcetree* __serialize__\]  
    >   

  - <a name='5'></a>*treeName* __\-\->__ *desttree*

    This is the reverse assignment operator for tree objects\. It copies the tree
    contained in the tree object *treeName* over the tree data in the object
    *desttree*\. The old contents of *desttree* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *desttree* __deserialize__ \[*treeName* __serialize__\]  
    >   

  - <a name='6'></a>*treeName* __ancestors__ *node*

    This method extends the method __parent__ and returns a list containing
    all ancestor nodes to the specified *node*\. The immediate ancestor, in
    other words, parent node, is the first element in that list, its parent the
    second element, and so on until the root node is reached, making it the last

    This is the assignment operator for tree objects\. It copies the tree
    contained in the tree object *sourcetree* over the tree data in
    *treeName*\. The old contents of *treeName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *treeName* __deserialize__ \[*sourcetree* __serialize__\]


  - <a name='5'></a>*treeName* __\-\->__ *desttree*

    This is the reverse assignment operator for tree objects\. It copies the tree
    contained in the tree object *treeName* over the tree data in the object
    *desttree*\. The old contents of *desttree* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *desttree* __deserialize__ \[*treeName* __serialize__\]


  - <a name='6'></a>*treeName* __ancestors__ *node*

    This method extends the method __parent__ and returns a list containing
    all ancestor nodes to the specified *node*\. The immediate ancestor, in
    other words, parent node, is the first element in that list, its parent the
    second element, and so on until the root node is reached, making it the last

    >       __\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\  
    >    __\-frame__ \{*\-label "Itinerary destination"*\} \\  
    >       __\-comment__ \{*\-text "Specify your itinerary destination"*\} \\  
    >       __\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\  
    >       __\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\  
    >       __\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\  
    >    __\-frame__ \{\} \\  
    >    __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}  

    \] This example opens a dialog box that has the title *Itinerary
    selection*\. A first entry widget in this box allows selecting a report
    file\. It follows two frames to define respectively an itinerary start and
    end location\. Each of these locations that are described with a comment has
    three entry widgets to specify respectively the city, street and the street
    number\. Bellow the second frame there is a check button that allows
    specifying if eventual highways should be ignored\.

  - <a name='2'></a>__tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\}

    Sometimes it is simpler to provide all the data entry item definitions in
    form of a single list to __argument\_dialogbox__, and not as individual
    arguments\. The second format that is supported by __argument\_dialogbox__
    corresponds exactly to the first one, except that all item definitions are
................................................................................
    packed into a single list that is provided to __argument\_dialogbox__\.
    The previous example can therefore also be written in the following way:

    > set DialogResult \[__tepam::argument\_dialogbox \{__  
    > &nbsp;&nbsp;&nbsp;__\-title__ "Itinerary selection"  
    > &nbsp;&nbsp;&nbsp;__\-file__ \{*\-label "Itinerary report" \-variable report\_file*\}  
    > &nbsp;&nbsp;&nbsp;\.\.\.  
    > &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}   

    __\}__\]

The commands __argument\_dialogbox__ as well as
__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the
namespace __tepam__\. To use these commands without the __tepam::__
namespace prefix, it is sufficient to import them into the main namespace:

> __namespace import tepam::\*__  
>   
> set DialogResult \[__argument\_dialogbox__ \\  
> &nbsp;&nbsp;&nbsp;\-title "Itinerary selection"  
> &nbsp;&nbsp;&nbsp;\.\.\.  

The following subsections explain the different argument item types that are
accepted by the __argument\_dialogbox__, classified into three groups\. The
first data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument\_dialogbox__\.
................................................................................
## <a name='subsection1'></a>Context Definition Items

The first item group allows specifying some context aspects of an argument
dialog box\. These items are taking a simple character string as item attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ *string* \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  

The following items are classified into this group:

  - \-title *string*

    The dialog box window title which is by default *Dialog* can be changed
    with the *\-title* item:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-title__ "System configuration" \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  

  - \-window *string*

    The argument dialog box uses by default *\.dialog* as dialog top level
    window\. This path can be changed with the *\-window* item:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-window__ \.dialog \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  

  - \-parent *string*

    By defining a parent window, the argument dialog box will be displayed
    beside this one\. Without explicit parent window definition, the top\-level
    window will be considered as parent window\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-parent__ \.my\_appl \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  

  - \-context *string*

    If a context is defined the dialog box state, e\.g\. the entered data as well
    as the window size and position, is restored the next time the argument
    dialog box is called\. The assignment of a context allows saving the dialog
    box state in its context to distinguish between different usages of the
    argument dialog box\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-context__ destination\_definitions \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  

## <a name='subsection2'></a>Formatting and Display Options

Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user\. A couple of items allow structuring
and commenting the dialog boxes\.

The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ \{ *  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?\-<attribute\_name> <attribute\_value>?  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?\-<attribute\_name> <attribute\_value>?  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?\.\.\.?*  

> &nbsp;&nbsp;&nbsp;\}  
> &nbsp;&nbsp;&nbsp;\.\.\.  

The following items are classified into this group:

  - \-frame *list*

    The *\-frame* item allows packing all following entry widgets into a
    labeled frame, until a next frame item is defined or until the last entry
................................................................................
        An optional frame label can be specified with the *\-label* statement\.

    Example:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Destination address"*\}  
> &nbsp;&nbsp;&nbsp;\.\.\.  

    To close an open frame without opening a new one, an empty list has to be
    provided to the *\-frame* statement\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\}  
> &nbsp;&nbsp;&nbsp;\.\.\.  

  - \-sep \[const \{\{\}\}\]

    Entry widgets can be separated with the *\-sep* statement which doesn't
    require additional definitions\. The related definition list has to exist,
    but its content is ignored\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-sep__ \{\}  
> &nbsp;&nbsp;&nbsp;\.\.\.  

  - \-comment *string*

    Comments and descriptions can be added with the *\-text* attribute of the
    *\-comment* item\. Please note that each entry widget itself can also
    contain a *\-text* attribute for comments and descriptions\. But the
    *\-comment* item allows for example adding a description between two
    frames\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify bellow the destination address"*\}  
> &nbsp;&nbsp;&nbsp;\.\.\.  

  - \-yscroll __0__&#124;__1__&#124;__auto__

    This attribute allows controlling an eventual vertical scrollbar\. Setting it
    to __0__ will permanently disable the scrollbar, setting it to __1__
    will enable it\. By default it is set to __auto__\. The scrollbar is
    enabled in this mode only if the vertical data entry form size exceeds 66%
    of the screen height\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-yscroll__ __auto__  
> &nbsp;&nbsp;&nbsp;\.\.\.  

## <a name='subsection3'></a>Global Custom Data Validation

This item group allows specifying global custom checks to validate the entered
data\.

  - \-validatecommand *script*

    Custom data checks can be performed via validation commands that are defined
    with the *\-validatecommand* item\. Example:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Your comment" \-variable YourCom\} \\  
> &nbsp;&nbsp;&nbsp;__\-validatecommand__ \{IllegalWordDetector $YourCom\}  

    The validation command is executed in the context of the calling procedure,
    once all the basic data checks have been performed and data variables are
    assigned\. All data is accessed via the data variables\. Note that there is
    also an entry widget specific attribute *\-validatecommand* that allows
    declaring custom checks for specific data entries\.

................................................................................

Data entry widgets are created with the widget items\. These items require as
item attributes a definition list, which contains itself attribute name and
value pairs:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ \{ *  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?\-<attribute\_name> <attribute\_value>?  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?\-<attribute\_name> <attribute\_value>?  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?\.\.\.?*  

> &nbsp;&nbsp;&nbsp;\}  
> &nbsp;&nbsp;&nbsp;\.\.\.  

The attribute list can contain various attributes to describe and comment an
entry widget and to constrain its entered value\. All entry widgets are accepting
a common set of attributes that are described in the section [Entry Widget Item
Attributes](#subsection5)\.

TEPAM defines a rich set of entry widgets\. If necessary, this set can be
................................................................................

  - \-entry *list*

    The *\-entry* item generates the simplest but most universal data entry
    widget\. It allows entering any kind of data in form of single line strings\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-entry__ \{\-label Name \-variable Entry\}  

  - \-text *list*

    The *\-text* item generates a multi line text entry widget\. The widget
    height can be selected with the *\-height* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-text__ \{\-label Name \-variable Text \-height 5\}  

  - \-checkbox *list*

    A group of check boxes is created with the *\-checkbox* item\. The number of
    check boxes and their option values are specified with a list assigned to
    the *\-choices* attribute or via a variable declared with the
    *\-choicevariable* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \-default italic\}  

    If the labels of the check boxes should differ from the option values, their
    labels can be defined with the *\-choicelabels* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicelabels \{Bold Italic Underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default italic\}  

    In contrast to a radio box group, a check box group allows selecting
    simultaneously several choice options\. The selection is stored for this
    reason inside the defined variable in form of a list, even if only one
    choice option has been selected\.

  - \-radiobox *list*
................................................................................

    In contrast to a check box group, a radio box group allows selecting
    simultaneously only one choice option\. The selected option value is stored
    directly, and not in form of a list, inside the defined variable\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{left center right\} \-default left\}  

    If the labels of the radio boxes should differ from the option values, their
    labels can be defined with the *\-choicelabels* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{left center right\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicelabels \{Left Center Right\} \-default left\}  

  - \-checkbutton *list*

    The *\-checkbutton* entry widget allows activating or deactivating a single
    choice option\. The result written into the variable will either be __0__
    if the check button was not activated or __1__ if it was activated\. An
    eventually provided default value has also to be either __0__ or
    __1__\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{\-label Capitalize \-variable Capitalize \-default 1\}  

Several types of list and combo boxes are available to handle selection lists\.

  - \-combobox *list*

    The combobox is a combination of a normal entry widget together with a
    drop\-down list box\. The combobox allows selecting from this drop\-down list
    box a single element\. The list of the available elements can be provided
    either as a list to the *\-choices* attribute, or via a variable that is
    specified with the *\-choicevariable* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-combobox__ \{\-label "Text size" \-variable Size \-choices \{8 9 10 12 15 18\} \-default 12\}  

    And here is an example of using a variable to define the selection list:

> set TextSizes \{8 9 10 12 15 18\}  
> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-combobox__ \{\-label "Text size" \-variable Size \-choicevariable TextSizes \-default 12\}  

  - \-listbox *list*

    In contrast to the combo box, the list box is always displayed by the
    *listbox* entry widget\. Only one element is selectable unless the
    *\-multiple\_selection* attribute is set\. The list box height can be
    selected with the *\-height* attribute\. If the height is not explicitly
................................................................................
    box size\. The first example uses a variable to define the available choices:

> set set AvailableSizes  
> for \{set k 0\} \{$k<16\} \{incr k\} \{lappend AvailableSizes \[expr 1<<$k\]\}  
>   
> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-listbox__ \{\-label "Distance" \-variable Distance \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicevariable AvailableSizes \-default 6 \-height 5\}  

    Here is a multi\-element selection example\. Please note that also the default
    selection can contain multiple elements:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-listbox__ \{\-label "Text styles" \-variable Styles \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline overstrike\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicelabels \{Bold Italic Underline Overstrike\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{bold underline\} \-multiple\_selection 1 \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-height 3\}  

  - \-disjointlistbox *list*

    A disjoint list box has to be used instead of a normal list box if the
    selection order is important\. The disjoint list box entry widget has in fact
    two list boxes, one to select elements and one to display the selected
    elements in the chosen order\.
................................................................................
    are accepting the same attributes as the normal listbox, e\.g\. *\-height,
    \-choices, \-choicevariable, \-default*\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-disjointlistbox__ \{\-label "Preferred scripting languages" \-variable Languages \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-comment "Please select your preferred languages in the order" \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{Tcl Perl Python\}\}  

The file and directory selectors are building a next group of data entry
widgets\. A paragraph of section [Entry Widget Item
Attributes](#subsection5) explains the widget specific attributes that allow
specifying the targeted file types, active directory etc\.

  - \-file *list*
................................................................................
    a button that allows opening a file browser\. The data type *file* is
    automatically selected for this entry if no data type has been explicitly
    defined with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-file__ \{\-label "Image file" \-variable ImageF \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-initialfile "picture\.gif"\}  

  - \-existingfile *list*

    The item *\-existingfile* creates a group composed by an entry widget
    together with a button that allows opening a browser to select an existing
    file\. The data type *existingfile* is automatically selected for this
    entry if no data type has been explicitly defined with the *\-type*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-existingfile__ \{\-label "Image file" \-variable ImageF \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-initialfile "picture\.gif"\}  

  - \-directory *list*

    The item *\-directory* creates a group composed by an entry widget together
    with a button that allows opening a directory browser\. The data type
    *directory* is automatically selected for this entry if no data type has
    been explicitly defined with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-directory__ \{\-label "Report directory" \-variable ReportDir\}  

  - \-existingdirectory *list*

    The item *\-existingdirectory* creates a group composed by an entry widget
    together with a button that allows opening a browser to select an existing
    directory\. The data type *existingdirectory* is automatically selected for
    this entry if no data type has been explicitly defined with the *\-type*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-existingdirectory__ \{\-label "Report directory" \-variable ReportDir\}  

Finally, there is a last group of some other special data entry widgets\.

  - \-color *list*

    The color selector is composed by an entry widget together with a button
    that allows opening a color browser\. The data type *color* is
    automatically selected for this entry widget type if no data type has been
    explicitly defined with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-color__ \{\-label "Background color" \-variable Color \-default red\}  

  - \-font *list*

    The font selector is composed by an entry widget together with a button that
    allows opening a font browser\. The data type *font* is automatically
    selected for this entry widget type if no data type has been explicitly
    defined with the *\-type* attribute\. The entry widget displays an example
................................................................................
    of the available families the first available family is used as default\. If
    the font size of this label widget is not part of the available sizes the
    next close available size is selected as default size\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-font__ \{\-label "Font" \-variable Font \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-font\_sizes \{8 10 12 16\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{Arial 20 italic\}\}  

## <a name='subsection5'></a>Entry Widget Item Attributes

All the entry widget items are accepting the following attributes:

  - \-text *string*

    Eventual descriptions and comments specified with the *\-text* attribute
    are displayed above the entry widget\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{__\-text "Please enter your name bellow"__ \-variable Name\}  

  - \-label *string*

    The label attribute creates left to the entry widget a label using the
    provided string as label text:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{__\-label Name__ \-variable Name\}  

  - \-variable *string*

    All entry widgets require a specified variable\. After accepting the entered
    information with the OK button, the entry widget data is stored inside the
    defined variables\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-existingdirectory \{\-label "Report directory" __\-variable ReportDir__\}  

  - \-default *string*

    Eventual default data for the entry widgets can be provided via the
    *\-default* attribute\. The default value is overridden if an argument
    dialog box with a defined context is called another time\. The value
    acknowledged in a previous call will be used in this case as default value\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-checkbox \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} __\-default italic__\}  

  - \-optional __0__&#124;__1__

    Data can be specified as optional or mandatory with the *\-optional*
    attribute that requires either __0__ \(mandatory\) or __1__ \(optional\)
    as attribute data\.

................................................................................
    In case an entry is optional and no data has been entered, e\.g\. the entry
    contains an empty character string, the entry will be considered as
    undefined and the assigned variable will not be defined\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "City" \-variable start\_city \-type string\} \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Street" \-variable start\_street \-type string __\-optional 0__\} \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Street number" \-variable start\_street\_nbr \-type integer __\-optional 1__\} \\  

  - \-type *string*

    If the data type is defined with the *\-type* attribute the argument dialog
    box will automatically perform a data type check after acknowledging the
    entered values and before the dialog box is closed\. If a type incompatible
    value is found an error message box appears and the user can correct the
................................................................................
    *tepam::procedure reference manual*\)\.

    Some entry widgets like the file and directory widgets, as well as the color
    and font widgets are specifying automatically the default data type if no
    type has been specified explicitly with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-entry__ \{\-label "Street number" \-variable start\_street\_nbr __\-type integer__\} \\  

  - \-range *string*

    Values can be constrained with the *\-range* attribute\. The valid range is
    defined with a list containing the minimum valid value and a maximum valid
    value\.

    The *\-range* attribute has to be used only for numerical arguments, like
    integers and doubles\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label Month \-variable Month \-type integer __\-range \{1 12\}__\}  

  - \-validatecommand *string*

    Custom argument value validations can be performed via specific validation
    commands that are defined with the *\-validatecommand* attribute\. The
    provided validation command can be a complete script in which the pattern
    *%P* is placeholder for the argument value that has to be validated\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Your comment" \-variable YourCom \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-validatecommand__ "IllegalWordDetector %P"\}  

    While the purpose of this custom argument validation attribute is the
    validation of a specific argument, there is also a global data validation
    attribute *\-validatecommand* that allows performing validation that
    involves multiple arguments\.

  - \-validatecommand\_error\_text *string*
................................................................................

    Choice lists can directly be defined with the *\-choices* attribute\. This
    way to define choice lists is especially adapted for smaller, fixed
    selection lists\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-listbox \{\-label "Text styles" \-variable Styles \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-choices \{bold italic underline\}__ \-default underline  

  - \-choicelabels *string* *\(only check and radio buttons\)*

    If the labels of the check and radio boxes should differ from the option
    values, they can be defined with the *\-choicelabels* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-checkbox \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-choicelabels \{Bold Italic Underline\}__   

  - \-choicevariable *string*

    Another way to define the choice lists is using the *\-choicevariable*
    attribute\. This way to define choice lists is especially adapted for huge
    and eventually variable selection lists\.

> set TextSizes \{8 9 10 12 15 18\}  
> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-combobox \{\-label "Text size" \-variable Size __\-choicevariable TextSizes__\}  

  - \-multiple\_selection __0__&#124;__1__

    The list box item \(__\-listbox__\) allows by default selecting only one
    list element\. By setting the *\-multiple\_selection* attribute to __1__,
    multiple elements can be selected\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-listbox \{\-label "Text styles" \-variable Styles \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \-default underline \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-multiple\_selection 1__ \-height 3\}  

Some additional attributes are supported by the file and directory selection
widgets\.

  - \-filetypes *string*

    The file type attribute is used by the __\-file__ and
    __\-existingfile__ items to define the file endings that are searched by
    the file browser\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-file \{\-label "Image file" \-variable ImageF \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\}__\}  

  - \-initialfile *string*

    The initial file used by the file browsers of the __\-file__ and
    __\-existingfile__ widgets are by default the file defined with the
    *\-default* attribute, unless a file is specified with the *\-initialfile*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-file \{\-variable ImageF __\-initialfile "picture\.gif"__\}  

  - \-activedir *string*

    The *\-activedir* attribute will override the default active search
    directory used by the file browsers of all file and directory entry widgets\.
    The default active search directory is defined by the directory of a
    specified initial file \(*\-initialfile*\) if defined, and otherwise by the
    directory of the default file/directory, specified with the *\-default*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-file "\-variable ImageF __\-activedir $pwd__"  

Finally, there is a last attribute supported by some widgets:

  - \-height *string*

    All widgets containing a selection list \(__\-listbox__,
    __\-disjointlistbox__, __\-font__\) as well as the multi line
    __\-text__ widget are accepting the *\-height* attribute that defines
    the number of displayed rows of the selection lists\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-listbox \{\-label "Text size" \-variable Size \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{8 9 10 12 15 18\} \-default 12 __\-height 3__\}  

    If the no height has been explicitly specified the height of the widget will
    be dynamically adapted to the argument dialog box size\.

# <a name='section3'></a>APPLICATION SPECIFIC ENTRY WIDGETS

An application specific entry widget can be made available to the argument
................................................................................
> &nbsp;&nbsp;&nbsp;*variable argument\_dialogbox; \# if required*  
> &nbsp;&nbsp;&nbsp;switch $Command \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"create" <CreateCommandSequence>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"set\_choice" <SetChoiceCommandSequence>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"set" <SetCommandv>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"get" <GetCommandSequence>  
> &nbsp;&nbsp;&nbsp;\}  
> \}  

__Argument\_dialogbox__ takes care about the *\-label* and *\-text*
attributes for all entry widgets\. For any data entry widget it creates a frame
into which the data entry widget components can be placed\. The path to this
frame is provided via the *W* argument\.

The entry widget procedure has to support 3 mandatory and an optional command

    >       __\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\  
    >    __\-frame__ \{*\-label "Itinerary destination"*\} \\  
    >       __\-comment__ \{*\-text "Specify your itinerary destination"*\} \\  
    >       __\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\  
    >       __\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\  
    >       __\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\  
    >    __\-frame__ \{\} \\  
    >    __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}\]

    This example opens a dialog box that has the title *Itinerary selection*\.
    A first entry widget in this box allows selecting a report file\. It follows
    two frames to define respectively an itinerary start and end location\. Each
    of these locations that are described with a comment has three entry widgets
    to specify respectively the city, street and the street number\. Bellow the
    second frame there is a check button that allows specifying if eventual
    highways should be ignored\.

  - <a name='2'></a>__tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\}

    Sometimes it is simpler to provide all the data entry item definitions in
    form of a single list to __argument\_dialogbox__, and not as individual
    arguments\. The second format that is supported by __argument\_dialogbox__
    corresponds exactly to the first one, except that all item definitions are
................................................................................
    packed into a single list that is provided to __argument\_dialogbox__\.
    The previous example can therefore also be written in the following way:

    > set DialogResult \[__tepam::argument\_dialogbox \{__  
    > &nbsp;&nbsp;&nbsp;__\-title__ "Itinerary selection"  
    > &nbsp;&nbsp;&nbsp;__\-file__ \{*\-label "Itinerary report" \-variable report\_file*\}  
    > &nbsp;&nbsp;&nbsp;\.\.\.  
    > &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\} __\}__\]



The commands __argument\_dialogbox__ as well as
__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the
namespace __tepam__\. To use these commands without the __tepam::__
namespace prefix, it is sufficient to import them into the main namespace:

> __namespace import tepam::\*__  
>   
> set DialogResult \[__argument\_dialogbox__ \\  
> &nbsp;&nbsp;&nbsp;\-title "Itinerary selection"  
> &nbsp;&nbsp;&nbsp;\.\.\.

The following subsections explain the different argument item types that are
accepted by the __argument\_dialogbox__, classified into three groups\. The
first data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument\_dialogbox__\.
................................................................................
## <a name='subsection1'></a>Context Definition Items

The first item group allows specifying some context aspects of an argument
dialog box\. These items are taking a simple character string as item attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ *string* \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

The following items are classified into this group:

  - \-title *string*

    The dialog box window title which is by default *Dialog* can be changed
    with the *\-title* item:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-title__ "System configuration" \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-window *string*

    The argument dialog box uses by default *\.dialog* as dialog top level
    window\. This path can be changed with the *\-window* item:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-window__ \.dialog \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-parent *string*

    By defining a parent window, the argument dialog box will be displayed
    beside this one\. Without explicit parent window definition, the top\-level
    window will be considered as parent window\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-parent__ \.my\_appl \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-context *string*

    If a context is defined the dialog box state, e\.g\. the entered data as well
    as the window size and position, is restored the next time the argument
    dialog box is called\. The assignment of a context allows saving the dialog
    box state in its context to distinguish between different usages of the
    argument dialog box\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-context__ destination\_definitions \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

## <a name='subsection2'></a>Formatting and Display Options

Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user\. A couple of items allow structuring
and commenting the dialog boxes\.

The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ \{   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\-<attribute\_name> <attribute\_value>?*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\-<attribute\_name> <attribute\_value>?*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\.\.\.?*  
>   
> &nbsp;&nbsp;&nbsp;\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

The following items are classified into this group:

  - \-frame *list*

    The *\-frame* item allows packing all following entry widgets into a
    labeled frame, until a next frame item is defined or until the last entry
................................................................................
        An optional frame label can be specified with the *\-label* statement\.

    Example:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Destination address"*\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

    To close an open frame without opening a new one, an empty list has to be
    provided to the *\-frame* statement\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-sep \[const \{\{\}\}\]

    Entry widgets can be separated with the *\-sep* statement which doesn't
    require additional definitions\. The related definition list has to exist,
    but its content is ignored\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-sep__ \{\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-comment *string*

    Comments and descriptions can be added with the *\-text* attribute of the
    *\-comment* item\. Please note that each entry widget itself can also
    contain a *\-text* attribute for comments and descriptions\. But the
    *\-comment* item allows for example adding a description between two
    frames\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify bellow the destination address"*\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-yscroll __0__&#124;__1__&#124;__auto__

    This attribute allows controlling an eventual vertical scrollbar\. Setting it
    to __0__ will permanently disable the scrollbar, setting it to __1__
    will enable it\. By default it is set to __auto__\. The scrollbar is
    enabled in this mode only if the vertical data entry form size exceeds 66%
    of the screen height\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-yscroll__ __auto__  
> &nbsp;&nbsp;&nbsp;\.\.\.

## <a name='subsection3'></a>Global Custom Data Validation

This item group allows specifying global custom checks to validate the entered
data\.

  - \-validatecommand *script*

    Custom data checks can be performed via validation commands that are defined
    with the *\-validatecommand* item\. Example:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Your comment" \-variable YourCom\} \\  
> &nbsp;&nbsp;&nbsp;__\-validatecommand__ \{IllegalWordDetector $YourCom\}

    The validation command is executed in the context of the calling procedure,
    once all the basic data checks have been performed and data variables are
    assigned\. All data is accessed via the data variables\. Note that there is
    also an entry widget specific attribute *\-validatecommand* that allows
    declaring custom checks for specific data entries\.

................................................................................

Data entry widgets are created with the widget items\. These items require as
item attributes a definition list, which contains itself attribute name and
value pairs:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ \{   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\-<attribute\_name> <attribute\_value>?*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\-<attribute\_name> <attribute\_value>?*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\.\.\.?*  
>   
> &nbsp;&nbsp;&nbsp;\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

The attribute list can contain various attributes to describe and comment an
entry widget and to constrain its entered value\. All entry widgets are accepting
a common set of attributes that are described in the section [Entry Widget Item
Attributes](#subsection5)\.

TEPAM defines a rich set of entry widgets\. If necessary, this set can be
................................................................................

  - \-entry *list*

    The *\-entry* item generates the simplest but most universal data entry
    widget\. It allows entering any kind of data in form of single line strings\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-entry__ \{\-label Name \-variable Entry\}

  - \-text *list*

    The *\-text* item generates a multi line text entry widget\. The widget
    height can be selected with the *\-height* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-text__ \{\-label Name \-variable Text \-height 5\}

  - \-checkbox *list*

    A group of check boxes is created with the *\-checkbox* item\. The number of
    check boxes and their option values are specified with a list assigned to
    the *\-choices* attribute or via a variable declared with the
    *\-choicevariable* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \-default italic\}

    If the labels of the check boxes should differ from the option values, their
    labels can be defined with the *\-choicelabels* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicelabels \{Bold Italic Underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default italic\}

    In contrast to a radio box group, a check box group allows selecting
    simultaneously several choice options\. The selection is stored for this
    reason inside the defined variable in form of a list, even if only one
    choice option has been selected\.

  - \-radiobox *list*
................................................................................

    In contrast to a check box group, a radio box group allows selecting
    simultaneously only one choice option\. The selected option value is stored
    directly, and not in form of a list, inside the defined variable\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{left center right\} \-default left\}

    If the labels of the radio boxes should differ from the option values, their
    labels can be defined with the *\-choicelabels* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{left center right\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicelabels \{Left Center Right\} \-default left\}

  - \-checkbutton *list*

    The *\-checkbutton* entry widget allows activating or deactivating a single
    choice option\. The result written into the variable will either be __0__
    if the check button was not activated or __1__ if it was activated\. An
    eventually provided default value has also to be either __0__ or
    __1__\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{\-label Capitalize \-variable Capitalize \-default 1\}

Several types of list and combo boxes are available to handle selection lists\.

  - \-combobox *list*

    The combobox is a combination of a normal entry widget together with a
    drop\-down list box\. The combobox allows selecting from this drop\-down list
    box a single element\. The list of the available elements can be provided
    either as a list to the *\-choices* attribute, or via a variable that is
    specified with the *\-choicevariable* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-combobox__ \{\-label "Text size" \-variable Size \-choices \{8 9 10 12 15 18\} \-default 12\}

    And here is an example of using a variable to define the selection list:

> set TextSizes \{8 9 10 12 15 18\}  
> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-combobox__ \{\-label "Text size" \-variable Size \-choicevariable TextSizes \-default 12\}

  - \-listbox *list*

    In contrast to the combo box, the list box is always displayed by the
    *listbox* entry widget\. Only one element is selectable unless the
    *\-multiple\_selection* attribute is set\. The list box height can be
    selected with the *\-height* attribute\. If the height is not explicitly
................................................................................
    box size\. The first example uses a variable to define the available choices:

> set set AvailableSizes  
> for \{set k 0\} \{$k<16\} \{incr k\} \{lappend AvailableSizes \[expr 1<<$k\]\}  
>   
> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-listbox__ \{\-label "Distance" \-variable Distance \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicevariable AvailableSizes \-default 6 \-height 5\}

    Here is a multi\-element selection example\. Please note that also the default
    selection can contain multiple elements:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-listbox__ \{\-label "Text styles" \-variable Styles \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline overstrike\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicelabels \{Bold Italic Underline Overstrike\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{bold underline\} \-multiple\_selection 1 \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-height 3\}

  - \-disjointlistbox *list*

    A disjoint list box has to be used instead of a normal list box if the
    selection order is important\. The disjoint list box entry widget has in fact
    two list boxes, one to select elements and one to display the selected
    elements in the chosen order\.
................................................................................
    are accepting the same attributes as the normal listbox, e\.g\. *\-height,
    \-choices, \-choicevariable, \-default*\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-disjointlistbox__ \{\-label "Preferred scripting languages" \-variable Languages \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-comment "Please select your preferred languages in the order" \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{Tcl Perl Python\}\}

The file and directory selectors are building a next group of data entry
widgets\. A paragraph of section [Entry Widget Item
Attributes](#subsection5) explains the widget specific attributes that allow
specifying the targeted file types, active directory etc\.

  - \-file *list*
................................................................................
    a button that allows opening a file browser\. The data type *file* is
    automatically selected for this entry if no data type has been explicitly
    defined with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-file__ \{\-label "Image file" \-variable ImageF \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-initialfile "picture\.gif"\}

  - \-existingfile *list*

    The item *\-existingfile* creates a group composed by an entry widget
    together with a button that allows opening a browser to select an existing
    file\. The data type *existingfile* is automatically selected for this
    entry if no data type has been explicitly defined with the *\-type*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-existingfile__ \{\-label "Image file" \-variable ImageF \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-initialfile "picture\.gif"\}

  - \-directory *list*

    The item *\-directory* creates a group composed by an entry widget together
    with a button that allows opening a directory browser\. The data type
    *directory* is automatically selected for this entry if no data type has
    been explicitly defined with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-directory__ \{\-label "Report directory" \-variable ReportDir\}

  - \-existingdirectory *list*

    The item *\-existingdirectory* creates a group composed by an entry widget
    together with a button that allows opening a browser to select an existing
    directory\. The data type *existingdirectory* is automatically selected for
    this entry if no data type has been explicitly defined with the *\-type*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-existingdirectory__ \{\-label "Report directory" \-variable ReportDir\}

Finally, there is a last group of some other special data entry widgets\.

  - \-color *list*

    The color selector is composed by an entry widget together with a button
    that allows opening a color browser\. The data type *color* is
    automatically selected for this entry widget type if no data type has been
    explicitly defined with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-color__ \{\-label "Background color" \-variable Color \-default red\}

  - \-font *list*

    The font selector is composed by an entry widget together with a button that
    allows opening a font browser\. The data type *font* is automatically
    selected for this entry widget type if no data type has been explicitly
    defined with the *\-type* attribute\. The entry widget displays an example
................................................................................
    of the available families the first available family is used as default\. If
    the font size of this label widget is not part of the available sizes the
    next close available size is selected as default size\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-font__ \{\-label "Font" \-variable Font \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-font\_sizes \{8 10 12 16\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{Arial 20 italic\}\}

## <a name='subsection5'></a>Entry Widget Item Attributes

All the entry widget items are accepting the following attributes:

  - \-text *string*

    Eventual descriptions and comments specified with the *\-text* attribute
    are displayed above the entry widget\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{__\-text "Please enter your name bellow"__ \-variable Name\}

  - \-label *string*

    The label attribute creates left to the entry widget a label using the
    provided string as label text:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{__\-label Name__ \-variable Name\}

  - \-variable *string*

    All entry widgets require a specified variable\. After accepting the entered
    information with the OK button, the entry widget data is stored inside the
    defined variables\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-existingdirectory \{\-label "Report directory" __\-variable ReportDir__\}

  - \-default *string*

    Eventual default data for the entry widgets can be provided via the
    *\-default* attribute\. The default value is overridden if an argument
    dialog box with a defined context is called another time\. The value
    acknowledged in a previous call will be used in this case as default value\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-checkbox \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} __\-default italic__\}

  - \-optional __0__&#124;__1__

    Data can be specified as optional or mandatory with the *\-optional*
    attribute that requires either __0__ \(mandatory\) or __1__ \(optional\)
    as attribute data\.

................................................................................
    In case an entry is optional and no data has been entered, e\.g\. the entry
    contains an empty character string, the entry will be considered as
    undefined and the assigned variable will not be defined\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "City" \-variable start\_city \-type string\} \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Street" \-variable start\_street \-type string __\-optional 0__\} \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Street number" \-variable start\_street\_nbr \-type integer __\-optional 1__\} \\

  - \-type *string*

    If the data type is defined with the *\-type* attribute the argument dialog
    box will automatically perform a data type check after acknowledging the
    entered values and before the dialog box is closed\. If a type incompatible
    value is found an error message box appears and the user can correct the
................................................................................
    *tepam::procedure reference manual*\)\.

    Some entry widgets like the file and directory widgets, as well as the color
    and font widgets are specifying automatically the default data type if no
    type has been specified explicitly with the *\-type* attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-entry__ \{\-label "Street number" \-variable start\_street\_nbr __\-type integer__\} \\

  - \-range *string*

    Values can be constrained with the *\-range* attribute\. The valid range is
    defined with a list containing the minimum valid value and a maximum valid
    value\.

    The *\-range* attribute has to be used only for numerical arguments, like
    integers and doubles\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label Month \-variable Month \-type integer __\-range \{1 12\}__\}

  - \-validatecommand *string*

    Custom argument value validations can be performed via specific validation
    commands that are defined with the *\-validatecommand* attribute\. The
    provided validation command can be a complete script in which the pattern
    *%P* is placeholder for the argument value that has to be validated\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-entry \{\-label "Your comment" \-variable YourCom \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-validatecommand__ "IllegalWordDetector %P"\}

    While the purpose of this custom argument validation attribute is the
    validation of a specific argument, there is also a global data validation
    attribute *\-validatecommand* that allows performing validation that
    involves multiple arguments\.

  - \-validatecommand\_error\_text *string*
................................................................................

    Choice lists can directly be defined with the *\-choices* attribute\. This
    way to define choice lists is especially adapted for smaller, fixed
    selection lists\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-listbox \{\-label "Text styles" \-variable Styles \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-choices \{bold italic underline\}__ \-default underline

  - \-choicelabels *string* *\(only check and radio buttons\)*

    If the labels of the check and radio boxes should differ from the option
    values, they can be defined with the *\-choicelabels* attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-checkbox \{\-label "Font sytle" \-variable FontStyle \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-choicelabels \{Bold Italic Underline\}__

  - \-choicevariable *string*

    Another way to define the choice lists is using the *\-choicevariable*
    attribute\. This way to define choice lists is especially adapted for huge
    and eventually variable selection lists\.

> set TextSizes \{8 9 10 12 15 18\}  
> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-combobox \{\-label "Text size" \-variable Size __\-choicevariable TextSizes__\}

  - \-multiple\_selection __0__&#124;__1__

    The list box item \(__\-listbox__\) allows by default selecting only one
    list element\. By setting the *\-multiple\_selection* attribute to __1__,
    multiple elements can be selected\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-listbox \{\-label "Text styles" \-variable Styles \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \-default underline \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-multiple\_selection 1__ \-height 3\}

Some additional attributes are supported by the file and directory selection
widgets\.

  - \-filetypes *string*

    The file type attribute is used by the __\-file__ and
    __\-existingfile__ items to define the file endings that are searched by
    the file browser\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-file \{\-label "Image file" \-variable ImageF \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\}__\}

  - \-initialfile *string*

    The initial file used by the file browsers of the __\-file__ and
    __\-existingfile__ widgets are by default the file defined with the
    *\-default* attribute, unless a file is specified with the *\-initialfile*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-file \{\-variable ImageF __\-initialfile "picture\.gif"__\}

  - \-activedir *string*

    The *\-activedir* attribute will override the default active search
    directory used by the file browsers of all file and directory entry widgets\.
    The default active search directory is defined by the directory of a
    specified initial file \(*\-initialfile*\) if defined, and otherwise by the
    directory of the default file/directory, specified with the *\-default*
    attribute\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-file "\-variable ImageF __\-activedir $pwd__"

Finally, there is a last attribute supported by some widgets:

  - \-height *string*

    All widgets containing a selection list \(__\-listbox__,
    __\-disjointlistbox__, __\-font__\) as well as the multi line
    __\-text__ widget are accepting the *\-height* attribute that defines
    the number of displayed rows of the selection lists\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\-listbox \{\-label "Text size" \-variable Size \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{8 9 10 12 15 18\} \-default 12 __\-height 3__\}

    If the no height has been explicitly specified the height of the widget will
    be dynamically adapted to the argument dialog box size\.

# <a name='section3'></a>APPLICATION SPECIFIC ENTRY WIDGETS

An application specific entry widget can be made available to the argument
................................................................................
> &nbsp;&nbsp;&nbsp;*variable argument\_dialogbox; \# if required*  
> &nbsp;&nbsp;&nbsp;switch $Command \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"create" <CreateCommandSequence>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"set\_choice" <SetChoiceCommandSequence>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"set" <SetCommandv>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"get" <GetCommandSequence>  
> &nbsp;&nbsp;&nbsp;\}  
> \}

__Argument\_dialogbox__ takes care about the *\-label* and *\-text*
attributes for all entry widgets\. For any data entry widget it creates a frame
into which the data entry widget components can be placed\. The path to this
frame is provided via the *W* argument\.

The entry widget procedure has to support 3 mandatory and an optional command

Support for a new document format can be added by defining in the
__tepam::doc\_gen__ namespace a set of procedures that generate the different
document components\.

The following documentation listing contains tokens that refer to the different
document generation procedures:

> &nbsp;*     <01>*  
> &nbsp;*<03> <20s>*   NAME*<20e>*  
> &nbsp;*     <30s>*       message\_box \- Displays text in a message box*<30e>*  
> &nbsp;*     <20s>*   SYNOPSYS*<20e>*  
> &nbsp;*     <40s>*       message\_box \[\-mtype <mtype>\] <text>*<40e>*  
> &nbsp;*     <20s>*   DESCRIPTION*<20e>*  
> &nbsp;*     <21s>     message\_box<21e>*  
> &nbsp;*     <54s>       message\_box \[\-mtype <mtype>\] <text><54e>*  
> &nbsp;*     <50s>*       This procedure allows displaying a text in an message box\. The following  
> &nbsp;*          *       message types are supported:*<50e>*  
> &nbsp;*<51> <53s>*       \* Info*<53e>*  
> &nbsp;*     <53s>*       \* Warning*<53e>*  
> &nbsp;*     <53s>*       \* Error*<53e>*                                           *<52>*  
> &nbsp;*     <50s>*       If the text parameter is use multiple times the different texts are  
> &nbsp;*          *       concatenated to create the message text\.*<50e>*  
> &nbsp;*     <20s>*   ARGUMENTS*<20e>*  
> &nbsp;*<60> <62s>*       \[\-mtype <mtype>\]*<62e>*  
> &nbsp;*<63> <65s>*          Message type*<65e>*  
> &nbsp;*     <66s>*          Default: "Warning"*<66e>*  
> &nbsp;*     <66s>*          Multiple: yes*<66e>*  
> &nbsp;*     <66s>*          Choices: Info, Warning, Error*<66e>*                  *<64>*  
> &nbsp;*     <62s>*       <text>*<62e>*  
> &nbsp;*<63> <65s>*          One or multiple text lines to display*<65e>*  
> &nbsp;*     <66s>*          Type: string*<66e>*  
> &nbsp;*     <66s>*          Multiple: yes*<66e>*                                  *<64><61>*  
> &nbsp;*     <20s>*   EXAMPLE*<20e>*  
> &nbsp;*<70> <72s>*       message\_box "Please save first the document"*<72e>*  
> &nbsp;*     <73s>*       \-> 1*<73e>*                                              *<71><04>*  
> &nbsp;*     <02>*  

There are 2 types of document generation procedures:

  - Content generation procedures \(e\.g\. <40s>\.\.\.<40e>\)

    These procedures generate some document content based on the text that is
    provided as procedure argument\. The listing above shows two tokens for these
................................................................................

      * *IsOptional*

        If true \(=__1__\) the argument is optional which should be indicated
        by the generated string \(for example by putting the argument into
        brackets \{\[\]\} or into question marks '?'\):

            gen(TXT,ArgumentString) mtype 1 0 string ->

        *"\[mtype\]"*

      * *IsNamed*

        If true \(=__1__\) an argument is a named argument \(option\)\. The
        generated string should in this case contain the argument/option name,
        followed by the argument itself:

            gen(TXT,ArgumentString) mtype 0 1 string ->

        *"\-mtype <mtype>"* Named arguments can also be optional:

            gen(TXT,ArgumentString) mtype 1 1 string ->

        *"\[\-mtype <mtype>\]"*

      * *Type*

        Indicates the type of the argument\. If the type is set to __none__
        the argument is a flag, which needs to be indicated by the generated
        string\. Example:

            gen(TXT,ArgumentString) close 1 1 none ->

        *"\[\-close\]"*

# <a name='section5'></a>EXAMPLES

## <a name='subsection5'></a>tepam::doc\_gen::generate

The __TEPAM Doc Gen__ package can be explored by generating the
documentation of the command __tepam::doc\_gen::generate__\. The following
example generates the document in text format \(default format\):

> __tepam::doc\_gen::generate__ tepam::doc\_gen::generate  

The next example generates the documentation in HTML format:

> __tepam::doc\_gen::generate__ \-format HTML tepam::doc\_gen::generate  

The flag ?header\_footer? adds also the file header and footer:

> __tepam::doc\_gen::generate__ \-format HTML \-header\_footer tepam::doc\_gen::generate  

The documentation can directly be stored in a file\. The file header and footer
are automatically generated in this way:

> __tepam::doc\_gen::generate__ \-format HTML \-dest\_file doc\_gen\.html tepam::doc\_gen::generate  

The generated HTML file refers a CSS stylesheet file \(default:
tepam\_doc\_stylesheet\.css\)\. To display the HTML file correctly this CSS
stylesheet file needs to be copied into the directory of the generated HTML
file\.

The Tcl DOC Tools format can be used as intermediate format to generate other
................................................................................
> *\# Create a new doc tools object \(HTML format\)*  
> package require doctools  
> ::doctools::new myDoc \-format html  
> **  
> *\# Open the HTML file, and write the HTML formatted documentation*  
> set fHtml \[open doc\_gen\.dt\.html w\]  
> puts $fHtml \[myDoc format $dt\]  
> close $fHtml  
>   

## <a name='subsection6'></a>tepam::doc\_gen::patch

While __generate__ provides a limited number of possibilities to vary the
document structure, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ offers more
flexibility\. Multiple documentations for different procedures and meta
information can for example be added\.
................................................................................
> __\{\*tepam::doc\_gen::generate\*\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<h2>Patch</h2>  
> __\{\*tepam::doc\_gen::patch\*\}__  
> &nbsp;&nbsp;</body>  
> <html>\\  
> \}  
> **  
> *\# Patch the master document: This will replace the placeholders by the   
> \# procedure documentation divisions:*  

> __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-src\_string $HtmlMasterDoc \-dest\_file tepam\_doc\_gen\.html  
>   

# <a name='seealso'></a>SEE ALSO

[tepam\(n\)](tepam\_introduction\.md),
[tepam::procedure\(n\)](tepam\_procedure\.md)

# <a name='keywords'></a>KEYWORDS

Support for a new document format can be added by defining in the
__tepam::doc\_gen__ namespace a set of procedures that generate the different
document components\.

The following documentation listing contains tokens that refer to the different
document generation procedures:

> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<01>*  
> &nbsp;*<03> <20s>*   NAME*<20e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<30s>*       message\_box \- Displays text in a message box*<30e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<20s>*   SYNOPSYS*<20e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<40s>*       message\_box \[\-mtype <mtype>\] <text>*<40e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<20s>*   DESCRIPTION*<20e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<21s>     message\_box<21e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<54s>       message\_box \[\-mtype <mtype>\] <text><54e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<50s>*       This procedure allows displaying a text in an message box\. The following  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**       message types are supported:*<50e>*  
> &nbsp;*<51> <53s>*       \* Info*<53e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<53s>*       \* Warning*<53e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<53s>*       \* Error*<53e>*                                           *<52>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<50s>*       If the text parameter is use multiple times the different texts are  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**       concatenated to create the message text\.*<50e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<20s>*   ARGUMENTS*<20e>*  
> &nbsp;*<60> <62s>*       \[\-mtype <mtype>\]*<62e>*  
> &nbsp;*<63> <65s>*          Message type*<65e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<66s>*          Default: "Warning"*<66e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<66s>*          Multiple: yes*<66e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<66s>*          Choices: Info, Warning, Error*<66e>*                  *<64>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<62s>*       <text>*<62e>*  
> &nbsp;*<63> <65s>*          One or multiple text lines to display*<65e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<66s>*          Type: string*<66e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<66s>*          Multiple: yes*<66e>*                                  *<64><61>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<20s>*   EXAMPLE*<20e>*  
> &nbsp;*<70> <72s>*       message\_box "Please save first the document"*<72e>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<73s>*       \-> 1*<73e>*                                              *<71><04>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<02>*

There are 2 types of document generation procedures:

  - Content generation procedures \(e\.g\. <40s>\.\.\.<40e>\)

    These procedures generate some document content based on the text that is
    provided as procedure argument\. The listing above shows two tokens for these
................................................................................

      * *IsOptional*

        If true \(=__1__\) the argument is optional which should be indicated
        by the generated string \(for example by putting the argument into
        brackets \{\[\]\} or into question marks '?'\):

> gen\(TXT,ArgumentString\) mtype 1 0 string \-> *"\[mtype\]"*



      * *IsNamed*

        If true \(=__1__\) an argument is a named argument \(option\)\. The
        generated string should in this case contain the argument/option name,
        followed by the argument itself:

> gen\(TXT,ArgumentString\) mtype 0 1 string \-> *"\-mtype <mtype>"*

        Named arguments can also be optional:



> gen\(TXT,ArgumentString\) mtype 1 1 string \-> *"\[\-mtype <mtype>\]"*

      * *Type*

        Indicates the type of the argument\. If the type is set to __none__
        the argument is a flag, which needs to be indicated by the generated
        string\. Example:



> gen\(TXT,ArgumentString\) close 1 1 none \-> *"\[\-close\]"*

# <a name='section5'></a>EXAMPLES

## <a name='subsection5'></a>tepam::doc\_gen::generate

The __TEPAM Doc Gen__ package can be explored by generating the
documentation of the command __tepam::doc\_gen::generate__\. The following
example generates the document in text format \(default format\):

> __tepam::doc\_gen::generate__ tepam::doc\_gen::generate

The next example generates the documentation in HTML format:

> __tepam::doc\_gen::generate__ \-format HTML tepam::doc\_gen::generate

The flag ?header\_footer? adds also the file header and footer:

> __tepam::doc\_gen::generate__ \-format HTML \-header\_footer tepam::doc\_gen::generate

The documentation can directly be stored in a file\. The file header and footer
are automatically generated in this way:

> __tepam::doc\_gen::generate__ \-format HTML \-dest\_file doc\_gen\.html tepam::doc\_gen::generate

The generated HTML file refers a CSS stylesheet file \(default:
tepam\_doc\_stylesheet\.css\)\. To display the HTML file correctly this CSS
stylesheet file needs to be copied into the directory of the generated HTML
file\.

The Tcl DOC Tools format can be used as intermediate format to generate other
................................................................................
> *\# Create a new doc tools object \(HTML format\)*  
> package require doctools  
> ::doctools::new myDoc \-format html  
> **  
> *\# Open the HTML file, and write the HTML formatted documentation*  
> set fHtml \[open doc\_gen\.dt\.html w\]  
> puts $fHtml \[myDoc format $dt\]  
> close $fHtml


## <a name='subsection6'></a>tepam::doc\_gen::patch

While __generate__ provides a limited number of possibilities to vary the
document structure, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ offers more
flexibility\. Multiple documentations for different procedures and meta
information can for example be added\.
................................................................................
> __\{\*tepam::doc\_gen::generate\*\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<h2>Patch</h2>  
> __\{\*tepam::doc\_gen::patch\*\}__  
> &nbsp;&nbsp;</body>  
> <html>\\  
> \}  
> **  
> *\# Patch the master document: This will replace the placeholders by the *  
> *\# procedure documentation divisions:*  
>   
> __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-src\_string $HtmlMasterDoc \-dest\_file tepam\_doc\_gen\.html


# <a name='seealso'></a>SEE ALSO

[tepam\(n\)](tepam\_introduction\.md),
[tepam::procedure\(n\)](tepam\_procedure\.md)

# <a name='keywords'></a>KEYWORDS

>       \{\-fg \-type color \-default black \-description "Message color"\}  
>       \{\-bg \-type color \-optional \-description "Background color"\}  
>       \{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\}  
>       \{\-log\_file \-type file \-optional \-description "Optional message log file"\}  
>       \{text \-type string \-multiple \-description "Multiple text lines to display"\}  
>    \}  
> \} \{  
> *   puts "display message:"  
>    foreach var \{mtype font level fg bg no\_border log\_file text\} \{  
>       if \{\[info exists $var\]\} \{  
>          puts  "  $var=\[set $var\]"  
>       \}  
>    \}  
> *\}  

A call of procedure that has been declared in this way will first invoke the
TEPAM argument manager, before the procedure body is executed\. The argument
manager parses the provided arguments, validates them, completes them eventually
with some default values, and makes them finally available to the procedure body
as local variables\. In case an argument is missing or has a wrong type, the
argument manager generates an error message that explains the reason for the
................................................................................

# <a name='section4'></a>PROCEDURE HELP

The declared procedure can simply be called with the *\-help* option to get the
information about the usage of the procedure and its arguments:

> __display message__ \-help  
>   


* \-> NAME display message \- Displays a simple message box SYNOPSYS display



message \[\-mtype <mtype>\] : Message type, default: "Warning", choices: \{Info

Warning Error\} \[\-font <font>\] : Message text font, type: font, default: Arial 10

italic \[\-level <level>\] : Message level, type: integer, range: 1\.\.10 \[\-fg <fg>\]

: Message color, type: color, default: black \[\-bg <bg>\] : Background color,
type: color \[\-no\_border \] : Use a splash window style \(no border\) \[\-log\_file
<log\_file>\] : Optional message log file, type: file <text> : Multiple text lines
to display, type: string DESCRIPTION This procedure allows displaying a









configurable message box\.*

# <a name='section5'></a>PROCEDURE CALL

The specified procedure can be called in many ways\. The following listing shows
some valid procedure calls:

> __display message__ "The document hasn't yet been saved\!"  
> *\-> display message:  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mtype=Warning  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;font=Arial 10 italic  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fg=black  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;no\_border=0  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;text=\{The document hasn't yet been saved\!\}*  
>   

> __display message__ \-fg red \-bg black "Please save first the document"  
> *\-> display message:  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mtype=Warning  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;font=Arial 10 italic  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fg=red  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bg=black  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;no\_border=0  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;text=\{Please save first the document\}*  
>   

> __display message__ \-mtype Error \-no\_border "Why is here no border?"  
> *\-> display message:  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mtype=Error  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;font=Arial 10 italic  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fg=black  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;no\_border=1  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;text=\{Why is here no border?\}*  

>   
> __display message__ \-font \{Courier 12\} \-level 10 \\  
> &nbsp;&nbsp;&nbsp;"Is there enough space?" "Reduce otherwise the font size\!"  
>   

*\-> display message: mtype=Warning font=Courier 12 level=10 fg=black





no\_border=0 text=\{Is there enough space?\} \{Reduce otherwise the font size\!\}*

The next lines show how wrong arguments are recognized\. The *text* argument
that is mandatory is missing in the first procedure call:

> __display message__ \-font \{Courier 12\}  
>   

* \-> display message: Required argument is missing: text* Only known arguments
are accepted:

> __display message__ \-category warning Hello  

>   

* \-> display message: Argument '\-category' not known* Argument types are
automatically checked and an error message is generated in case the argument
value has not the expected type:

> __display message__ \-fg MyColor "Hello"  

>   

* \-> display message: Argument 'fg' requires type 'color'\. Provided value:
'MyColor'* Selection choices have to be respected \.\.\.

> __display message__ \-mtype Fatal Hello  

>   

* \-> display message: Argument \(mtype\) has to be one of the following elements:
Info, Warning, Error* \.\.\. as well as valid value ranges:

> __display message__ \-level 12 Hello  
>   

* \-> display message: Argument \(level\) has to be between 1 and 10*

# <a name='section6'></a>INTERACTIVE PROCEDURE CALLS

The most intuitive way to call the procedure is using an form that allows
specifying all arguments interactively\. This form will automatically be
generated if the declared procedure is called with the *\-interactive* flag\. To
use this feature the Tk library has to be loaded\.

> __display message__ \-interactive  

The generated form contains for each argument a data entry widget that is
adapted to the argument type\. Check buttons are used to specify flags, radio
boxes for tiny choice lists, disjoint list boxes for larger choice lists and
files, directories, fonts and colors can be selected with dedicated browsers\.

After acknowledging the specified argument data via an OK button, the entered
................................................................................
files and directories\. And finally, the form offers also the possibility to
accept and decline the selection\. Here is the code snippet that is doing all
this:

> __[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\  
> &nbsp;&nbsp;&nbsp;__\-existingfile__ \{\-label "Source file" \-variable SourceFile\} \\  
> &nbsp;&nbsp;&nbsp;__\-existingdirectory__ \{\-label "Destination folder" \-variable DestDir\} \\  
> &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{\-label "Overwrite existing file" \-variable Overwrite\}  

The __argument\_dialogbox__ returns __ok__ if the entered data are
validated\. It will return __cancel__ if the data entry has been canceled\.
After the validation of the entered data, the __argument\_dialogbox__ defines
all the specified variables with the entered data inside the calling context\.

An __argument\_dialogbox__ requires a pair of arguments for each variable
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-file__ \{\-label "Output file" \-variable OutputFile\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-sep__ \{\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-existingdirectory__ \{\-label "Input directory" \-variable InputDirectory\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-directory__ \{\-label "Output irectory" \-variable OutputDirectory\} \\  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\-label "Colors and fonts"\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-color__ \{\-label "Background color" \-variable Color \-default red\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-sep__ \{\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-font__ \{\-label "Font" \-variable Font \-default \{Courier 12 italic\}\}  

\] The __argument\_dialogbox__ defines all the specified variables with the
entered data and returns __ok__ if the data have been validated via the Ok
button\. If the data entry is cancelled by activating the Cancel button, the
__argument\_dialogbox__ returns __cancel__\.

    if {$Result=="cancel"} {
       puts "Canceled"
    } else { # $Result=="ok"
       puts "Arguments: "
       foreach Var {
          Entry1 Entry2
          Listbox1 Listbox2 DisJntListbox
          Combobox Checkbox Radiobox Checkbutton
          InputFile OutputFile InputDirectory OutputDirectory
          Color Font
       } {
          puts "  $Var: '[set $Var]'"
       }
    }




*\-> Arguments: Entry1: 'Hello, this is a trial' Entry2: 'my default' Listbox1:



'1' Listbox2: '\{Choice 2\} \{Choice 3\}' DisJntListbox: '\{Choice 3\} \{Choice 5\}'


Combobox: '3' Checkbox: 'italic' Radiobox: 'underline' Checkbutton: '1'


InputFile: 'c:\\tepam\\in\.txt' OutputFile: 'c:\\tepam\\out\.txt' InputDirectory:

'c:\\tepam\\input' OutputDirectory: 'c:\\tepam\\output' Color: 'red' Font: 'Courier

12 italic'*

# <a name='seealso'></a>SEE ALSO

[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md),
[tepam::procedure\(n\)](tepam\_procedure\.md)

# <a name='keywords'></a>KEYWORDS

>       \{\-fg \-type color \-default black \-description "Message color"\}  
>       \{\-bg \-type color \-optional \-description "Background color"\}  
>       \{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\}  
>       \{\-log\_file \-type file \-optional \-description "Optional message log file"\}  
>       \{text \-type string \-multiple \-description "Multiple text lines to display"\}  
>    \}  
> \} \{  
>    *puts "display message:"*  
>    *foreach var \{mtype font level fg bg no\_border log\_file text\} \{*  
>       *if \{\[info exists $var\]\} \{*  
>          *puts  "  $var=\[set $var\]"*  
>       *\}*  
>    *\}*  
> \}

A call of procedure that has been declared in this way will first invoke the
TEPAM argument manager, before the procedure body is executed\. The argument
manager parses the provided arguments, validates them, completes them eventually
with some default values, and makes them finally available to the procedure body
as local variables\. In case an argument is missing or has a wrong type, the
argument manager generates an error message that explains the reason for the
................................................................................

# <a name='section4'></a>PROCEDURE HELP

The declared procedure can simply be called with the *\-help* option to get the
information about the usage of the procedure and its arguments:

> __display message__ \-help  
> &nbsp;&nbsp;*\->*  

> *NAME*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*display message \- Displays a simple message box*  
> *SYNOPSYS*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*display message*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-mtype <mtype>\] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Message type, default: "Warning", choices: \{Info Warning Error\}*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-font <font>\] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Message text font, type: font, default: Arial 10 italic*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-level <level>\] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Message level, type: integer, range: 1\.\.10*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-fg <fg>\] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Message color, type: color, default: black*  



> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-bg <bg>\] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Background color, type: color*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-no\_border \] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Use a splash window style \(no border\)*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-log\_file <log\_file>\] :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Optional message log file, type: file*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<text> :*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Multiple text lines to display, type: string*  
> *DESCRIPTION*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*This procedure allows displaying a configurable message box\.*

# <a name='section5'></a>PROCEDURE CALL

The specified procedure can be called in many ways\. The following listing shows
some valid procedure calls:

> __display message__ "The document hasn't yet been saved\!"  
> *\-> display message:*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*mtype=Warning*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*font=Arial 10 italic*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*fg=black*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*no\_border=0*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*text=\{The document hasn't yet been saved\!\}*  
>   
>   
> __display message__ \-fg red \-bg black "Please save first the document"  
> *\-> display message:*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*mtype=Warning*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*font=Arial 10 italic*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*fg=red*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*bg=black*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*no\_border=0*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*text=\{Please save first the document\}*  
>   
>   
> __display message__ \-mtype Error \-no\_border "Why is here no border?"  
> *\-> display message:*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*mtype=Error*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*font=Arial 10 italic*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*fg=black*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*no\_border=1*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*text=\{Why is here no border?\}*  
>   
>   
> __display message__ \-font \{Courier 12\} \-level 10 \\  
> &nbsp;&nbsp;&nbsp;"Is there enough space?" "Reduce otherwise the font size\!"  


> *\-> display message:*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*mtype=Warning*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*font=Courier 12*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*level=10*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*fg=black*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*no\_border=0*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*text=\{Is there enough space?\} \{Reduce otherwise the font size\!\}*

The next lines show how wrong arguments are recognized\. The *text* argument
that is mandatory is missing in the first procedure call:

> __display message__ \-font \{Courier 12\}  
> &nbsp;&nbsp;*\-> display message: Required argument is missing: text*


Only known arguments are accepted:

> __display message__ \-category warning Hello  
> &nbsp;&nbsp;*\-> display message: Argument '\-category' not known*



Argument types are automatically checked and an error message is generated in
case the argument value has not the expected type:

> __display message__ \-fg MyColor "Hello"  
> &nbsp;&nbsp;*\-> display message: Argument 'fg' requires type 'color'\.  Provided value: 'MyColor'*



Selection choices have to be respected \.\.\.

> __display message__ \-mtype Fatal Hello  
> &nbsp;&nbsp;*\-> display message: Argument \(mtype\) has to be one of the  following elements: Info, Warning, Error*



\.\.\. as well as valid value ranges:

> __display message__ \-level 12 Hello  


> &nbsp;&nbsp;*\-> display message: Argument \(level\) has to be between 1 and 10*

# <a name='section6'></a>INTERACTIVE PROCEDURE CALLS

The most intuitive way to call the procedure is using an form that allows
specifying all arguments interactively\. This form will automatically be
generated if the declared procedure is called with the *\-interactive* flag\. To
use this feature the Tk library has to be loaded\.

> __display message__ \-interactive

The generated form contains for each argument a data entry widget that is
adapted to the argument type\. Check buttons are used to specify flags, radio
boxes for tiny choice lists, disjoint list boxes for larger choice lists and
files, directories, fonts and colors can be selected with dedicated browsers\.

After acknowledging the specified argument data via an OK button, the entered
................................................................................
files and directories\. And finally, the form offers also the possibility to
accept and decline the selection\. Here is the code snippet that is doing all
this:

> __[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\  
> &nbsp;&nbsp;&nbsp;__\-existingfile__ \{\-label "Source file" \-variable SourceFile\} \\  
> &nbsp;&nbsp;&nbsp;__\-existingdirectory__ \{\-label "Destination folder" \-variable DestDir\} \\  
> &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{\-label "Overwrite existing file" \-variable Overwrite\}

The __argument\_dialogbox__ returns __ok__ if the entered data are
validated\. It will return __cancel__ if the data entry has been canceled\.
After the validation of the entered data, the __argument\_dialogbox__ defines
all the specified variables with the entered data inside the calling context\.

An __argument\_dialogbox__ requires a pair of arguments for each variable
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-file__ \{\-label "Output file" \-variable OutputFile\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-sep__ \{\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-existingdirectory__ \{\-label "Input directory" \-variable InputDirectory\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-directory__ \{\-label "Output irectory" \-variable OutputDirectory\} \\  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\-label "Colors and fonts"\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-color__ \{\-label "Background color" \-variable Color \-default red\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-sep__ \{\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-font__ \{\-label "Font" \-variable Font \-default \{Courier 12 italic\}\}\]

The __argument\_dialogbox__ defines all the specified variables with the
entered data and returns __ok__ if the data have been validated via the Ok
button\. If the data entry is cancelled by activating the Cancel button, the
__argument\_dialogbox__ returns __cancel__\.

> if \{$Result=="cancel"\} \{  
> &nbsp;&nbsp;&nbsp;puts "Canceled"  
> \} else \{ \# $Result=="ok"  
> &nbsp;&nbsp;&nbsp;puts "Arguments: "  
> &nbsp;&nbsp;&nbsp;foreach Var \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Entry1 Entry2  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Listbox1 Listbox2 DisJntListbox  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Combobox Checkbox Radiobox Checkbutton  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;InputFile OutputFile InputDirectory OutputDirectory  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Color Font  
> &nbsp;&nbsp;&nbsp;\} \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;puts "  $Var: '\[set $Var\]'"  



> &nbsp;&nbsp;&nbsp;\}  
> \}  
> *\-> Arguments:*  
> &nbsp;&nbsp;&nbsp;*Entry1: 'Hello, this is a trial'*  
> &nbsp;&nbsp;&nbsp;*Entry2: 'my default'*  
> &nbsp;&nbsp;&nbsp;*Listbox1: '1'*  
> &nbsp;&nbsp;&nbsp;*Listbox2: '\{Choice 2\} \{Choice 3\}'*  
> &nbsp;&nbsp;&nbsp;*DisJntListbox: '\{Choice 3\} \{Choice 5\}'*  
> &nbsp;&nbsp;&nbsp;*Combobox: '3'*  
> &nbsp;&nbsp;&nbsp;*Checkbox: 'italic'*  
> &nbsp;&nbsp;&nbsp;*Radiobox: 'underline'*  
> &nbsp;&nbsp;&nbsp;*Checkbutton: '1'*  
> &nbsp;&nbsp;&nbsp;*InputFile: 'c:\\tepam\\in\.txt'*  
> &nbsp;&nbsp;&nbsp;*OutputFile: 'c:\\tepam\\out\.txt'*  
> &nbsp;&nbsp;&nbsp;*InputDirectory: 'c:\\tepam\\input'*  
> &nbsp;&nbsp;&nbsp;*OutputDirectory: 'c:\\tepam\\output'*  
> &nbsp;&nbsp;&nbsp;*Color: 'red'*  
> &nbsp;&nbsp;&nbsp;*Font: 'Courier 12 italic'*

# <a name='seealso'></a>SEE ALSO

[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md),
[tepam::procedure\(n\)](tepam\_procedure\.md)

# <a name='keywords'></a>KEYWORDS

    The __string__ command is an example of such a command that implements
    for example subcommands to check a character string length, to compare
    strings, to extract substrings, etc:

    > __string length__ *string*  
    > __string compare__ *string* *string*  
    > __string range__ *string* *first* *last*  
    > \.\.\.  

    TEPAM provides a framework that allows implementing easily such subcommands
    in form of Tcl procedures\. It allows not only defining a first level of
    subcommands, but also a higher level of subcommands\. The __string__
    command class check could be implemented as independent sub\-sub\-commands of
    the __string__ command:

    > __string is alnum__ *string*  
    > __string is integer__ *string*  
    > __string is double__ *string*  
    > \.\.\.  

  - *Procedure attribute*

    TEPAM allows attaching to a declared procedure different kind of attributes\.
    Some of these attributes are *just* used for documentation purposes, but
    other attributes specify the way how the procedure has to be called\. Also
    the procedure arguments are defined in form of a procedure attribute\.
................................................................................
  - *Argument*

    TEPAM uses the term *argument* for the parameters of a procedure\.

    The following example calls the subcommand __string compare__ with
    several arguments:

    > __string compare__   

    *\-nocase \-length 3 "emphasized" "emphasised"* The following paragraphs
    discuss these different argument types\.

  - *Named argument*

    Some parameters, as *\-length 3* of the subcommand __string compare__
    have to be provided as pairs of argument names and argument values\. This
    parameter type is often also called *option*\.

................................................................................

  - *Named arguments first, unnamed arguments later*

    The __string compare__ command of the previous example requires that the
    *named arguments* \(options, flags\) are provided first\. The two mandatory
    \(unnamed\) arguments have to be provided as last argument\.

    > __string compare__   

    *\-nocase \-length 3 Water $Text* This is the usual Tcl style \(exceptions
    exist\) which is referred in the TEPAM documentation as *named arguments
    first, unnamed arguments later style*\.

  - *Unnamed arguments first, named arguments later*

    In contrast to most Tcl commands, Tk uses generally \(exceptions exist also
    here\) a different calling style where the *unnamed arguments* have to be
    provided first, before the *named arguments* have to be provided:

    > __pack__   

    *\.ent1 \.ent2 \-fill x \-expand yes \-side left* This style is referred in the
    TEPAM documentation as *unnamed arguments first, named arguments later
    style*\.

# <a name='section3'></a>PROCEDURE DECLARATION

TEPAM allows declaring new Tcl procedures with the command
__tepam::procedure__ that has similar to the standard Tcl command
__proc__ also 3 arguments:

................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default Warning \-description "Message type"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text   \-type string \-multiple \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-description "Multiple text lines to display"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "Message type: $mtype"  
> &nbsp;&nbsp;&nbsp;puts "Message: $text"  
> \}  

The 3 arguments of __procedure__ are:

  - *name*

    The procedure name can be used in very flexible ways\. Procedure names can
    have namespace qualifiers\. By providing a two element name list as procedure
................................................................................
> *\# Procedure declared in the main namespace:*  
> tepam::procedure __::display\_message__ \{\} \{\}  
> **  
> *\# Procedure in the namespace* __::ns__*:*  
> tepam::procedure __::ns::display\_message__ \{\} \{\}  
> **  
> *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:*  
> tepam::procedure __\{display message\}__ \{\} \{\}  

  - *attributes*

    All procedure attributes are provided in form of an option list that
    contains pairs of option names and option values\. The example above has as
    procedure attribute a short and a normal description, but also the procedure
    arguments are defined in form of a procedure attribute\.
................................................................................
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-__mtype__ \-default Warning \-choices \{Warning Error\}\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{__text__ \-type string\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "Message type: __$mtype__"  
> &nbsp;&nbsp;&nbsp;puts "Message: __$text__"  
> \}  

The commands __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ as well as
__argument\_dialogbox__ are exported from the namespace __tepam__\. To use
these commands without the __tepam::__ namespace prefix, it is sufficient to
import them into the main namespace:

> __namespace import tepam::\*__  
>   
> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\.\.\.  

## <a name='subsection1'></a>Procedure Attributes

The first group of attributes affect the behavior of the declared procedure:

  - \-named\_arguments\_first __0__&#124;__1__

................................................................................
    Validation command declaration example:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-description "Message text"\} \}  
> &nbsp;&nbsp;&nbsp;__\-validatecommand \{IllegalWordDetector $text\}__  
> \} \{  
> \}  

    The validation command is executed in the context of the declared procedure
    body\. The different argument values are accessed via the argument names\.
    Note there is also an argument attribute *\-validatecommand* that allows
    declaring custom checks for specific arguments\.

    The attribute *\-validatecommand* can be repeated to declare multiple
................................................................................

## <a name='subsection2'></a>Argument Declaration

The following example shows the structure that is used for the argument
definitions in the context of a procedure declaration:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args __\{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-fg \-type color \-optional \-description "Message color"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-log\_file \-type file \-optional \-description "Optional message log file"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-multiple \-description "Multiple text lines to display"\}  
> &nbsp;&nbsp;&nbsp;\}__  

> \} \{  
> \}  

Each of the procedure arguments is declared with a list that has as first
element the argument name, followed by eventual attributes\. The argument
definition syntax can be formalized in the following way:

> tepam::procedure <name> \{  
> &nbsp;&nbsp;&nbsp;\-args __\{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a>  <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a>  <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;\}__  

> \} <body>  

The argument names and attributes have to be used in the following way:

  - Argument name \(*<argument\_name\_<n>>*\)

    The provided argument name specifies whether the argument is an *unnamed
    argument* or a *named argument*\. In addition to this, an argument name
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts __$text__  
> \}  
>   
> print\_string __"Hello"__  
>   

        * \-> Hello*

      * *"\-<Name>"*

        An argument whose name starts with '\-' is a *named argument* \(also
        called *option*\)\. The parameter provided during a procedure call will
        be assigned to a variable with the name *<Name>* \(not *\-<Name>*\)\.

................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{__\-text__ \-type string \-description "This is a named argument"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts __$text__  
> \}  
>   
> print\_string __\-text "Hello"__  
>   

        * \-> Hello*

      * *"\-\-"*

        This flag allows clearly specifying the end of the named arguments and
        the beginning of the unnamed arguments, in case the *named arguments
        first, unnamed arguments later style \(Tcl\)* has been selected\.

................................................................................
>   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\- The following arguments are optional:\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{seconds \-type integer \-default 0 \-description "Seconds"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{milliseconds \-type integer \-default 0 \-description "Milliseconds"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "$\{hour\}h$\{minutes\}:\[expr $seconds\+0\.001\*$milliseconds\]"  
> \}  

        Argument comments are basically used in the graphical argument
        definition forms that are created if a procedure is called
        interactively\.

      * *"\#\*"*

................................................................................
>   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\#\#\#\# Second complex number \#\#\#\#\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-r1 \-type double \-description "Second number real part"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-i1 \-type double \-description "Second number imaginary part"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;return \[expr $r0\*$r1 \- $i0\*$i1\]  
> \}  

  - Argument attributes \(*<arg\_attr\_name\_<mn>> <arg\_attr\_value\_<mn>>*\)

    The following argument attributes are supported:

      * \-description *string*

................................................................................
        Validation command declaration example:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-description "Message text" \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-validatecommand \{IllegalWordDetector %P\}__\}  
> \} \{  
> \}  

        While the purpose of this custom argument validation attribute is the
        validation of a specific argument, there is also a global attribute
        *\-validatecommand* that allows performing validation that involves
        multiple arguments\.

      * \-validatecommand\_error\_text *string*
................................................................................

> tepam::procedure LoadPicture \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{FileName \-type existingfile \-description "Picture file" \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> \}  

      * \-auxargs\_commands *script*

        If the auxiliary argument attributes are not static but have to be
        dynamically adaptable, the *\-auxargs\_commands* allows defining them
        via commands that are executed during a procedure call\. A list of pairs
        of auxiliary attribute names and commands has to be provided to the
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-font __\-type font__ \-default \{Arial 10 italic\}\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-fg __\-type color__ \-optional \-description "Message color"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text __\-type string__ \-multiple \-description "Multiple text lines to display"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> \}  

There are some *special purpose types* that are building the first category of
predefined argument types:

  - __none__ A *flag*, also called *switch*, is defined as a named
    argument that has the type __none__\. Flags are always optional and the
    default value of the assigned variable is set to __0__\. In contrast to
................................................................................
> &nbsp;&nbsp;&nbsp;puts __$flag__  
> \}  
>   
> flag\_test  
> *\-> 0*  
>   
> flag\_test \-flag  
>   

    *\-> 1*

    Since no argument value has to be provided to a flag, also no data check is
    performed for this argument type\.

  - __string__ __String__ is a generic argument data type\. Any data
    string can be provided to a string type argument and no data type checks are
    therefore performed\. The string type allows defining single line strings
................................................................................

Several *numerical types* are defined by TEPAM\. The type validation procedures
are using the __string is <type> \-strict__ commands to check the validity of
the provided arguments, which assures that no empty strings are accepted as
argument value\. The type validation expression for the numerical types and the
argument types to which this expression is applied are:

> string is __<type\_to\_check>__ \-strict   

*<argument\_value>*

  - *boolean*

  - *integer*

  - *double*

Empty strings are accepted as argument value for all the alpha numeric argument
types\. The argument types that are falling into this category and validation
expression used for them are:

> string is *<type\_to\_check>*   

*<argument\_value>*

  - *alnum*

  - *alpha*

  - *ascii*

................................................................................

In addition to the data types checked with the __string is <type>__
commands, TEPAM specifies some other useful data types:

  - *char* Each string that has a length of 1 character meets the
    *character* type\. The type check is made with the following expression:

> expr \[string length *<argument\_value>*\]==1  

  - *color* Any character strings that are accepted by Tk as a color are
    considered as valid color argument\. Please note that the Tk package has to
    be loaded to use the type *color*\. TEPAM is using the following command to
    validate the color type:

> expr \!\[catch \{winfo rgb \. *<argument\_value>*\}  

    \]

  - *font* Any character strings that are accepted by Tk as a font are
    considered as valid font argument\. Please note that the Tk package has to be
    loaded to use the *font* type\. TEPAM is using the following command to
    validate the color type:

        expr ![catch {font measure <argument_value> ""}

    \]

  - *file* Any strings that are not containing one of the following characters
    are considered as valid file names: \* ? " < >\. It is not necessary that the
    file and its containing directory exist\. Zero\-length strings are not
    considered as valid file names\.

    The following expression is used to validate the file names:

        expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>

    \]

  - *existingfile* The argument is valid if it matches with an existing file\.
    The following check is performed to validate the arguments of this type:

        file exists <argument_value>

  - *directory* The directory argument is validated exactly in the same way as
................................................................................
print a generated help text to *stdout* and will then return without
performing any additional actions\.

Taking the first procedure declared in [PROCEDURE CALLS](#section6), the
help request and the printed help text would be:

> __display message \-help__  
>   


*\-> NAME display message \- Displays a simple message box SYNOPSIS display



message \[\-mtype <mtype>\] Message type, default: "Warning", choices: \{Info,

Warning, Error\} <text> Multiple text lines to display, type: string DESCRIPTION

This procedure allows displaying a configurable message box\. The default message
type that is created is a warning, but also errors and info can be generated\.

The procedure accepts multiple text lines\. EXAMPLE display message \-mtype



Warning "Save first your job"* The argument manager is checking if the last
provided argument is *\-help* and generates the requested help message if this
is the case\. So, also the following example will print the help message:

__display message \-mtype Info "It is 7:00" \-help__ On the other hand, the

following call will result in an error:

> __display message \-help \-mtype Info "It is 7:00"__  
>   


*\-> display message: Argument '\-help' not known*

## <a name='subsection6'></a>Interactive Procedure Call

If Tk has been loaded a procedure can be called with the *\-interactive* flag
to open a graphical form that allows specifying interactively all procedure
arguments\. The following example assures that the Tk library is loaded and shows
the command line to call interactively the procedure declared in [PROCEDURE
CALLS](#section6):

    package require Tk


__display message \-interactive__ Also the *\-interactive* flag has to be
placed at the last argument position as this is also required for the *\-help*
flag\. Arguments defined before the *\-interactive* flag will be ignored\. The
following example is therefore also a valid interactive procedure call:

> __display message__ \-mtype Info "It is 7:00"   

__\-interactive__

## <a name='subsection7'></a>Unnamed Arguments

Unnamed arguments are typically provided to the called procedure as simple
parameters\. This procedure calling form requires that the provided arguments are
strictly following the order of the specified arguments\. Several parameters can
be assigned to the last argument if this one has the *\-multiple* attribute\.
................................................................................

\.\.\. can for example be called in the following ways:

> __display\_message Info "It is PM 7:00\."__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message Info "It is PM 7:00\." "You should go home\."__  
>   

*\-> Info: It is PM 7:00\. You should go home\.* The nice thing is that unnamed
arguments can also be called as named arguments, which can be handy, for example
if the exact specified argument order is not known to a user:


> __display\_message \-mtype Info \-text "It is PM 7:00\."__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message \-text "It is PM 7:00\." \-mtype Info__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__  
> *\-> Info: It is PM 7:00\. You should go home\.*  
>   
> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__  
>   

*\-> Info: It is PM 7:00\. You should go home\.*

## <a name='subsection8'></a>Named Arguments

Named arguments have to be provided to a procedure in form of a parameter pairs
composed by the argument names and the argument values\. The order how they are
provided during a procedure call is irrelevant and has not to match with the
argument specification order\.
................................................................................
> __display\_message \-text "It is PM 7:00\." \-mtype Info__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__  
> *\-> Info: It is PM 7:00\. You should go home\.*  
>   
> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__  
>   

*\-> Info: It is PM 7:00\. You should go home\.* Also named arguments that have
not the *\-multiple* attribute can be provided multiple times\. Only the last
provided argument will be retained in such a case:

> __display\_message \-mtype Info \-text "It is PM 7:00\." \-mtype Warning__  
>   

*\-> Warning: It is PM 7:00\.*

## <a name='subsection9'></a>Unnamed Arguments First, Named Arguments Later \(Tk Style\)

A procedure that has been defined while the variable
__tepam::named\_arguments\_first__ was set to 1, or with the procedure
attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\.
The following procedure declaration will be used in this section to illustrate
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n1 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n2 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u1 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u2 \-default ""\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"  
> \}  

The unnamed arguments are placed at the end of procedure call, after the named
arguments:

> my\_proc __\-n1 N1 \-n2 N2 U1 U2__  
>   

*\-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'* The argument parser considers the
first argument that doesn't start with the '\-' character as well as all
following arguments as unnamed argument:

> my\_proc __U1 U2__  

>   

*\-> n1:'', n2:'', u1:'U1', u2:'U2'* Named arguments can be defined multiple
times\. If the named argument has the *\-multiply* attribute, all argument
values will be collected in a list\. Otherwise, only the last provided attribute
value will be retained:

> my\_proc __\-n1 N1 \-n2 N2 \-n1 M1 U1 U2__  

>   

*\-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'* The name of the first unnamed argument
has therefore not to start with the '\-' character\. The unnamed argument is
otherwise considered as name of another named argument\. This is especially
important if the first unnamed argument is given by a variable that can contain
any character strings:

> my\_proc __\-n1 N1 \-n2 N2 "\->" "<\-"__  
> *\-> my\_proc: Argument '\->' not known*  
>   
> set U1 "\->"  
> my\_proc __\-n1 N1 \-n2 N2 $U1 U2__  
> my\_proc: Argument '\->' not known  

The '\-\-' flag allows separating unambiguously the unnamed arguments from the
named arguments\. All data after the '\-\-' flag will be considered as unnamed
argument:

> my\_proc __\-n1 N1 \-n2 N2 \-\- "\->" "<\-"__  
> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'*  
>   
> set U1 "\->"  
> my\_proc __\-n1 N1 \-n2 N2 \-\- $U1 U2__  
>   

*\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'*

## <a name='subsection10'></a>Named Arguments First, Unnamed Arguments Later \(Tcl Style\)

The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute
*\-named\_arguments\_first* has been set to 0\. The following procedure will be
used in this section to illustrate this calling style:
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n1 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n2 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u1\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u2 \-default "" \-multiple\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"  
> \}  

The unnamed arguments have to be provided first in this case\. The named
arguments are provided afterwards:

> my\_proc __U1 U2 \-n1 N1 \-n2 N2__  
>   

*\-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* The argument parser will assign to
each defined unnamed argument a value before it switches to read the named
arguments\. This default behavior changes a bit if there are unnamed arguments
that are optional or that can take multiple values\.

An argument value will only be assigned to an unnamed argument that is optional
\(that has either the *\-optional* attribute or that has a default value\), if
the value is not beginning with the '\-' character or if no named arguments are
defined\. The value that starts with '\-' is otherwise considered as the name of a
named argument\.

................................................................................
separating unambiguously the named arguments from the unnamed ones with the '\-\-'
flag\.

Let's explore in a bit less theoretically the ways how the previously defined
procedure can be called: The first example calls the procedure without any
parameters, which leads to an error since *u1* is a mandatory argument:

    my_proc


*\-> my\_proc: Required argument is missing: u1* The procedure call is valid if
one parameter is provided for *u1*:

> my\_proc __U1__  
>   

*\-> n1:'', n2:'', u1:'U1', u2:''* If more parameters are provided that are not
starting with the '\-' character, they will be attributed to the unnamed
arguments\. *U2* will receive 3 of these parameters, since it accepts multiple
values:

> my\_proc __U1 U2 U3 U4__  

>   

*\-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'* As soon as one parameter starts with
'\-' and all unnamed arguments have been assigned, the argument manager tries to
interpret the parameter as name of a named argument\. The procedure call will
fail if a value beginning with '\-' is assigned to an unnamed argument:

> my\_proc __U1 U2 U3 U4 \-U5__  

>   

*\-> my\_proc: Argument '\-U5' not known* The attribution of a parameter to a
named argument will fail if there are undefined unnamed \(non optional\)
arguments\. The name specification will in this case simply be considered as a
parameter value that is attributed to the *next* unnamed argument\. This was
certainly not the intention in the following example:


> my\_proc __\-n1 N1__  

>   

*\-> n1:'', n2:'', u1:'\-n1', u2:'N1'* The situation is completely different if
values have already been assigned to all mandatory unnamed arguments\. A
parameter beginning with the '\-' character will in this case be considered as a
name identifier for a named argument:

> my\_proc __U1 \-n1 N1__  

>   

*\-> n1:'N1', n2:'', u1:'U1', u2:''* No unnamed arguments are allowed behind
the named arguments:

> my\_proc __U1 \-n1 N1 U2__  

>   

*\-> my\_proc: Argument 'U2' is not an option* The '\-\-' flag has no special
meaning if not all mandatory arguments have got assigned a value\. This flag will
simply be attributed to one of the unnamed arguments:


> my\_proc __\-\- \-n1 N1__  

>   

*\-> n1:'N1', n2:'', u1:'\-\-', u2:''* But the '\-\-' flag is simply ignored if the
argument parser has started to handle the named arguments:

> my\_proc __U1 \-\- \-n1 N1__  
> *\-> n1:'N1', n2:'', u1:'U1', u2:''*  
>   
> my\_proc __U1 \-n1 N1 \-\- \-n2 N2__  
>   

*\-> n1:'N1', n2:'N2', u1:'U1', u2:''*

## <a name='subsection11'></a>Raw Argument List

It may be necessary sometimes that the procedure body is able to access the
entire list of arguments provided during a procedure call\. This can happen via
the __args__ variable that contains always the unprocessed argument list:

................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-multiple\}  
>   
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "args: __$args__"  
> \}  
> display\_message \-mtype Warning "It is 7:00"  
>   

*\-> args: \-mtype Warning \{It is 7:00\}*

# <a name='seealso'></a>SEE ALSO

[tepam\(n\)](tepam\_introduction\.md),
[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md)

# <a name='keywords'></a>KEYWORDS

    The __string__ command is an example of such a command that implements
    for example subcommands to check a character string length, to compare
    strings, to extract substrings, etc:

    > __string length__ *string*  
    > __string compare__ *string* *string*  
    > __string range__ *string* *first* *last*  
    > \.\.\.

    TEPAM provides a framework that allows implementing easily such subcommands
    in form of Tcl procedures\. It allows not only defining a first level of
    subcommands, but also a higher level of subcommands\. The __string__
    command class check could be implemented as independent sub\-sub\-commands of
    the __string__ command:

    > __string is alnum__ *string*  
    > __string is integer__ *string*  
    > __string is double__ *string*  
    > \.\.\.

  - *Procedure attribute*

    TEPAM allows attaching to a declared procedure different kind of attributes\.
    Some of these attributes are *just* used for documentation purposes, but
    other attributes specify the way how the procedure has to be called\. Also
    the procedure arguments are defined in form of a procedure attribute\.
................................................................................
  - *Argument*

    TEPAM uses the term *argument* for the parameters of a procedure\.

    The following example calls the subcommand __string compare__ with
    several arguments:

    > __string compare__ *\-nocase \-length 3 "emphasized" "emphasised"*


    The following paragraphs discuss these different argument types\.

  - *Named argument*

    Some parameters, as *\-length 3* of the subcommand __string compare__
    have to be provided as pairs of argument names and argument values\. This
    parameter type is often also called *option*\.

................................................................................

  - *Named arguments first, unnamed arguments later*

    The __string compare__ command of the previous example requires that the
    *named arguments* \(options, flags\) are provided first\. The two mandatory
    \(unnamed\) arguments have to be provided as last argument\.

    > __string compare__ *\-nocase \-length 3 Water $Text*

    This is the usual Tcl style \(exceptions exist\) which is referred in the
    TEPAM documentation as *named arguments first, unnamed arguments later
    style*\.

  - *Unnamed arguments first, named arguments later*

    In contrast to most Tcl commands, Tk uses generally \(exceptions exist also
    here\) a different calling style where the *unnamed arguments* have to be
    provided first, before the *named arguments* have to be provided:

    > __pack__ *\.ent1 \.ent2 \-fill x \-expand yes \-side left*

    This style is referred in the TEPAM documentation as *unnamed arguments
    first, named arguments later style*\.


# <a name='section3'></a>PROCEDURE DECLARATION

TEPAM allows declaring new Tcl procedures with the command
__tepam::procedure__ that has similar to the standard Tcl command
__proc__ also 3 arguments:

................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default Warning \-description "Message type"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text   \-type string \-multiple \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-description "Multiple text lines to display"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "Message type: $mtype"  
> &nbsp;&nbsp;&nbsp;puts "Message: $text"  
> \}

The 3 arguments of __procedure__ are:

  - *name*

    The procedure name can be used in very flexible ways\. Procedure names can
    have namespace qualifiers\. By providing a two element name list as procedure
................................................................................
> *\# Procedure declared in the main namespace:*  
> tepam::procedure __::display\_message__ \{\} \{\}  
> **  
> *\# Procedure in the namespace* __::ns__*:*  
> tepam::procedure __::ns::display\_message__ \{\} \{\}  
> **  
> *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:*  
> tepam::procedure __\{display message\}__ \{\} \{\}

  - *attributes*

    All procedure attributes are provided in form of an option list that
    contains pairs of option names and option values\. The example above has as
    procedure attribute a short and a normal description, but also the procedure
    arguments are defined in form of a procedure attribute\.
................................................................................
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-__mtype__ \-default Warning \-choices \{Warning Error\}\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{__text__ \-type string\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "Message type: __$mtype__"  
> &nbsp;&nbsp;&nbsp;puts "Message: __$text__"  
> \}

The commands __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ as well as
__argument\_dialogbox__ are exported from the namespace __tepam__\. To use
these commands without the __tepam::__ namespace prefix, it is sufficient to
import them into the main namespace:

> __namespace import tepam::\*__  
>   
> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\.\.\.

## <a name='subsection1'></a>Procedure Attributes

The first group of attributes affect the behavior of the declared procedure:

  - \-named\_arguments\_first __0__&#124;__1__

................................................................................
    Validation command declaration example:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-description "Message text"\} \}  
> &nbsp;&nbsp;&nbsp;__\-validatecommand \{IllegalWordDetector $text\}__  
> \} \{  
> \}

    The validation command is executed in the context of the declared procedure
    body\. The different argument values are accessed via the argument names\.
    Note there is also an argument attribute *\-validatecommand* that allows
    declaring custom checks for specific arguments\.

    The attribute *\-validatecommand* can be repeated to declare multiple
................................................................................

## <a name='subsection2'></a>Argument Declaration

The following example shows the structure that is used for the argument
definitions in the context of a procedure declaration:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args __\{__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\-fg \-type color \-optional \-description "Message color"\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\-log\_file \-type file \-optional \-description "Optional message log file"\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{text \-type string \-multiple \-description "Multiple text lines to display"\}__  
> &nbsp;&nbsp;&nbsp;__\}__  
>   
> \} \{  
> \}

Each of the procedure arguments is declared with a list that has as first
element the argument name, followed by eventual attributes\. The argument
definition syntax can be formalized in the following way:

> tepam::procedure <name> \{  
> &nbsp;&nbsp;&nbsp;\-args __\{__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a>  <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a>  <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\.\.\.__  
> &nbsp;&nbsp;&nbsp;__\}__  
>   
> \} <body>

The argument names and attributes have to be used in the following way:

  - Argument name \(*<argument\_name\_<n>>*\)

    The provided argument name specifies whether the argument is an *unnamed
    argument* or a *named argument*\. In addition to this, an argument name
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts __$text__  
> \}  
>   
> print\_string __"Hello"__  


> &nbsp;*\-> Hello*

      * *"\-<Name>"*

        An argument whose name starts with '\-' is a *named argument* \(also
        called *option*\)\. The parameter provided during a procedure call will
        be assigned to a variable with the name *<Name>* \(not *\-<Name>*\)\.

................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{__\-text__ \-type string \-description "This is a named argument"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts __$text__  
> \}  
>   
> print\_string __\-text "Hello"__  


> &nbsp;*\-> Hello*

      * *"\-\-"*

        This flag allows clearly specifying the end of the named arguments and
        the beginning of the unnamed arguments, in case the *named arguments
        first, unnamed arguments later style \(Tcl\)* has been selected\.

................................................................................
>   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\- The following arguments are optional:\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{seconds \-type integer \-default 0 \-description "Seconds"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{milliseconds \-type integer \-default 0 \-description "Milliseconds"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "$\{hour\}h$\{minutes\}:\[expr $seconds\+0\.001\*$milliseconds\]"  
> \}

        Argument comments are basically used in the graphical argument
        definition forms that are created if a procedure is called
        interactively\.

      * *"\#\*"*

................................................................................
>   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\#\#\#\# Second complex number \#\#\#\#\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-r1 \-type double \-description "Second number real part"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-i1 \-type double \-description "Second number imaginary part"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;return \[expr $r0\*$r1 \- $i0\*$i1\]  
> \}

  - Argument attributes \(*<arg\_attr\_name\_<mn>> <arg\_attr\_value\_<mn>>*\)

    The following argument attributes are supported:

      * \-description *string*

................................................................................
        Validation command declaration example:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-description "Message text" \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-validatecommand \{IllegalWordDetector %P\}__\}  
> \} \{  
> \}

        While the purpose of this custom argument validation attribute is the
        validation of a specific argument, there is also a global attribute
        *\-validatecommand* that allows performing validation that involves
        multiple arguments\.

      * \-validatecommand\_error\_text *string*
................................................................................

> tepam::procedure LoadPicture \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{FileName \-type existingfile \-description "Picture file" \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> \}

      * \-auxargs\_commands *script*

        If the auxiliary argument attributes are not static but have to be
        dynamically adaptable, the *\-auxargs\_commands* allows defining them
        via commands that are executed during a procedure call\. A list of pairs
        of auxiliary attribute names and commands has to be provided to the
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-font __\-type font__ \-default \{Arial 10 italic\}\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-fg __\-type color__ \-optional \-description "Message color"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text __\-type string__ \-multiple \-description "Multiple text lines to display"\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> \}

There are some *special purpose types* that are building the first category of
predefined argument types:

  - __none__ A *flag*, also called *switch*, is defined as a named
    argument that has the type __none__\. Flags are always optional and the
    default value of the assigned variable is set to __0__\. In contrast to
................................................................................
> &nbsp;&nbsp;&nbsp;puts __$flag__  
> \}  
>   
> flag\_test  
> *\-> 0*  
>   
> flag\_test \-flag  


> *\-> 1*

    Since no argument value has to be provided to a flag, also no data check is
    performed for this argument type\.

  - __string__ __String__ is a generic argument data type\. Any data
    string can be provided to a string type argument and no data type checks are
    therefore performed\. The string type allows defining single line strings
................................................................................

Several *numerical types* are defined by TEPAM\. The type validation procedures
are using the __string is <type> \-strict__ commands to check the validity of
the provided arguments, which assures that no empty strings are accepted as
argument value\. The type validation expression for the numerical types and the
argument types to which this expression is applied are:

> string is __<type\_to\_check>__ \-strict *<argument\_value>*



  - *boolean*

  - *integer*

  - *double*

Empty strings are accepted as argument value for all the alpha numeric argument
types\. The argument types that are falling into this category and validation
expression used for them are:

> string is *<type\_to\_check>* *<argument\_value>*



  - *alnum*

  - *alpha*

  - *ascii*

................................................................................

In addition to the data types checked with the __string is <type>__
commands, TEPAM specifies some other useful data types:

  - *char* Each string that has a length of 1 character meets the
    *character* type\. The type check is made with the following expression:

> expr \[string length *<argument\_value>*\]==1

  - *color* Any character strings that are accepted by Tk as a color are
    considered as valid color argument\. Please note that the Tk package has to
    be loaded to use the type *color*\. TEPAM is using the following command to
    validate the color type:

> expr \!\[catch \{winfo rgb \. *<argument\_value>*\}\]



  - *font* Any character strings that are accepted by Tk as a font are
    considered as valid font argument\. Please note that the Tk package has to be
    loaded to use the *font* type\. TEPAM is using the following command to
    validate the color type:

        expr ![catch {font measure <argument_value> ""}]



  - *file* Any strings that are not containing one of the following characters
    are considered as valid file names: \* ? " < >\. It is not necessary that the
    file and its containing directory exist\. Zero\-length strings are not
    considered as valid file names\.

    The following expression is used to validate the file names:

        expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]



  - *existingfile* The argument is valid if it matches with an existing file\.
    The following check is performed to validate the arguments of this type:

        file exists <argument_value>

  - *directory* The directory argument is validated exactly in the same way as
................................................................................
print a generated help text to *stdout* and will then return without
performing any additional actions\.

Taking the first procedure declared in [PROCEDURE CALLS](#section6), the
help request and the printed help text would be:

> __display message \-help__  
> *\->*  

> *NAME*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*display message \- Displays a simple message box*  
> *SYNOPSIS*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*display message*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*\[\-mtype <mtype>\]*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Message type, default: "Warning", choices: \{Info, Warning, Error\}*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*<text>*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Multiple text lines to display, type: string*  
> *DESCRIPTION*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*This procedure allows displaying a configurable message box\. The default*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*message type that is created is a warning, but also errors and info can*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*be generated\.*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*The procedure accepts multiple text lines\.*  
> *EXAMPLE*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*display message \-mtype Warning "Save first your job"*

The argument manager is checking if the last provided argument is *\-help* and
generates the requested help message if this is the case\. So, also the following
example will print the help message:

> __display message \-mtype Info "It is 7:00" \-help__

On the other hand, the following call will result in an error:

> __display message \-help \-mtype Info "It is 7:00"__  


> *\->*  
> *display message: Argument '\-help' not known*

## <a name='subsection6'></a>Interactive Procedure Call

If Tk has been loaded a procedure can be called with the *\-interactive* flag
to open a graphical form that allows specifying interactively all procedure
arguments\. The following example assures that the Tk library is loaded and shows
the command line to call interactively the procedure declared in [PROCEDURE
CALLS](#section6):

> package require Tk  
> __display message \-interactive__

Also the *\-interactive* flag has to be placed at the last argument position as
this is also required for the *\-help* flag\. Arguments defined before the
*\-interactive* flag will be ignored\. The following example is therefore also a
valid interactive procedure call:

> __display message__ \-mtype Info "It is 7:00" __\-interactive__



## <a name='subsection7'></a>Unnamed Arguments

Unnamed arguments are typically provided to the called procedure as simple
parameters\. This procedure calling form requires that the provided arguments are
strictly following the order of the specified arguments\. Several parameters can
be assigned to the last argument if this one has the *\-multiple* attribute\.
................................................................................

\.\.\. can for example be called in the following ways:

> __display\_message Info "It is PM 7:00\."__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message Info "It is PM 7:00\." "You should go home\."__  
> *\-> Info: It is PM 7:00\. You should go home\.*


The nice thing is that unnamed arguments can also be called as named arguments,
which can be handy, for example if the exact specified argument order is not
known to a user:

> __display\_message \-mtype Info \-text "It is PM 7:00\."__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message \-text "It is PM 7:00\." \-mtype Info__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__  
> *\-> Info: It is PM 7:00\. You should go home\.*  
>   
> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__  


> *\-> Info: It is PM 7:00\. You should go home\.*

## <a name='subsection8'></a>Named Arguments

Named arguments have to be provided to a procedure in form of a parameter pairs
composed by the argument names and the argument values\. The order how they are
provided during a procedure call is irrelevant and has not to match with the
argument specification order\.
................................................................................
> __display\_message \-text "It is PM 7:00\." \-mtype Info__  
> *\-> Info: It is PM 7:00\.*  
>   
> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__  
> *\-> Info: It is PM 7:00\. You should go home\.*  
>   
> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__  
> *\-> Info: It is PM 7:00\. You should go home\.*


Also named arguments that have not the *\-multiple* attribute can be provided
multiple times\. Only the last provided argument will be retained in such a case:

> __display\_message \-mtype Info \-text "It is PM 7:00\." \-mtype Warning__  


> *\-> Warning: It is PM 7:00\.*

## <a name='subsection9'></a>Unnamed Arguments First, Named Arguments Later \(Tk Style\)

A procedure that has been defined while the variable
__tepam::named\_arguments\_first__ was set to 1, or with the procedure
attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\.
The following procedure declaration will be used in this section to illustrate
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n1 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n2 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u1 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u2 \-default ""\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"  
> \}

The unnamed arguments are placed at the end of procedure call, after the named
arguments:

> my\_proc __\-n1 N1 \-n2 N2 U1 U2__  
> *\-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'*


The argument parser considers the first argument that doesn't start with the '\-'
character as well as all following arguments as unnamed argument:

> my\_proc __U1 U2__  
> *\-> n1:'', n2:'', u1:'U1', u2:'U2'*


Named arguments can be defined multiple times\. If the named argument has the
*\-multiply* attribute, all argument values will be collected in a list\.
Otherwise, only the last provided attribute value will be retained:


> my\_proc __\-n1 N1 \-n2 N2 \-n1 M1 U1 U2__  
> *\-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'*



The name of the first unnamed argument has therefore not to start with the '\-'
character\. The unnamed argument is otherwise considered as name of another named
argument\. This is especially important if the first unnamed argument is given by
a variable that can contain any character strings:

> my\_proc __\-n1 N1 \-n2 N2 "\->" "<\-"__  
> *\-> my\_proc: Argument '\->' not known*  
>   
> set U1 "\->"  
> my\_proc __\-n1 N1 \-n2 N2 $U1 U2__  
> my\_proc: Argument '\->' not known

The '\-\-' flag allows separating unambiguously the unnamed arguments from the
named arguments\. All data after the '\-\-' flag will be considered as unnamed
argument:

> my\_proc __\-n1 N1 \-n2 N2 \-\- "\->" "<\-"__  
> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'*  
>   
> set U1 "\->"  
> my\_proc __\-n1 N1 \-n2 N2 \-\- $U1 U2__  


> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'*

## <a name='subsection10'></a>Named Arguments First, Unnamed Arguments Later \(Tcl Style\)

The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute
*\-named\_arguments\_first* has been set to 0\. The following procedure will be
used in this section to illustrate this calling style:
................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n1 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-n2 \-default ""\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u1\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{u2 \-default "" \-multiple\}  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"  
> \}

The unnamed arguments have to be provided first in this case\. The named
arguments are provided afterwards:

> my\_proc __U1 U2 \-n1 N1 \-n2 N2__  
> *\-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'*


The argument parser will assign to each defined unnamed argument a value before
it switches to read the named arguments\. This default behavior changes a bit if
there are unnamed arguments that are optional or that can take multiple values\.

An argument value will only be assigned to an unnamed argument that is optional
\(that has either the *\-optional* attribute or that has a default value\), if
the value is not beginning with the '\-' character or if no named arguments are
defined\. The value that starts with '\-' is otherwise considered as the name of a
named argument\.

................................................................................
separating unambiguously the named arguments from the unnamed ones with the '\-\-'
flag\.

Let's explore in a bit less theoretically the ways how the previously defined
procedure can be called: The first example calls the procedure without any
parameters, which leads to an error since *u1* is a mandatory argument:

> my\_proc  
> *\-> my\_proc: Required argument is missing: u1*


The procedure call is valid if one parameter is provided for *u1*:

> my\_proc __U1__  
> *\-> n1:'', n2:'', u1:'U1', u2:''*

If more parameters are provided that are not starting with the '\-' character,
they will be attributed to the unnamed arguments\. *U2* will receive 3 of these
parameters, since it accepts multiple values:


> my\_proc __U1 U2 U3 U4__  
> *\-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'*


As soon as one parameter starts with '\-' and all unnamed arguments have been
assigned, the argument manager tries to interpret the parameter as name of a
named argument\. The procedure call will fail if a value beginning with '\-' is
assigned to an unnamed argument:

> my\_proc __U1 U2 U3 U4 \-U5__  
> *\-> my\_proc: Argument '\-U5' not known*



The attribution of a parameter to a named argument will fail if there are
undefined unnamed \(non optional\) arguments\. The name specification will in this
case simply be considered as a parameter value that is attributed to the
*next* unnamed argument\. This was certainly not the intention in the following
example:

> my\_proc __\-n1 N1__  
> *\-> n1:'', n2:'', u1:'\-n1', u2:'N1'*


The situation is completely different if values have already been assigned to

all mandatory unnamed arguments\. A parameter beginning with the '\-' character
will in this case be considered as a name identifier for a named argument:

> my\_proc __U1 \-n1 N1__  
> *\-> n1:'N1', n2:'', u1:'U1', u2:''*


No unnamed arguments are allowed behind the named arguments:


> my\_proc __U1 \-n1 N1 U2__  
> *\-> my\_proc: Argument 'U2' is not an option*



The '\-\-' flag has no special meaning if not all mandatory arguments have got
assigned a value\. This flag will simply be attributed to one of the unnamed
arguments:

> my\_proc __\-\- \-n1 N1__  
> *\-> n1:'N1', n2:'', u1:'\-\-', u2:''*


But the '\-\-' flag is simply ignored if the argument parser has started to handle
the named arguments:

> my\_proc __U1 \-\- \-n1 N1__  
> *\-> n1:'N1', n2:'', u1:'U1', u2:''*  
>   
> my\_proc __U1 \-n1 N1 \-\- \-n2 N2__  


> *\-> n1:'N1', n2:'N2', u1:'U1', u2:''*

## <a name='subsection11'></a>Raw Argument List

It may be necessary sometimes that the procedure body is able to access the
entire list of arguments provided during a procedure call\. This can happen via
the __args__ variable that contains always the unprocessed argument list:

................................................................................
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{text \-type string \-multiple\}  
>   
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts "args: __$args__"  
> \}  
> display\_message \-mtype Warning "It is 7:00"  


> *\-> args: \-mtype Warning \{It is 7:00\}*

# <a name='seealso'></a>SEE ALSO

[tepam\(n\)](tepam\_introduction\.md),
[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md)

# <a name='keywords'></a>KEYWORDS

    The command creates a new expander object with an associated Tcl command
    whose name is *expanderName*\. This command may be used to invoke various
    operations on the graph\. If the *expanderName* is not fully qualified it
    is interpreted as relative to the current namespace\. The command has the
    following general form:

    > *expanderName* option ?*arg arg \.\.\.*?  
    >   

    *Option* and the *arg*s determine the exact behavior of the command\.

The following commands are possible for expander objects:

  - <a name='2'></a>*expanderName* __cappend__ *text*

    The command creates a new expander object with an associated Tcl command
    whose name is *expanderName*\. This command may be used to invoke various
    operations on the graph\. If the *expanderName* is not fully qualified it
    is interpreted as relative to the current namespace\. The command has the
    following general form:

    > *expanderName* option ?*arg arg \.\.\.*?


    *Option* and the *arg*s determine the exact behavior of the command\.

The following commands are possible for expander objects:

  - <a name='2'></a>*expanderName* __cappend__ *text*

  - <a name='1'></a>__::throw__ *error\_code* *error\_message*

    throw is merely a reordering of the arguments of the error command\. It
    throws an error with the indicated error code and error message\.

# <a name='section2'></a>EXAMPLES

> __throw__ \{MYERROR CODE\} "My error message"  
>   

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

  - <a name='1'></a>__::throw__ *error\_code* *error\_message*

    throw is merely a reordering of the arguments of the error command\. It
    throws an error with the indicated error code and error message\.

# <a name='section2'></a>EXAMPLES

> __throw__ \{MYERROR CODE\} "My error message"


# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

> set f \[open /some/file/name a\]  
> __try__ \{  
>     puts \\$f "some message"  
>     \# \.\.\.  
> \} __finally__ \{  
>     close \\$f  
> \}  
>   

Handle different reasons for a file to not be openable for reading:

> __try__ \{  
>     set f \[open /some/file/name\]  
> \} __trap__ \{POSIX EISDIR\} \{\} \{  
>     puts "failed to open /some/file/name: it's a directory"  
> \} __trap__ \{POSIX ENOENT\} \{\} \{  
>     puts "failed to open /some/file/name: it doesn't exist"  
> \}  
>   

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

> set f \[open /some/file/name a\]  
> __try__ \{  
>     puts \\$f "some message"  
>     \# \.\.\.  
> \} __finally__ \{  
>     close \\$f  
> \}


Handle different reasons for a file to not be openable for reading:

> __try__ \{  
>     set f \[open /some/file/name\]  
> \} __trap__ \{POSIX EISDIR\} \{\} \{  
>     puts "failed to open /some/file/name: it's a directory"  
> \} __trap__ \{POSIX ENOENT\} \{\} \{  
>     puts "failed to open /some/file/name: it doesn't exist"  
> \}


# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

    30second                 30.0 second
    30 second                30.0 second
    30 seconds               30.0 second
    200*meter/20.5*second    9.75609756098 meter / second

# <a name='section4'></a>SI UNITS

The standard SI units are predefined according to *NIST Special Publication
330*\. Standard units for both SI Base Units \(Table 1\) and SI Derived Units with
Special Names \(Tables 3a and 3b\) are included here for reference\. Each standard
unit name and abbreviation are included in this package\.

## <a name='subsection2'></a>SI Base Units

    Quantity                Unit Name    Abbr.
    ---------------------------------------------
    Length                  meter        m
    Mass                    kilogram     kg
................................................................................
\(kelvins\) to absolute degrees Celsius or Farenheit\. Conversion of thermodynamic
quantities, such as thermal expansion \(per unit temperature\), however, are easy
to add to the units library\.

SI Units can have a multiple or sub\-multiple prefix\. The prefix or its
abbreviation should appear before the unit, without spaces\. Compound prefixes
are not allowed, and a prefix should never be used alone\. These prefixes are
defined in Table 5 of *Special Publication 330*\.

## <a name='subsection4'></a>SI Prefixes

    Prefix Name     Abbr.   Factor
    ---------------------------------------
    yotta           Y       1e24
    zetta           Z       1e21
................................................................................
types \(e\.g\., *typedef float Length*\), and target units \(expected by the C
application code\) are specified in an associative array\. Default units are also
defined for each quantity type, and are applied to any unit\-less quantity
strings\.

A units system enhanced with quantity type checking might benefit from inclusion
of other derived types which are expressed in terms of special units, as
illustrated in Table 2 of *NIST Publication 330*\. The quantity *area*, for
example, could be defined as units properly reducing to *meter^2*, although
the utility of defining a unit named *square meter* is arguable\.

# <a name='section5'></a>REFERENCES

The unit names, abbreviations, and conversion values are derived from those
published by the United States Department of Commerce Technology Administration,
National Institute of Standards and Technology \(NIST\) in *NIST Special
Publication 330: The International System of Units \(SI\)* and *NIST Special
Publication 811: Guide for the Use of the International System of Units \(SI\)*\.
Both of these publications are available \(as of December 2000\) from
[http://physics\.nist\.gov/cuu/Reference/contents\.html](http://physics\.nist\.gov/cuu/Reference/contents\.html)

The ideas behind implementation of this package is based in part on code written
in 1993 by Adrian Mariano which performed dimensional analysis of unit strings
using fixed size tables of C structs\. After going missing in the late 1990's,
Adrian's code has reappeared in the GNU Units program at
[http://www\.gnu\.org/software/units/](http://www\.gnu\.org/software/units/)

    30second                 30.0 second
    30 second                30.0 second
    30 seconds               30.0 second
    200*meter/20.5*second    9.75609756098 meter / second

# <a name='section4'></a>SI UNITS

The standard SI units are predefined according to *NIST Special* *Publication
330* \. Standard units for both SI Base Units \(Table 1\) and SI Derived Units
with Special Names \(Tables 3a and 3b\) are included here for reference\. Each
standard unit name and abbreviation are included in this package\.

## <a name='subsection2'></a>SI Base Units

    Quantity                Unit Name    Abbr.
    ---------------------------------------------
    Length                  meter        m
    Mass                    kilogram     kg
................................................................................
\(kelvins\) to absolute degrees Celsius or Farenheit\. Conversion of thermodynamic
quantities, such as thermal expansion \(per unit temperature\), however, are easy
to add to the units library\.

SI Units can have a multiple or sub\-multiple prefix\. The prefix or its
abbreviation should appear before the unit, without spaces\. Compound prefixes
are not allowed, and a prefix should never be used alone\. These prefixes are
defined in Table 5 of *Special Publication* *330* \.

## <a name='subsection4'></a>SI Prefixes

    Prefix Name     Abbr.   Factor
    ---------------------------------------
    yotta           Y       1e24
    zetta           Z       1e21
................................................................................
types \(e\.g\., *typedef float Length*\), and target units \(expected by the C
application code\) are specified in an associative array\. Default units are also
defined for each quantity type, and are applied to any unit\-less quantity
strings\.

A units system enhanced with quantity type checking might benefit from inclusion
of other derived types which are expressed in terms of special units, as
illustrated in Table 2 of *NIST Publication* *330* \. The quantity *area*,
for example, could be defined as units properly reducing to *meter^2*,
although the utility of defining a unit named *square meter* is arguable\.

# <a name='section5'></a>REFERENCES

The unit names, abbreviations, and conversion values are derived from those
published by the United States Department of Commerce Technology Administration,
National Institute of Standards and Technology \(NIST\) in *NIST Special
Publication 330: The International System of* *Units \(SI\)* and *NIST Special
Publication 811: Guide for* *the Use of the International System of Units
\(SI\)* \. Both of these publications are available \(as of December 2000\) from
[http://physics\.nist\.gov/cuu/Reference/contents\.html](http://physics\.nist\.gov/cuu/Reference/contents\.html)

The ideas behind implementation of this package is based in part on code written
in 1993 by Adrian Mariano which performed dimensional analysis of unit strings
using fixed size tables of C structs\. After going missing in the late 1990's,
Adrian's code has reappeared in the GNU Units program at
[http://www\.gnu\.org/software/units/](http://www\.gnu\.org/software/units/)

    particularly on Windows the __info\-zip__ and the Windows built\-in zip
    view have rather poor support for this part of the ZIP file specification\.
    The __7\-Zip__ program does correctly display utf8 filenames however and
    the __vfs::zip__ package will use these of course\.

    If you use

    > __::mkzip::mkzip__ mystuff\.tm \-zipkit \-directory mystuff\.vfs  

    it will pack your "mystuff\.vfs/" virtual filesystem tree into a zip archive
    with a suitable header such that on unix you may mark it executable and it
    should run with tclkit\. Or you can run it with __tclsh__ or __wish__
    8\.6 if you like\.

    To change the executable header, specify the __\-runtime__ "preface"

    particularly on Windows the __info\-zip__ and the Windows built\-in zip
    view have rather poor support for this part of the ZIP file specification\.
    The __7\-Zip__ program does correctly display utf8 filenames however and
    the __vfs::zip__ package will use these of course\.

    If you use

    > __::mkzip::mkzip__ mystuff\.tm \-zipkit \-directory mystuff\.vfs

    it will pack your "mystuff\.vfs/" virtual filesystem tree into a zip archive
    with a suitable header such that on unix you may mark it executable and it
    should run with tclkit\. Or you can run it with __tclsh__ or __wish__
    8\.6 if you like\.

    To change the executable header, specify the __\-runtime__ "preface"

'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5\&.4 tcllib "Documentation tools"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
doctools \- doctools - Processing documents
.SH SYNOPSIS
package require \fBTcl  8\&.2\fR
.sp
package require \fBdoctools  ?1\&.5\&.4?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp

'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5\&.5 tcllib "Documentation tools"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
doctools \- doctools - Processing documents
.SH SYNOPSIS
package require \fBTcl  8\&.2\fR
.sp
package require \fBdoctools  ?1\&.5\&.5?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp

&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.5.4 tcllib &quot;Documentation tools&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.5.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>

&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.5.5 tcllib &quot;Documentation tools&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.5.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>

		}
		set pid $sect($fid)
	    }
	}
    }

    # If we have no text take the section title as text, if we
    # can. Last fallback for thext is the id.
    if {$title == {}} {
	if {$pid != {}} {
	    set title $sectt($fid)
	} else {
	    set title $id
	}
    }

		}
		set pid $sect($fid)
	    }
	}
    }

    # If we have no text take the section title as text, if we
    # can. Last fallback for text is the id.
    if {$title == {}} {
	if {$pid != {}} {
	    set title $sectt($fid)
	} else {
	    set title $id
	}
    }

[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5.4]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]

[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5.5]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]

    # => FOO/mpformats

    #catch {search [file join $here                lib doctools mpformats]}
    #catch {search [file join [file dirname $here] lib doctools mpformats]}
    catch {search [file join $here                             mpformats]}
}

package provide doctools 1.5.4

    # => FOO/mpformats

    #catch {search [file join $here                lib doctools mpformats]}
    #catch {search [file join [file dirname $here] lib doctools mpformats]}
    catch {search [file join $here                             mpformats]}
}

package provide doctools 1.5.5

proc Sub4Title {lb title} {
    upvar 1 $lb lines
    lappend lines "[Hash][Hash][Hash][Hash] $title"
    return
}

proc Strong {text} { return [Undr][Undr]${text}[Undr][Undr] }
proc Em     {text} { return [Star]${text}[Star] }

##
# # ## ### ##### ########
##

set __comments 0

proc Sub4Title {lb title} {
    upvar 1 $lb lines
    lappend lines "[Hash][Hash][Hash][Hash] $title"
    return
}

proc _Strong {text} { return [Undr][Undr]${text}[Undr][Undr] }
proc _Em     {text} { return [Star]${text}[Star] }

##
# # ## ### ##### ########
##

set __comments 0

    upvar 1 $lb lines
    #lappend lines ""
    lappend lines $title
    lappend lines [RepeatM - $title]
    return
}




proc Strong {text} { return *${text}* }
proc Em     {text} { return _${text}_ }


























# # ## ### ##### ########
## Bulleting
#
# itembullet  = index of the bullet to use in the next itemized list
# enumbullet  = index of the bullet to use in the next enumerated list

    upvar 1 $lb lines
    #lappend lines ""
    lappend lines $title
    lappend lines [RepeatM - $title]
    return
}

proc Strong {text} { SplitLine $text _Strong }
proc Em     {text} { SplitLine $text _Em }

proc _Strong {text} { return *${text}* }
proc _Em     {text} { return _${text}_ }

proc SplitLine {text cmd} {
    #puts_stderr AAA/SLI=[string map [list \1 \\1 \t \\t { } \\s] <<[join [split $text \n] >>\n<<]>>]
    if {![string match *\n* $text]} {
	foreach {lead content} [LeadSplit $text] break
	return ${lead}[uplevel 1 [list $cmd $content]]
    }
    set r {}   
    foreach line [split $text \n] {
	foreach {lead content} [LeadSplit $line] break
	if {$content == {}} {
	    lappend r {}
	    continue
	}
	lappend r ${lead}[uplevel 1 [list $cmd $content]]
    }
    set text [string trimright [join $r \n]]\n
    #puts_stderr AAA/SLE=[string map [list \1 \\1 \t \\t { } \\s] <<[join [split $text \n] >>\n<<]>>]
    return $text
}

proc LeadSplit {line} {
    regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _
    list $lead $content
}

# # ## ### ##### ########
## Bulleting
#
# itembullet  = index of the bullet to use in the next itemized list
# enumbullet  = index of the bullet to use in the next enumerated list

    return
}
proc Text?     {} { global __currentp ; return $__currentp }
proc TextClear {} { global __currentp ; set __currentp "" }

proc TextTrimLeadingSpace {} {
    global __currentp
    regsub {^([ \t\v\f]*\n)*} $__currentp {} __currentp







    return
}

proc TextPlain {text} {
    #puts_stderr "<<text_plain_text>>"

    if  {[IsOff]} {return}

    # Note: Whenever we get plain text it is possible that a macro for
    # visual markup actually generated output before the expander got
    # to the current text. This output was captured by the expander in
    # its current context. Given the current organization of the
    # engine we have to retrieve this formatted text from the expander
    # or it will be lost. This is the purpose of the 'ctopandclear',
    # which retrieves the data and also clears the capture buffer. The
    # latter to prevent us from retrieving it again later, after the
    # next macro added more data.

    set text [ex_ctopandclear]$text



    # ... TODO ... Handling of example => verbatim

    if {[string length [string trim $text]] == 0} return

    Text $text
    return
}

##
# # ## ### ##### ########
return

    return
}
proc Text?     {} { global __currentp ; return $__currentp }
proc TextClear {} { global __currentp ; set __currentp "" }

proc TextTrimLeadingSpace {} {
    global __currentp
    regsub {^([ \t\v\f]*\x01?\n)*} $__currentp {} __currentp
    return
}

proc TextTrimTrailingSpace {} {
    global __currentp
    regsub {([ \t\v\f]*\x01?\n)*$} $__currentp {} __currentp
    append __currentp \n
    return
}

proc TextPlain {text} {


    if  {[IsOff]} {return}

    # Note: Whenever we get plain text it is possible that a macro for
    # visual markup actually generated output before the expander got
    # to the current text. This output was captured by the expander in
    # its current context. Given the current organization of the
    # engine we have to retrieve this formatted text from the expander
    # or it will be lost. This is the purpose of the 'ctopandclear',
    # which retrieves the data and also clears the capture buffer. The
    # latter to prevent us from retrieving it again later, after the
    # next macro added more data.

    set text [ex_ctopandclear]$text

    #puts_stderr "<<text_plain_text>>=<<[string map [list \t \\t { } \\s \n \\n \r \\r \v \\v \f \\f \1 \\1] $text]>>"

    # ... TODO ... Handling of example => verbatim

    if {[string length [string trim $text]] == 0} return

    Text $text
    return
}

##
# # ## ### ##### ########
return

    regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _
    # Drop trailing spaces, make leading non-breaking, keep content (and inner spaces).
    return [RepeatM " " $lead]$content
}

c_pass 2 fmt_example_end {} {
    #puts_stderr "AAA/fmt_example_end"



    TextTrimLeadingSpace

    # Check for protected markdown markup in the input. If present
    # this is a complex example with highlighted parts.
    set complex [string match *\1* [Text?]]

    #puts_stderr "AAA/fmt_example_end/$complex"
................................................................................
	set t [join [Breaks [LeadSpaces [split $t \n]]] {}]
    } else {
	# Process for code block (verbatim)
	set t [Mark $t]
    }
    TextClear
    Text $t

    
    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.

    regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _
    # Drop trailing spaces, make leading non-breaking, keep content (and inner spaces).
    return [RepeatM " " $lead]$content
}

c_pass 2 fmt_example_end {} {
    #puts_stderr "AAA/fmt_example_end"
    # Flush markup from preceding commands into the text buffer.
    TextPlain ""

    TextTrimLeadingSpace

    # Check for protected markdown markup in the input. If present
    # this is a complex example with highlighted parts.
    set complex [string match *\1* [Text?]]

    #puts_stderr "AAA/fmt_example_end/$complex"
................................................................................
	set t [join [Breaks [LeadSpaces [split $t \n]]] {}]
    } else {
	# Process for code block (verbatim)
	set t [Mark $t]
    }
    TextClear
    Text $t
    TextTrimTrailingSpace
    
    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.

    #puts_stderr "AAA/fmt_example_begin/Done"
    return
}

c_pass 1 fmt_example_end {} NOP
c_pass 2 fmt_example_end {} {
    #puts_stderr "AAA/fmt_example_end"





    TextTrimLeadingSpace

    # Look for and convert continuation lines protected from Tcl
    # substitution into a regular continuation line.
    set t [string map [list \\\\\n \\\n] [Text?]]
    TextClear
    Text $t



    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.
	ContextPush

    #puts_stderr "AAA/fmt_example_begin/Done"
    return
}

c_pass 1 fmt_example_end {} NOP
c_pass 2 fmt_example_end {} {
    #puts_stderr "AAA/fmt_example_end"
    #puts_stderr AAA/EIN=[string map [list \1 \\1 \t \\t { } \\s] <<[join [split [Text?] \n] >>\n<<]>>]

    # Flush markup from preceding commands into the text buffer.
    TextPlain ""
    
    TextTrimLeadingSpace

    # Look for and convert continuation lines protected from Tcl
    # substitution into a regular continuation line.
    set t [string map [list \\\\\n \\\n] [Text?]]
    TextClear
    Text $t

    #puts_stderr AAA/EFT=[string map [list \1\\1 \t \\t { } \\s] <<[join [split [Text?] \n] >>\n<<]>>]
    
    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.
	ContextPush

if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools            1.5.4 [list source [file join $dir doctools.tcl]]
package ifneeded doctools::toc       1.2   [list source [file join $dir doctoc.tcl]]
package ifneeded doctools::idx       1.1   [list source [file join $dir docidx.tcl]]
package ifneeded doctools::cvs       1     [list source [file join $dir cvs.tcl]]
package ifneeded doctools::changelog 1.1   [list source [file join $dir changelog.tcl]]

if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools            1.5.5 [list source [file join $dir doctools.tcl]]
package ifneeded doctools::toc       1.2   [list source [file join $dir doctoc.tcl]]
package ifneeded doctools::idx       1.1   [list source [file join $dir docidx.tcl]]
package ifneeded doctools::cvs       1     [list source [file join $dir cvs.tcl]]
package ifneeded doctools::changelog 1.1   [list source [file join $dir changelog.tcl]]

<!DOCTYPE html><html><head>
<title>TEST - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- TEST.T
   -->
<body><div class="doctools">
<h1 class="doctools_title">TEST(T) 0 .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>TEST -</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>= = == === ===== ======== =============</p>
<pre class="doctools_example">[<b class="cmd">bar</b> \
  foo]</pre>
<p>= = == === ===== ======== =============</p>
<pre class="doctools_example">
<em>  many lines
  highlighted
</em>
</pre>
<p>= = == === ===== ======== =============</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; .COPYRIGHT.</p>
</div>
</div></body></html>

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.T
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
= = == === ===== ======== =============
\begin{alltt}
[{\bf bar} \textbackslash
  foo]\end{alltt}
= = == === ===== ======== =============
\begin{alltt}
{\it   many lines
  highlighted
}
\end{alltt}
= = == === ===== ======== =============
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

manpage {seealso {} keywords {} file .FILE. section T category {} module .MODULE. version 0 title TEST shortdesc {} desc {} fid .FILE}

[comment { -- Example 1 }]
[manpage_begin TEST z 3.14.15.926]
[description]
[example {
Special markdown __non-special__
}]
[manpage_end]

[comment { -- Example 2 }]
[manpage_begin TEST z 3.14.15.926]
[description]
[example {
Special markdown __non-special__
}]
[manpage_end]

[comment { -- Example 2 }]
[manpage_begin TEST z 3.14.15.926]
[description]
[example {
Example Block \
More Lines \\
Ever More
Never

[comment { -- Example 3 }]
[manpage_begin TEST z 3.14.15.926]
[description]
[example {
Example Block \
More Lines \\
Ever More
Never

[comment { -- Example 4 }]
[manpage_begin TEST T 0]
[description]
= = == === ===== ======== =============
[example_begin][lb][cmd bar] \
  foo[rb][example_end]
= = == === ===== ======== =============
[example_begin]
[emph {  many lines
  highlighted
}]
[example_end]
= = == === ===== ======== =============
[manpage_end]

    Second \
    Continuing Lines \
    Done

\.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\.

> __command__    x \\  
> \-\- __command__ \-\-  
>   

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; \.COPYRIGHT\.

    Second \
    Continuing Lines \
    Done

\.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\.

> __command__    x \\  
> \-\- __command__ \-\-


# <a name='copyright'></a>COPYRIGHT

Copyright &copy; \.COPYRIGHT\.

[//000000001]: # (TEST \- )
[//000000002]: # (Generated from file '\.FILE\.' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright © \.COPYRIGHT\.)
[//000000004]: # (TEST\(T\) 0 \.MODULE\. "")

# NAME

TEST \-

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Copyright](#copyright)

# <a name='description'></a>DESCRIPTION

= = == === ===== ======== =============

> \[__bar__ \\  
> &nbsp;&nbsp;foo\]

= = == === ===== ======== =============

> &nbsp;&nbsp;*many lines*  
> &nbsp;&nbsp;*highlighted*

= = == === ===== ======== =============

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; \.COPYRIGHT\.

'\"
'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff'
'\" Copyright (c) \&.COPYRIGHT\&.
'\"
.TH "TEST" T 0 \&.MODULE\&. ""
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
TEST \-
.SH DESCRIPTION
= = == === ===== ======== =============
.CS

[\fBbar\fR \\
  foo]
.CE
= = == === ===== ======== =============
.CS


\fI  many lines
  highlighted
\fR

.CE
= = == === ===== ======== =============
.SH COPYRIGHT
.nf
Copyright (c) \&.COPYRIGHT\&.

.fi

TEST - 
Generated from file '.FILE.' by tcllib/doctools with format 'text'
TEST(T) 0 .MODULE. ""

NAME
====

TEST -

DESCRIPTION
===========

= = == === ===== ======== =============

| [bar \
|   foo]

= = == === ===== ======== =============

| _many lines_
| _highlighted_

= = == === ===== ======== =============

COPYRIGHT
=========

Copyright (c) .COPYRIGHT.

<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' -->
<manpage id='.FILE' cat='cmd' title='TEST' version='0' package='.MODULE.'>
<head>
<info key='copyright' value='Copyright (c) .COPYRIGHT.'/>
</head>
<namesection>
<name>TEST</name>
<desc></desc>

</namesection>


<section id='section1'>
<title>DESCRIPTION</title>
= = == === ===== ======== =============

<example>[<cmd>bar</cmd> \
  foo]
</example>
= = == === ===== ======== =============

<example>
<emph>  many lines
  highlighted
</emph>

</example>
= = == === ===== ======== =============
</section>



</manpage>

'''TEST 0''' '''.MODULE.'''




**DESCRIPTION**

= = == === ===== ======== =============
======
['''bar''' \
  foo]
======
= = == === ===== ======== =============
======

''  many lines
  highlighted
''

======
= = == === ===== ======== =============

**COPYRIGHT**

 Copyright (c) .COPYRIGHT.