Tcl Library Source Code

Check-in [97fc04ebd2]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Doctools: - Markdown: Fix indentation for examples formatted as block quotes. Replace leading whitespace with non-breaking spaces. Note: Works only for leading whitespace. Non-breaking inner spaces seem to cause trouble, i.e. are not recognized and not formatted. - Latex: changed to use `alltt` as the environment for examples. This allows markup the same as doctools does for example_begin/end. Refixed handling of continuation lines to use the proper latex macro for the character. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.4 B (latex, markdown) T (latex, markdown)
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 97fc04ebd2784127f4fd317909a81c8a47011e86b19cb6cdc8dd8450ceadbda5
User & Date: aku 2019-04-12 06:49:12
Context
2019-04-12
21:59
mime - Tkt [57909d2e1c] - Issue introduced with commit [913f7d92c5c35342]. Conversion of superfluous nested `expr` command forgot to convert braces to proper parens. This was able to break \r detection at the end of a line. - Further properly indented some of the code around this. - Lastly removed superflous reboxing of `mime::initializeaux` in `mime::initialize`. The command got boxed followed by immediate unboxing, making the whole thing superflous. Version bump 1.6.1 - (B) mime - (T) mime check-in: b2ae85b606 user: aku tags: trunk
15:12
Get doctools example and indent fixes check-in: 5f9bcaa466 user: aku tags: doc-overhaul
06:49
Doctools: - Markdown: Fix indentation for examples formatted as block quotes. Replace leading whitespace with non-breaking spaces. Note: Works only for leading whitespace. Non-breaking inner spaces seem to cause trouble, i.e. are not recognized and not formatted. - Latex: changed to use `alltt` as the environment for examples. This allows markup the same as doctools does for example_begin/end. Refixed handling of continuation lines to use the proper latex macro for the character. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.4 B (latex, markdown) T (latex, markdown) check-in: 97fc04ebd2 user: aku tags: trunk
2019-04-11
20:00
dicttool - Tkt [e79990908f] - Fixed doc grammar. No version change. Removed DOS EOL from .md doc variant. check-in: e6a4a02868 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to embedded/md/tcllib/files/modules/bench/bench_lang_intro.md.

77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
...
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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__ \{  
>     set A $sx\($times,$n\)  
>     set B $A  
> \} \-body \{  
>     struct::set include A x  
> \} __\-ipost__ \{  
>     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






|

|

|







 







|
|

|

|







77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
...
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;set key \[aes::Init ecb $k $i\]  
> \} \-body \{  
> &nbsp;&nbsp;&nbsp;&nbsp;aes::Encrypt $key $p  
> \} __\-post__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;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

Changes to embedded/md/tcllib/files/modules/docstrip/docstrip.md.

391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
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  
>    %<\*driver>  
>    \\documentclass\{tclldoc\}  
>    \\begin\{document\}  
>    \\DocInput\{*filename\.dtx*\}  
>    \\end\{document\}  
>    %</driver>  
>    % \\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






|
|
|
|
|
|
|
|







391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
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

> &nbsp;&nbsp;&nbsp;% \\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

Changes to embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md.

166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
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\.






|
|
|
|
|







166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
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='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\.

Changes to embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md.

238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
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\.






|
|
|
|
|







238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
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='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\.

Changes to embedded/md/tcllib/files/modules/doctools/doctools.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
[//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\.3 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\.3?  

[__::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)  



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
[//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)  

Changes to embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md.

219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
...
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
...
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
...
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
...
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
...
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
...
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
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
................................................................................
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
................................................................................
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\.

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






|

|

|







 







|

|

|

|







 







|

|

|

|

|

|







 







|
|

|
|
|
|
|







 







|
|
|
|
|







 







|
|
|
|
|
|
|
|







 







|
|





|
|







 







|
|
|

|
|
|

|

|
|

|
|

|
|
|
|

|
|






|
|
|
|
|
|
|
|







219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
...
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
...
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
...
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
...
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
...
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
...
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
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\]  
> &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
................................................................................
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\]  
> &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
................................................................................
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\]  
> &nbsp;\.\.\.  
> \[section \{Section A\}\]  
> &nbsp;\.\.\.  
> \[__subsection \{Sub 1\}__\]  
> &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\.
................................................................................
    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\.

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

> &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
................................................................................
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__ \{  
> &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
................................................................................
    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\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__list\_begin__ definitions\]  
> &nbsp;&nbsp;\[__def__ \[const arg\]\]  
>   
> &nbsp;&nbsp;\(\[cmd arg\_def\]\) This opens an argument \(declaration\) list\. It is a  
> &nbsp;&nbsp;specialized form of a definition list where the term is an argument  
> &nbsp;&nbsp;name, with its type and i/o\-mode\.  
>   
> &nbsp;&nbsp;\[__def__ \[const itemized\]\]  
>   
> &nbsp;&nbsp;\(\[cmd item\]\)  
> &nbsp;&nbsp;This opens a general itemized list\.  
>   
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__def__ \[const tkoption\]\]  
>   
> &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

Changes to embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md.

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
...
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
...
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
...
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
...
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
...
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
...
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
...
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
...
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
...
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
...
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
...
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
...
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
    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
................................................................................
    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 \{__  
    >    __\-title__ "Itinerary selection"  
    >    __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\}  
    >    \.\.\.  
    >    __\-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__ \\  
>    \-title "Itinerary selection"  
>    \.\.\.  

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 \\  
>    __\-<argument\_name>__ *string* \\  
>    \.\.\.  

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 \\  
>    __\-title__ "System configuration" \\  
>    \.\.\.  

  - \-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 \\  
>    __\-window__ \.dialog \\  
>    \.\.\.  

  - \-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 \\  
>    __\-parent__ \.my\_appl \\  
>    \.\.\.  

  - \-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 \\  
>    __\-context__ destination\_definitions \\  
>    \.\.\.  

## <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 \\  
>    \.\.\.  
>    __\-<argument\_name>__ \{ *  
>       ?\-<attribute\_name> <attribute\_value>?  
>       ?\-<attribute\_name> <attribute\_value>?  
>       ?\.\.\.?*  
>    \}  
>    \.\.\.  

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
................................................................................
      * \-label *string*

        An optional frame label can be specified with the *\-label* statement\.

    Example:

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

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

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

  - \-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 \\  
>    \.\.\.  
>    __\-sep__ \{\}  
>    \.\.\.  

  - \-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 \\  
>    \.\.\.  
>    __\-comment__ \{*\-text "Specify bellow the destination address"*\}  
>    \.\.\.  

  - \-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 \\  
>    \.\.\.  
>    __\-yscroll__ __auto__  
>    \.\.\.  

## <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 \\  
>    \-entry \{\-label "Your comment" \-variable YourCom\} \\  
>    __\-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 \\  
>    \.\.\.  
>    __\-<argument\_name>__ \{ *  
>       ?\-<attribute\_name> <attribute\_value>?  
>       ?\-<attribute\_name> <attribute\_value>?  
>       ?\.\.\.?*  
>    \}  
>    \.\.\.  

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 \\  
>    __\-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 \\  
>    __\-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 \\  
>    __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\  
>                \-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 \\  
>    __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\  
>               \-choices \{bold italic underline\} \\  
>               \-choicelabels \{Bold Italic Underline\} \\  
>               \-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*
................................................................................
    *\-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 \\  
>    __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\  
>               \-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 \\  
>    __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\  
>               \-choices \{left center right\} \\  
>               \-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 \\  
>    __\-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 \\  
>    __\-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 \\  
>    __\-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 \\  
>    __\-listbox__ \{\-label "Distance" \-variable Distance \\  
>              \-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 \\  
>    __\-listbox__ \{\-label "Text styles" \-variable Styles \\  
>              \-choices \{bold italic underline overstrike\} \\  
>              \-choicelabels \{Bold Italic Underline Overstrike\} \\  
>              \-default \{bold underline\} \-multiple\_selection 1 \\  
>              \-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 \\  
>    __\-disjointlistbox__ \{\-label "Preferred scripting languages" \-variable Languages \\  
>              \-comment "Please select your preferred languages in the order" \\  
>              \-choices \{JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl\} \\  
>              \-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 \\  
>    __\-file__ \{\-label "Image file" \-variable ImageF \\  
>           \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\  
>           \-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 \\  
>    __\-existingfile__ \{\-label "Image file" \-variable ImageF \\  
>                   \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\  
>                   \-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 \\  
>    __\-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 \\  
>    __\-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 \\  
>    __\-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 \\  
>    \-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 \\  
>    \-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 \\  
>    \-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 \\  
>    \-checkbox \{\-label "Font sytle" \-variable FontStyle \\  
>                \-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 \\  
>    \-entry \{\-label "City" \-variable start\_city \-type string\} \\  
>    \-entry \{\-label "Street" \-variable start\_street \-type string __\-optional 0__\} \\  
>    \-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 \\  
>    __\-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 \\  
>    \-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 \\  
>    \-entry \{\-label "Your comment" \-variable YourCom \\  
>            __\-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__&#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 \\  
>    \-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 ""\}\} \{  
>    *upvar Option Option; \# if required*  
>    *variable argument\_dialogbox; \# if required*  
>    switch $Command \{  
>       "create" <CreateCommandSequence>  
>       "set\_choice" <SetChoiceCommandSequence>  
>       "set" <SetCommandv>  
>       "get" <GetCommandSequence>  
>    \}  
> \}  

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







|
|
|
|
|
|
|
|
|
|
|
|
|
|







 







|
|
|
|











|
|







 







|
|









|
|







|
|








|
|










|
|












|
|
|
|
|
|
|







 







|
|
|





|
|
|








|
|
|










|
|
|










|
|
|












|
|







 







|
|
|
|
|
|
|







 







|







|









|
|





|
|
|
|







 







|
|





|
|
|










|












|





|







 







|
|





|
|
|
|
|







 







|
|
|
|







 







|
|
|










|
|
|









|










|











|







 







|
|
|











|







|








|









|
|












|
|
|







 







|











|









|
|







 







|
|







|
|
|









|








|
|
|











|
|









|











|











|
|












|
|
|
|
|
|
|
|







78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
...
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
...
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
...
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
...
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
...
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
...
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
...
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
...
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
...
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
...
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
...
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
...
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
    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__ \\  
    > &nbsp;&nbsp;&nbsp;__\-title__ "Itinerary selection" \\  
    > &nbsp;&nbsp;&nbsp;__\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} \\  
    > &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Itinerary start"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify your itinerary start location"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "City" \-variable start\_city \-type string*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street" \-variable start\_street \-type string \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Itinerary destination"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify your itinerary destination"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;__\-frame__ \{\} \\  
    > &nbsp;&nbsp;&nbsp;__\-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
................................................................................
    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
................................................................................
      * \-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
................................................................................

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

Changes to embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md.

240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
...
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
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:

> *     <01>*  
> *<03> <20s>*   NAME*<20e>*  
> *     <30s>*       message\_box \- Displays text in a message box*<30e>*  
> *     <20s>*   SYNOPSYS*<20e>*  
> *     <40s>*       message\_box \[\-mtype <mtype>\] <text>*<40e>*  
> *     <20s>*   DESCRIPTION*<20e>*  
> *     <21s>     message\_box<21e>*  
> *     <54s>       message\_box \[\-mtype <mtype>\] <text><54e>*  
> *     <50s>*       This procedure allows displaying a text in an message box\. The following  
> *          *       message types are supported:*<50e>*  
> *<51> <53s>*       \* Info*<53e>*  
> *     <53s>*       \* Warning*<53e>*  
> *     <53s>*       \* Error*<53e>*                                           *<52>*  
> *     <50s>*       If the text parameter is use multiple times the different texts are  
> *          *       concatenated to create the message text\.*<50e>*  
> *     <20s>*   ARGUMENTS*<20e>*  
> *<60> <62s>*       \[\-mtype <mtype>\]*<62e>*  
> *<63> <65s>*          Message type*<65e>*  
> *     <66s>*          Default: "Warning"*<66e>*  
> *     <66s>*          Multiple: yes*<66e>*  
> *     <66s>*          Choices: Info, Warning, Error*<66e>*                  *<64>*  
> *     <62s>*       <text>*<62e>*  
> *<63> <65s>*          One or multiple text lines to display*<65e>*  
> *     <66s>*          Type: string*<66e>*  
> *     <66s>*          Multiple: yes*<66e>*                                  *<64><61>*  
> *     <20s>*   EXAMPLE*<20e>*  
> *<70> <72s>*       message\_box "Please save first the document"*<72e>*  
> *     <73s>*       \-> 1*<73e>*                                              *<71><04>*  
> *     <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>  
>   <head>  
>     <title>tepam::doc\_gen</title>  
>     <link rel="stylesheet" href="tepam\_doc\_stylesheet\.css">  
>     <meta content="documentation" name="keywords"></meta>  
>   </head>  
>   <body>  
>     <h1>tepam::doc\_gen</h1>  
>       <h2>Generate</h2>  
> __\{\*tepam::doc\_gen::generate\*\}__  
>       <h2>Patch</h2>  
> __\{\*tepam::doc\_gen::patch\*\}__  
>   </body>  
> <html>\\  
> \}  
> **  
> *\# Patch the master document: This will replace the placeholders by the   
> \# procedure documentation divisions:*  
> __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\  
>                       \-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)







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|







 







|
|
|
|
|
|
|
|

|

|






|







240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
...
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
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)

Changes to embedded/md/tcllib/files/modules/tepam/tepam_introduction.md.

131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
...
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
...
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
...
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
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:  
>      mtype=Warning  
>      font=Arial 10 italic  
>      fg=black  
>      no\_border=0  
>      text=\{The document hasn't yet been saved\!\}*  
>   
> __display message__ \-fg red \-bg black "Please save first the document"  
> *\-> display message:  
>      mtype=Warning  
>      font=Arial 10 italic  
>      fg=red  
>      bg=black  
>      no\_border=0  
>      text=\{Please save first the document\}*  
>   
> __display message__ \-mtype Error \-no\_border "Why is here no border?"  
> *\-> display message:  
>      mtype=Error  
>      font=Arial 10 italic  
>      fg=black  
>      no\_border=1  
>      text=\{Why is here no border?\}*  
>   
> __display message__ \-font \{Courier 12\} \-level 10 \\  
>    "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"} {






|
|
|
|
|
|
|
|
|
|
|
|
|


|
|
|
|
|







 







|
|
|
|
|



|
|
|
|
|
|



|
|
|
|
|


|







 







|
|
|







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|







131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
...
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
...
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
...
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
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\} \{  
> &nbsp;&nbsp;&nbsp;\-return            \-  
> &nbsp;&nbsp;&nbsp;\-short\_description "Displays a simple message box"  
> &nbsp;&nbsp;&nbsp;\-description       "This procedure allows displaying a configurable message box\."  
> &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 \-default black \-description "Message color"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-bg \-type color \-optional \-description "Background color"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\}  
> &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;\}  
> \} \{  
> *   puts "display message:"  
> &nbsp;&nbsp;&nbsp;foreach var \{mtype font level fg bg no\_border log\_file text\} \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if \{\[info exists $var\]\} \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;puts  "  $var=\[set $var\]"  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\}  
> &nbsp;&nbsp;&nbsp;\}  
> *\}  

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)__ \\  
> &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
................................................................................
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)__ \\  
> &nbsp;&nbsp;&nbsp;__\-title__ "System configuration" \\  
> &nbsp;&nbsp;&nbsp;__\-context__ test\_1 \\  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\-label "Entries"\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{\-label Entry1 \-variable Entry1\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{\-label Entry2 \-variable Entry2 \-default "my default"\} \\  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\-label "Listbox & combobox"\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-listbox__ \{\-label "Listbox, single selection" \-variable Listbox1 \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{1 2 3 4 5 6 7 8\} \-default 1 \-height 3\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-listbox__ \{\-label "Listbox, multiple selection" \-variable Listbox2  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicevariable ChoiceList \-default \{"Choice 2" "Choice 3"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-multiple\_selection 1 \-height 3\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-disjointlistbox__ \{\-label "Disjoined listbox" \-variable DisJntListbox  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choicevariable ChoiceList \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default \{"Choice 3" "Choice 5"\} \-height 3\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-combobox__ \{\-label "Combobox" \-variable Combobox \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{1 2 3 4 5 6 7 8\} \-default 3\} \\  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\-label "Checkbox, radiobox and checkbutton"\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-checkbox__ \{\-label Checkbox \-variable Checkbox  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default italic\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-radiobox__ \{\-label Radiobox \-variable Radiobox  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\-default underline\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-checkbutton__ \{\-label CheckButton \-variable Checkbutton \-default 1\} \\  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\-label "Files & directories"\} \\  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-existingfile__ \{\-label "Input file" \-variable InputFile\} \\  
> &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"} {

Changes to embedded/md/tcllib/files/modules/tepam/tepam_procedure.md.

210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
...
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
...
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
...
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
...
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
...
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
...
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
...
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
...
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
...
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
...
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
....
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
....
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
....
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
__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\} \{  
>    \-short\_description  
>       "Displays a simple message box"  
>    \-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"\}  
>    \-args \{  
>       \{\-mtype \-choices \{Info Warning Error\} \\  
>               \-default Warning \-description "Message type"\}  
>       \{text   \-type string \-multiple \\  
>               \-description "Multiple text lines to display"\}  
>    \}  
> \} \{  
>    puts "Message type: $mtype"  
>    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\} \{  
>    \-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 \-optional \-description "Message color"\}  
>       \{\-log\_file \-type file \-optional \-description "Optional message log file"\}  
>       \{text \-type string \-multiple \-description "Multiple text lines to display"\}  
>    \}__  
> \} \{  
> \}  

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> \{  
>    \-args __\{  
>       \{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a>  <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}  
>       \{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a>  <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}  
>       \.\.\.  
>    \}__  
> \} <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
................................................................................

        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\} \{  
>    \-args \{  
>       \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\}  
>    \}  
> \} \{  
>    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\} \{  
>    \-args \{  
>       \{__\-text__ \-type string \-description "This is a named argument"\}  
>    \}  
> \} \{  
>    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\.

      * *"\#\*"*
................................................................................
        '\#' 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\} \{  
>    \-args \{  
>       \{\-font __\-type font__ \-default \{Arial 10 italic\}\}  
>       \{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\}  
>       \{\-fg __\-type color__ \-optional \-description "Message color"\}  
>       \{text __\-type string__ \-multiple \-description "Multiple text lines to display"\}  
>    \}  
> \} \{  
>    \.\.\.  
> \}  

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 \{  
>    \-args \{  
>       __\{\-flag \-type none \-description "This is a flag"\}__  
>    \}  
> \} \{  
>    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\} \{  
>    \-args \{  
>       \{\-mtype \-choices \{Warning Error\} \-default Warning\}  
>       \{text \-type string \-multiple\}  
>   
>    \}  
> \} \{  
>    puts "args: __$args__"  
> \}  
> display\_message \-mtype Warning "It is 7:00"  
>   

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

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






|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

|
|







 







|
|
|
|

|
|










|
|







 







|
|
|







 







|
|
|
|
|
|
|
|








|
|
|
|
|







 







|
|
|

|







 







|
|
|

|







 







|
|
|
|

|
|
|
|

|







 







|
|
|
|
|

|
|
|
|

|







 







|
|
|







 







|
|
|
|







 







|
|
|
|
|
|

|












|
|
|

|







 







|
|
|
|
|
|

|







 







|
|
|
|
|
|

|







 







|
|
|

|

|







210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
...
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
...
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
...
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
...
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
...
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
...
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
...
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
...
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
...
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
...
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
....
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
....
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
....
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
__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\} \{  
> &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__

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

    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\} \{  
> &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\.
................................................................................

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

        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\} \{  
> &nbsp;&nbsp;&nbsp;\-interactive\_display\_format short  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{hours \-type integer \-description "Hour"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{minutes \-type integer \-description "Minute"\}  
>   
> &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\.

      * *"\#\*"*
................................................................................
        '\#' 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\} \{  
> &nbsp;&nbsp;&nbsp;\-description "This function perform a complex multiplication"  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\{\#\#\#\# First complex number \#\#\#\#\}__  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-r0 \-type double \-description "First number real part"\}  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\{\-i0 \-type double \-description "First number imaginary part"\}  
>   
> &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*
................................................................................
        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\} \{  
> &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\.
................................................................................

        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 \{  
> &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
................................................................................
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 \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &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__  
>   
................................................................................
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 \{  
> &nbsp;&nbsp;&nbsp;\-args \{  
> &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__  
>   
................................................................................
## <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

Changes to embedded/md/tcllib/files/modules/try/tcllib_try.md.

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# <a name='section2'></a>EXAMPLES

Ensure that a file is closed no matter what:

> 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






|
|

|






|

|

|







108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# <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

Changes to idoc/man/files/modules/doctools/doctools.n.

1
2
3
4
5
6
7
8
9
10
11
12
...
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]ers\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5\&.3 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\&.3?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
...
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
'\"
'\" 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

Changes to idoc/www/tcllib/files/modules/doctools/doctools.html.

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
&#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.3 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.3?</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>






|







 







|







103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
&#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>

Changes to modules/doctools/doctools.man.

1
2
3
4
5
6
7
8
9
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5.3]
[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]
|







1
2
3
4
5
6
7
8
9
[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]

Changes to modules/doctools/doctools.tcl.

1354
1355
1356
1357
1358
1359
1360
1361
    # => 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.3






|
1354
1355
1356
1357
1358
1359
1360
1361
    # => 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

Changes to modules/doctools/mpformats/fmt.latex.

15
16
17
18
19
20
21



22
23
24
25
26

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
..
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
..
78
79
80
81
82
83
84



85
86
87
88
89
90
91
...
308
309
310
311
312
313
314
315

316
317

318
319
320
321
322
323
324
325


326
327
328
329
330
331
332
global _in_example
set    _in_example 0

global _has_images
set    _has_images 0




# Called to handle plain text from the input
proc fmt_plain_text {text} {
    global _in_example
    if {$_in_example} {
	

	# NOTE: The example_begin/end combo allows for the example
	# text to contain markup. The currently used verbatim
	# environment will cause show the latex markup of the example,
	# instead of formatting per that markup.
	#
	# TODO: Use a different environment to handle fixed font stuff
	# while allowing for actual markup of parts.
	
	set text [string map [list \\\\\n \\\n] $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

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

    set     hdr ""
................................................................................
    append  hdr \n
    append  hdr "\1\\documentclass\{article\}" \n

    if {$_has_images} {
	append hdr "\1\\usepackage{epsfig}" \n
	append hdr "\1\\usepackage{epstopdf}" \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 _in_example

    set    _in_example 1
    return {\begin{verbatim}}

}
proc fmt_example_end   {} {
    global _in_example
    set    _in_example 0
    return {\end{verbatim}}
}
# No mapping of special characters
proc fmt_example {code} { return "\1\\begin\{verbatim\}\n${code}\n\1\\end\{verbatim\}\n" }



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} {






>
>
>



|
<
>
|
<
<
<
<
<
<
<
|







 







|







 







>
>
>







 







|
>

<
>




|


|
>
>







15
16
17
18
19
20
21
22
23
24
25
26
27
28

29
30







31
32
33
34
35
36
37
38
..
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
..
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
...
307
308
309
310
311
312
313
314
315
316

317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
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 \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} {

Changes to modules/doctools/mpformats/fmt.markdown.

366
367
368
369
370
371
372



















373
374
375
376
377
378
379
...
385
386
387
388
389
390
391
392
393
394
395
396

397
398
399
400
401
402
403
    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
}




















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.
................................................................................
    # 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} {
	set tmp {}
	foreach line [split $t \n] { append tmp $line[LB] }
	set t $tmp
	unset tmp
    } else {

	set t [Mark $t]
    }
    TextClear
    Text $t
    
    set penv [GetCurrent]
    if {$penv != {}} {






>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|
|
|
|

>







366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
    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 "&nbsp;" $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.
................................................................................
    # 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 != {}} {

Changes to modules/doctools/pkgIndex.tcl.

1
2
3
4
5
6
if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools            1.5.3 [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]]
|




1
2
3
4
5
6
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]]

Changes to modules/doctools/tests/fmt/html/26.

119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
<pre class="doctools_example">
Second \
Continuing Lines \
Done
</pre>
<p>............... Vorwaerts ..........</p>
<pre class="doctools_example">
<b class="cmd">command</b> \
-- <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>






|







119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
<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>

Changes to modules/doctools/tests/fmt/latex/04.

1
2
3
4

5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}

\begin{document}
\author{@[email protected]}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
BEGINNE HIER
\begin{verbatim}
	 Example Block  More Lines
\end{verbatim}

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



>

|




|

|

|
|

|






1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
% 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}

Changes to modules/doctools/tests/fmt/latex/08.

1
2
3
4

5
6
7
8
9
10
11
12
13
..
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) **Copyright**
% ALL.a
\documentclass{article}

\begin{document}
\author{@[email protected]}
\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{verbatim}
    THE ARGUMENT IS USED IN THIS
    AND/OR THAT MANNER
\end{verbatim}
\end{itemize}
%
\item[] CMDNAME ...
%
 DESCRIPTION ::{\bf Package}::
%
\item[] CMDNAME ...



>

|







 







|


|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
..
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
% 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 ...

Changes to modules/doctools/tests/fmt/latex/09.

1
2
3
4

5
6
7
8
9
10
11
12
13
14

15
16
17
18
19
20

21
22
23
24
25
26
27
28
29
30
31
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}

\begin{document}
\author{@[email protected]}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
lorem
\begin{verbatim}
1 lorem ipsum dolores
\end{verbatim}
ipsum

\begin{verbatim} 2 lorem ipsum dolores \end{verbatim}
dolores
\begin{verbatim}
3 lorem ipsum dolores
\end{verbatim}
lorem

\begin{verbatim} 4 lorem ipsum dolores
\end{verbatim}
ipsum
\begin{verbatim}
5 lorem ipsum dolores \end{verbatim}
dolores
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}



>

|




|

|

>
|

|

|

>
|
|

|
|






1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
% 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}

Changes to modules/doctools/tests/fmt/latex/13.

1
2
3
4

5
6
7
8
9
10
11
12
13
14

15
16
17
18
19

20
21
22
23
24
25

26
27
28
29
30
31
32
33
34
35
36
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-itemized-examples.1
\documentclass{article}

\begin{document}
\author{@[email protected]}
\title{.MODULE. / test-itemized-examples --  : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item
%

\begin{verbatim} A lorem ipsum dolores \end{verbatim}
%
\item
%
 lorem ipsum dolores

\begin{verbatim} B lorem ipsum dolores \end{verbatim}
lorem ipsum dolores
%
\item
%
 lorem ipsum dolores

\begin{verbatim} C lorem ipsum dolores \end{verbatim}
%
\item
%
 lorem ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}



>

|








>
|




>
|





>
|










1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
% 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}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

Changes to modules/doctools/tests/fmt/latex/14.

1
2
3
4

5
6
7
8
9
10
11
12
13
14

15
16
17
18
19

20
21
22
23
24
25

26
27
28
29
30
31
32
33
34
35
36
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-enumerated-examples.1
\documentclass{article}

\begin{document}
\author{@[email protected]}
\title{.MODULE. / test-enumerated-examples --  : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{enumerate}
%
\item
%

\begin{verbatim} A1 lorem ipsum dolores \end{verbatim}
%
\item
%
 lorem ipsum dolores

\begin{verbatim} B2 lorem ipsum dolores \end{verbatim}
lorem ipsum dolores
%
\item
%
 lorem ipsum dolores

\begin{verbatim} C3 lorem ipsum dolores \end{verbatim}
%
\item
%
 lorem ipsum dolores
\end{enumerate}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}



>

|








>
|




>
|





>
|










1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
% 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}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

Changes to modules/doctools/tests/fmt/latex/15.

1
2
3
4

5
6
7
8
9
10
11
12
13
14

15
16
17
18
19

20
21
22
23
24
25

26
27
28
29
30
31
32
33
34
35
36
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-definition-examples.1
\documentclass{article}

\begin{document}
\author{@[email protected]}
\title{.MODULE. / test-definition-examples --  : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item[] lorem
%

\begin{verbatim} A1 lorem ipsum dolores \end{verbatim}
%
\item[] lorem
%
 ipsum dolores

\begin{verbatim} B2 lorem ipsum dolores \end{verbatim}
lorem ipsum dolores
%
\item[] lorem
%
 ipsum dolores

\begin{verbatim} C3 lorem ipsum dolores \end{verbatim}
%
\item[] lorem
%
 ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}



>

|








>
|




>
|





>
|










1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
% 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}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}

Changes to modules/doctools/tests/fmt/latex/25.

1
2
3
4

5
6
7
8
9
10
11
12
13
14
15
16
17
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}

\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
\begin{verbatim}
Special markdown __non-special__
\end{verbatim}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}



>





|

|





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
% 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}

Changes to modules/doctools/tests/fmt/latex/26.

1
2
3
4

5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}

\begin{document}
\author{aku}
\title{.MODULE. / TEST --  : }
\maketitle
\section{Description}\label{section1}
\begin{verbatim}
Example Block  More Lines \
Ever More
Never
\end{verbatim}

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

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



>





|
|


|



|
|
|

|

|
|

|





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
% 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}

Changes to modules/doctools/tests/fmt/man/26.

13
14
15
16
17
18
19
20
21
22
23
[example_begin]
Second \
Continuing Lines \\
Done
[example_end]
............... Vorwaerts ..........
[example_begin]
[cmd command] \\
-- [cmd command] --
[example_end]
[manpage_end]






|



13
14
15
16
17
18
19
20
21
22
23
[example_begin]
Second \
Continuing Lines \\
Done
[example_end]
............... Vorwaerts ..........
[example_begin]
   [cmd command]    x \\
-- [cmd command] --
[example_end]
[manpage_end]

Changes to modules/doctools/tests/fmt/markdown/26.

26
27
28
29
30
31
32
33
34
35
36
37
38
39
    Second \
    Continuing Lines \
    Done

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

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

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

Copyright &copy; \.COPYRIGHT\.






|






26
27
28
29
30
31
32
33
34
35
36
37
38
39
    Second \
    Continuing Lines \
    Done

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

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

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

Copyright &copy; \.COPYRIGHT\.

Changes to modules/doctools/tests/fmt/nroff/26.

293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
Done

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


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

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

.fi






|








293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
Done

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


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

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

.fi

Changes to modules/doctools/tests/fmt/text/26.

19
20
21
22
23
24
25
26
27
28
29
30
31
32
| Second \
| Continuing Lines \
| Done

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

| command \
| -- command --

COPYRIGHT
=========

Copyright (c) .COPYRIGHT.






|






19
20
21
22
23
24
25
26
27
28
29
30
31
32
| Second \
| Continuing Lines \
| Done

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

| command    x \
| -- command --

COPYRIGHT
=========

Copyright (c) .COPYRIGHT.

Changes to modules/doctools/tests/fmt/tmml/26.

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
Continuing Lines \
Done

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

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

</example>
</section>



</manpage>






|








30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
Continuing Lines \
Done

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

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

</example>
</section>



</manpage>

Changes to modules/doctools/tests/fmt/wiki/26.

22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
Continuing Lines \
Done

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

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

======


**COPYRIGHT**

 Copyright (c) .COPYRIGHT.






|








22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
Continuing Lines \
Done

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

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

======


**COPYRIGHT**

 Copyright (c) .COPYRIGHT.