Tcl Library Source Code

In our example, directly drawn from the benchmark suite of Tcllib's
__[aes](\.\./aes/aes\.md)__ package, the concrete initialization code
constructs the key schedule used by the encryption command whose speed we
measure, and the cleanup code releases any resources bound to that schedule\.

> 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

initialization and cleanup\. Its concrete initialization code constructs a
variable refering to a set with specific properties \(The set has a string
representation, which is shared\) affecting the speed of the inclusion command,
and the cleanup code releases the temporary variables created by this
initialization\.

> 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

that files employing that document format are given the suffix "\.ddt", to
distinguish them from the more traditional LaTeX\-based "\.dtx" files\.

Master source files with "\.dtx" extension are usually set up so that they can be
typeset directly by __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ without any
support from other files\. This is achieved by beginning the file with the lines

>    % \\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

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

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\.

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

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
*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\.

[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\_kupries@users\.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)  

command closes the previous paragraph and automatically opens the next\. The
first paragraph is automatically opened at the beginning of the body, by
__description__\. In the same manner the last paragraph automatically ends at
__manpage\_end__\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
>  \.\.\.  
> \[__para__\]  
>  \.\.\.  
> \[__para__\]  
>  \.\.\.  
> \[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
is automatically opened at the beginning of the body, by __description__
\(This section is labeled "DESCRIPTION"\)\. In the same manner the last section
automatically ends at __manpage\_end__\.

Empty sections are *not* ignored\. We are free to \(not\) use paragraphs within
sections\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
>  \.\.\.  
> \[__section \{Section A\}__\]  
>  \.\.\.  
> \[para\]  
>  \.\.\.  
> \[__section \{Section B\}__\]  
>  \.\.\.  
> \[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__\.

Empty subsections are *not* ignored\. We are free to \(not\) use paragraphs
within subsections\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
>  \.\.\.  
> \[section \{Section A\}\]  
>  \.\.\.  
> \[__subsection \{Sub 1\}__\]  
>  \.\.\.  
> \[para\]  
>  \.\.\.  
> \[__subsection \{Sub 2\}__\]  
>  \.\.\.  
> \[section \{Section B\}\]  
>  \.\.\.  
> \[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\.

    Its argument is a widget name\.

The example demonstrating the use of text markup is an excerpt from the
*[doctools language command reference](doctools\_lang\_cmdref\.md)*, with
some highlighting added\. It shows their use within a block of text, as the
arguments of a list item command \(__call__\), and our ability to nest them\.

>   \.\.\.  
>   \[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\]  
>   
>   Text structure\. List element\. Argument list\. Automatically closes the  
>   previous list element\. Specifies the data\-\[__arg type__\] of the described  
>   argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The  
>   latter is optional\.  
>   \.\.\.  
>   

## <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
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

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

whether she wants to have them at the beginning of the body, or at its end,
maybe near the place a keyword is actually defined by the main content, or
considers them as meta data which should be in the header, etc\.

Our example shows the sources for the cross\-references of this document, with
some highlighting added\. Incidentally they are found at the end of the body\.

>   \.\.\.  
>   \[__see\_also doctools\_intro__\]  
>   \[__see\_also doctools\_lang\_syntax__\]  
>   \[__see\_also doctools\_lang\_cmdref__\]  
>   \[__keywords markup \{semantic markup\}__\]  
>   \[__keywords \{doctools markup\} \{doctools language\}__\]  
>   \[__keywords \{doctools syntax\} \{doctools commands\}__\]  
>   \[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

templating commands within example blocks to read their contents from a file
\(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__ \{  
>     \.\.\. \[list\_begin enumerated\] \.\.\.  
>   \}\]  
>   

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

> \[__example\_begin__\]  
>     \.\.\. \[list\_begin enumerated\] \.\.\.  
>   \[__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

    is a specialized form of a term definition list where the term is the name
    of a configuration option for a widget, with its name and class in the
    option database\.

Our example is the source of the definition list in the previous paragraph, with
most of the content in the middle removed\.

>   \.\.\.  
>   \[__list\_begin__ definitions\]  
>   \[__def__ \[const arg\]\]  
>   
>   \(\[cmd arg\_def\]\) This opens an argument \(declaration\) list\. It is a  
>   specialized form of a definition list where the term is an argument  
>   name, with its type and i/o\-mode\.  
>   
>   \[__def__ \[const itemized\]\]  
>   
>   \(\[cmd item\]\)  
>   This opens a general itemized list\.  
>   
>   \.\.\.  
>   \[__def__ \[const tkoption\]\]  
>   
>   \(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It  
>   is a specialized form of a definition list where the term is the name  
>   of a configuration option for a widget, with its name and class in the  
>   option database\.  
>   
>   \[__list\_end__\]  
>   \.\.\.  
>   

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

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

# <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

    If the entered data have been rejected \(via the *Cancel* button\) the
    __argument\_dialogbox__ returns __cancel__\.

    A small example illustrates how the __argument\_dialogbox__ can be
    employed:

    > set DialogResult \[__tepam::argument\_dialogbox__ \\  
    >    __\-title__ "Itinerary selection" \\  
    >    __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} \\  
    >    __\-frame__ \{*\-label "Itinerary start"*\} \\  
    >       __\-comment__ \{*\-text "Specify your itinerary start location"*\} \\  
    >       __\-entry__ \{*\-label "City" \-variable start\_city \-type string*\} \\  
    >       __\-entry__ \{*\-label "Street" \-variable start\_street \-type string \-optional 1*\} \\  
    >       __\-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
    widget has been defined\. It recognizes the following attributes inside the
    item attribute list:

      * \-label *string*

        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\.

## <a name='subsection4'></a>Data Entry Widget Items

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
extended with additional application specific entry widgets \(see [APPLICATION
SPECIFIC ENTRY WIDGETS](#section3)\):

  - \-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*

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

    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
    defined, the list box height is automatically adapted to the argument dialog
    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\.

    Disjoint listboxes allow always selecting multiple elements\. With the
    exception of the *\-multiple\_selection* attribute, disjointed list boxes
    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*

    The item *\-file* creates a group composed by an entry widget together with
    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

    font of the label widget to display the selected font will be used as
    default selected font\. If the font family of this label widget is not part
    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 \\  
>    __\-font__ \{\-label "Font" \-variable Font \\  
>           \-font\_sizes \{8 10 12 16\} \\  
>           \-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
    value\.

    The argument dialog box accepts all types that have been specified by the
    TEPAM package and that are also used by
    __[tepam::procedure](tepam\_procedure\.md)__ \(see 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*

  - \-choices *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 \\  
>    \-listbox \{\-label "Text styles" \-variable Styles \\  
>              __\-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 \\  
>    \-checkbox \{\-label "Font sytle" \-variable FontStyle \\  
>               \-choices \{bold italic underline\} \\  
>               __\-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 \\  
>    \-combobox \{\-label "Text size" \-variable Size __\-choicevariable TextSizes__\}  

  - \-multiple\_selection __0__|__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 \\  
>    \-listbox \{\-label "Text styles" \-variable Styles \\  
>              \-choices \{bold italic underline\} \-default underline \\  
>              __\-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 \\  
>    \-file \{\-label "Image file" \-variable ImageF \\  
>           __\-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 \\  
>    \-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 \\  
>    \-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 \\  
>    \-listbox \{\-label "Text size" \-variable Size \\  
>              \-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
dialog box by adding a dedicated procedure to the __tepam__ namespace\. This
procedure has three arguments; the first one is the widget path, the second one
a subcommand and the third argument has various purposes:

> *proc* tepam::ad\_form\(<WidgetName>\) \{W Command \{Par ""\}\} \{  
> &nbsp;&nbsp;&nbsp;*upvar Option Option; \# if required*  
> &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\.

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

of the referred procedures\. Since nonstandard placeholders are used,
__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ is called with an explicit
placeholder pattern definition \(argument *search\_pattern*\)\.

> *\# Define the HTML master document*  
> set HtmlMasterDoc \{\\  
> <html>  
> &nbsp;&nbsp;<head>  
> &nbsp;&nbsp;&nbsp;&nbsp;<title>tepam::doc\_gen</title>  
> &nbsp;&nbsp;&nbsp;&nbsp;<link rel="stylesheet" href="tepam\_doc\_stylesheet\.css">  
> &nbsp;&nbsp;&nbsp;&nbsp;<meta content="documentation" name="keywords"></meta>  
> &nbsp;&nbsp;</head>  
> &nbsp;&nbsp;<body>  
> &nbsp;&nbsp;&nbsp;&nbsp;<h1>tepam::doc\_gen</h1>  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<h2>Generate</h2>  
> __\{\*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)

procedure name, the procedure header and the procedure body\.

The following example declares the subcommand
__[message](\.\./\.\./\.\./\.\./index\.md\#message)__ of the procedure
__display__\. This command has several named and unnamed arguments:

> __[tepam::procedure](tepam\_procedure\.md)__ \{display message\} \{  
>    \-return            \-  
>    \-short\_description "Displays a simple message box"  
>    \-description       "This procedure allows displaying a configurable message box\."  
>    \-args \{  
>       \{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}  
>       \{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}  
>       \{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}  
>       \{\-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

# <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:

destination folder as well as a checkbox that allows specifying if an eventual
existing file can be overwritten\. Comfortable browsers can be used to select
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)__ \\  
>    __\-existingfile__ \{\-label "Source file" \-variable SourceFile\} \\  
>    __\-existingdirectory__ \{\-label "Destination folder" \-variable DestDir\} \\  
>    __\-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

about the different available entry widget types and parameter attributes\. The
example contains also some formatting instructions like *\-frame* and *\-sep*
which allows organizing the different entry widgets in frames and sections:

> set ChoiceList \{"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"\}  
>   
> set Result \[__[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\  
>    __\-title__ "System configuration" \\  
>    __\-context__ test\_1 \\  
>    __\-frame__ \{\-label "Entries"\} \\  
>       __\-entry__ \{\-label Entry1 \-variable Entry1\} \\  
>       __\-entry__ \{\-label Entry2 \-variable Entry2 \-default "my default"\} \\  
>    __\-frame__ \{\-label "Listbox & combobox"\} \\  
>       __\-listbox__ \{\-label "Listbox, single selection" \-variable Listbox1 \\  
>                 \-choices \{1 2 3 4 5 6 7 8\} \-default 1 \-height 3\} \\  
>       __\-listbox__ \{\-label "Listbox, multiple selection" \-variable Listbox2  
>                 \-choicevariable ChoiceList \-default \{"Choice 2" "Choice 3"\}  
>                 \-multiple\_selection 1 \-height 3\} \\  
>       __\-disjointlistbox__ \{\-label "Disjoined listbox" \-variable DisJntListbox  
>                         \-choicevariable ChoiceList \\  
>                         \-default \{"Choice 3" "Choice 5"\} \-height 3\} \\  
>       __\-combobox__ \{\-label "Combobox" \-variable Combobox \\  
>                  \-choices \{1 2 3 4 5 6 7 8\} \-default 3\} \\  
>    __\-frame__ \{\-label "Checkbox, radiobox and checkbutton"\} \\  
>       __\-checkbox__ \{\-label Checkbox \-variable Checkbox  
>                  \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\  
>                  \-default italic\} \\  
>       __\-radiobox__ \{\-label Radiobox \-variable Radiobox  
>                  \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\  
>                  \-default underline\} \\  
>       __\-checkbutton__ \{\-label CheckButton \-variable Checkbutton \-default 1\} \\  
>    __\-frame__ \{\-label "Files & directories"\} \\  
>       __\-existingfile__ \{\-label "Input file" \-variable InputFile\} \\  
>       __\-file__ \{\-label "Output file" \-variable OutputFile\} \\  
>       __\-sep__ \{\} \\  
>       __\-existingdirectory__ \{\-label "Input directory" \-variable InputDirectory\} \\  
>       __\-directory__ \{\-label "Output irectory" \-variable OutputDirectory\} \\  
>    __\-frame__ \{\-label "Colors and fonts"\} \\  
>       __\-color__ \{\-label "Background color" \-variable Color \-default red\} \\  
>       __\-sep__ \{\} \\  
>       __\-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"} {

__proc__ also 3 arguments:

  - <a name='1'></a>__tepam::procedure__ *name* *attributes* *body*

The TEPAM procedure declaration syntax is demonstrated by the following example:

> __tepam::procedure__ \{display message\} \{  
> &nbsp;&nbsp;&nbsp;\-short\_description  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"Displays a simple message box"  
> &nbsp;&nbsp;&nbsp;\-description  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"This procedure allows displaying a configurable\\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;message box\. The default message type that is\\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;created is a warning, but also errors and info can\\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;be generated\.  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The procedure accepts multiple text lines\."  
> &nbsp;&nbsp;&nbsp;\-example  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{display message \-mtype Warning "Save first your job"\}  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-mtype \-choices \{Info Warning Error\} \\  
> &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

    This is the normal procedure body\. The declared arguments will be available
    to the procedure body in form of variables\.

    The procedure body will only be executed if the provided set of arguments
    could be validated by the TEPAM argument manager\.

> tepam::procedure \{display\_message\} \{  
>    \-args \{  
>       \{\-__mtype__ \-default Warning \-choices \{Warning Error\}\}  
>       \{__text__ \-type string\}  
>    \}  
> \} \{  
>    puts "Message type: __$mtype__"  
>    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\} \{  
>    \-args \{  
>       \.\.\.  

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

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

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

    Custom argument validations can be performed via specific validation
    commands that are defined with the *\-validatecommand* attribute\.

    Validation command declaration example:

> tepam::procedure \{display\_message\} \{  
>    \-args \{  
>       \{text \-type string \-description "Message text"\} \}  
>    __\-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\.

## <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
    can also be blank to indicate an argument comment, or it can start with \# to
    indicate a section comment\.

      * *"<Name>"*

        This is the simplest form of an argument name: An argument whose name is
        not starting with '\-' is an *unnamed argument*\. The parameter provided
        during a procedure call will be assigned to a variable with the name
        *<Name>*\.

> tepam::procedure \{print\_string\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &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>*\)\.

> tepam::procedure \{print\_string\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &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*

      * *"\-"* or *""*

        A blank argument name \(either '\-' or *''*\) starts a comment for the
        following arguments\.

> tepam::procedure \{print\_time\} \{  
>    \-interactive\_display\_format short  
>    \-args \{  
>       \{hours \-type integer \-description "Hour"\}  
>       \{minutes \-type integer \-description "Minute"\}  
>   
>       __\{\- The following arguments are optional:\}__  
>       \{seconds \-type integer \-default 0 \-description "Seconds"\}  
>       \{milliseconds \-type integer \-default 0 \-description "Milliseconds"\}  
>    \}  
> \} \{  
>    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\.

      * *"\#\*"*

        An argument definition list that starts with '\#' is considered as a
        section comment\. The argument definition list will be trimmed from the
        '\#' characters and the remaining string will be used as section comment\.

        Section comments can be used to structure visually the argument
        definition code\. Section comments are also used to structure the
        generated help texts and the interactive argument definition forms\.

> tepam::procedure \{complex\_multiply\} \{  
>    \-description "This function perform a complex multiplication"  
>    \-args \{  
>       __\{\#\#\#\# First complex number \#\#\#\#\}__  
>       \{\-r0 \-type double \-description "First number real part"\}  
>       \{\-i0 \-type double \-description "First number imaginary part"\}  
>   
>       __\{\#\#\#\# Second complex number \#\#\#\#\}__  
>       \{\-r1 \-type double \-description "Second number real part"\}  
>       \{\-i1 \-type double \-description "Second number imaginary part"\}  
>    \}  
> \} \{  
>    return \[expr $r0\*$r1 \- $i0\*$i1\]  
> \}  

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

    The following argument attributes are supported:

      * \-description *string*

        attribute\. The provided validation command can be a complete script in
        which the pattern *%P* is replaced by the argument value that has to
        be validated\.

        Validation command declaration example:

> tepam::procedure \{display\_message\} \{  
>    \-args \{  
>       \{text \-type string \-description "Message text" \\  
>             __\-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\.

        For example, if a procedure takes as argument a file name it may be
        beneficial to specify the required file type for the interactive
        argument definition form\. This information can be provided via the
        *\-auxargs* attribute to the argument definition form:

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

      * \-auxargs\_commands *script*

        If the auxiliary argument attributes are not static but have to be
        dynamically adaptable, the *\-auxargs\_commands* allows defining them

be completed with application specific types if necessary\.

## <a name='subsection3'></a>Predefined Argument Types

To remember, a type can be assigned to each specified procedure argument:

> tepam::procedure \{warning\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &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
    the \(normal\) named arguments, no argument value has to be provided to a
    flag\.

> tepam::procedure flag\_test \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\-flag \-type none \-description "This is a flag"\}__  
> &nbsp;&nbsp;&nbsp;\}  
> \} \{  
> &nbsp;&nbsp;&nbsp;puts __$flag__  
> \}  
>   
> flag\_test  
> *\-> 0*  
>   
> flag\_test \-flag  
>   

__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
the meaning of this calling style:

> __set tepam::named\_arguments\_first 1__  
> tepam::procedure my\_proc \{  
>    \-args \{  
>       \{\-n1 \-default ""\}  
>       \{\-n2 \-default ""\}  
>       \{u1 \-default ""\}  
>       \{u2 \-default ""\}  
>    \}  
> \} \{  
>    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__  
>   

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:

> __set tepam::named\_arguments\_first 0__  
> tepam::procedure my\_proc \{  
>    \-args \{  
>       \{\-n1 \-default ""\}  
>       \{\-n2 \-default ""\}  
>       \{u1\}  
>       \{u2 \-default "" \-multiple\}  
>    \}  
> \} \{  
>    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__  
>   

## <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:

> tepam::procedure \{display\_message\} \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-mtype \-choices \{Warning Error\} \-default Warning\}  
> &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

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

Ensure that a file is closed no matter what:

> set f \[open /some/file/name a\]  
> __try__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;puts \\$f "some message"  
> &nbsp;&nbsp;&nbsp;&nbsp;\# \.\.\.  
> \} __finally__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;close \\$f  
> \}  
>   

Handle different reasons for a file to not be openable for reading:

> __try__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;set f \[open /some/file/name\]  
> \} __trap__ \{POSIX EISDIR\} \{\} \{  
> &nbsp;&nbsp;&nbsp;&nbsp;puts "failed to open /some/file/name: it's a directory"  
> \} __trap__ \{POSIX ENOENT\} \{\} \{  
> &nbsp;&nbsp;&nbsp;&nbsp;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

'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users\&.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

&#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>

[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]

    # => 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

global _in_example
set    _in_example 0

global _has_images
set    _has_images 0

global _has_examples
set    _has_examples 0

# Called to handle plain text from the input
proc fmt_plain_text {text} {
    global _in_example
    if {$_in_example} {	
	lappend map \\\\\n \1\\textbackslash\n







	lappend map \\\n   \1\\textbackslash\n	
	set text [string map $map $text]
	return $text
    }
    return [texEscape $text]
}

proc Year {} {clock format [clock seconds] -format %Y}

}

################################################################
## Backend for LaTeX markup

c_pass 1 fmt_manpage_begin {title section version} NOP
c_pass 2 fmt_manpage_begin {title section version} {
    global _has_images _has_examples

    set module      [dt_module]
    set shortdesc   [c_get_module]
    set description [c_get_title]
    set copyright   [c_get_copyright]

    set     hdr ""
    append  hdr [Comment [c_provenance]] \n
    if {$copyright != {}} {
	append  hdr [Comment $copyright] \n
    }
    append  hdr [Comment "$title.$section"] \n
    append  hdr \n
    append  hdr "\1\\documentclass\{article\}" \n

    if {$_has_images} {
	append hdr "\1\\usepackage{epsfig}" \n
	append hdr "\1\\usepackage{epstopdf}" \n
    }
    if {$_has_examples} {
	append hdr "\1\\usepackage{alltt}" \n
    }

    append  hdr "\1\\begin\{document\}" \n
    append  hdr "\1\\author\{[dt_user]\}" \n

    set    titletext ""
    append titletext "$module / $title -- "
    append titletext "$shortdesc : $description"

    append text "Database Class:	[Bold $dbclass]\\\\\n"
    return "\n%\n\1\\item\[\] $text\n%\n"
}

################################################################

proc fmt_example_begin {} {
    global _has_examples _in_example
    set _has_examples 1
    set    _in_example 1
    return "\1\\begin{alltt}\n"
}
proc fmt_example_end   {} {
    global _in_example
    set    _in_example 0
    return "\1\\end{alltt}\n"
}
# No mapping of special characters
proc fmt_example {code} {
    return [fmt_example_begin][fmt_plain_text $code][fmt_example_end]
}

proc fmt_arg    {text} {Underline $text}
proc fmt_cmd    {text} {Bold      $text}
proc fmt_emph   {text} {Italic    $text}
proc fmt_opt    {text} {return   ?$text?}

proc fmt_comment {text} {

    CloseParagraph
    if {[llength $sa]} { Special {SEE ALSO} seealso   [join [XrefList [lsort $sa] sa] ", "] }
    if {[llength $kw]} { Special KEYWORDS   keywords  [join [XrefList [lsort $kw] kw] ", "] }
    if {$ca ne ""}     { Special CATEGORY   category  $ca            }
    if {$ct != {}}     { Special COPYRIGHT  copyright $ct [Verbatim] }
    return
}

proc Breaks {lines} {
    set r {}
    foreach line $lines { lappend r $line[LB] }
    return $r
}

proc LeadSpaces {lines} {
    set r {}
    foreach line $lines { lappend r [LeadSpace $line] }
    return $r
}

proc LeadSpace {line} {
    # Split into leading and trailing whitespace, plus content
    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"
    
    # In examples (verbatim markup) markdown's special characters are
    # no such by default, thus must not be quoted. Mark them as
    # protected from quoting. Further look for and convert
    # continuation lines protected from Tcl substitution into a
    # regular continuation line.
    set t [Text?]
    set t [string map [list \\\\\n \\\n] $t]
    if {$complex} {
	# Process for block quote
	# - make leading spaces non-breaking
	# - force linebreaks
	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 != {}} {

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]]

<pre class="doctools_example">
Second \
Continuing Lines \
Done
</pre>
<p>............... Vorwaerts ..........</p>
<pre class="doctools_example">
   <b class="cmd">command</b>    x \
-- <b class="cmd">command</b> --
</pre>
</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.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
BEGINNE HIER
\begin{alltt}
	 Example Block  More Lines
\end{alltt}

\begin{alltt}
Inlined Example \textbackslash
Next Line
\end{alltt}
FERTIG
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) **Copyright**
% ALL.a
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / ALL -- ..THE\_MODULE.. : ..THE\_TITLE..}
\maketitle
\section{Synopsis}\label{synopsis}
\begin{flushleft}
package require {\bf AAA}
package require {\bf BBB VVV}
package require {\bf CCC ?VVV?}

\item[] \underline{NAME} TYPE
%
 DESCRIPTION ::{\bf Option}::
%
\item[] \underline{NAME} TYPE (MODE)
%
 DESCRIPTION ::?Optional?::
\begin{alltt}
    THE ARGUMENT IS USED IN THIS
    AND/OR THAT MANNER
\end{alltt}
\end{itemize}
%
\item[] CMDNAME ...
%
 DESCRIPTION ::{\bf Package}::
%
\item[] CMDNAME ...

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
lorem
\begin{alltt}
1 lorem ipsum dolores
\end{alltt}
ipsum
\begin{alltt}
 2 lorem ipsum dolores \end{alltt}
dolores
\begin{alltt}
3 lorem ipsum dolores
\end{alltt}
lorem
\begin{alltt}
 4 lorem ipsum dolores
\end{alltt}
ipsum
\begin{alltt}
5 lorem ipsum dolores \end{alltt}
dolores
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-itemized-examples.1
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / test-itemized-examples --  : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item
%
\begin{alltt}
 A lorem ipsum dolores \end{alltt}
%
\item
%
 lorem ipsum dolores
\begin{alltt}
 B lorem ipsum dolores \end{alltt}
lorem ipsum dolores
%
\item
%
 lorem ipsum dolores
\begin{alltt}
 C lorem ipsum dolores \end{alltt}
%
\item
%
 lorem ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-enumerated-examples.1
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / test-enumerated-examples --  : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{enumerate}
%
\item
%
\begin{alltt}
 A1 lorem ipsum dolores \end{alltt}
%
\item
%
 lorem ipsum dolores
\begin{alltt}
 B2 lorem ipsum dolores \end{alltt}
lorem ipsum dolores
%
\item
%
 lorem ipsum dolores
\begin{alltt}
 C3 lorem ipsum dolores \end{alltt}
%
\item
%
 lorem ipsum dolores
\end{enumerate}
\section{Copyright}\label{copyright}
\begin{flushleft}

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-definition-examples.1
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / test-definition-examples --  : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item[] lorem
%
\begin{alltt}
 A1 lorem ipsum dolores \end{alltt}
%
\item[] lorem
%
 ipsum dolores
\begin{alltt}
 B2 lorem ipsum dolores \end{alltt}
lorem ipsum dolores
%
\item[] lorem
%
 ipsum dolores
\begin{alltt}
 C3 lorem ipsum dolores \end{alltt}
%
\item[] lorem
%
 ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
\begin{alltt}
Special markdown __non-special__
\end{alltt}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
\begin{alltt}
Example Block  More Lines \textbackslash
Ever More
Never
\end{alltt}

............... Weiter .............

\begin{alltt}
Second \textbackslash
Continuing Lines \textbackslash
Done
\end{alltt}
............... Vorwaerts ..........
\begin{alltt}
   {\bf command}    x \textbackslash
-- {\bf command} --
\end{alltt}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

[example_begin]
Second \
Continuing Lines \\
Done
[example_end]
............... Vorwaerts ..........
[example_begin]
   [cmd command]    x \\
-- [cmd command] --
[example_end]
[manpage_end]

    Second \
    Continuing Lines \
    Done

\.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\.

> __command__    x \\  
> \-\- __command__ \-\-  
>   

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; \.COPYRIGHT\.

Done

.CE
\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&. Vorwaerts \&.\&.\&.\&.\&.\&.\&.\&.\&.\&.
.CS


   \fBcommand\fR    x \\
-- \fBcommand\fR --

.CE
.SH COPYRIGHT
.nf
Copyright (c) \&.COPYRIGHT\&.

| Second \
| Continuing Lines \
| Done

............... Vorwaerts ..........

| command    x \
| -- command --

COPYRIGHT
=========

Copyright (c) .COPYRIGHT.

Continuing Lines \
Done

</example>
............... Vorwaerts ..........

<example>
   <cmd>command</cmd>    x \
-- <cmd>command</cmd> --

</example>
</section>

Continuing Lines \
Done

======
............... Vorwaerts ..........
======

   '''command'''    x \
-- '''command''' --

======


**COPYRIGHT**