Tcl Library Source Code

Check-in [be90a82c61]
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: - Better handling of continuation lines protected against Tcl substitution in the input. I.e. "\\n" written as "\\\n". Detect and convert this form into something which will look like a normal continuation line in the output. - Fixed situations where \1 characters slipped into the generated markdown. The relevant examples are now formatted as block quotes instead of code blocks. Price paid is loss of indentation. Might be fixable with the insertion of non-breaking spaces. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.3 B (html, latex, markdown, nroff, text, tmml, wiki) T (html, latex, markdown, nroff, text, tmml, wiki)
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: be90a82c61c172fa61bc97f6c53bfada52c9d473f48abd0926a14abc1921ed90
User & Date: aku 2019-04-11 06:44:36
Context
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
06:44
Doctools: - Better handling of continuation lines protected against Tcl substitution in the input. I.e. "\\n" written as "\\\n". Detect and convert this form into something which will look like a normal continuation line in the output. - Fixed situations where \1 characters slipped into the generated markdown. The relevant examples are now formatted as block quotes instead of code blocks. Price paid is loss of indentation. Might be fixable with the insertion of non-breaking spaces. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.3 B (html, latex, markdown, nroff, text, tmml, wiki) T (html, latex, markdown, nroff, text, tmml, wiki) check-in: be90a82c61 user: aku tags: trunk
03:16
imap4 Tkt [e1b2ade141] D - Added category information (Networking). check-in: 5ed7010be0 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

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

76
77
78
79
80
81
82
83
84
85
86
87
88
89


90
91
92
93
94
95
96
...
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141


142
143
144
145
146
147
148
__\-post__\-body, respectively\.

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
section it is necessary to know a bit more about how bench actually measures the
speed of the the __\-body__\.
................................................................................
example we used above to demonstrate the necessity for the advanced
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
*bench language specfication*\. It will also serve as the detailed
specification and cheat sheet for all available commands and their syntax\.






|
|
|
|
|
|
<
>
>







 







|
|
|
|
|
|
|
<
>
>







76
77
78
79
80
81
82
83
84
85
86
87
88

89
90
91
92
93
94
95
96
97
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141

142
143
144
145
146
147
148
149
150
__\-post__\-body, respectively\.

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
section it is necessary to know a bit more about how bench actually measures the
speed of the the __\-body__\.
................................................................................
example we used above to demonstrate the necessity for the advanced
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
*bench language specfication*\. It will also serve as the detailed
specification and cheat sheet for all available commands and their syntax\.

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
LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth






|
|
|
|
|
|
|
|
>







391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
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
LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth

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

59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
..
75
76
77
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
106
107
108
109
110
111
112
113

114
115
116
117
118
119
120
...
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
...
162
163
164
165
166
167
168
169
170
171
172
173

174
175
176
177
178
179
180
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [key {markup language}] ...

    ... [manpage thefile \\
            {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in docidx is

    [index_begin GROUPTITLE TITLE]
................................................................................

Not very useful, but valid\. This also shows us that all docidx documents consist
of only one part where we will list all keys and their references\.

A more useful index will contain at least keywords, or short 'keys', i\.e\. the
phrases which were indexed\. So:

    [index_begin GROUPTITLE TITLE]
    [__key markup__]
    [__key {semantic markup}]__]
    [__key {docidx markup}__]
    [__key {docidx language}__]
    [__key {docidx commands}__]
    [index_end]


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

However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords\. Here is a
made\-up index for all the manpages in the module
*[base64](\.\./\.\./\.\./\.\./index\.md\#base64)*:

    [index_begin tcllib/base64 {De- & Encoding}]
    [key base64]
    [__manpage base64__]
    [key encoding]
    [__manpage base64__]
    [__manpage uuencode__]
    [__manpage yencode__]
    [key uuencode]
    [__manpage uuencode__]
    [key yEnc]
    [__manpage yencode__]
    [key ydecode]
    [__manpage yencode__]
    [key yencode]
    [__manpage yencode__]
    [index_end]


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

The other command to insert references is
................................................................................
to be used before the __index\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

    [__include FILE__]
    [__vset VAR VALUE__]
    [index_begin GROUPTITLE TITLE]
    ...
    [index_end]


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

    [index_begin GROUPTITLE TITLE]
    [__include FILE__]
    [__vset VAR VALUE__]
    ...
    [index_end]


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

................................................................................
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\.
From here on out the *[docidx language command






|







 







|
|
|
|
|
|
|
>









|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>







 







|
|
|
|
|
>




|
|
|
|
|
>







 







|
|
|
|
|
>







59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
..
75
76
77
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
...
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
...
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [key {markup language}] ...

    ... [manpage thefile \
            {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in docidx is

    [index_begin GROUPTITLE TITLE]
................................................................................

Not very useful, but valid\. This also shows us that all docidx documents consist
of only one part where we will list all keys and their references\.

A more useful index will contain at least keywords, or short 'keys', i\.e\. the
phrases which were indexed\. So:

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

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

However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords\. Here is a
made\-up index for all the manpages in the module
*[base64](\.\./\.\./\.\./\.\./index\.md\#base64)*:

> \[index\_begin tcllib/base64 \{De\- & Encoding\}\]  
> \[key base64\]  
> \[__manpage base64__\]  
> \[key encoding\]  
> \[__manpage base64__\]  
> \[__manpage uuencode__\]  
> \[__manpage yencode__\]  
> \[key uuencode\]  
> \[__manpage uuencode__\]  
> \[key yEnc\]  
> \[__manpage yencode__\]  
> \[key ydecode\]  
> \[__manpage yencode__\]  
> \[key yencode\]  
> \[__manpage yencode__\]  
> \[index\_end\]  
>   

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

The other command to insert references is
................................................................................
to be used before the __index\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

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

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

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

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

................................................................................
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\.
From here on out the *[docidx language command

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

63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
..
98
99
100
101
102
103
104
105
106
107
108
109
110
111

112
113
114
115
116
117
118
...
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
219
220

221
222
223
224
225
226
227
...
232
233
234
235
236
237
238
239
240
241
242
243

244
245
246
247
248
249
250
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [division_start {Appendix 1}] ...

    ... [item thefile \\
            label {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in doctoc is

    [toc_begin GROUPTITLE TITLE]
................................................................................
Symbolic names are used to preserve the convertibility of this format to any
output format\. The actual name of any file will be inserted by the chosen
formatting engine when converting the input, based on a mapping from symbolic to
actual names given to the engine\.

Here a made up example for a table of contents of this document:

    [toc_begin Doctoc {Language Introduction}]
    [__item 1 DESCRIPTION__]
    [__item 1.1 {Basic structure}__]
    [__item 1.2 Items__]
    [__item 1.3 Divisions__]
    [__item 2 {FURTHER READING}__]
    [toc_end]


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

One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1\.
................................................................................

  - __division\_end__

    This command closes the last opened and not yet closed division\.

Using this we can recast the last example like this

    [toc_begin Doctoc {Language Introduction}]
    [__division_start DESCRIPTION__]
    [item 1 {Basic structure}]
    [item 2 Items]
    [item 3 Divisions]
    [__division_end__]
    [__division_start {FURTHER READING}__]
    [__division_end__]
    [toc_end]


Or, to demonstrate deeper nesting

    [toc_begin Doctoc {Language Introduction}]
    [__division_start DESCRIPTION__]
    [__division_start {Basic structure}__]
    [item 1 Do]
    [item 2 Re]
    [__division_end__]
    [__division_start Items__]

    [item a Fi]
    [item b Fo]
    [item c Fa]
    [__division_end__]
    [__division_start Divisions__]
    [item 1 Sub]
    [item 1 Zero]
    [__division_end__]
    [__division_end__]
    [__division_start {FURTHER READING}__]
    [__division_end__]
    [toc_end]


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

    [toc_begin Doctoc {Language Introduction}]
    [item 1 Do]
    [__division_start DESCRIPTION__]
    [__division_start {Basic structure}__]
    [item 2 Re]
    [__division_end__]
    [item a Fi]
    [__division_start Items__]

    [item b Fo]
    [item c Fa]
    [__division_end__]
    [__division_start Divisions__]
    [__division_end__]
    [__division_end__]
    [__division_start {FURTHER READING}__]
    [__division_end__]
    [toc_end]


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

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

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

    [__include FILE__]
    [__vset VAR VALUE__]
    [toc_begin GROUPTITLE TITLE]
    ...
    [toc_end]


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

    [toc_begin GROUPTITLE TITLE]
    [__include FILE__]
    [__vset VAR VALUE__]
    ...
    [toc_end]


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

................................................................................
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\.
From here on out the *[doctoc language command






|







 







|
|
|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
|
|
>


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



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











|
|
|
|
|
>




|
|
|
|
|
>







 







|
|
|
|
|
>







63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
..
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
...
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
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
...
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [division_start {Appendix 1}] ...

    ... [item thefile \
            label {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in doctoc is

    [toc_begin GROUPTITLE TITLE]
................................................................................
Symbolic names are used to preserve the convertibility of this format to any
output format\. The actual name of any file will be inserted by the chosen
formatting engine when converting the input, based on a mapping from symbolic to
actual names given to the engine\.

Here a made up example for a table of contents of this document:

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

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

One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1\.
................................................................................

  - __division\_end__

    This command closes the last opened and not yet closed division\.

Using this we can recast the last example like this

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__division\_start DESCRIPTION__\]  
> \[item 1 \{Basic structure\}\]  
> \[item 2 Items\]  
> \[item 3 Divisions\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]  
>   

Or, to demonstrate deeper nesting

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__division\_start DESCRIPTION__\]  
> \[__division\_start \{Basic structure\}__\]  
> \[item 1 Do\]  
> \[item 2 Re\]  
> \[__division\_end__\]  

> \[__division\_start Items__\]  
> \[item a Fi\]  
> \[item b Fo\]  
> \[item c Fa\]  
> \[__division\_end__\]  
> \[__division\_start Divisions__\]  
> \[item 1 Sub\]  
> \[item 1 Zero\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]  
>   

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

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[item 1 Do\]  
> \[__division\_start DESCRIPTION__\]  
> \[__division\_start \{Basic structure\}__\]  
> \[item 2 Re\]  
> \[__division\_end__\]  
> \[item a Fi\]  

> \[__division\_start Items__\]  
> \[item b Fo\]  
> \[item c Fa\]  
> \[__division\_end__\]  
> \[__division\_start Divisions__\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]  
>   

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

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

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

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

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

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

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

................................................................................
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\.
From here on out the *[doctoc language command

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

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

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

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

143
144
145
146
147
148
149
...
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
...
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
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
...
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
404
405
406
407

408
409
410
411
412
413
414
...
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446

447
448
449
450
451
452
453
...
459
460
461
462
463
464
465
466
467
468

469
470
471
472
473
474

475
476
477
478
479
480
481
...
530
531
532
533
534
535
536
537
538
539
540
541
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
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [list_begin enumerated] ...

    ... [call [cmd foo] \\
            [arg bar]] ...

    ... [term {complex concept}] ...

    ... [opt "[arg key] [arg value]"] ...

## <a name='subsection2'></a>Basic structure
................................................................................
and they can be used in any order\. However for __titledesc__ and
__moddesc__ only the last occurrence is taken\. For the other two the
specified information is accumulated, in the given order\. Regular text is not
allowed within the header\.

Given the above a less minimal example of a document is

    [manpage_begin NAME SECTION VERSION]
    [__copyright {YEAR AUTHOR}__]
    [__titledesc TITLE__]
    [__moddesc   MODULE_TITLE__]
    [__require   PACKAGE VERSION__]
    [__require   PACKAGE__]
    [description]
    [manpage_end]


Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
................................................................................
has the same meaning as the example before\.

On the other hand, if *whitespace* is present it consists not only of any
sequence of characters containing the space character, horizontal and vertical
tabs, carriage return, and newline, but it may contain comment markup as well,
in the form of the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ command\.

    [__comment { ... }__]
    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}]
    [titledesc TITLE]
    [moddesc   MODULE_TITLE][__comment { ... }__]
    [require   PACKAGE VERSION]
    [require   PACKAGE]
    [description]
    [manpage_end]
    [__comment { ... }__]


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

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

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the document\. I\.e\. it is possible to write

    [__include FILE__]
    [__vset VAR VALUE__]
    [manpage_begin NAME SECTION VERSION]
    [description]
    [manpage_end]


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

    [manpage_begin NAME SECTION VERSION]
    [__include FILE__]
    [__vset VAR VALUE__]
    [description]
    [manpage_end]


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

................................................................................
The simplest way of structuring the body is through the introduction of
paragraphs\. The command for doing so is __para__\. Each occurrence of this
command closes the previous paragraph and automatically opens the next\. The
first paragraph is automatically opened at the beginning of the body, by
__description__\. In the same manner the last paragraph automatically ends at
__manpage\_end__\.

    [manpage_begin NAME SECTION VERSION]
    [description]
     ...
    [__para__]
     ...
    [__para__]
     ...
    [manpage_end]


Empty paragraphs are ignored\.

A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces\. The command for doing so is
__section__\. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph\. The first section
................................................................................
is automatically opened at the beginning of the body, by __description__
\(This section is labeled "DESCRIPTION"\)\. In the same manner the last section
automatically ends at __manpage\_end__\.

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

    [manpage_begin NAME SECTION VERSION]
    [description]
     ...
    [__section {Section A}__]
     ...
    [para]
     ...
    [__section {Section B}__]
     ...
    [manpage_end]


Between sections and paragraphs we have subsections, to split sections\. The
command for doing so is __subsection__\. Each occurrence of this command
closes the previous subsection and automatically opens the next, including its
first paragraph\. A subsection is automatically opened at the beginning of the
body, by __description__, and at the beginning of each section\. In the same
manner the last subsection automatically ends at __manpage\_end__\.

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

    [manpage_begin NAME SECTION VERSION]
    [description]
     ...
    [section {Section A}]
     ...
    [__subsection {Sub 1}__]
     ...
    [para]
     ...
    [__subsection {Sub 2}__]
     ...
    [section {Section B}]
     ...
    [manpage_end]


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

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

While most often this is just the unadorned content of the document we do have
................................................................................
    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
take an arbitrary number of arguments, all of which have to be plain unmarked
................................................................................
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
have markup within an example we have to use the 2\-command combination
................................................................................
embed examples and lists within an example\. On the other hand, we *can* use
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
this in turn determines which of the eight existing list item commands are
................................................................................
    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
well\. From here on out the *[doctools language command






|







 







|
|
|
|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
|
|
>











|
|
|
|
|
>





|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
|
|
>











|
|
|
|
|
|
|
|
|
|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
>













|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
>







 







|
|
|
>



|
|
|
>







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>




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







68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
...
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
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
...
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
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
...
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
423
...
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
...
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
...
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
593
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [list_begin enumerated] ...

    ... [call [cmd foo] \
            [arg bar]] ...

    ... [term {complex concept}] ...

    ... [opt "[arg key] [arg value]"] ...

## <a name='subsection2'></a>Basic structure
................................................................................
and they can be used in any order\. However for __titledesc__ and
__moddesc__ only the last occurrence is taken\. For the other two the
specified information is accumulated, in the given order\. Regular text is not
allowed within the header\.

Given the above a less minimal example of a document is

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

Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
................................................................................
has the same meaning as the example before\.

On the other hand, if *whitespace* is present it consists not only of any
sequence of characters containing the space character, horizontal and vertical
tabs, carriage return, and newline, but it may contain comment markup as well,
in the form of the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ command\.

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

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

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

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the document\. I\.e\. it is possible to write

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

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

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

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

................................................................................
The simplest way of structuring the body is through the introduction of
paragraphs\. The command for doing so is __para__\. Each occurrence of this
command closes the previous paragraph and automatically opens the next\. The
first paragraph is automatically opened at the beginning of the body, by
__description__\. In the same manner the last paragraph automatically ends at
__manpage\_end__\.

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

Empty paragraphs are ignored\.

A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces\. The command for doing so is
__section__\. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph\. The first section
................................................................................
is automatically opened at the beginning of the body, by __description__
\(This section is labeled "DESCRIPTION"\)\. In the same manner the last section
automatically ends at __manpage\_end__\.

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

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
>  \.\.\.  
> \[__section \{Section A\}__\]  
>  \.\.\.  
> \[para\]  
>  \.\.\.  
> \[__section \{Section B\}__\]  
>  \.\.\.  
> \[manpage\_end\]  
>   

Between sections and paragraphs we have subsections, to split sections\. The
command for doing so is __subsection__\. Each occurrence of this command
closes the previous subsection and automatically opens the next, including its
first paragraph\. A subsection is automatically opened at the beginning of the
body, by __description__, and at the beginning of each section\. In the same
manner the last subsection automatically ends at __manpage\_end__\.

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

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
>  \.\.\.  
> \[section \{Section A\}\]  
>  \.\.\.  
> \[__subsection \{Sub 1\}__\]  
>  \.\.\.  
> \[para\]  
>  \.\.\.  
> \[__subsection \{Sub 2\}__\]  
>  \.\.\.  
> \[section \{Section B\}\]  
>  \.\.\.  
> \[manpage\_end\]  
>   

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

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

While most often this is just the unadorned content of the document we do have
................................................................................
    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
take an arbitrary number of arguments, all of which have to be plain unmarked
................................................................................
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
have markup within an example we have to use the 2\-command combination
................................................................................
embed examples and lists within an example\. On the other hand, we *can* use
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
this in turn determines which of the eight existing list item commands are
................................................................................
    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
well\. From here on out the *[doctools language command

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md.

135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                            |                         |     |    |                  |
                    doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                            docidx                    |     |    |                  docidx, json
                            json                      |     |    |                  |           \\
                            html                      |     |    |          doctools::idx::parse \\
                            nroff                     |     |    |                  |             \\
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::idx::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat






|
|
|







135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                            |                         |     |    |                  |
                    doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                            docidx                    |     |    |                  docidx, json
                            json                      |     |    |                  |           \
                            html                      |     |    |          doctools::idx::parse \
                            nroff                     |     |    |                  |             \
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::idx::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md.

135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                            |                         |     |    |                  |
                    doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                            doctoc                    |     |    |                  doctoc, json
                            json                      |     |    |                  |           \\
                            html                      |     |    |          doctools::toc::parse \\
                            nroff                     |     |    |                  |             \\
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::toc::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat






|
|
|







135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                            |                         |     |    |                  |
                    doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                            doctoc                    |     |    |                  doctoc, json
                            json                      |     |    |                  |           \
                            html                      |     |    |          doctools::toc::parse \
                            nroff                     |     |    |                  |             \
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::toc::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat

Changes to embedded/md/tcllib/files/modules/fileutil/multiop.md.

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
    Returns the current path type limiter\.

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

The following examples assume that the variable __F__ contains a reference
to a multi\-file operation object\.

        $F do copy                       \\
    	the  *.dll                    \\
    	from c:/TDK/PrivateOpenSSL/bin \\
    	to   [installdir_of tls]

        $F do move      \\
    	the  *       \\
    	from /sources \\
    	into /scratch  \\
    	but not *.html

        # Alternatively use 'except for *.html'.

        $F do           \\
    	move         \\
    	the  index    \\
    	from /sources  \\
    	into /scratch   \\
    	as   pkgIndex.tcl

        $F do         \\
    	remove     \\
    	the *.txt  \\
    	in /scratch

Note that the fact that most commands just modify the object state allows us to
use more off forms as specifications instead of just nearly\-natural language
sentences\. For example the second example in this section can re\-arranged into:

        $F do            \\
    	from /sources \\
    	into /scratch  \\
    	but not *.html \\
    	move           \\
    	the  *

and the result is not only still a valid specification, but even stays
relatively readable\.

Further note that the information collected by the commands __but__,
__except__, and __as__ is automatically reset after the associated
__the__ was executed\. However no other state is reset in that manner,
allowing the user to avoid repetitions of unchanging information\. For example
the second and third examples of this section can be merged and rewritten into
the equivalent:

    $F do                   \\
        move                 \\
        the  *                \\
        from /sources          \\
        into /scratch           \\
        but not *.html not index \\
        the  index               \\
        as   pkgIndex.tcl

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *fileutil* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas






|
|
|


|
|
|
|




|
|
|
|
|


|
|
|






|
|
|
|
|












|
|
|
|
|
|
|







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
    Returns the current path type limiter\.

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

The following examples assume that the variable __F__ contains a reference
to a multi\-file operation object\.

        $F do copy                       \
    	the  *.dll                    \
    	from c:/TDK/PrivateOpenSSL/bin \
    	to   [installdir_of tls]

        $F do move      \
    	the  *       \
    	from /sources \
    	into /scratch  \
    	but not *.html

        # Alternatively use 'except for *.html'.

        $F do           \
    	move         \
    	the  index    \
    	from /sources  \
    	into /scratch   \
    	as   pkgIndex.tcl

        $F do         \
    	remove     \
    	the *.txt  \
    	in /scratch

Note that the fact that most commands just modify the object state allows us to
use more off forms as specifications instead of just nearly\-natural language
sentences\. For example the second example in this section can re\-arranged into:

        $F do            \
    	from /sources \
    	into /scratch  \
    	but not *.html \
    	move           \
    	the  *

and the result is not only still a valid specification, but even stays
relatively readable\.

Further note that the information collected by the commands __but__,
__except__, and __as__ is automatically reset after the associated
__the__ was executed\. However no other state is reset in that manner,
allowing the user to avoid repetitions of unchanging information\. For example
the second and third examples of this section can be merged and rewritten into
the equivalent:

    $F do                   \
        move                 \
        the  *                \
        from /sources          \
        into /scratch           \
        but not *.html not index \
        the  index               \
        as   pkgIndex.tcl

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *fileutil* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas

Changes to embedded/md/tcllib/files/modules/grammar_fa/fa.md.

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
...
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
    overwriting any existing definition\. This is the assignment operator for
    automatons\. It copies the automaton contained in the FA object *srcFA*
    over the automaton definition in *faName*\. The old contents of *faName*
    are deleted by this operation\.

    This operation is in effect equivalent to

        *faName* __deserialize__ [*srcFA* __serialize__]


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

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

    This operation is in effect equivalent to

        *dstFA* __deserialize__ [*faName* __serialize__]


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

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

        Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
        (...) is the start state.

    a possible serialization is

        grammar::fa \\
        {yellow red green red/yellow} \\
        {Drive     {0 0 {yellow     Brake}} \\
         Brake     {0 0 {red        Stop}} \\
         Stop      {1 0 {red/yellow Attention}} \\
         Attention {0 0 {green      Drive}}}

    A possible one, because I did not care about creation order here

  - <a name='8'></a>*faName* __deserialize__ *serialization*

    This is the complement to __serialize__\. It replaces the automaton






|
>










|
>







 







|
|
|
|
|







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
...
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
    overwriting any existing definition\. This is the assignment operator for
    automatons\. It copies the automaton contained in the FA object *srcFA*
    over the automaton definition in *faName*\. The old contents of *faName*
    are deleted by this operation\.

    This operation is in effect equivalent to

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

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

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

    This operation is in effect equivalent to

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

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

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

        Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
        (...) is the start state.

    a possible serialization is

        grammar::fa \
        {yellow red green red/yellow} \
        {Drive     {0 0 {yellow     Brake}} \
         Brake     {0 0 {red        Stop}} \
         Stop      {1 0 {red/yellow Attention}} \
         Attention {0 0 {green      Drive}}}

    A possible one, because I did not care about creation order here

  - <a name='8'></a>*faName* __deserialize__ *serialization*

    This is the complement to __serialize__\. It replaces the automaton

Changes to embedded/md/tcllib/files/modules/grammar_peg/peg.md.

219
220
221
222
223
224
225
226

227
228
229
230
231
232
233
234
235
236
237

238
239
240
241
242
243
244
...
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
298
299
300
    overwriting any existing definition\. This is the assignment operator for
    grammars\. It copies the grammar contained in the grammar object *srcPEG*
    over the grammar definition in *pegName*\. The old contents of *pegName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    *pegName* __deserialize__ [*srcPEG* __serialize__]


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

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

    This operation is in effect equivalent to

    *dstPEG* __deserialize__ [*pegName* __serialize__]


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

    This method serializes the grammar stored in *pegName*\. In other words it
    returns a tcl *value* completely describing that grammar\. This allows, for
    example, the transfer of grammars over arbitrary channels, persistence, etc\.
    This method is also the basis for both the copy constructor and the
................................................................................
    MulOp      <- '*' / '/'
    Factor     <- Term (AddOp Term)*
    AddOp      <- '+'/'-'
    Term       <- Number

    a possible serialization is

    grammar::peg \\
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
     Factor     {x Term {* {x AddOp Term}}} \\
     Term       Number \\
     MulOp      {/ * /} \\
     AddOp      {/ + -} \\
     Number     {x {? Sign} {+ Digit}} \\
     Sign       {/ + -} \\
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
    } \\
    {Expression value     Factor     value \\
     Term       value     MulOp      value \\
     AddOp      value     Number     value \\
     Sign       value     Digit      value \\
    }
    Expression

    A possible one, because the order of the nonterminals in the dictionary is
    not relevant\.

  - <a name='7'></a>*pegName* __deserialize__ *serialization*






|
>










|
>







 







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







219
220
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
...
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
    overwriting any existing definition\. This is the assignment operator for
    grammars\. It copies the grammar contained in the grammar object *srcPEG*
    over the grammar definition in *pegName*\. The old contents of *pegName*
    are deleted by this operation\.

    This operation is in effect equivalent to

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

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

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

    This operation is in effect equivalent to

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

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

    This method serializes the grammar stored in *pegName*\. In other words it
    returns a tcl *value* completely describing that grammar\. This allows, for
    example, the transfer of grammars over arbitrary channels, persistence, etc\.
    This method is also the basis for both the copy constructor and the
................................................................................
    MulOp      <- '*' / '/'
    Factor     <- Term (AddOp Term)*
    AddOp      <- '+'/'-'
    Term       <- Number

    a possible serialization is

    grammar::peg \
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \
     Factor     {x Term {* {x AddOp Term}}} \
     Term       Number \
     MulOp      {/ * /} \
     AddOp      {/ + -} \
     Number     {x {? Sign} {+ Digit}} \
     Sign       {/ + -} \
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \
    } \
    {Expression value     Factor     value \
     Term       value     MulOp      value \
     AddOp      value     Number     value \
     Sign       value     Digit      value \
    }
    Expression

    A possible one, because the order of the nonterminals in the dictionary is
    not relevant\.

  - <a name='7'></a>*pegName* __deserialize__ *serialization*

Changes to embedded/md/tcllib/files/modules/mime/smtp.md.

179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# <a name='section3'></a>EXAMPLE

    proc send_simple_message {recipient email_server subject body} {
        package require smtp
        package require mime

        set token [mime::initialize -canonical text/plain \\
    	-string $body]
        mime::setheader $token Subject $subject
        smtp::sendmessage $token \\
    	-recipients $recipient -servers $email_server
        mime::finalize $token
    }

    send_simple_message [email protected] localhost \\
        "This is the subject." "This is the message."

# <a name='section4'></a>TLS Security Considerations

This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to
handle the security for __https__ urls and other socket connections\.







|


|




|







179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# <a name='section3'></a>EXAMPLE

    proc send_simple_message {recipient email_server subject body} {
        package require smtp
        package require mime

        set token [mime::initialize -canonical text/plain \
    	-string $body]
        mime::setheader $token Subject $subject
        smtp::sendmessage $token \
    	-recipients $recipient -servers $email_server
        mime::finalize $token
    }

    send_simple_message [email protected] localhost \
        "This is the subject." "This is the message."

# <a name='section4'></a>TLS Security Considerations

This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to
handle the security for __https__ urls and other socket connections\.

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

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
suitable for POP3 servers which expect SSL connections only\. These will
generally be listening on port 995\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -socketcmd tls::socket \\
    	$thehost $theuser $thepassword

    ...

The second method, option __\-stls__, will connect to the standard POP3 port
and then perform an STARTTLS handshake\. This will only work for POP3 servers
which have this capability\. The package will confirm that the server supports
................................................................................
STARTTLS and the handshake was performed correctly before proceeding with
authentication\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -stls 1 \\
    	$thehost $theuser $thepassword

    ...

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and






|







 







|







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
suitable for POP3 servers which expect SSL connections only\. These will
generally be listening on port 995\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -socketcmd tls::socket \
    	$thehost $theuser $thepassword

    ...

The second method, option __\-stls__, will connect to the standard POP3 port
and then perform an STARTTLS handshake\. This will only work for POP3 servers
which have this capability\. The package will confirm that the server supports
................................................................................
STARTTLS and the handshake was performed correctly before proceeding with
authentication\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -stls 1 \
    	$thehost $theuser $thepassword

    ...

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and

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

258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
The option __\-socket__ \(see [Options](#section2)\) enables users of the
package to override how the server opens its listening socket\. The envisioned
main use is the specification of the __tls::socket__ command, see package
__[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\.

    package require tls
    tls::init \\
    	...

    pop3d::new S -socket tls::socket
    ...

# <a name='section6'></a>References







|







258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
The option __\-socket__ \(see [Options](#section2)\) enables users of the
package to override how the server opens its listening socket\. The envisioned
main use is the specification of the __tls::socket__ command, see package
__[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\.

    package require tls
    tls::init \
    	...

    pop3d::new S -socket tls::socket
    ...

# <a name='section6'></a>References

Changes to embedded/md/tcllib/files/modules/pt/pt_peg_container.md.

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
    This method assigns the contents of the PEG object *source* to ourselves,
    overwriting the existing definition\. This is the assignment operator for
    grammars\.

    This operation is in effect equivalent to

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


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

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

    This operation is in effect equivalent to

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


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

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






|
>









|
>







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
    This method assigns the contents of the PEG object *source* to ourselves,
    overwriting the existing definition\. This is the assignment operator for
    grammars\.

    This operation is in effect equivalent to

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

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

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

    This operation is in effect equivalent to

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

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

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

Changes to embedded/md/tcllib/files/modules/struct/graph.md.

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
219
220
221
222
...
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
    This is the *assignment* operator for graph objects\. It copies the graph
    contained in the graph object *sourcegraph* over the graph data in
    *graphName*\. The old contents of *graphName* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *graphName* __deserialize__ [*sourcegraph* __serialize__]


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

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

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

    This operation is in effect equivalent to

        *destgraph* __deserialize__ [*graphName* __serialize__]


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

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

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

    *Note:* The order of the nodes in the serialization has no relevance, nor
    has the order of the arcs per node\.

        # A possible serialization for the graph structure
        #
        #        d -----> %2
        #       /         ^ \\
        #      /         /   \\
        #     /         b     \\
        #    /         /       \\
        #  %1 <- a - %0         e
        #    ^         \\      /
        #     \\        c     /
        #      \\        \\  /
        #       \\        v v
        #        f ------ %3
        # is






|
>













|
>







 







|
|
|
|







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
219
220
221
222
223
224
...
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
    This is the *assignment* operator for graph objects\. It copies the graph
    contained in the graph object *sourcegraph* over the graph data in
    *graphName*\. The old contents of *graphName* are deleted by this
    operation\.

    This operation is in effect equivalent to

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

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

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

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

    This operation is in effect equivalent to

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

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

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

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

    *Note:* The order of the nodes in the serialization has no relevance, nor
    has the order of the arcs per node\.

        # A possible serialization for the graph structure
        #
        #        d -----> %2
        #       /         ^ \
        #      /         /   \
        #     /         b     \
        #    /         /       \
        #  %1 <- a - %0         e
        #    ^         \\      /
        #     \\        c     /
        #      \\        \\  /
        #       \\        v v
        #        f ------ %3
        # is

Changes to embedded/md/tcllib/files/modules/struct/matrix.md.

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
    This is the assignment operator for matrix objects\. It copies the matrix
    contained in the matrix object *sourcematrix* over the matrix data in
    *matrixName*\. The old contents of *matrixName* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *matrixName* __deserialize__ [*sourcematrix* __serialize__]


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

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

    This operation is in effect equivalent to

        *destmatrix* __deserialize__ [*matrixName* __serialize__]


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

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






|
>










|
>







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
    This is the assignment operator for matrix objects\. It copies the matrix
    contained in the matrix object *sourcematrix* over the matrix data in
    *matrixName*\. The old contents of *matrixName* are deleted by this
    operation\.

    This operation is in effect equivalent to

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

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

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

    This operation is in effect equivalent to

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

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

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

Changes to embedded/md/tcllib/files/modules/struct/struct_tree.md.

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
219
    This is the assignment operator for tree objects\. It copies the tree
    contained in the tree object *sourcetree* over the tree data in
    *treeName*\. The old contents of *treeName* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *treeName* __deserialize__ [*sourcetree* __serialize__]


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

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

    This operation is in effect equivalent to

        *desttree* __deserialize__ [*treeName* __serialize__]


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

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






|
>










|
>







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
219
220
221
    This is the assignment operator for tree objects\. It copies the tree
    contained in the tree object *sourcetree* over the tree data in
    *treeName*\. The old contents of *treeName* are deleted by this
    operation\.

    This operation is in effect equivalent to

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

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

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

    This operation is in effect equivalent to

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

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

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

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

77
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
...
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
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
...
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
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
...
316
317
318
319
320
321
322
323
324
325
326
327
328
329

330
331
332
333
334
335
336
337
...
339
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
...
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
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
...
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
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
...
633
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
...
678
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
794
    been acknowledged \(via the *OK* button\) and validated by a data checker\.
    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
................................................................................
    Sometimes it is simpler to provide all the data entry item definitions in
    form of a single list to __argument\_dialogbox__, and not as individual
    arguments\. The second format that is supported by __argument\_dialogbox__
    corresponds exactly to the first one, except that all item definitions are
    packed into a single list that is provided to __argument\_dialogbox__\.
    The previous example can therefore also be written in the following way:

        set DialogResult [__tepam::argument_dialogbox {__
           __-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
................................................................................
SPECIFIC ENTRY WIDGETS](#section3)\):

  - \-entry *list*

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

    tepam::argument_dialogbox \
       __-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*
................................................................................
    the *\-choices* attribute or via a variable declared with the
    *\-choicevariable* attribute\.

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

    tepam::argument_dialogbox \
       __-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
................................................................................
    If no default font is provided via the *\-default* attribute, the default
    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](tepam\_procedure\.md)__ \(see the
    *tepam::procedure reference manual*\)\.

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

    tepam::argument_dialogbox \
       __-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\.

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






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







 







|
|
|
|
|








|
|
|
|
|













|
|
|








|
|
|






|
|
|







|
|
|









|
|
|











|
|
|
|
|
|
<
>
|







 







|
|
|
|




|
|
|
|







|
|
|
|









|
|
|
|









|
|
|
|











|
|
|







 







|
|
|
|
|
|
<
>
|







 







|
|






|
|








|
|
|




|
|
|
|
|







 







|
|
|




|
|
|
|









|
|











|
|



|
|
|










|
|
|
|
|
|




|
|
|
|
|
|













|
|
|
|
|













|
|
|
|









|
|
|
|








|
|









|
|










|
|







 







|
|
|
|










|
|






|
|







|
|








|
|
|











|
|
|
|







 







|
|










|
|








|
|
|







 







|
|
|






|
|
|
|







|
|
|







|
|
|
|










|
|
|








|
|










|
|










|
|
|











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







77
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
...
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
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
...
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
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
...
316
317
318
319
320
321
322
323
324
325
326
327
328

329
330
331
332
333
334
335
336
337
...
339
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
...
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
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
...
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
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
...
633
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
...
678
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
794
    been acknowledged \(via the *OK* button\) and validated by a data checker\.
    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
................................................................................
    Sometimes it is simpler to provide all the data entry item definitions in
    form of a single list to __argument\_dialogbox__, and not as individual
    arguments\. The second format that is supported by __argument\_dialogbox__
    corresponds exactly to the first one, except that all item definitions are
    packed into a single list that is provided to __argument\_dialogbox__\.
    The previous example can therefore also be written in the following way:

    > set DialogResult \[__tepam::argument\_dialogbox \{__  
    >    __\-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
................................................................................
SPECIFIC ENTRY WIDGETS](#section3)\):

  - \-entry *list*

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

> tepam::argument\_dialogbox \\  
>    __\-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*
................................................................................
    the *\-choices* attribute or via a variable declared with the
    *\-choicevariable* attribute\.

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

> tepam::argument\_dialogbox \\  
>    __\-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
................................................................................
    If no default font is provided via the *\-default* attribute, the default
    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](tepam\_procedure\.md)__ \(see the
    *tepam::procedure reference manual*\)\.

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

> tepam::argument\_dialogbox \\  
>    __\-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\.

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

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
...
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
...
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
548
549
550
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
................................................................................

      * *IsOptional*

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

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

        *"\[mtype\]"*

      * *IsNamed*

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

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

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

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

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

      * *Type*

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

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

        *"\[\-close\]"*

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

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

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

    __tepam::doc_gen::generate__ tepam::doc_gen::generate

The next example generates the documentation in HTML format:

    __tepam::doc_gen::generate__ -format HTML tepam::doc_gen::generate

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

    __tepam::doc_gen::generate__ -format HTML -header_footer tepam::doc_gen::generate

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

    __tepam::doc_gen::generate__ -format HTML -dest_file doc_gen.html tepam::doc_gen::generate

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

The Tcl DOC Tools format can be used as intermediate format to generate other
formats, for example HTML:

    *# Generate the documentation in Tcl Doc Tool format*
    set dt [__tepam::doc_gen::generate__ -format DT -header_footer tepam::doc_gen::generate]
    **
    *# Create a new doc tools object (HTML format)*
    package require doctools
    ::doctools::new myDoc -format html
    **
    *# Open the HTML file, and write the HTML formatted documentation*
    set fHtml [open doc_gen.dt.html w]
    puts $fHtml [myDoc format $dt]
    close $fHtml


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

While __generate__ provides a limited number of possibilities to vary the
document structure, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ offers more
flexibility\. Multiple documentations for different procedures and meta
information can for example be added\.
................................................................................
a HTML master document string that contains 2 procedure documentation
placeholders \(*\{\*<ProcedureName>\*\}*\)\. There placeholders are replaced by
__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ with the generated documentation
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)

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






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







 







|









|



|









|











|



|



|




|









|
|
|
|
|
|
|
|
|
|
|
>







 







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







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
...
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
...
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
548
549
550
551
552
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
................................................................................

      * *IsOptional*

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

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

        *"\[mtype\]"*

      * *IsNamed*

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

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

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

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

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

      * *Type*

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

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

        *"\[\-close\]"*

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

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

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

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

The next example generates the documentation in HTML format:

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

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

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

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

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

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

The Tcl DOC Tools format can be used as intermediate format to generate other
formats, for example HTML:

> *\# Generate the documentation in Tcl Doc Tool format*  
> set dt \[__tepam::doc\_gen::generate__ \-format DT \-header\_footer tepam::doc\_gen::generate\]  
> **  
> *\# Create a new doc tools object \(HTML format\)*  
> package require doctools  
> ::doctools::new myDoc \-format html  
> **  
> *\# Open the HTML file, and write the HTML formatted documentation*  
> set fHtml \[open doc\_gen\.dt\.html w\]  
> puts $fHtml \[myDoc format $dt\]  
> close $fHtml  
>   

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

While __generate__ provides a limited number of possibilities to vary the
document structure, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ offers more
flexibility\. Multiple documentations for different procedures and meta
information can for example be added\.
................................................................................
a HTML master document string that contains 2 procedure documentation
placeholders \(*\{\*<ProcedureName>\*\}*\)\. There placeholders are replaced by
__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ with the generated documentation
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)

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

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

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
...
201
202
203
204
205
206
207
208

209
210
211
212
213
214
215
...
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
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
...
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
...
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
383
384
385
386
387
388
389
390
391
392
393
394
395
396
takes as __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ also 3 arguments: The
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
argument manager generates an error message that explains the reason for the
................................................................................
the named arguments \(Tk style\)\.

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

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

    __display message__ -help


* \-> NAME display message \- Displays a simple message box SYNOPSYS display
message \[\-mtype <mtype>\] : Message type, default: "Warning", choices: \{Info
Warning Error\} \[\-font <font>\] : Message text font, type: font, default: Arial 10
italic \[\-level <level>\] : Message level, type: integer, range: 1\.\.10 \[\-fg <fg>\]
: Message color, type: color, default: black \[\-bg <bg>\] : Background color,
type: color \[\-no\_border \] : Use a splash window style \(no border\) \[\-log\_file
................................................................................
configurable message box\.*

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

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

    __display message__ "The document hasn't yet been saved!"
    *-> display message:
         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:

    __display message__ -font {Courier 12}


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

    __display message__ -category warning Hello


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

    __display message__ -fg MyColor "Hello"


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

    __display message__ -mtype Fatal Hello


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

    __display message__ -level 12 Hello


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

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

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

    __display message__ -interactive

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

After acknowledging the specified argument data via an OK button, the entered
................................................................................
entry forms\. It creates an input mask that allows specifying a file to copy, a
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
................................................................................
expected data types, valid data ranges, etc\.

The next example of a more complex argument dialog box provides a good overview
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"} {






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







 







|
>







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>





|
>




|
>





|
>




|
>




|
>










|







 







|
|
|
|







 







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







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
...
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
...
219
220
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
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
298
299
300
301
302
303
304
...
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
...
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
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
takes as __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ also 3 arguments: The
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
argument manager generates an error message that explains the reason for the
................................................................................
the named arguments \(Tk style\)\.

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

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

> __display message__ \-help  
>   

* \-> NAME display message \- Displays a simple message box SYNOPSYS display
message \[\-mtype <mtype>\] : Message type, default: "Warning", choices: \{Info
Warning Error\} \[\-font <font>\] : Message text font, type: font, default: Arial 10
italic \[\-level <level>\] : Message level, type: integer, range: 1\.\.10 \[\-fg <fg>\]
: Message color, type: color, default: black \[\-bg <bg>\] : Background color,
type: color \[\-no\_border \] : Use a splash window style \(no border\) \[\-log\_file
................................................................................
configurable message box\.*

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

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

> __display message__ "The document hasn't yet been saved\!"  
> *\-> display message:  
>      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:

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

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

> __display message__ \-category warning Hello  
>   

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

> __display message__ \-fg MyColor "Hello"  
>   

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

> __display message__ \-mtype Fatal Hello  
>   

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

> __display message__ \-level 12 Hello  
>   

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

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

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

> __display message__ \-interactive  

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

After acknowledging the specified argument data via an OK button, the entered
................................................................................
entry forms\. It creates an input mask that allows specifying a file to copy, a
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
................................................................................
expected data types, valid data ranges, etc\.

The next example of a more complex argument dialog box provides a good overview
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"} {

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

106
107
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
...
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
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
...
209
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
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
...
284
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
...
363
364
365
366
367
368
369
370
371
372
373
374
375

376
377
378
379
380
381
382
...
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
...
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
...
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
...
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
...
651
652
653
654
655
656
657
658
659
660
661
662
663

664
665
666
667
668
669
670
...
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
...
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
...
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
...
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
...
808
809
810
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
850
851
852
853
...
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
...
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
...
993
994
995
996
997
998
999
1000

1001
1002
1003
1004
1005
1006
1007
....
1008
1009
1010
1011
1012
1013
1014
1015

1016
1017
1018
1019
1020
1021
1022
....
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
....
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060

1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075

1076
1077
1078
1079
1080
1081
1082
....
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108

1109
1110
1111
1112
1113
1114

1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133

1134
1135
1136

1137
1138
1139
1140
1141

1142
1143
1144
1145
1146
1147

1148
1149
1150
1151
1152
1153
1154

1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177

1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195

1196
1197
1198

1199
1200
1201
1202
1203

1204
1205
1206
1207
1208
1209
1210
....
1227
1228
1229
1230
1231
1232
1233
1234

1235
1236
1237
1238
1239
1240
1241

1242
1243
1244
1245
1246
1247
1248

1249
1250
1251
1252
1253
1254
1255
1256

1257
1258
1259
1260
1261
1262
1263

1264
1265
1266
1267
1268

1269
1270
1271
1272
1273
1274

1275
1276
1277
1278
1279
1280
1281
1282

1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297

1298
1299
1300

1301

1302
1303
1304
1305
1306
1307
1308
    commands are incorporated into a single main command and are selectable via
    the first argument\.

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

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

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

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

  - *Procedure attribute*

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

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

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

        __string compare__

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

  - *Named argument*

    Some parameters, as *\-length 3* of the subcommand __string compare__
................................................................................

  - *Named arguments first, unnamed arguments later*

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

        __string compare__

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

  - *Unnamed arguments first, named arguments later*

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

        __pack__

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

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

................................................................................
__tepam::procedure__ that has similar to the standard Tcl command
__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
    have namespace qualifiers\. By providing a two element name list as procedure
................................................................................
    name, a subcommand of a procedure will be declared\. It is even possible to
    declare sub\-sub\-commands of a procedure by providing name lists with three
    elements\.

    Here are some valid procedure declarations using different procedure names
    \(the attribute and body arguments are empty for simplicity\):

    *# Simple procedure name:*
    tepam::procedure __display_message__ {} {}
    **
    *# Procedure declared in the main namespace:*
    tepam::procedure __::display_message__ {} {}
    **
    *# Procedure in the namespace* __::ns__*:*
    tepam::procedure __::ns::display_message__ {} {}
    **
    *# Declaration of the subcommand* __message__ *of the procedure* __display__*:*
    tepam::procedure __{display message}__ {} {}

  - *attributes*

    All procedure attributes are provided in form of an option list that
    contains pairs of option names and option values\. The example above has as
    procedure attribute a short and a normal description, but also the procedure
    arguments are defined in form of a procedure attribute\.
................................................................................

    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__

................................................................................
  - \-validatecommand *script*

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

    The attribute *\-validatecommand* can be repeated to declare multiple
................................................................................
    examples, using the *\-example* attribute\.

## <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
    argument* or a *named argument*\. In addition to this, an argument name
................................................................................
      * *"<Name>"*

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

    tepam::procedure {print_string} {
       -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*

      * *"\-\-"*

        This flag allows clearly specifying the end of the named arguments and
        the beginning of the unnamed arguments, in case the *named arguments
................................................................................
        unnamed argument\.

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

      * *"\#\*"*

................................................................................
        section comment\. The argument definition list will be trimmed from the
        '\#' characters and the remaining string will be used as section comment\.

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

    tepam::procedure {complex_multiply} {
       -description "This function perform a complex multiplication"
       -args {
          __{#### First complex number ####}__
          {-r0 -type double -description "First number real part"}
          {-i0 -type double -description "First number imaginary part"}

          __{#### Second complex number ####}__
          {-r1 -type double -description "Second number real part"}
          {-i1 -type double -description "Second number imaginary part"}
       }

    } {
       return [expr $r0*$r1 - $i0*$i1]
    }


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

    The following argument attributes are supported:

      * \-description *string*

................................................................................
        validation commands that are defined with the *\-validatecommand*
        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\.

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

        In case a procedure is called interactively, additional argument
        attributes can be provided to the interactive argument definition form
        via the *\-auxargs* attribute that is itself a list of attribute
        name/attribute value pairs:

    -auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
              -<arg_attr_name_1b> <arg_attr_value_1b>
              ...
    }

        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
        via commands that are executed during a procedure call\. A list of pairs
        of auxiliary attribute names and commands has to be provided to the
        *\-auxargs\_commands* attribute\. The provided commands are executed in
        the context of the calling procedure\.

    -auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
                       -<arg_attr_name_1b> <arg_attr_command_1b>
                       ...
    }

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

Several variables defined inside the __::tepam__ namespace impact the mode
of operation of the procedures that have been declared with the TEPAM
__procedure__ command\.

................................................................................
    This variable defines the general calling style of the procedures\. It is by
    default set to __1__ which selects the *named arguments first, unnamed
    arguments later* style \(Tcl style\)\.

    By setting this variable to __0__, the *named arguments first, unnamed
    arguments later* style is globally selected \(Tk style\):

    set tepam::named_arguments_first 0

    While this variable defines the general calling style, the procedure
    attribute *\-named\_arguments\_first* can adapt this style individually for
    each declared procedure\.

  - __auto\_argument\_name\_completion__

................................................................................
    default it is set to __1__, meaning that the called procedures are
    trying to match eventually abbreviated argument names with the declared
    argument names\.

    By setting this variable to __0__ the automatic argument name matching
    mode is disabled:

    set tepam::auto_argument_name_completion 0

    While this variable defines the general matching mode, the procedure
    attribute *\-auto\_argument\_name\_completion* can adapt this mode
    individually for each declared procedure\.

  - __interactive\_display\_format__

................................................................................
    arguments\.

    There are two display modes for these interactive forms\. The *extended*
    mode which is the default mode is more adapted for small procedure argument
    sets\. The __short__ form is more adequate for huge procedure argument
    sets:

    set tepam::interactive_display_format "short"

    The choice to use short or extended forms can be globally configured via the
    variable __interactive\_display\_format__\. This global setting can be
    changed individually for a procedure with the procedure attribute
    *\-interactive\_display\_format*\.

  - __help\_line\_length__

    The maximum line length used by the procedure help text generator can be
    specified with this variable\. The default length which is set to 80
    \(characters\) can easily be adapted to the need of an application:

    set tepam::help_line_length 120

    Since this variable is applied directly during the help text generation, its
    value can continuously be adapted to the current need\.

  - __command\_log__

    Procedure calls can be logged inside the list variable
................................................................................
TEPAM provides a comprehensive set of procedure argument types\. They can easily
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


    *\-> 1*

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

  - __string__ __String__ is a generic argument data type\. Any data
................................................................................

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

    string is __<type_to_check>__ -strict

*<argument\_value>*

  - *boolean*

  - *integer*

  - *double*

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

    string is *<type_to_check>*

*<argument\_value>*

  - *alnum*

  - *alpha*

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

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

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

    expr [string length *<argument_value>*]==1

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

    expr ![catch {winfo rgb . *<argument_value>*}

    \]

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

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

    \]

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

    The following expression is used to validate the file names:

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

    \]

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

    file exists <argument_value>

  - *directory* The directory argument is validated exactly in the same way as
    the file arguments\.

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

    file isdirectory <argument_value>

## <a name='subsection4'></a>Defining Application Specific Argument Types

To add support for a new application specific argument type it is just necessary
to add into the namespace __tepam__ a validation function
__Validation\(<type>\)__\. This function requires one argument\. It has to
returns __1__ if the provided argument matches with the relevant data type\.
................................................................................
Each procedure can be called with the *\-help* flag\. The procedure will then
print a generated help text to *stdout* and will then return without
performing any additional actions\.

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

    __display message -help__


*\-> NAME display message \- Displays a simple message box SYNOPSIS display
message \[\-mtype <mtype>\] Message type, default: "Warning", choices: \{Info,
Warning, Error\} <text> Multiple text lines to display, type: string DESCRIPTION
This procedure allows displaying a configurable message box\. The default message
type that is created is a warning, but also errors and info can be generated\.
The procedure accepts multiple text lines\. EXAMPLE display message \-mtype
................................................................................
Warning "Save first your job"* The argument manager is checking if the last
provided argument is *\-help* and generates the requested help message if this
is the case\. So, also the following example will print the help message:

__display message \-mtype Info "It is 7:00" \-help__ On the other hand, the
following call will result in an error:

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


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

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

If Tk has been loaded a procedure can be called with the *\-interactive* flag
to open a graphical form that allows specifying interactively all procedure
................................................................................
    package require Tk

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

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

__\-interactive__

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

Unnamed arguments are typically provided to the called procedure as simple
parameters\. This procedure calling form requires that the provided arguments are
................................................................................
       }
    } {
       puts "$mtype: [join $text]"
    }

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

    __display_message Info "It is PM 7:00."__
    *-> Info: It is PM 7:00.*

    __display_message Info "It is PM 7:00." "You should go home."__


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

    __display_message -mtype Info -text "It is PM 7:00."__
    *-> Info: It is PM 7:00.*

    __display_message -text "It is PM 7:00." -mtype Info__
    *-> Info: It is PM 7:00.*

    __display_message -mtype Info -text "It is PM 7:00." -text "You should go home."__
    *-> Info: It is PM 7:00. You should go home.*

    __display_message -text "It is PM 7:00." -text "You should go home." -mtype Info__


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

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

Named arguments have to be provided to a procedure in form of a parameter pairs
composed by the argument names and the argument values\. The order how they are
................................................................................
       }
    } {
       puts "$mtype: [join $text]"
    }

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

    __display_message -mtype Info -text "It is PM 7:00."__
    *-> Info: It is PM 7:00.*

    __display_message -text "It is PM 7:00." -mtype Info__
    *-> Info: It is PM 7:00.*

    __display_message -mtype Info -text "It is PM 7:00." -text "You should go home."__
    *-> Info: It is PM 7:00. You should go home.*

    __display_message -text "It is PM 7:00." -text "You should go home." -mtype Info__


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

    __display_message -mtype Info -text "It is PM 7:00." -mtype Warning__


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

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

A procedure that has been defined while the variable
__tepam::named\_arguments\_first__ was set to 1, or with the procedure
attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\.
The following procedure declaration will be used in this section to illustrate
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__


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

    my_proc __U1 U2__


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

    my_proc __-n1 N1 -n2 N2 -n1 M1 U1 U2__


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

    my_proc __-n1 N1 -n2 N2 "->" "<-"__
    *-> my_proc: Argument '->' not known*

    set U1 "->"
    my_proc __-n1 N1 -n2 N2 $U1 U2__
    my_proc: Argument '->' not known

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

    my_proc __-n1 N1 -n2 N2 -- "->" "<-"__
    *-> n1:'N1', n2:'N2', u1:'->', u2:'<-'*

    set U1 "->"
    my_proc __-n1 N1 -n2 N2 -- $U1 U2__


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

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

The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute
*\-named\_arguments\_first* has been set to 0\. The following procedure will be
used in this section to illustrate this calling style:

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


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

An argument value will only be assigned to an unnamed argument that is optional
................................................................................
parameters, which leads to an error since *u1* is a mandatory argument:

    my_proc

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

    my_proc __U1__


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

    my_proc __U1 U2 U3 U4__


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

    my_proc __U1 U2 U3 U4 -U5__


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

    my_proc __-n1 N1__


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

    my_proc __U1 -n1 N1__


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

    my_proc __U1 -n1 N1 U2__


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

    my_proc __-- -n1 N1__


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

    my_proc __U1 -- -n1 N1__
    *-> n1:'N1', n2:'', u1:'U1', u2:''*

    my_proc __U1 -n1 N1 -- -n2 N2__


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

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

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

    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

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






|
|
|
|







|
|
|
|







 







|







 







|











|







 







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







 







|
|
|
|
|
|
|
|
|
|
|







 







|
|
|
|
<
>
|
|
|
<
>






|
|
|
|
|







 







|
|
|
|
|
<
>







 







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





|
|
|
|
|
|
|







 







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









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







 







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







 







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







 







|
|
|
|
|
<
>







 







|
|
|
|






|
|
|
|
|
|
|










|
|
|
|







 







|







 







|







 







|












|







 







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










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







 







|













|







 







|






|








|










|






|








|







 







|
>







 







|
>







 







|







 







|
|
|
|
>





|
|
|
|
|
|
|
|
|
|
>







 







|
|
|
|
|
|
|
|
|
|
>





|
>











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




|
>





|
>






|
>







|
|
|
|
|
|





|
|
|
|
|
>










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




|
>







 







|
>






|
>






|
>







|
>






|
>




|
>





|
>




|
|
|
|
>









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







106
107
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
...
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
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
...
209
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
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
...
284
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
...
363
364
365
366
367
368
369
370
371
372
373
374

375
376
377
378
379
380
381
382
...
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
...
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
...
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
...
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
...
653
654
655
656
657
658
659
660
661
662
663
664

665
666
667
668
669
670
671
672
...
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
...
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
...
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
...
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
...
810
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
850
851
852
853
854
855
856
...
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
...
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
...
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
....
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
....
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
....
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
....
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141

1142
1143
1144

1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207

1208
1209
1210

1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
....
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318

1319
1320
1321

1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
    commands are incorporated into a single main command and are selectable via
    the first argument\.

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

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

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

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

  - *Procedure attribute*

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

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

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

    > __string compare__   

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

  - *Named argument*

    Some parameters, as *\-length 3* of the subcommand __string compare__
................................................................................

  - *Named arguments first, unnamed arguments later*

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

    > __string compare__   

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

  - *Unnamed arguments first, named arguments later*

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

    > __pack__   

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

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

................................................................................
__tepam::procedure__ that has similar to the standard Tcl command
__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
    have namespace qualifiers\. By providing a two element name list as procedure
................................................................................
    name, a subcommand of a procedure will be declared\. It is even possible to
    declare sub\-sub\-commands of a procedure by providing name lists with three
    elements\.

    Here are some valid procedure declarations using different procedure names
    \(the attribute and body arguments are empty for simplicity\):

> *\# Simple procedure name:*  
> tepam::procedure __display\_message__ \{\} \{\}  
> **  
> *\# Procedure declared in the main namespace:*  
> tepam::procedure __::display\_message__ \{\} \{\}  
> **  
> *\# Procedure in the namespace* __::ns__*:*  
> tepam::procedure __::ns::display\_message__ \{\} \{\}  
> **  
> *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:*  
> tepam::procedure __\{display message\}__ \{\} \{\}  

  - *attributes*

    All procedure attributes are provided in form of an option list that
    contains pairs of option names and option values\. The example above has as
    procedure attribute a short and a normal description, but also the procedure
    arguments are defined in form of a procedure attribute\.
................................................................................

    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__

................................................................................
  - \-validatecommand *script*

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

    The attribute *\-validatecommand* can be repeated to declare multiple
................................................................................
    examples, using the *\-example* attribute\.

## <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
    argument* or a *named argument*\. In addition to this, an argument name
................................................................................
      * *"<Name>"*

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

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

      * *"\-\-"*

        This flag allows clearly specifying the end of the named arguments and
        the beginning of the unnamed arguments, in case the *named arguments
................................................................................
        unnamed argument\.

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

      * *"\#\*"*

................................................................................
        section comment\. The argument definition list will be trimmed from the
        '\#' characters and the remaining string will be used as section comment\.

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

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

>    \}  
> \} \{  
>    return \[expr $r0\*$r1 \- $i0\*$i1\]  

> \}  

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

    The following argument attributes are supported:

      * \-description *string*

................................................................................
        validation commands that are defined with the *\-validatecommand*
        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\.

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

        In case a procedure is called interactively, additional argument
        attributes can be provided to the interactive argument definition form
        via the *\-auxargs* attribute that is itself a list of attribute
        name/attribute value pairs:

            -auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
                      -<arg_attr_name_1b> <arg_attr_value_1b>
                      ...
            }

        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
        via commands that are executed during a procedure call\. A list of pairs
        of auxiliary attribute names and commands has to be provided to the
        *\-auxargs\_commands* attribute\. The provided commands are executed in
        the context of the calling procedure\.

            -auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
                               -<arg_attr_name_1b> <arg_attr_command_1b>
                               ...
            }

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

Several variables defined inside the __::tepam__ namespace impact the mode
of operation of the procedures that have been declared with the TEPAM
__procedure__ command\.

................................................................................
    This variable defines the general calling style of the procedures\. It is by
    default set to __1__ which selects the *named arguments first, unnamed
    arguments later* style \(Tcl style\)\.

    By setting this variable to __0__, the *named arguments first, unnamed
    arguments later* style is globally selected \(Tk style\):

        set tepam::named_arguments_first 0

    While this variable defines the general calling style, the procedure
    attribute *\-named\_arguments\_first* can adapt this style individually for
    each declared procedure\.

  - __auto\_argument\_name\_completion__

................................................................................
    default it is set to __1__, meaning that the called procedures are
    trying to match eventually abbreviated argument names with the declared
    argument names\.

    By setting this variable to __0__ the automatic argument name matching
    mode is disabled:

        set tepam::auto_argument_name_completion 0

    While this variable defines the general matching mode, the procedure
    attribute *\-auto\_argument\_name\_completion* can adapt this mode
    individually for each declared procedure\.

  - __interactive\_display\_format__

................................................................................
    arguments\.

    There are two display modes for these interactive forms\. The *extended*
    mode which is the default mode is more adapted for small procedure argument
    sets\. The __short__ form is more adequate for huge procedure argument
    sets:

        set tepam::interactive_display_format "short"

    The choice to use short or extended forms can be globally configured via the
    variable __interactive\_display\_format__\. This global setting can be
    changed individually for a procedure with the procedure attribute
    *\-interactive\_display\_format*\.

  - __help\_line\_length__

    The maximum line length used by the procedure help text generator can be
    specified with this variable\. The default length which is set to 80
    \(characters\) can easily be adapted to the need of an application:

        set tepam::help_line_length 120

    Since this variable is applied directly during the help text generation, its
    value can continuously be adapted to the current need\.

  - __command\_log__

    Procedure calls can be logged inside the list variable
................................................................................
TEPAM provides a comprehensive set of procedure argument types\. They can easily
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  
>   

    *\-> 1*

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

  - __string__ __String__ is a generic argument data type\. Any data
................................................................................

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

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

*<argument\_value>*

  - *boolean*

  - *integer*

  - *double*

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

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

*<argument\_value>*

  - *alnum*

  - *alpha*

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

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

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

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

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

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

    \]

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

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

    \]

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

    The following expression is used to validate the file names:

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

    \]

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

        file exists <argument_value>

  - *directory* The directory argument is validated exactly in the same way as
    the file arguments\.

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

        file isdirectory <argument_value>

## <a name='subsection4'></a>Defining Application Specific Argument Types

To add support for a new application specific argument type it is just necessary
to add into the namespace __tepam__ a validation function
__Validation\(<type>\)__\. This function requires one argument\. It has to
returns __1__ if the provided argument matches with the relevant data type\.
................................................................................
Each procedure can be called with the *\-help* flag\. The procedure will then
print a generated help text to *stdout* and will then return without
performing any additional actions\.

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

> __display message \-help__  
>   

*\-> NAME display message \- Displays a simple message box SYNOPSIS display
message \[\-mtype <mtype>\] Message type, default: "Warning", choices: \{Info,
Warning, Error\} <text> Multiple text lines to display, type: string DESCRIPTION
This procedure allows displaying a configurable message box\. The default message
type that is created is a warning, but also errors and info can be generated\.
The procedure accepts multiple text lines\. EXAMPLE display message \-mtype
................................................................................
Warning "Save first your job"* The argument manager is checking if the last
provided argument is *\-help* and generates the requested help message if this
is the case\. So, also the following example will print the help message:

__display message \-mtype Info "It is 7:00" \-help__ On the other hand, the
following call will result in an error:

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

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

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

If Tk has been loaded a procedure can be called with the *\-interactive* flag
to open a graphical form that allows specifying interactively all procedure
................................................................................
    package require Tk

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

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

__\-interactive__

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

Unnamed arguments are typically provided to the called procedure as simple
parameters\. This procedure calling form requires that the provided arguments are
................................................................................
       }
    } {
       puts "$mtype: [join $text]"
    }

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

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

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

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

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

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

Named arguments have to be provided to a procedure in form of a parameter pairs
composed by the argument names and the argument values\. The order how they are
................................................................................
       }
    } {
       puts "$mtype: [join $text]"
    }

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

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

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

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

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

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

A procedure that has been defined while the variable
__tepam::named\_arguments\_first__ was set to 1, or with the procedure
attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\.
The following procedure declaration will be used in this section to illustrate
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__  
>   

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

> my\_proc __U1 U2__  
>   

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

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

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

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

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

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

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

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

The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute
*\-named\_arguments\_first* has been set to 0\. The following procedure will be
used in this section to illustrate this calling style:

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

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

An argument value will only be assigned to an unnamed argument that is optional
................................................................................
parameters, which leads to an error since *u1* is a mandatory argument:

    my_proc

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

> my\_proc __U1__  
>   

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

> my\_proc __U1 U2 U3 U4__  
>   

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

> my\_proc __U1 U2 U3 U4 \-U5__  
>   

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

> my\_proc __\-n1 N1__  
>   

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

> my\_proc __U1 \-n1 N1__  
>   

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

> my\_proc __U1 \-n1 N1 U2__  
>   

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

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

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

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

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

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

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

> 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

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

Changes to embedded/md/tcllib/files/modules/textutil/expander.md.

126
127
128
129
130
131
132
133

134
135
136
137
138
139
140
    The command creates a new expander object with an associated Tcl command
    whose name is *expanderName*\. This command may be used to invoke various
    operations on the graph\. If the *expanderName* is not fully qualified it
    is interpreted as relative to the current namespace\. The command has the
    following general form:

    *expanderName* option ?*arg arg ...*?


    *Option* and the *arg*s determine the exact behavior of the command\.

The following commands are possible for expander objects:

  - <a name='2'></a>*expanderName* __cappend__ *text*







|
>







126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
    The command creates a new expander object with an associated Tcl command
    whose name is *expanderName*\. This command may be used to invoke various
    operations on the graph\. If the *expanderName* is not fully qualified it
    is interpreted as relative to the current namespace\. The command has the
    following general form:

    > *expanderName* option ?*arg arg \.\.\.*?  
    >   

    *Option* and the *arg*s determine the exact behavior of the command\.

The following commands are possible for expander objects:

  - <a name='2'></a>*expanderName* __cappend__ *text*

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

183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
            #   have such an attribute.
            # - And returns this information.

            # Below we can see the same query, but rewritten
            # to show the structure as it is seen by the query
            # interpreter.

            q query \\
        	    root \\
        	    children \\
        	    get data

    The operators of the TreeQL language available for this are explained in the
    section about [The Tree Query Language](#section3)\. This section also
    explains the term *node set* used above\.

  - <a name='3'></a>*qo* __result__






|
|
|







183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
            #   have such an attribute.
            # - And returns this information.

            # Below we can see the same query, but rewritten
            # to show the structure as it is seen by the query
            # interpreter.

            q query \
        	    root \
        	    children \
        	    get data

    The operators of the TreeQL language available for this are explained in the
    section about [The Tree Query Language](#section3)\. This section also
    explains the term *node set* used above\.

  - <a name='3'></a>*qo* __result__

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

51
52
53
54
55
56
57
58

59
60
61
62
63
64
65
  - <a name='1'></a>__::throw__ *error\_code* *error\_message*

    throw is merely a reordering of the arguments of the error command\. It
    throws an error with the indicated error code and error message\.

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

    __throw__ {MYERROR CODE} "My error message"


# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.






|
>







51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
  - <a name='1'></a>__::throw__ *error\_code* *error\_message*

    throw is merely a reordering of the arguments of the error command\. It
    throws an error with the indicated error code and error message\.

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

> __throw__ \{MYERROR CODE\} "My error message"  
>   

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

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

106
107
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
        original exception's status dictionary will be added to the new
        exception's status dictionary under the __\-during__ key\.

# <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
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.






|
|
|
|
|
|
<
>
|
>


<
>
|
|
|
|
|
<
>
>







106
107
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
137
138
        original exception's status dictionary will be added to the new
        exception's status dictionary under the __\-during__ key\.

# <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
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

Changes to embedded/md/tcllib/files/modules/zip/mkzip.md.

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
    particularly on Windows the __info\-zip__ and the Windows built\-in zip
    view have rather poor support for this part of the ZIP file specification\.
    The __7\-Zip__ program does correctly display utf8 filenames however and
    the __vfs::zip__ package will use these of course\.

    If you use

        __::mkzip::mkzip__ mystuff.tm -zipkit -directory mystuff.vfs

    it will pack your "mystuff\.vfs/" virtual filesystem tree into a zip archive
    with a suitable header such that on unix you may mark it executable and it
    should run with tclkit\. Or you can run it with __tclsh__ or __wish__
    8\.6 if you like\.

    To change the executable header, specify the __\-runtime__ "preface"






|







58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
    particularly on Windows the __info\-zip__ and the Windows built\-in zip
    view have rather poor support for this part of the ZIP file specification\.
    The __7\-Zip__ program does correctly display utf8 filenames however and
    the __vfs::zip__ package will use these of course\.

    If you use

    > __::mkzip::mkzip__ mystuff\.tm \-zipkit \-directory mystuff\.vfs  

    it will pack your "mystuff\.vfs/" virtual filesystem tree into a zip archive
    with a suitable header such that on unix you may mark it executable and it
    should run with tclkit\. Or you can run it with __tclsh__ or __wish__
    8\.6 if you like\.

    To change the executable header, specify the __\-runtime__ "preface"

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

297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
    \&.\&.\&. [key {markup language}] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [manpage thefile \\\\
          {file description}] \&.\&.\&.

.CE
.SS "BASIC STRUCTURE"
The most simple document which can be written in docidx is
.CS







|







297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
    \&.\&.\&. [key {markup language}] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [manpage thefile \\
          {file description}] \&.\&.\&.

.CE
.SS "BASIC STRUCTURE"
The most simple document which can be written in docidx is
.CS

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

297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
    \&.\&.\&. [division_start {Appendix 1}] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [item thefile \\\\
          label {file description}] \&.\&.\&.

.CE
.SS "BASIC STRUCTURE"
The most simple document which can be written in doctoc is
.CS







|







297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
    \&.\&.\&. [division_start {Appendix 1}] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [item thefile \\
          label {file description}] \&.\&.\&.

.CE
.SS "BASIC STRUCTURE"
The most simple document which can be written in doctoc is
.CS

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]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5\&.2 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\&.2?\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\&.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

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

296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
  \&.\&.\&. [list_begin enumerated] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [call [cmd foo] \\\\
          [arg bar]] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [term {complex concept}] \&.\&.\&.






|







296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
  \&.\&.\&. [list_begin enumerated] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [call [cmd foo] \\
          [arg bar]] \&.\&.\&.

.CE
.CS


  \&.\&.\&. [term {complex concept}] \&.\&.\&.

Changes to idoc/man/files/modules/doctools2idx/idx_introduction.n.

373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                        docidx                    |     |    |                  docidx, json
                        json                      |     |    |                  |           \\\\
                        html                      |     |    |          doctools::idx::parse \\\\
                        nroff                     |     |    |                  |             \\\\
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::idx::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat






|
|
|







373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                        docidx                    |     |    |                  docidx, json
                        json                      |     |    |                  |           \\
                        html                      |     |    |          doctools::idx::parse \\
                        nroff                     |     |    |                  |             \\
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::idx::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat

Changes to idoc/man/files/modules/doctools2toc/toc_introduction.n.

373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                        doctoc                    |     |    |                  doctoc, json
                        json                      |     |    |                  |           \\\\
                        html                      |     |    |          doctools::toc::parse \\\\
                        nroff                     |     |    |                  |             \\\\
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::toc::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat






|
|
|







373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                        doctoc                    |     |    |                  doctoc, json
                        json                      |     |    |                  |           \\
                        html                      |     |    |          doctools::toc::parse \\
                        nroff                     |     |    |                  |             \\
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::toc::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat

Changes to idoc/man/files/modules/fileutil/multiop.n.

632
633
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
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
...
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
.PP
.SH EXAMPLES
The following examples assume that the variable \fBF\fR contains a
reference to a multi-file operation object\&.
.CS


    $F do copy                       \\\\
	the  *\&.dll                    \\\\
	from c:/TDK/PrivateOpenSSL/bin \\\\
	to   [installdir_of tls]

.CE
.CS


    $F do move      \\\\
	the  *       \\\\
	from /sources \\\\
	into /scratch  \\\\
	but not *\&.html

    # Alternatively use 'except for *\&.html'\&.

.CE
.CS


    $F do           \\\\
	move         \\\\
	the  index    \\\\
	from /sources  \\\\
	into /scratch   \\\\
	as   pkgIndex\&.tcl

.CE
.CS


    $F do         \\\\
	remove     \\\\
	the *\&.txt  \\\\
	in /scratch

.CE
Note that the fact that most commands just modify the object state
allows us to use more off forms as specifications instead of just
nearly-natural language sentences\&.
For example the second example in this section can re-arranged into:
.CS


    $F do            \\\\
	from /sources \\\\
	into /scratch  \\\\
	but not *\&.html \\\\
	move           \\\\
	the  *

.CE
and the result is not only still a valid specification, but even stays
relatively readable\&.
.PP
Further note that the information collected by the commands \fBbut\fR,
................................................................................
\fBthe\fR was executed\&. However no other state is reset in that
manner, allowing the user to avoid repetitions of unchanging
information\&. For example the second and third examples of this section
can be merged and rewritten into the equivalent:
.CS


$F do                   \\\\
    move                 \\\\
    the  *                \\\\
    from /sources          \\\\
    into /scratch           \\\\
    but not *\&.html not index \\\\
    the  index               \\\\
    as   pkgIndex\&.tcl

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIfileutil\fR of the






|
|
|






|
|
|
|








|
|
|
|
|






|
|
|










|
|
|
|
|







 







|
|
|
|
|
|
|







632
633
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
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
...
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
.PP
.SH EXAMPLES
The following examples assume that the variable \fBF\fR contains a
reference to a multi-file operation object\&.
.CS


    $F do copy                       \\
	the  *\&.dll                    \\
	from c:/TDK/PrivateOpenSSL/bin \\
	to   [installdir_of tls]

.CE
.CS


    $F do move      \\
	the  *       \\
	from /sources \\
	into /scratch  \\
	but not *\&.html

    # Alternatively use 'except for *\&.html'\&.

.CE
.CS


    $F do           \\
	move         \\
	the  index    \\
	from /sources  \\
	into /scratch   \\
	as   pkgIndex\&.tcl

.CE
.CS


    $F do         \\
	remove     \\
	the *\&.txt  \\
	in /scratch

.CE
Note that the fact that most commands just modify the object state
allows us to use more off forms as specifications instead of just
nearly-natural language sentences\&.
For example the second example in this section can re-arranged into:
.CS


    $F do            \\
	from /sources \\
	into /scratch  \\
	but not *\&.html \\
	move           \\
	the  *

.CE
and the result is not only still a valid specification, but even stays
relatively readable\&.
.PP
Further note that the information collected by the commands \fBbut\fR,
................................................................................
\fBthe\fR was executed\&. However no other state is reset in that
manner, allowing the user to avoid repetitions of unchanging
information\&. For example the second and third examples of this section
can be merged and rewritten into the equivalent:
.CS


$F do                   \\
    move                 \\
    the  *                \\
    from /sources          \\
    into /scratch           \\
    but not *\&.html not index \\
    the  index               \\
    as   pkgIndex\&.tcl

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIfileutil\fR of the

Changes to idoc/man/files/modules/grammar_fa/fa.n.

545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
.CE
.sp
a possible serialization is
.sp
.CS


    grammar::fa \\\\
    {yellow red green red/yellow} \\\\
    {Drive     {0 0 {yellow     Brake}} \\\\
     Brake     {0 0 {red        Stop}} \\\\
     Stop      {1 0 {red/yellow Attention}} \\\\
     Attention {0 0 {green      Drive}}}

.CE
.sp
A possible one, because I did not care about creation order here
.TP
\fIfaName\fR \fBdeserialize\fR \fIserialization\fR






|
|
|
|
|







545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
.CE
.sp
a possible serialization is
.sp
.CS


    grammar::fa \\
    {yellow red green red/yellow} \\
    {Drive     {0 0 {yellow     Brake}} \\
     Brake     {0 0 {red        Stop}} \\
     Stop      {1 0 {red/yellow Attention}} \\
     Attention {0 0 {green      Drive}}}

.CE
.sp
A possible one, because I did not care about creation order here
.TP
\fIfaName\fR \fBdeserialize\fR \fIserialization\fR

Changes to idoc/man/files/modules/grammar_peg/peg.n.

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
.CE
.sp
a possible serialization is
.sp
.CS


    grammar::peg \\\\
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\\\
     Factor     {x Term {* {x AddOp Term}}} \\\\
     Term       Number \\\\
     MulOp      {/ * /} \\\\
     AddOp      {/ + -} \\\\
     Number     {x {? Sign} {+ Digit}} \\\\
     Sign       {/ + -} \\\\
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\\\
    } \\\\
    {Expression value     Factor     value \\\\
     Term       value     MulOp      value \\\\
     AddOp      value     Number     value \\\\
     Sign       value     Digit      value \\\\
    }
    Expression

.CE
.sp
A possible one, because the order of the nonterminals in the
dictionary is not relevant\&.






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







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
.CE
.sp
a possible serialization is
.sp
.CS


    grammar::peg \\
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
     Factor     {x Term {* {x AddOp Term}}} \\
     Term       Number \\
     MulOp      {/ * /} \\
     AddOp      {/ + -} \\
     Number     {x {? Sign} {+ Digit}} \\
     Sign       {/ + -} \\
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
    } \\
    {Expression value     Factor     value \\
     Term       value     MulOp      value \\
     AddOp      value     Number     value \\
     Sign       value     Digit      value \\
    }
    Expression

.CE
.sp
A possible one, because the order of the nonterminals in the
dictionary is not relevant\&.

Changes to idoc/man/files/modules/mime/smtp.n.

403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
.CS


proc send_simple_message {recipient email_server subject body} {
    package require smtp
    package require mime

    set token [mime::initialize -canonical text/plain \\\\
	-string $body]
    mime::setheader $token Subject $subject
    smtp::sendmessage $token \\\\
	-recipients $recipient -servers $email_server
    mime::finalize $token
}

send_simple_message [email protected]\&.com localhost \\\\
    "This is the subject\&." "This is the message\&."

.CE
.SH "TLS SECURITY CONSIDERATIONS"
.PP
This package uses the \fBTLS\fR package to handle the
security for \fBhttps\fR urls and other socket connections\&.






|


|




|







403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
.CS


proc send_simple_message {recipient email_server subject body} {
    package require smtp
    package require mime

    set token [mime::initialize -canonical text/plain \\
	-string $body]
    mime::setheader $token Subject $subject
    smtp::sendmessage $token \\
	-recipients $recipient -servers $email_server
    mime::finalize $token
}

send_simple_message [email protected]\&.com localhost \\
    "This is the subject\&." "This is the message\&."

.CE
.SH "TLS SECURITY CONSIDERATIONS"
.PP
This package uses the \fBTLS\fR package to handle the
security for \fBhttps\fR urls and other socket connections\&.

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

499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
...
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
.CS


	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile \&.\&.\&.

	# Create secured pop3 channel
	pop3::open -socketcmd tls::socket \\\\
		$thehost $theuser $thepassword

	\&.\&.\&.

.CE
The second method, option \fB-stls\fR, will connect to the standard POP3
port and then perform an STARTTLS handshake\&. This will only work for POP3
................................................................................
.CS


	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile \&.\&.\&.

	# Create secured pop3 channel
	pop3::open -stls 1 \\\\
		$thehost $theuser $thepassword

	\&.\&.\&.

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain






|







 







|







499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
...
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
.CS


	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile \&.\&.\&.

	# Create secured pop3 channel
	pop3::open -socketcmd tls::socket \\
		$thehost $theuser $thepassword

	\&.\&.\&.

.CE
The second method, option \fB-stls\fR, will connect to the standard POP3
port and then perform an STARTTLS handshake\&. This will only work for POP3
................................................................................
.CS


	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile \&.\&.\&.

	# Create secured pop3 channel
	pop3::open -stls 1 \\
		$thehost $theuser $thepassword

	\&.\&.\&.

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain

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

489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
the package to override how the server opens its listening socket\&.
The envisioned main use is the specification of the \fBtls::socket\fR
command, see package \fBtls\fR, to secure the communication\&.
.CS


	package require tls
	tls::init \\\\
		\&.\&.\&.

	pop3d::new S -socket tls::socket
	\&.\&.\&.

.CE
.SH REFERENCES






|







489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
the package to override how the server opens its listening socket\&.
The envisioned main use is the specification of the \fBtls::socket\fR
command, see package \fBtls\fR, to secure the communication\&.
.CS


	package require tls
	tls::init \\
		\&.\&.\&.

	pop3d::new S -socket tls::socket
	\&.\&.\&.

.CE
.SH REFERENCES

Changes to idoc/man/files/modules/struct/graph.n.

1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
relevance, nor has the order of the arcs per node\&.
.CS


    # A possible serialization for the graph structure
    #
    #        d -----> %2
    #       /         ^ \\\\
    #      /         /   \\\\
    #     /         b     \\\\
    #    /         /       \\\\
    #  %1 <- a - %0         e
    #    ^         \\\\      /
    #     \\\\        c     /
    #      \\\\        \\\\  /
    #       \\\\        v v
    #        f ------ %3
    # is






|
|
|
|







1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
relevance, nor has the order of the arcs per node\&.
.CS


    # A possible serialization for the graph structure
    #
    #        d -----> %2
    #       /         ^ \\
    #      /         /   \\
    #     /         b     \\
    #    /         /       \\
    #  %1 <- a - %0         e
    #    ^         \\\\      /
    #     \\\\        c     /
    #      \\\\        \\\\  /
    #       \\\\        v v
    #        f ------ %3
    # is

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

404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
    #   have such an attribute\&.
    # - And returns this information\&.

    # Below we can see the same query, but rewritten
    # to show the structure as it is seen by the query
    # interpreter\&.

    q query \\\\
	    root \\\\
	    children \\\\
	    get data

.CE
.sp
The operators of the TreeQL language available for this are explained
in the section about \fBThe Tree Query Language\fR\&. This section
also explains the term \fInode set\fR used above\&.






|
|
|







404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
    #   have such an attribute\&.
    # - And returns this information\&.

    # Below we can see the same query, but rewritten
    # to show the structure as it is seen by the query
    # interpreter\&.

    q query \\
	    root \\
	    children \\
	    get data

.CE
.sp
The operators of the TreeQL language available for this are explained
in the section about \fBThe Tree Query Language\fR\&. This section
also explains the term \fInode set\fR used above\&.

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

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
    ... [key {markup language}] ...
</pre>
<pre class="doctools_example">
  ... [manpage thefile \\
          {file description}] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in docidx is</p>
<pre class="doctools_example">
    [index_begin GROUPTITLE TITLE]






|







146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
    ... [key {markup language}] ...
</pre>
<pre class="doctools_example">
  ... [manpage thefile \
          {file description}] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in docidx is</p>
<pre class="doctools_example">
    [index_begin GROUPTITLE TITLE]

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

148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
    ... [division_start {Appendix 1}] ...
</pre>
<pre class="doctools_example">
  ... [item thefile \\
          label {file description}] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in doctoc is</p>
<pre class="doctools_example">
    [toc_begin GROUPTITLE TITLE]






|







148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
    ... [division_start {Appendix 1}] ...
</pre>
<pre class="doctools_example">
  ... [item thefile \
          label {file description}] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in doctoc is</p>
<pre class="doctools_example">
    [toc_begin GROUPTITLE TITLE]

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.2 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.2?</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.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>

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

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
  ... [list_begin enumerated] ...
</pre>
<pre class="doctools_example">
  ... [call [cmd foo] \\
          [arg bar]] ...
</pre>
<pre class="doctools_example">
  ... [term {complex concept}] ...
</pre>
<pre class="doctools_example">
  ... [opt &quot;[arg key] [arg value]&quot;] ...






|







150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
  ... [list_begin enumerated] ...
</pre>
<pre class="doctools_example">
  ... [call [cmd foo] \
          [arg bar]] ...
</pre>
<pre class="doctools_example">
  ... [term {complex concept}] ...
</pre>
<pre class="doctools_example">
  ... [opt &quot;[arg key] [arg value]&quot;] ...

Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_introduction.html.

210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::idx::export::&lt;*&gt;        |     |    |          doctools::idx::import::&lt;*&gt;
                        docidx                    |     |    |                  docidx, json
                        json                      |     |    |                  |           \\
                        html                      |     |    |          doctools::idx::parse \\
                        nroff                     |     |    |                  |             \\
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::idx::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        






|
|
|







210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::idx::export::&lt;*&gt;        |     |    |          doctools::idx::import::&lt;*&gt;
                        docidx                    |     |    |                  docidx, json
                        json                      |     |    |                  |           \
                        html                      |     |    |          doctools::idx::parse \
                        nroff                     |     |    |                  |             \
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::idx::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        

Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_introduction.html.

210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::toc::export::&lt;*&gt;        |     |    |          doctools::toc::import::&lt;*&gt;
                        doctoc                    |     |    |                  doctoc, json
                        json                      |     |    |                  |           \\
                        html                      |     |    |          doctools::toc::parse \\
                        nroff                     |     |    |                  |             \\
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::toc::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        






|
|
|







210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
                        |                               |                       |
        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
        |               |                         |     |    |                  |               |                       |               |
doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                        |                         |     |    |                  |
                doctools::toc::export::&lt;*&gt;        |     |    |          doctools::toc::import::&lt;*&gt;
                        doctoc                    |     |    |                  doctoc, json
                        json                      |     |    |                  |           \
                        html                      |     |    |          doctools::toc::parse \
                        nroff                     |     |    |                  |             \
                        wiki                      |     |    |  +---------------+              json
                        text                      |     |    |  |               |
                                                doctools::toc::structure        |
                                                                                |
                                                                        +-------+---------------+
                                                                        |                       |
          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        

Changes to idoc/www/tcllib/files/modules/fileutil/multiop.html.

381
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
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
<dd><p>Returns the current path type limiter.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>The following examples assume that the variable <b class="variable">F</b> contains a
reference to a multi-file operation object.</p>
<pre class="doctools_example">
    $F do copy                       \\
	the  *.dll                    \\
	from c:/TDK/PrivateOpenSSL/bin \\
	to   [installdir_of tls]
</pre>
<pre class="doctools_example">
    $F do move      \\
	the  *       \\
	from /sources \\
	into /scratch  \\
	but not *.html
    # Alternatively use 'except for *.html'.
</pre>
<pre class="doctools_example">
    $F do           \\
	move         \\
	the  index    \\
	from /sources  \\
	into /scratch   \\
	as   pkgIndex.tcl
</pre>
<pre class="doctools_example">
    $F do         \\
	remove     \\
	the *.txt  \\
	in /scratch
</pre>
<p>Note that the fact that most commands just modify the object state
allows us to use more off forms as specifications instead of just
nearly-natural language sentences.
For example the second example in this section can re-arranged into:</p>
<pre class="doctools_example">
    $F do            \\
	from /sources \\
	into /scratch  \\
	but not *.html \\
	move           \\
	the  *
</pre>
<p>and the result is not only still a valid specification, but even stays
relatively readable.</p>
<p>Further note that the information collected by the commands <b class="cmd">but</b>,
<b class="cmd">except</b>, and <b class="cmd">as</b> is automatically reset after the associated
<b class="cmd">the</b> was executed. However no other state is reset in that
manner, allowing the user to avoid repetitions of unchanging
information. For example the second and third examples of this section
can be merged and rewritten into the equivalent:</p>
<pre class="doctools_example">
$F do                   \\
    move                 \\
    the  *                \\
    from /sources          \\
    into /scratch           \\
    but not *.html not index \\
    the  index               \\
    as   pkgIndex.tcl
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil</em> of the






|
|
|



|
|
|
|




|
|
|
|
|



|
|
|







|
|
|
|
|











|
|
|
|
|
|
|







381
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
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
<dd><p>Returns the current path type limiter.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>The following examples assume that the variable <b class="variable">F</b> contains a
reference to a multi-file operation object.</p>
<pre class="doctools_example">
    $F do copy                       \
	the  *.dll                    \
	from c:/TDK/PrivateOpenSSL/bin \
	to   [installdir_of tls]
</pre>
<pre class="doctools_example">
    $F do move      \
	the  *       \
	from /sources \
	into /scratch  \
	but not *.html
    # Alternatively use 'except for *.html'.
</pre>
<pre class="doctools_example">
    $F do           \
	move         \
	the  index    \
	from /sources  \
	into /scratch   \
	as   pkgIndex.tcl
</pre>
<pre class="doctools_example">
    $F do         \
	remove     \
	the *.txt  \
	in /scratch
</pre>
<p>Note that the fact that most commands just modify the object state
allows us to use more off forms as specifications instead of just
nearly-natural language sentences.
For example the second example in this section can re-arranged into:</p>
<pre class="doctools_example">
    $F do            \
	from /sources \
	into /scratch  \
	but not *.html \
	move           \
	the  *
</pre>
<p>and the result is not only still a valid specification, but even stays
relatively readable.</p>
<p>Further note that the information collected by the commands <b class="cmd">but</b>,
<b class="cmd">except</b>, and <b class="cmd">as</b> is automatically reset after the associated
<b class="cmd">the</b> was executed. However no other state is reset in that
manner, allowing the user to avoid repetitions of unchanging
information. For example the second and third examples of this section
can be merged and rewritten into the equivalent:</p>
<pre class="doctools_example">
$F do                   \
    move                 \
    the  *                \
    from /sources          \
    into /scratch           \
    but not *.html not index \
    the  index               \
    as   pkgIndex.tcl
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil</em> of the

Changes to idoc/www/tcllib/files/modules/grammar_fa/fa.html.

309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
in a very simple way :)</p>
<pre class="doctools_example">
    Drive -- yellow --&gt; Brake -- red --&gt; (Stop) -- red/yellow --&gt; Attention -- green --&gt; Drive
    (...) is the start state.
</pre>
<p>a possible serialization is</p>
<pre class="doctools_example">
    grammar::fa \\
    {yellow red green red/yellow} \\
    {Drive     {0 0 {yellow     Brake}} \\
     Brake     {0 0 {red        Stop}} \\
     Stop      {1 0 {red/yellow Attention}} \\
     Attention {0 0 {green      Drive}}}
</pre>
<p>A possible one, because I did not care about creation order here</p></dd>
<dt><a name="8"><i class="arg">faName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the
automaton definition in <i class="arg">faName</i> with the automaton described by
the <i class="arg">serialization</i> value. The old contents of <i class="arg">faName</i> are






|
|
|
|
|







309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
in a very simple way :)</p>
<pre class="doctools_example">
    Drive -- yellow --&gt; Brake -- red --&gt; (Stop) -- red/yellow --&gt; Attention -- green --&gt; Drive
    (...) is the start state.
</pre>
<p>a possible serialization is</p>
<pre class="doctools_example">
    grammar::fa \
    {yellow red green red/yellow} \
    {Drive     {0 0 {yellow     Brake}} \
     Brake     {0 0 {red        Stop}} \
     Stop      {1 0 {red/yellow Attention}} \
     Attention {0 0 {green      Drive}}}
</pre>
<p>A possible one, because I did not care about creation order here</p></dd>
<dt><a name="8"><i class="arg">faName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the
automaton definition in <i class="arg">faName</i> with the automaton described by
the <i class="arg">serialization</i> value. The old contents of <i class="arg">faName</i> are

Changes to idoc/www/tcllib/files/modules/grammar_peg/peg.html.

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
    MulOp      &lt;- '*' / '/'
    Factor     &lt;- Term (AddOp Term)*
    AddOp      &lt;- '+'/'-'
    Term       &lt;- Number
</pre>
<p>a possible serialization is</p>
<pre class="doctools_example">
    grammar::peg \\
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
     Factor     {x Term {* {x AddOp Term}}} \\
     Term       Number \\
     MulOp      {/ * /} \\
     AddOp      {/ + -} \\
     Number     {x {? Sign} {+ Digit}} \\
     Sign       {/ + -} \\
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
    } \\
    {Expression value     Factor     value \\
     Term       value     MulOp      value \\
     AddOp      value     Number     value \\
     Sign       value     Digit      value \\
    }
    Expression
</pre>
<p>A possible one, because the order of the nonterminals in the
dictionary is not relevant.</p></dd>
<dt><a name="7"><i class="arg">pegName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the grammar






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







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
    MulOp      &lt;- '*' / '/'
    Factor     &lt;- Term (AddOp Term)*
    AddOp      &lt;- '+'/'-'
    Term       &lt;- Number
</pre>
<p>a possible serialization is</p>
<pre class="doctools_example">
    grammar::peg \
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \
     Factor     {x Term {* {x AddOp Term}}} \
     Term       Number \
     MulOp      {/ * /} \
     AddOp      {/ + -} \
     Number     {x {? Sign} {+ Digit}} \
     Sign       {/ + -} \
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \
    } \
    {Expression value     Factor     value \
     Term       value     MulOp      value \
     AddOp      value     Number     value \
     Sign       value     Digit      value \
    }
    Expression
</pre>
<p>A possible one, because the order of the nonterminals in the
dictionary is not relevant.</p></dd>
<dt><a name="7"><i class="arg">pegName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the grammar

Changes to idoc/www/tcllib/files/modules/mime/smtp.html.

239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
and <b class="package"><a href="../ripemd/ripemd160.html">ripemd160</a></b>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLE</a></h2>
<pre class="doctools_example">
proc send_simple_message {recipient email_server subject body} {
    package require smtp
    package require mime
    set token [mime::initialize -canonical text/plain \\
	-string $body]
    mime::setheader $token Subject $subject
    smtp::sendmessage $token \\
	-recipients $recipient -servers $email_server
    mime::finalize $token
}
send_simple_message [email protected] localhost \\
    &quot;This is the subject.&quot; &quot;This is the message.&quot;
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what






|


|



|







239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
and <b class="package"><a href="../ripemd/ripemd160.html">ripemd160</a></b>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLE</a></h2>
<pre class="doctools_example">
proc send_simple_message {recipient email_server subject body} {
    package require smtp
    package require mime
    set token [mime::initialize -canonical text/plain \
	-string $body]
    mime::setheader $token Subject $subject
    smtp::sendmessage $token \
	-recipients $recipient -servers $email_server
    mime::finalize $token
}
send_simple_message [email protected] localhost \
    &quot;This is the subject.&quot; &quot;This is the message.&quot;
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what

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

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
335
336
337
of the <b class="cmd">tls::socket</b> command when opening the connection. This is
suitable for POP3 servers which expect SSL connections only. These will
generally be listening on port 995.</p>
<pre class="doctools_example">
	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile ...
	# Create secured pop3 channel
	pop3::open -socketcmd tls::socket \\
		$thehost $theuser $thepassword
	...
</pre>
<p>The second method, option <b class="option">-stls</b>, will connect to the standard POP3
port and then perform an STARTTLS handshake. This will only work for POP3
servers which have this capability. The package will confirm that the
server supports STARTTLS and the handshake was performed correctly before
proceeding with authentication.</p>
<pre class="doctools_example">
	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile ...
	# Create secured pop3 channel
	pop3::open -stls 1 \\
		$thehost $theuser $thepassword
	...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.






|












|







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
335
336
337
of the <b class="cmd">tls::socket</b> command when opening the connection. This is
suitable for POP3 servers which expect SSL connections only. These will
generally be listening on port 995.</p>
<pre class="doctools_example">
	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile ...
	# Create secured pop3 channel
	pop3::open -socketcmd tls::socket \
		$thehost $theuser $thepassword
	...
</pre>
<p>The second method, option <b class="option">-stls</b>, will connect to the standard POP3
port and then perform an STARTTLS handshake. This will only work for POP3
servers which have this capability. The package will confirm that the
server supports STARTTLS and the handshake was performed correctly before
proceeding with authentication.</p>
<pre class="doctools_example">
	package require tls
	tls::init -cafile /path/to/ca/cert -keyfile ...
	# Create secured pop3 channel
	pop3::open -stls 1 \
		$thehost $theuser $thepassword
	...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.

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

305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
<div id="section5" class="doctools_section"><h2><a name="section5">Secure mail transfer</a></h2>
<p>The option <b class="option">-socket</b> (see <span class="sectref"><a href="#section2">Options</a></span>) enables users of
the package to override how the server opens its listening socket.
The envisioned main use is the specification of the <b class="cmd">tls::socket</b>
command, see package <b class="package"><a href="../../../../index.html#tls">tls</a></b>, to secure the communication.</p>
<pre class="doctools_example">
	package require tls
	tls::init \\
		...
	pop3d::new S -socket tls::socket
	...
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">References</a></h2>
<ol class="doctools_enumerated">






|







305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
<div id="section5" class="doctools_section"><h2><a name="section5">Secure mail transfer</a></h2>
<p>The option <b class="option">-socket</b> (see <span class="sectref"><a href="#section2">Options</a></span>) enables users of
the package to override how the server opens its listening socket.
The envisioned main use is the specification of the <b class="cmd">tls::socket</b>
command, see package <b class="package"><a href="../../../../index.html#tls">tls</a></b>, to secure the communication.</p>
<pre class="doctools_example">
	package require tls
	tls::init \
		...
	pop3d::new S -socket tls::socket
	...
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">References</a></h2>
<ol class="doctools_enumerated">

Changes to idoc/www/tcllib/files/modules/struct/graph.html.

671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
attributes, and the values are the values for each name.</p>
<p><em>Note:</em> The order of the nodes in the serialization has no
relevance, nor has the order of the arcs per node.</p>
<pre class="doctools_example">
    # A possible serialization for the graph structure
    #
    #        d -----&gt; %2
    #       /         ^ \\
    #      /         /   \\
    #     /         b     \\
    #    /         /       \\
    #  %1 &lt;- a - %0         e
    #    ^         \\      /
    #     \\        c     /
    #      \\        \\  /
    #       \\        v v
    #        f ------ %3
    # is






|
|
|
|







671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
attributes, and the values are the values for each name.</p>
<p><em>Note:</em> The order of the nodes in the serialization has no
relevance, nor has the order of the arcs per node.</p>
<pre class="doctools_example">
    # A possible serialization for the graph structure
    #
    #        d -----&gt; %2
    #       /         ^ \
    #      /         /   \
    #     /         b     \
    #    /         /       \
    #  %1 &lt;- a - %0         e
    #    ^         \\      /
    #     \\        c     /
    #      \\        \\  /
    #       \\        v v
    #        f ------ %3
    # is

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

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
    #   values for the attribute 'data',
    #   for all nodes in the set which
    #   have such an attribute.
    # - And returns this information.
    # Below we can see the same query, but rewritten
    # to show the structure as it is seen by the query
    # interpreter.
    q query \\
	    root \\
	    children \\
	    get data
</pre>
<p>The operators of the TreeQL language available for this are explained
in the section about <span class="sectref"><a href="#section3">The Tree Query Language</a></span>. This section
also explains the term <i class="term">node set</i> used above.</p></dd>
<dt><a name="3"><i class="arg">qo</i> <b class="method">result</b></a></dt>
<dd><p>This method returns a list containing the current node set.</p></dd>






|
|
|







250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
    #   values for the attribute 'data',
    #   for all nodes in the set which
    #   have such an attribute.
    # - And returns this information.
    # Below we can see the same query, but rewritten
    # to show the structure as it is seen by the query
    # interpreter.
    q query \
	    root \
	    children \
	    get data
</pre>
<p>The operators of the TreeQL language available for this are explained
in the section about <span class="sectref"><a href="#section3">The Tree Query Language</a></span>. This section
also explains the term <i class="term">node set</i> used above.</p></dd>
<dt><a name="3"><i class="arg">qo</i> <b class="method">result</b></a></dt>
<dd><p>This method returns a list containing the current node set.</p></dd>

Changes to modules/doctools/doctools.man.

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

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






|
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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16



17
18
19
20
21
22
23
..
45
46
47
48
49
50
51




52
53
54
55
56
57
58
...
348
349
350
351
352
353
354

355
356
357

358
359
360
361
362
363
364
# -*- tcl -*-
#
# fmt.html
#
# Copyright (c) 2001-2008 Andreas Kupries <[email protected]>
#
# Definitions to convert a tcl based manpage definition into
# a manpage based upon HTML markup.
#
################################################################
################################################################

dt_source _common.tcl   ; # Shared code
dt_source _html.tcl     ; # HTML basic formatting
dt_source _xref.tcl     ; # xref management




proc c_copyrightsymbol {} {return "[markup "&"]copy;"}

proc bgcolor {} {return ""}
proc border  {} {return 0}
proc Year    {} {clock format [clock seconds] -format %Y}

c_holdBuffers require synopsis
................................................................................
    set liststack [lreplace $liststack end end]
    foreach {t l} $t break
    litc_set $l
    return $t
}

proc fmt_plain_text {text} {




    return $text
}

################################################################
# Formatting commands.

c_pass 1 fmt_manpage_begin {title section version} {c_cinit ; c_clrSections ; return}
................................................................................
    append text "Database Class:\t[bold $dbclass optdbclass][tag br]\n"
    fmt_lst_item $text
}

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

proc fmt_example_begin {} {

	return [para_close]\n[tag* pre class doctools_example]
}
proc fmt_example_end   {} {

    return [tag/ pre]\n[para_open]
}
proc fmt_example {code} {
    return "[fmt_example_begin][fmt_plain_text $code][fmt_example_end]"
}

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



|











>
>
>







 







>
>
>
>







 







>
|


>







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
..
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
...
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
# -*- tcl -*-
#
# fmt.html
#
# Copyright (c) 2001-2019 Andreas Kupries <[email protected]>
#
# Definitions to convert a tcl based manpage definition into
# a manpage based upon HTML markup.
#
################################################################
################################################################

dt_source _common.tcl   ; # Shared code
dt_source _html.tcl     ; # HTML basic formatting
dt_source _xref.tcl     ; # xref management

global _in_example
set    _in_example 0

proc c_copyrightsymbol {} {return "[markup "&"]copy;"}

proc bgcolor {} {return ""}
proc border  {} {return 0}
proc Year    {} {clock format [clock seconds] -format %Y}

c_holdBuffers require synopsis
................................................................................
    set liststack [lreplace $liststack end end]
    foreach {t l} $t break
    litc_set $l
    return $t
}

proc fmt_plain_text {text} {
    global _in_example
    if {$_in_example} {
	set text [string map [list \\\\\n \\\n] $text]
    }
    return $text
}

################################################################
# Formatting commands.

c_pass 1 fmt_manpage_begin {title section version} {c_cinit ; c_clrSections ; return}
................................................................................
    append text "Database Class:\t[bold $dbclass optdbclass][tag br]\n"
    fmt_lst_item $text
}

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

proc fmt_example_begin {} {
    global _in_example ; set _in_example 1
    return [para_close]\n[tag* pre class doctools_example]
}
proc fmt_example_end   {} {
    global _in_example ; set _in_example 0
    return [tag/ pre]\n[para_open]
}
proc fmt_example {code} {
    return "[fmt_example_begin][fmt_plain_text $code][fmt_example_end]"
}

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

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

19
20
21
22
23
24
25










26
27
28
29
30
31
32
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} {










	return $text
    }
    return [texEscape $text]
}

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







>
>
>
>
>
>
>
>
>
>







19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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}

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

33
34
35
36
37
38
39

40
41
42
43











44
45







46

47
48
49
50
51
52
53
...
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
383
384
385
386
proc In? {} {
    if {![CAttrHas mdindent]} {
	CAttrSet mdindent ""
    }
    CAttrGet mdindent
}

proc In! {ws} {
    CAttrSet mdindent $ws
}












proc NewExample {} {
    return [ContextNew Example {







	VerbatimOn ; Example! ; Prefix+ "    "

    }] ; # {}
}

proc NewUnorderedList {} {
    # Itemized list - unordered list - bullet
    # 1. Base context provides indentation.
    # 2. First paragraph in a list item.
................................................................................
    set kw [c_xref_keywords]
    set ca [c_xref_category]
    set ct [c_get_copyright]

    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







    # In examples (verbatim markup) markdown's special characters are
    # no such by default, thus must not be quoted. Mark them as
    # protected from quoting.










    set t [Mark [Text?]]

    TextClear
    Text $t
    
    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.
	ContextPush
	ContextSet $penv
	#if {[CloseParagraph [Example]]} PAdvance
	CloseParagraph [Example]
	ContextPop
    } else {
	# In a regular paragraph we simple close the example
	#if {[CloseParagraph [Example]]} PAdvance
	CloseParagraph [Example]
    }

    #puts_stderr "AAA/fmt_example_end/Done"
    return
}

proc c_get_copyright {} {






>




>
>
>
>
>
>
>
>
>
>
>
|
|
>
>
>
>
>
>
>
|
>







 







|
|







>
>
>
>
>
>


|
>
>
>
>
>
>
>
>
>
>
|
>











<
|



<
|







33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
...
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
404
405
406
407
408
409

410
411
412
413

414
415
416
417
418
419
420
421
proc In? {} {
    if {![CAttrHas mdindent]} {
	CAttrSet mdindent ""
    }
    CAttrGet mdindent
}

proc In! {ws} {
    CAttrSet mdindent $ws
}

proc Example {complex} {
    if {![CAttrHas exenv$complex]} {
	ContextPush
	set exenv [NewExample $complex]
	ContextPop
	CAttrSet exenv$complex $exenv
	ContextCommit
    }
    return [CAttrGet exenv$complex]
}

proc NewExample {complex} {
    return [ContextNew Example$complex {
	VerbatimOn
	Example!
	if {$complex} {
	    # Block quote
	    Prefix+ "> "
	} else {
	    # Code block
	    Prefix+ "    "
	}
    }] ; # {}
}

proc NewUnorderedList {} {
    # Itemized list - unordered list - bullet
    # 1. Base context provides indentation.
    # 2. First paragraph in a list item.
................................................................................
    set kw [c_xref_keywords]
    set ca [c_xref_category]
    set ct [c_get_copyright]

    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.
    set complex [string match *\1* [Text?]]

    #puts_stderr "AAA/fmt_example_end/$complex"
    
    # In examples (verbatim markup) markdown's special characters are
    # no such by default, thus must not be quoted. Mark them as
    # protected from quoting. Further look for and convert
    # continuation lines protected from Tcl substitution into a
    # regular continuation line.
    set t [Text?]
    set t [string map [list \\\\\n \\\n] $t]
    if {$complex} {
	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 != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.
	ContextPush
	ContextSet $penv

	CloseParagraph [Example $complex]
	ContextPop
    } else {
	# In a regular paragraph we simple close the example

	CloseParagraph [Example $complex]
    }

    #puts_stderr "AAA/fmt_example_end/Done"
    return
}

proc c_get_copyright {} {

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

11
12
13
14
15
16
17



18
19









20
21
22
23
24
25
26
...
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
################################################################
# Load shared code, load nroff support.

dt_source _common.tcl
dt_source _nroff.tcl




################################################################
# Define the API commands.










c_pass 1 fmt_manpage_begin {title section version} c_begin
c_pass 2 fmt_manpage_begin {title section version} {
    c_begin

    set module      [dt_module]
    set shortdesc   [c_get_module]
................................................................................
    append text "[nr_item]\n"
    return $text
}

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

proc fmt_example_begin {} {

    return [nr_cs]\n
}
proc fmt_example_end   {} {

    if {[dt_lnesting]} {
	return [nr_ce][nr_item]
    }
    nr_ce
}
proc fmt_example {code} { 

    set lines [list "" [nr_cs]]
    foreach line [split $code "\n"] {
    	lappend lines [fmt_plain_text $line]
    }
    lappend lines [nr_ce] ""

    return [join $lines "\n"]
}

proc fmt_nl     {}     {nr_vspace}
proc fmt_arg    {text} {underline $text}
proc fmt_cmd    {text} {bold      $text}
proc fmt_emph   {text} {underline $text}






>
>
>


>
>
>
>
>
>
>
>
>







 







>



>





|
>





>







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
...
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
################################################################
# Load shared code, load nroff support.

dt_source _common.tcl
dt_source _nroff.tcl

global _in_example
set    _in_example 0

################################################################
# Define the API commands.

# Called to handle plain text from the input
proc fmt_plain_text {text} {
    global _in_example
    if {$_in_example} {
	set text [string map [list \\\\\n \\\n] $text]
    }
    return $text
}

c_pass 1 fmt_manpage_begin {title section version} c_begin
c_pass 2 fmt_manpage_begin {title section version} {
    c_begin

    set module      [dt_module]
    set shortdesc   [c_get_module]
................................................................................
    append text "[nr_item]\n"
    return $text
}

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

proc fmt_example_begin {} {
    global _in_example ; set _in_example 1
    return [nr_cs]\n
}
proc fmt_example_end   {} {
    global _in_example ; set _in_example 0
    if {[dt_lnesting]} {
	return [nr_ce][nr_item]
    }
    nr_ce
}
proc fmt_example {code} {
    global _in_example ; set _in_example 1
    set lines [list "" [nr_cs]]
    foreach line [split $code "\n"] {
    	lappend lines [fmt_plain_text $line]
    }
    lappend lines [nr_ce] ""
    set _in_example 0
    return [join $lines "\n"]
}

proc fmt_nl     {}     {nr_vspace}
proc fmt_arg    {text} {underline $text}
proc fmt_cmd    {text} {bold      $text}
proc fmt_emph   {text} {underline $text}

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

462
463
464
465
466
467
468
469






470
471
472
473
474
475
476
    return
}

c_pass 1 fmt_example_end {} NOP
c_pass 2 fmt_example_end {} {
    #puts_stderr "AAA/fmt_example_end"
    TextTrimLeadingSpace
    






    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.
	ContextPush






|
>
>
>
>
>
>







462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
    return
}

c_pass 1 fmt_example_end {} NOP
c_pass 2 fmt_example_end {} {
    #puts_stderr "AAA/fmt_example_end"
    TextTrimLeadingSpace

    # Look for and convert continuation lines protected from Tcl
    # substitution into a regular continuation line.
    set t [string map [list \\\\\n \\\n] [Text?]]
    TextClear
    Text $t

    set penv [GetCurrent]
    if {$penv != {}} {
	# In a list we save the current list context, activate the
	# proper paragraph context and create its example
	# variant. After closing the paragraph using the example we
	# restore and reactivate the list context.
	ContextPush

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

36
37
38
39
40
41
42


43

44





45












46
47
48
49
50
51
52
proc fmt_cmd	{text}	{ wrap $text cmd }
proc fmt_emph	{text}	{ wrap $text emph }
proc fmt_opt 	{text}	{ wrap $text o }

c_pass 1 fmt_example_begin {}	NOP
c_pass 1 fmt_example_end {} 	NOP
c_pass 1 fmt_example {code}	NOP


c_pass 2 fmt_example_begin {}	{ sequence [xmlContext $::block] [start example] }

c_pass 2 fmt_example_end   {}	{ end example }





c_pass 2 fmt_example {code} 	{ sequence [xmlContext $::block] [wrap $code example] }













proc fmt_comment {text} {xmlComment $text}
proc fmt_sectref {text {id {}}} {
    global SectionNames
    if {$id == {}} {
	set id [c_sectionId $text]
    }






>
>
|
>
|
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>







36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
proc fmt_cmd	{text}	{ wrap $text cmd }
proc fmt_emph	{text}	{ wrap $text emph }
proc fmt_opt 	{text}	{ wrap $text o }

c_pass 1 fmt_example_begin {}	NOP
c_pass 1 fmt_example_end {} 	NOP
c_pass 1 fmt_example {code}	NOP
c_pass 2 fmt_example_begin {}	{
    global inexample ; set inexample 1
    sequence [xmlContext $::block] [start example]
}
c_pass 2 fmt_example_end   {}	{
    global inexample ; set inexample 0
    end example
}
c_pass 2 fmt_example {code} {
    set code [string map [list \\\\\n \\\n] $code]
    sequence [xmlContext $::block] [wrap $code example]
}

global inexample
set    inexample 0

proc fmt_plain_text {text} {
    global inexample
    if {$inexample} {
	set text [string map [list \\\\\n \\\n] $text]
    }
    return $text
}

proc fmt_comment {text} {xmlComment $text}
proc fmt_sectref {text {id {}}} {
    global SectionNames
    if {$id == {}} {
	set id [c_sectionId $text]
    }

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

198
199
200
201
202
203
204








205
206
207
208
209
210
211
...
212
213
214
215
216
217
218
219

220
221
222
223
224
225
226
...
281
282
283
284
285
286
287

288
289
290
291
292
293
294
295
    return $text
}

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

global textmode
set    textmode ""









proc fmt_example_begin {} {
    global  mode_save textmode
    lappend mode_save $textmode
    set     textmode example
    return "\n======\n"
}
................................................................................
proc fmt_example_end   {} {
    global  mode_save textmode
    set textmode  [lindex $mode_save end]
    set mode_save [lrange $mode_save 0 end-1]
    return "\n======\n"
}
proc fmt_example {code} {
    return "$code"

}

proc emph    {text} {return ''$text''}
proc strong  {text} {return '''$text'''}

proc fmt_arg     {text} {return ''$text''}
proc fmt_cmd     {text} {return '''$text'''}
................................................................................
    # For the wiki we have to force certain text into a single line.
    # We also have to make sure that the text is on the same line as
    # the initiator (i.e. list bullet).

    global textmode

    if {"$textmode" == "example"} {

	return "$text"
    }

    regsub -all "\[ \t\n\]+" $text { } text
    return $text
}

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






>
>
>
>
>
>
>
>







 







|
>







 







>








198
199
200
201
202
203
204
205
206
207
208
209
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
...
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
    return $text
}

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

global textmode
set    textmode ""

# NOTE: The example_begin/end combo allows for the example
# text to contain markup. The currently used verbatim
# environment will cause show the wiki markup of the example,
# instead of formatting per that markup.
#
# TODO: Strip internal markup from the example text, wiki cannot
# handle such at all.

proc fmt_example_begin {} {
    global  mode_save textmode
    lappend mode_save $textmode
    set     textmode example
    return "\n======\n"
}
................................................................................
proc fmt_example_end   {} {
    global  mode_save textmode
    set textmode  [lindex $mode_save end]
    set mode_save [lrange $mode_save 0 end-1]
    return "\n======\n"
}
proc fmt_example {code} {
    set code [string map [list \\\\\n \\\n] $code]
    return "\n======\n$code\n======\n"
}

proc emph    {text} {return ''$text''}
proc strong  {text} {return '''$text'''}

proc fmt_arg     {text} {return ''$text''}
proc fmt_cmd     {text} {return '''$text'''}
................................................................................
    # For the wiki we have to force certain text into a single line.
    # We also have to make sure that the text is on the same line as
    # the initiator (i.e. list bullet).

    global textmode

    if {"$textmode" == "example"} {
	set text [string map [list \\\\\n \\\n] $text]
	return "$text"
    }

    regsub -all "\[ \t\n\]+" $text { } text
    return $text
}

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

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

Added modules/doctools/tests/fmt/desc/26.

Added modules/doctools/tests/fmt/html/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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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
106
107
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
<!DOCTYPE html><html><head>
<title>TEST - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- TEST.z
   -->
<body><div class="doctools">
<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>TEST -</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<pre class="doctools_example">
Example Block  More Lines \
Ever More
Never
</pre>
<p>............... Weiter .............</p>
<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>

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

Added modules/doctools/tests/fmt/list/26.



>
1
manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE}

Added modules/doctools/tests/fmt/man/26.














































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[comment { -- Example 2 }]
[manpage_begin TEST z 3.14.15.926]
[description]
[example {
Example Block \
More Lines \\
Ever More
Never
}]
[para]
............... Weiter .............
[para]
[example_begin]
Second \
Continuing Lines \\
Done
[example_end]
............... Vorwaerts ..........
[example_begin]
[cmd command] \\
-- [cmd command] --
[example_end]
[manpage_end]

Added modules/doctools/tests/fmt/markdown/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
33
34
35
36
37
38
39
[//000000001]: # (TEST \- )
[//000000002]: # (Generated from file '\.FILE\.' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; \.COPYRIGHT\.)
[//000000004]: # (TEST\(z\) 3\.14\.15\.926 \.MODULE\. "")

# NAME

TEST \-

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Copyright](#copyright)

# <a name='description'></a>DESCRIPTION

    Example Block  More Lines \
    Ever More
    Never

\.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Weiter \.\.\.\.\.\.\.\.\.\.\.\.\.

    Second \
    Continuing Lines \
    Done

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

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

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

Copyright &copy; \.COPYRIGHT\.

Added modules/doctools/tests/fmt/nroff/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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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
106
107
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
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
219
220
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
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
298
299
300
301
302
303
304
305
306
307
308
'\"
'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff'
'\" Copyright (c) \&.COPYRIGHT\&.
'\"
.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. ""
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
TEST \-
.SH DESCRIPTION
.CS


Example Block  More Lines \\
Ever More
Never

.CE
.PP
\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&. Weiter \&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.
.PP
.CS


Second \\
Continuing Lines \\
Done

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


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

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

.fi

Added modules/doctools/tests/fmt/null/26.

Added modules/doctools/tests/fmt/syntax/26.

Added modules/doctools/tests/fmt/text/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
TEST - 
Generated from file '.FILE.' by tcllib/doctools with format 'text'
TEST(z) 3.14.15.926 .MODULE. ""

NAME
====

TEST -

DESCRIPTION
===========

| Example Block  More Lines \
| Ever More
| Never

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

| Second \
| Continuing Lines \
| Done

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

| command \
| -- command --

COPYRIGHT
=========

Copyright (c) .COPYRIGHT.

Added modules/doctools/tests/fmt/tmml/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
33
34
35
36
37
38
39
40
41
42
43
44
45
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' -->
<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'>
<head>
<info key='copyright' value='Copyright (c) .COPYRIGHT.'/>
</head>
<namesection>
<name>TEST</name>
<desc></desc>

</namesection>


<section id='section1'>
<title>DESCRIPTION</title>

<example>
Example Block  More Lines \
Ever More
Never

</example>

<p>
............... Weiter .............
</p>
<p>
</p>
<example>
Second \
Continuing Lines \
Done

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

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

</example>
</section>



</manpage>

Added modules/doctools/tests/fmt/wiki/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
33
34
35
36
37
'''TEST 3.14.15.926''' '''.MODULE.'''




**DESCRIPTION**


======

Example Block  More Lines \
Ever More
Never

======

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

======

Second \
Continuing Lines \
Done

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

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

======


**COPYRIGHT**

 Copyright (c) .COPYRIGHT.