Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | Doctools: - Markdown: Fix indentation for examples formatted as block quotes. Replace leading whitespace with non-breaking spaces. Note: Works only for leading whitespace. Non-breaking inner spaces seem to cause trouble, i.e. are not recognized and not formatted. - Latex: changed to use `alltt` as the environment for examples. This allows markup the same as doctools does for example_begin/end. Refixed handling of continuation lines to use the proper latex macro for the character. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.4 B (latex, markdown) T (latex, markdown) |
|---|---|
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
97fc04ebd2784127f4fd317909a81c8a |
| User & Date: | aku 2019-04-12 06:49:12 |
Context
|
2019-04-12
| ||
| 21:59 | mime - Tkt [57909d2e1c] - Issue introduced with commit [913f7d92c5c35342]. Conversion of superfluous nested `expr` command forgot to convert braces to proper parens. This was able to break \r detection at the end of a line. - Further properly indented some of the code around this. - Lastly removed superflous reboxing of `mime::initializeaux` in `mime::initialize`. The command got boxed followed by immediate unboxing, making the whole thing superflous. Version bump 1.6.1 - (B) mime - (T) mime check-in: b2ae85b606 user: aku tags: trunk | |
| 15:12 | Get doctools example and indent fixes check-in: 5f9bcaa466 user: aku tags: doc-overhaul | |
| 06:49 | Doctools: - Markdown: Fix indentation for examples formatted as block quotes. Replace leading whitespace with non-breaking spaces. Note: Works only for leading whitespace. Non-breaking inner spaces seem to cause trouble, i.e. are not recognized and not formatted. - Latex: changed to use `alltt` as the environment for examples. This allows markup the same as doctools does for example_begin/end. Refixed handling of continuation lines to use the proper latex macro for the character. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.4 B (latex, markdown) T (latex, markdown) check-in: 97fc04ebd2 user: aku tags: trunk | |
|
2019-04-11
| ||
| 20:00 | dicttool - Tkt [e79990908f] - Fixed doc grammar. No version change. Removed DOS EOL from .md doc variant. check-in: e6a4a02868 user: aku tags: trunk | |
Changes
Changes to embedded/md/tcllib/files/modules/bench/bench_lang_intro.md.
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
...
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
In our example, directly drawn from the benchmark suite of Tcllib's
__[aes](\.\./aes/aes\.md)__ package, the concrete initialization code
constructs the key schedule used by the encryption command whose speed we
measure, and the cleanup code releases any resources bound to that schedule\.
> bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{
> set key \[aes::Init ecb $k $i\]
> \} \-body \{
> aes::Encrypt $key $p
> \} __\-post__ \{
> aes::Final $key
> \}
>
## <a name='subsection4'></a>Advanced pre\- and postprocessing
Our last example again deals with initialization and cleanup code\. To see the
difference to the regular initialization and cleanup discussed in the last
................................................................................
initialization and cleanup\. Its concrete initialization code constructs a
variable refering to a set with specific properties \(The set has a string
representation, which is shared\) affecting the speed of the inclusion command,
and the cleanup code releases the temporary variables created by this
initialization\.
> bench \-desc "set include, missing <SC> x$times $n" __\-ipre__ \{
> set A $sx\($times,$n\)
> set B $A
> \} \-body \{
> struct::set include A x
> \} __\-ipost__ \{
> unset A B
> \}
>
# <a name='section2'></a>FURTHER READING
Now that this document has been digested the reader, assumed to be a *writer*
of benchmarks, he should be fortified enough to be able to understand the formal
|
|
|
|
|
|
|
|
|
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
...
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
In our example, directly drawn from the benchmark suite of Tcllib's
__[aes](\.\./aes/aes\.md)__ package, the concrete initialization code
constructs the key schedule used by the encryption command whose speed we
measure, and the cleanup code releases any resources bound to that schedule\.
> bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{
> set key \[aes::Init ecb $k $i\]
> \} \-body \{
> aes::Encrypt $key $p
> \} __\-post__ \{
> aes::Final $key
> \}
>
## <a name='subsection4'></a>Advanced pre\- and postprocessing
Our last example again deals with initialization and cleanup code\. To see the
difference to the regular initialization and cleanup discussed in the last
................................................................................
initialization and cleanup\. Its concrete initialization code constructs a
variable refering to a set with specific properties \(The set has a string
representation, which is shared\) affecting the speed of the inclusion command,
and the cleanup code releases the temporary variables created by this
initialization\.
> bench \-desc "set include, missing <SC> x$times $n" __\-ipre__ \{
> set A $sx\($times,$n\)
> set B $A
> \} \-body \{
> struct::set include A x
> \} __\-ipost__ \{
> unset A B
> \}
>
# <a name='section2'></a>FURTHER READING
Now that this document has been digested the reader, assumed to be a *writer*
of benchmarks, he should be fortified enough to be able to understand the formal
|
Changes to embedded/md/tcllib/files/modules/docstrip/docstrip.md.
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 |
that files employing that document format are given the suffix "\.ddt", to distinguish them from the more traditional LaTeX\-based "\.dtx" files\. Master source files with "\.dtx" extension are usually set up so that they can be typeset directly by __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ without any support from other files\. This is achieved by beginning the file with the lines > % \\iffalse > %<\*driver> > \\documentclass\{tclldoc\} > \\begin\{document\} > \\DocInput\{*filename\.dtx*\} > \\end\{document\} > %</driver> > % \\fi > or some variation thereof\. The trick is that the file gets read twice\. With normal LaTeX reading rules, the first two lines are comments and therefore ignored\. The third line is the document preamble, the fourth line begins the document body, and the sixth line ends the document, so LaTeX stops there — non\-comments below that point in the file are never subjected to the normal |
| | | | | | | | |
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 |
that files employing that document format are given the suffix "\.ddt", to distinguish them from the more traditional LaTeX\-based "\.dtx" files\. Master source files with "\.dtx" extension are usually set up so that they can be typeset directly by __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ without any support from other files\. This is achieved by beginning the file with the lines > % \\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 |
Changes to embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md.
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 |
characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. > # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\. |
| | | | | |
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 |
characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > 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\. |
Changes to embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md.
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 |
characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. > # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\. |
| | | | | |
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 |
characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > 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\. |
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 © 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> | <a href="../../../toc.md">Table Of Contents</a> | <a href="../../../../index.md">Keyword Index</a> | <a href="../../../../toc0.md">Categories</a> | <a href="../../../../toc1.md">Modules</a> | <a href="../../../../toc2.md">Applications</a> ] <hr> ................................................................................ - [Category](#category) - [Copyright](#copyright) # <a name='synopsis'></a>SYNOPSIS package require Tcl 8\.2 package require doctools ?1\.5\.3? [__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1) [__::doctools::help__](#2) [__::doctools::search__ *path*](#3) [__objectName__ __method__ ?*arg arg \.\.\.*?](#4) [*objectName* __configure__](#5) [*objectName* __configure__ *option*](#6) |
|
|
|
1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
[//000000001]: # (doctools \- Documentation tools) [//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>) [//000000004]: # (doctools\(n\) 1\.5\.4 tcllib "Documentation tools") <hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a href="../../../toc.md">Table Of Contents</a> | <a href="../../../../index.md">Keyword Index</a> | <a href="../../../../toc0.md">Categories</a> | <a href="../../../../toc1.md">Modules</a> | <a href="../../../../toc2.md">Applications</a> ] <hr> ................................................................................ - [Category](#category) - [Copyright](#copyright) # <a name='synopsis'></a>SYNOPSIS package require Tcl 8\.2 package require doctools ?1\.5\.4? [__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1) [__::doctools::help__](#2) [__::doctools::search__ *path*](#3) [__objectName__ __method__ ?*arg arg \.\.\.*?](#4) [*objectName* __configure__](#5) [*objectName* __configure__ *option*](#6) |
Changes to embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md.
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 ... 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 ... 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 ... 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 ... 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 ... 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 ... 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 ... 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 |
command closes the previous paragraph and automatically opens the next\. The first paragraph is automatically opened at the beginning of the body, by __description__\. In the same manner the last paragraph automatically ends at __manpage\_end__\. > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[__para__\] > \.\.\. > \[__para__\] > \.\.\. > \[manpage\_end\] > Empty paragraphs are ignored\. A structure coarser than paragraphs are sections, which allow the writer to split a document into larger, and labeled, pieces\. The command for doing so is ................................................................................ automatically ends at __manpage\_end__\. Empty sections are *not* ignored\. We are free to \(not\) use paragraphs within sections\. > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[__section \{Section A\}__\] > \.\.\. > \[para\] > \.\.\. > \[__section \{Section B\}__\] > \.\.\. > \[manpage\_end\] > Between sections and paragraphs we have subsections, to split sections\. The command for doing so is __subsection__\. Each occurrence of this command closes the previous subsection and automatically opens the next, including its first paragraph\. A subsection is automatically opened at the beginning of the ................................................................................ manner the last subsection automatically ends at __manpage\_end__\. Empty subsections are *not* ignored\. We are free to \(not\) use paragraphs within subsections\. > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[section \{Section A\}\] > \.\.\. > \[__subsection \{Sub 1\}__\] > \.\.\. > \[para\] > \.\.\. > \[__subsection \{Sub 2\}__\] > \.\.\. > \[section \{Section B\}\] > \.\.\. > \[manpage\_end\] > ## <a name='subsection5'></a>Text markup Having handled the overall structure a writer can impose on the document we now take a closer at the text in a paragraph\. ................................................................................ Its argument is a widget name\. The example demonstrating the use of text markup is an excerpt from the *[doctools language command reference](doctools\_lang\_cmdref\.md)*, with some highlighting added\. It shows their use within a block of text, as the arguments of a list item command \(__call__\), and our ability to nest them\. > \.\.\. > \[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\] > > Text structure\. List element\. Argument list\. Automatically closes the > previous list element\. Specifies the data\-\[__arg type__\] of the described > argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The > latter is optional\. > \.\.\. > ## <a name='subsection6'></a>Escapes Beyond the 20 commands for simple markup shown in the previous section we have two more available which are technically simple markup\. However their function is not the marking up of phrases as specific types of things, but the insertion ................................................................................ of characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. > ## <a name='subsection7'></a>Cross\-references The last two commands we have to discuss are for the declaration of cross\-references between documents, explicit and implicit\. They are __[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both ................................................................................ whether she wants to have them at the beginning of the body, or at its end, maybe near the place a keyword is actually defined by the main content, or considers them as meta data which should be in the header, etc\. Our example shows the sources for the cross\-references of this document, with some highlighting added\. Incidentally they are found at the end of the body\. > \.\.\. > \[__see\_also doctools\_intro__\] > \[__see\_also doctools\_lang\_syntax__\] > \[__see\_also doctools\_lang\_cmdref__\] > \[__keywords markup \{semantic markup\}__\] > \[__keywords \{doctools markup\} \{doctools language\}__\] > \[__keywords \{doctools syntax\} \{doctools commands\}__\] > \[manpage\_end\] > ## <a name='subsection8'></a>Examples Where ever we can write plain text we can write examples too\. For simple examples we have the command __example__ which takes a single argument, the text of the argument\. The example text must not contain markup\. If we wish to ................................................................................ templating commands within example blocks to read their contents from a file \(Remember section [Advanced structure](#subsection3)\)\. The source for the very first example in this document \(see section [Fundamentals](#subsection1)\), with some highlighting added, is > \[__example__ \{ > \.\.\. \[list\_begin enumerated\] \.\.\. > \}\] > Using __example\_begin__ / __example\_end__ this would look like > \[__example\_begin__\] > \.\.\. \[list\_begin enumerated\] \.\.\. > \[__example\_end__\] > ## <a name='subsection9'></a>Lists Where ever we can write plain text we can write lists too\. The main commands are __list\_begin__ to start a list, and __list\_end__ to close one\. The opening command takes an argument specifying the type of list started it, and ................................................................................ is a specialized form of a term definition list where the term is the name of a configuration option for a widget, with its name and class in the option database\. Our example is the source of the definition list in the previous paragraph, with most of the content in the middle removed\. > \.\.\. > \[__list\_begin__ definitions\] > \[__def__ \[const arg\]\] > > \(\[cmd arg\_def\]\) This opens an argument \(declaration\) list\. It is a > specialized form of a definition list where the term is an argument > name, with its type and i/o\-mode\. > > \[__def__ \[const itemized\]\] > > \(\[cmd item\]\) > This opens a general itemized list\. > > \.\.\. > \[__def__ \[const tkoption\]\] > > \(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It > is a specialized form of a definition list where the term is the name > of a configuration option for a widget, with its name and class in the > option database\. > > \[__list\_end__\] > \.\.\. > Note that a list cannot begin in one \(sub\)section and end in another\. Differently said, \(sub\)section breaks are not allowed within lists and list items\. An example of this *illegal* construct is > \.\.\. > \[list\_begin itemized\] > \[item\] > \.\.\. > \[__section \{ILLEGAL WITHIN THE LIST\}__\] > \.\.\. > \[list\_end\] > \.\.\. > # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[doctools language syntax](doctools\_lang\_syntax\.md)* specification as |
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 ... 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 ... 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 ... 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 ... 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 ... 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 ... 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 ... 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 |
command closes the previous paragraph and automatically opens the next\. The first paragraph is automatically opened at the beginning of the body, by __description__\. In the same manner the last paragraph automatically ends at __manpage\_end__\. > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[__para__\] > \.\.\. > \[__para__\] > \.\.\. > \[manpage\_end\] > Empty paragraphs are ignored\. A structure coarser than paragraphs are sections, which allow the writer to split a document into larger, and labeled, pieces\. The command for doing so is ................................................................................ automatically ends at __manpage\_end__\. Empty sections are *not* ignored\. We are free to \(not\) use paragraphs within sections\. > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[__section \{Section A\}__\] > \.\.\. > \[para\] > \.\.\. > \[__section \{Section B\}__\] > \.\.\. > \[manpage\_end\] > Between sections and paragraphs we have subsections, to split sections\. The command for doing so is __subsection__\. Each occurrence of this command closes the previous subsection and automatically opens the next, including its first paragraph\. A subsection is automatically opened at the beginning of the ................................................................................ manner the last subsection automatically ends at __manpage\_end__\. Empty subsections are *not* ignored\. We are free to \(not\) use paragraphs within subsections\. > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[section \{Section A\}\] > \.\.\. > \[__subsection \{Sub 1\}__\] > \.\.\. > \[para\] > \.\.\. > \[__subsection \{Sub 2\}__\] > \.\.\. > \[section \{Section B\}\] > \.\.\. > \[manpage\_end\] > ## <a name='subsection5'></a>Text markup Having handled the overall structure a writer can impose on the document we now take a closer at the text in a paragraph\. ................................................................................ Its argument is a widget name\. The example demonstrating the use of text markup is an excerpt from the *[doctools language command reference](doctools\_lang\_cmdref\.md)*, with some highlighting added\. It shows their use within a block of text, as the arguments of a list item command \(__call__\), and our ability to nest them\. > \.\.\. > \[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\] > > Text structure\. List element\. Argument list\. Automatically closes the > previous list element\. Specifies the data\-\[__arg type__\] of the described > argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The > latter is optional\. > \.\.\. > ## <a name='subsection6'></a>Escapes Beyond the 20 commands for simple markup shown in the previous section we have two more available which are technically simple markup\. However their function is not the marking up of phrases as specific types of things, but the insertion ................................................................................ of characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. > ## <a name='subsection7'></a>Cross\-references The last two commands we have to discuss are for the declaration of cross\-references between documents, explicit and implicit\. They are __[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both ................................................................................ whether she wants to have them at the beginning of the body, or at its end, maybe near the place a keyword is actually defined by the main content, or considers them as meta data which should be in the header, etc\. Our example shows the sources for the cross\-references of this document, with some highlighting added\. Incidentally they are found at the end of the body\. > \.\.\. > \[__see\_also doctools\_intro__\] > \[__see\_also doctools\_lang\_syntax__\] > \[__see\_also doctools\_lang\_cmdref__\] > \[__keywords markup \{semantic markup\}__\] > \[__keywords \{doctools markup\} \{doctools language\}__\] > \[__keywords \{doctools syntax\} \{doctools commands\}__\] > \[manpage\_end\] > ## <a name='subsection8'></a>Examples Where ever we can write plain text we can write examples too\. For simple examples we have the command __example__ which takes a single argument, the text of the argument\. The example text must not contain markup\. If we wish to ................................................................................ templating commands within example blocks to read their contents from a file \(Remember section [Advanced structure](#subsection3)\)\. The source for the very first example in this document \(see section [Fundamentals](#subsection1)\), with some highlighting added, is > \[__example__ \{ > \.\.\. \[list\_begin enumerated\] \.\.\. > \}\] > Using __example\_begin__ / __example\_end__ this would look like > \[__example\_begin__\] > \.\.\. \[list\_begin enumerated\] \.\.\. > \[__example\_end__\] > ## <a name='subsection9'></a>Lists Where ever we can write plain text we can write lists too\. The main commands are __list\_begin__ to start a list, and __list\_end__ to close one\. The opening command takes an argument specifying the type of list started it, and ................................................................................ is a specialized form of a term definition list where the term is the name of a configuration option for a widget, with its name and class in the option database\. Our example is the source of the definition list in the previous paragraph, with most of the content in the middle removed\. > \.\.\. > \[__list\_begin__ definitions\] > \[__def__ \[const arg\]\] > > \(\[cmd arg\_def\]\) This opens an argument \(declaration\) list\. It is a > specialized form of a definition list where the term is an argument > name, with its type and i/o\-mode\. > > \[__def__ \[const itemized\]\] > > \(\[cmd item\]\) > This opens a general itemized list\. > > \.\.\. > \[__def__ \[const tkoption\]\] > > \(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It > is a specialized form of a definition list where the term is the name > of a configuration option for a widget, with its name and class in the > option database\. > > \[__list\_end__\] > \.\.\. > Note that a list cannot begin in one \(sub\)section and end in another\. Differently said, \(sub\)section breaks are not allowed within lists and list items\. An example of this *illegal* construct is > \.\.\. > \[list\_begin itemized\] > \[item\] > \.\.\. > \[__section \{ILLEGAL WITHIN THE LIST\}__\] > \.\.\. > \[list\_end\] > \.\.\. > # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[doctools language syntax](doctools\_lang\_syntax\.md)* specification as |
Changes to embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md.
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 ... 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 ... 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 ... 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 ... 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 ... 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 ... 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 ... 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 ... 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 ... 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 ... 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 ... 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 ... 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 |
If the entered data have been rejected \(via the *Cancel* button\) the
__argument\_dialogbox__ returns __cancel__\.
A small example illustrates how the __argument\_dialogbox__ can be
employed:
> set DialogResult \[__tepam::argument\_dialogbox__ \\
> __\-title__ "Itinerary selection" \\
> __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} \\
> __\-frame__ \{*\-label "Itinerary start"*\} \\
> __\-comment__ \{*\-text "Specify your itinerary start location"*\} \\
> __\-entry__ \{*\-label "City" \-variable start\_city \-type string*\} \\
> __\-entry__ \{*\-label "Street" \-variable start\_street \-type string \-optional 1*\} \\
> __\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\
> __\-frame__ \{*\-label "Itinerary destination"*\} \\
> __\-comment__ \{*\-text "Specify your itinerary destination"*\} \\
> __\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\
> __\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\
> __\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\
> __\-frame__ \{\} \\
> __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}
\] This example opens a dialog box that has the title *Itinerary
selection*\. A first entry widget in this box allows selecting a report
file\. It follows two frames to define respectively an itinerary start and
end location\. Each of these locations that are described with a comment has
three entry widgets to specify respectively the city, street and the street
number\. Bellow the second frame there is a check button that allows
................................................................................
form of a single list to __argument\_dialogbox__, and not as individual
arguments\. The second format that is supported by __argument\_dialogbox__
corresponds exactly to the first one, except that all item definitions are
packed into a single list that is provided to __argument\_dialogbox__\.
The previous example can therefore also be written in the following way:
> set DialogResult \[__tepam::argument\_dialogbox \{__
> __\-title__ "Itinerary selection"
> __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\}
> \.\.\.
> __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}
__\}__\]
The commands __argument\_dialogbox__ as well as
__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the
namespace __tepam__\. To use these commands without the __tepam::__
namespace prefix, it is sufficient to import them into the main namespace:
> __namespace import tepam::\*__
>
> set DialogResult \[__argument\_dialogbox__ \\
> \-title "Itinerary selection"
> \.\.\.
The following subsections explain the different argument item types that are
accepted by the __argument\_dialogbox__, classified into three groups\. The
first data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument\_dialogbox__\.
................................................................................
## <a name='subsection1'></a>Context Definition Items
The first item group allows specifying some context aspects of an argument
dialog box\. These items are taking a simple character string as item attribute:
> tepam::argument\_dialogbox \\
> __\-<argument\_name>__ *string* \\
> \.\.\.
The following items are classified into this group:
- \-title *string*
The dialog box window title which is by default *Dialog* can be changed
with the *\-title* item:
> tepam::argument\_dialogbox \\
> __\-title__ "System configuration" \\
> \.\.\.
- \-window *string*
The argument dialog box uses by default *\.dialog* as dialog top level
window\. This path can be changed with the *\-window* item:
> tepam::argument\_dialogbox \\
> __\-window__ \.dialog \\
> \.\.\.
- \-parent *string*
By defining a parent window, the argument dialog box will be displayed
beside this one\. Without explicit parent window definition, the top\-level
window will be considered as parent window\.
> tepam::argument\_dialogbox \\
> __\-parent__ \.my\_appl \\
> \.\.\.
- \-context *string*
If a context is defined the dialog box state, e\.g\. the entered data as well
as the window size and position, is restored the next time the argument
dialog box is called\. The assignment of a context allows saving the dialog
box state in its context to distinguish between different usages of the
argument dialog box\.
> tepam::argument\_dialogbox \\
> __\-context__ destination\_definitions \\
> \.\.\.
## <a name='subsection2'></a>Formatting and Display Options
Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user\. A couple of items allow structuring
and commenting the dialog boxes\.
The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-<argument\_name>__ \{ *
> ?\-<attribute\_name> <attribute\_value>?
> ?\-<attribute\_name> <attribute\_value>?
> ?\.\.\.?*
> \}
> \.\.\.
The following items are classified into this group:
- \-frame *list*
The *\-frame* item allows packing all following entry widgets into a
labeled frame, until a next frame item is defined or until the last entry
................................................................................
* \-label *string*
An optional frame label can be specified with the *\-label* statement\.
Example:
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-frame__ \{*\-label "Destination address"*\}
> \.\.\.
To close an open frame without opening a new one, an empty list has to be
provided to the *\-frame* statement\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-frame__ \{\}
> \.\.\.
- \-sep \[const \{\{\}\}\]
Entry widgets can be separated with the *\-sep* statement which doesn't
require additional definitions\. The related definition list has to exist,
but its content is ignored\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-sep__ \{\}
> \.\.\.
- \-comment *string*
Comments and descriptions can be added with the *\-text* attribute of the
*\-comment* item\. Please note that each entry widget itself can also
contain a *\-text* attribute for comments and descriptions\. But the
*\-comment* item allows for example adding a description between two
frames\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-comment__ \{*\-text "Specify bellow the destination address"*\}
> \.\.\.
- \-yscroll __0__|__1__|__auto__
This attribute allows controlling an eventual vertical scrollbar\. Setting it
to __0__ will permanently disable the scrollbar, setting it to __1__
will enable it\. By default it is set to __auto__\. The scrollbar is
enabled in this mode only if the vertical data entry form size exceeds 66%
of the screen height\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-yscroll__ __auto__
> \.\.\.
## <a name='subsection3'></a>Global Custom Data Validation
This item group allows specifying global custom checks to validate the entered
data\.
- \-validatecommand *script*
Custom data checks can be performed via validation commands that are defined
with the *\-validatecommand* item\. Example:
> tepam::argument\_dialogbox \\
> \-entry \{\-label "Your comment" \-variable YourCom\} \\
> __\-validatecommand__ \{IllegalWordDetector $YourCom\}
The validation command is executed in the context of the calling procedure,
once all the basic data checks have been performed and data variables are
assigned\. All data is accessed via the data variables\. Note that there is
also an entry widget specific attribute *\-validatecommand* that allows
declaring custom checks for specific data entries\.
................................................................................
## <a name='subsection4'></a>Data Entry Widget Items
Data entry widgets are created with the widget items\. These items require as
item attributes a definition list, which contains itself attribute name and
value pairs:
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-<argument\_name>__ \{ *
> ?\-<attribute\_name> <attribute\_value>?
> ?\-<attribute\_name> <attribute\_value>?
> ?\.\.\.?*
> \}
> \.\.\.
The attribute list can contain various attributes to describe and comment an
entry widget and to constrain its entered value\. All entry widgets are accepting
a common set of attributes that are described in the section [Entry Widget Item
Attributes](#subsection5)\.
TEPAM defines a rich set of entry widgets\. If necessary, this set can be
................................................................................
- \-entry *list*
The *\-entry* item generates the simplest but most universal data entry
widget\. It allows entering any kind of data in form of single line strings\.
> tepam::argument\_dialogbox \\
> __\-entry__ \{\-label Name \-variable Entry\}
- \-text *list*
The *\-text* item generates a multi line text entry widget\. The widget
height can be selected with the *\-height* attribute\.
> tepam::argument\_dialogbox \\
> __\-text__ \{\-label Name \-variable Text \-height 5\}
- \-checkbox *list*
A group of check boxes is created with the *\-checkbox* item\. The number of
check boxes and their option values are specified with a list assigned to
the *\-choices* attribute or via a variable declared with the
*\-choicevariable* attribute:
> tepam::argument\_dialogbox \\
> __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} \-default italic\}
If the labels of the check boxes should differ from the option values, their
labels can be defined with the *\-choicelabels* attribute:
> tepam::argument\_dialogbox \\
> __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} \\
> \-choicelabels \{Bold Italic Underline\} \\
> \-default italic\}
In contrast to a radio box group, a check box group allows selecting
simultaneously several choice options\. The selection is stored for this
reason inside the defined variable in form of a list, even if only one
choice option has been selected\.
- \-radiobox *list*
................................................................................
*\-choicevariable* attribute\.
In contrast to a check box group, a radio box group allows selecting
simultaneously only one choice option\. The selected option value is stored
directly, and not in form of a list, inside the defined variable\.
> tepam::argument\_dialogbox \\
> __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\
> \-choices \{left center right\} \-default left\}
If the labels of the radio boxes should differ from the option values, their
labels can be defined with the *\-choicelabels* attribute:
> tepam::argument\_dialogbox \\
> __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\
> \-choices \{left center right\} \\
> \-choicelabels \{Left Center Right\} \-default left\}
- \-checkbutton *list*
The *\-checkbutton* entry widget allows activating or deactivating a single
choice option\. The result written into the variable will either be __0__
if the check button was not activated or __1__ if it was activated\. An
eventually provided default value has also to be either __0__ or
__1__\.
> tepam::argument\_dialogbox \\
> __\-checkbutton__ \{\-label Capitalize \-variable Capitalize \-default 1\}
Several types of list and combo boxes are available to handle selection lists\.
- \-combobox *list*
The combobox is a combination of a normal entry widget together with a
drop\-down list box\. The combobox allows selecting from this drop\-down list
box a single element\. The list of the available elements can be provided
either as a list to the *\-choices* attribute, or via a variable that is
specified with the *\-choicevariable* attribute\.
> tepam::argument\_dialogbox \\
> __\-combobox__ \{\-label "Text size" \-variable Size \-choices \{8 9 10 12 15 18\} \-default 12\}
And here is an example of using a variable to define the selection list:
> set TextSizes \{8 9 10 12 15 18\}
> tepam::argument\_dialogbox \\
> __\-combobox__ \{\-label "Text size" \-variable Size \-choicevariable TextSizes \-default 12\}
- \-listbox *list*
In contrast to the combo box, the list box is always displayed by the
*listbox* entry widget\. Only one element is selectable unless the
*\-multiple\_selection* attribute is set\. The list box height can be
selected with the *\-height* attribute\. If the height is not explicitly
................................................................................
defined, the list box height is automatically adapted to the argument dialog
box size\. The first example uses a variable to define the available choices:
> set set AvailableSizes
> for \{set k 0\} \{$k<16\} \{incr k\} \{lappend AvailableSizes \[expr 1<<$k\]\}
>
> tepam::argument\_dialogbox \\
> __\-listbox__ \{\-label "Distance" \-variable Distance \\
> \-choicevariable AvailableSizes \-default 6 \-height 5\}
Here is a multi\-element selection example\. Please note that also the default
selection can contain multiple elements:
> tepam::argument\_dialogbox \\
> __\-listbox__ \{\-label "Text styles" \-variable Styles \\
> \-choices \{bold italic underline overstrike\} \\
> \-choicelabels \{Bold Italic Underline Overstrike\} \\
> \-default \{bold underline\} \-multiple\_selection 1 \\
> \-height 3\}
- \-disjointlistbox *list*
A disjoint list box has to be used instead of a normal list box if the
selection order is important\. The disjoint list box entry widget has in fact
two list boxes, one to select elements and one to display the selected
elements in the chosen order\.
................................................................................
Disjoint listboxes allow always selecting multiple elements\. With the
exception of the *\-multiple\_selection* attribute, disjointed list boxes
are accepting the same attributes as the normal listbox, e\.g\. *\-height,
\-choices, \-choicevariable, \-default*\.
> tepam::argument\_dialogbox \\
> __\-disjointlistbox__ \{\-label "Preferred scripting languages" \-variable Languages \\
> \-comment "Please select your preferred languages in the order" \\
> \-choices \{JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl\} \\
> \-default \{Tcl Perl Python\}\}
The file and directory selectors are building a next group of data entry
widgets\. A paragraph of section [Entry Widget Item
Attributes](#subsection5) explains the widget specific attributes that allow
specifying the targeted file types, active directory etc\.
- \-file *list*
................................................................................
The item *\-file* creates a group composed by an entry widget together with
a button that allows opening a file browser\. The data type *file* is
automatically selected for this entry if no data type has been explicitly
defined with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-file__ \{\-label "Image file" \-variable ImageF \\
> \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\
> \-initialfile "picture\.gif"\}
- \-existingfile *list*
The item *\-existingfile* creates a group composed by an entry widget
together with a button that allows opening a browser to select an existing
file\. The data type *existingfile* is automatically selected for this
entry if no data type has been explicitly defined with the *\-type*
attribute\.
> tepam::argument\_dialogbox \\
> __\-existingfile__ \{\-label "Image file" \-variable ImageF \\
> \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\
> \-initialfile "picture\.gif"\}
- \-directory *list*
The item *\-directory* creates a group composed by an entry widget together
with a button that allows opening a directory browser\. The data type
*directory* is automatically selected for this entry if no data type has
been explicitly defined with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-directory__ \{\-label "Report directory" \-variable ReportDir\}
- \-existingdirectory *list*
The item *\-existingdirectory* creates a group composed by an entry widget
together with a button that allows opening a browser to select an existing
directory\. The data type *existingdirectory* is automatically selected for
this entry if no data type has been explicitly defined with the *\-type*
attribute\.
> tepam::argument\_dialogbox \\
> __\-existingdirectory__ \{\-label "Report directory" \-variable ReportDir\}
Finally, there is a last group of some other special data entry widgets\.
- \-color *list*
The color selector is composed by an entry widget together with a button
that allows opening a color browser\. The data type *color* is
automatically selected for this entry widget type if no data type has been
explicitly defined with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-color__ \{\-label "Background color" \-variable Color \-default red\}
- \-font *list*
The font selector is composed by an entry widget together with a button that
allows opening a font browser\. The data type *font* is automatically
selected for this entry widget type if no data type has been explicitly
defined with the *\-type* attribute\. The entry widget displays an example
................................................................................
font of the label widget to display the selected font will be used as
default selected font\. If the font family of this label widget is not part
of the available families the first available family is used as default\. If
the font size of this label widget is not part of the available sizes the
next close available size is selected as default size\.
> tepam::argument\_dialogbox \\
> __\-font__ \{\-label "Font" \-variable Font \\
> \-font\_sizes \{8 10 12 16\} \\
> \-default \{Arial 20 italic\}\}
## <a name='subsection5'></a>Entry Widget Item Attributes
All the entry widget items are accepting the following attributes:
- \-text *string*
Eventual descriptions and comments specified with the *\-text* attribute
are displayed above the entry widget\.
> tepam::argument\_dialogbox \\
> \-entry \{__\-text "Please enter your name bellow"__ \-variable Name\}
- \-label *string*
The label attribute creates left to the entry widget a label using the
provided string as label text:
> tepam::argument\_dialogbox \\
> \-entry \{__\-label Name__ \-variable Name\}
- \-variable *string*
All entry widgets require a specified variable\. After accepting the entered
information with the OK button, the entry widget data is stored inside the
defined variables\.
> tepam::argument\_dialogbox \\
> \-existingdirectory \{\-label "Report directory" __\-variable ReportDir__\}
- \-default *string*
Eventual default data for the entry widgets can be provided via the
*\-default* attribute\. The default value is overridden if an argument
dialog box with a defined context is called another time\. The value
acknowledged in a previous call will be used in this case as default value\.
> tepam::argument\_dialogbox \\
> \-checkbox \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} __\-default italic__\}
- \-optional __0__|__1__
Data can be specified as optional or mandatory with the *\-optional*
attribute that requires either __0__ \(mandatory\) or __1__ \(optional\)
as attribute data\.
In case an entry is optional and no data has been entered, e\.g\. the entry
contains an empty character string, the entry will be considered as
undefined and the assigned variable will not be defined\.
> tepam::argument\_dialogbox \\
> \-entry \{\-label "City" \-variable start\_city \-type string\} \\
> \-entry \{\-label "Street" \-variable start\_street \-type string __\-optional 0__\} \\
> \-entry \{\-label "Street number" \-variable start\_street\_nbr \-type integer __\-optional 1__\} \\
- \-type *string*
If the data type is defined with the *\-type* attribute the argument dialog
box will automatically perform a data type check after acknowledging the
entered values and before the dialog box is closed\. If a type incompatible
value is found an error message box appears and the user can correct the
................................................................................
*tepam::procedure reference manual*\)\.
Some entry widgets like the file and directory widgets, as well as the color
and font widgets are specifying automatically the default data type if no
type has been specified explicitly with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-entry__ \{\-label "Street number" \-variable start\_street\_nbr __\-type integer__\} \\
- \-range *string*
Values can be constrained with the *\-range* attribute\. The valid range is
defined with a list containing the minimum valid value and a maximum valid
value\.
The *\-range* attribute has to be used only for numerical arguments, like
integers and doubles\.
> tepam::argument\_dialogbox \\
> \-entry \{\-label Month \-variable Month \-type integer __\-range \{1 12\}__\}
- \-validatecommand *string*
Custom argument value validations can be performed via specific validation
commands that are defined with the *\-validatecommand* attribute\. The
provided validation command can be a complete script in which the pattern
*%P* is placeholder for the argument value that has to be validated\.
> tepam::argument\_dialogbox \\
> \-entry \{\-label "Your comment" \-variable YourCom \\
> __\-validatecommand__ "IllegalWordDetector %P"\}
While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global data validation
attribute *\-validatecommand* that allows performing validation that
involves multiple arguments\.
- \-validatecommand\_error\_text *string*
................................................................................
- \-choices *string*
Choice lists can directly be defined with the *\-choices* attribute\. This
way to define choice lists is especially adapted for smaller, fixed
selection lists\.
> tepam::argument\_dialogbox \\
> \-listbox \{\-label "Text styles" \-variable Styles \\
> __\-choices \{bold italic underline\}__ \-default underline
- \-choicelabels *string* *\(only check and radio buttons\)*
If the labels of the check and radio boxes should differ from the option
values, they can be defined with the *\-choicelabels* attribute:
> tepam::argument\_dialogbox \\
> \-checkbox \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} \\
> __\-choicelabels \{Bold Italic Underline\}__
- \-choicevariable *string*
Another way to define the choice lists is using the *\-choicevariable*
attribute\. This way to define choice lists is especially adapted for huge
and eventually variable selection lists\.
> set TextSizes \{8 9 10 12 15 18\}
> tepam::argument\_dialogbox \\
> \-combobox \{\-label "Text size" \-variable Size __\-choicevariable TextSizes__\}
- \-multiple\_selection __0__|__1__
The list box item \(__\-listbox__\) allows by default selecting only one
list element\. By setting the *\-multiple\_selection* attribute to __1__,
multiple elements can be selected\.
> tepam::argument\_dialogbox \\
> \-listbox \{\-label "Text styles" \-variable Styles \\
> \-choices \{bold italic underline\} \-default underline \\
> __\-multiple\_selection 1__ \-height 3\}
Some additional attributes are supported by the file and directory selection
widgets\.
- \-filetypes *string*
The file type attribute is used by the __\-file__ and
__\-existingfile__ items to define the file endings that are searched by
the file browser\.
> tepam::argument\_dialogbox \\
> \-file \{\-label "Image file" \-variable ImageF \\
> __\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\}__\}
- \-initialfile *string*
The initial file used by the file browsers of the __\-file__ and
__\-existingfile__ widgets are by default the file defined with the
*\-default* attribute, unless a file is specified with the *\-initialfile*
attribute\.
> tepam::argument\_dialogbox \\
> \-file \{\-variable ImageF __\-initialfile "picture\.gif"__\}
- \-activedir *string*
The *\-activedir* attribute will override the default active search
directory used by the file browsers of all file and directory entry widgets\.
The default active search directory is defined by the directory of a
specified initial file \(*\-initialfile*\) if defined, and otherwise by the
directory of the default file/directory, specified with the *\-default*
attribute\.
> tepam::argument\_dialogbox \\
> \-file "\-variable ImageF __\-activedir $pwd__"
Finally, there is a last attribute supported by some widgets:
- \-height *string*
All widgets containing a selection list \(__\-listbox__,
__\-disjointlistbox__, __\-font__\) as well as the multi line
__\-text__ widget are accepting the *\-height* attribute that defines
the number of displayed rows of the selection lists\.
> tepam::argument\_dialogbox \\
> \-listbox \{\-label "Text size" \-variable Size \\
> \-choices \{8 9 10 12 15 18\} \-default 12 __\-height 3__\}
If the no height has been explicitly specified the height of the widget will
be dynamically adapted to the argument dialog box size\.
# <a name='section3'></a>APPLICATION SPECIFIC ENTRY WIDGETS
An application specific entry widget can be made available to the argument
dialog box by adding a dedicated procedure to the __tepam__ namespace\. This
procedure has three arguments; the first one is the widget path, the second one
a subcommand and the third argument has various purposes:
> *proc* tepam::ad\_form\(<WidgetName>\) \{W Command \{Par ""\}\} \{
> *upvar Option Option; \# if required*
> *variable argument\_dialogbox; \# if required*
> switch $Command \{
> "create" <CreateCommandSequence>
> "set\_choice" <SetChoiceCommandSequence>
> "set" <SetCommandv>
> "get" <GetCommandSequence>
> \}
> \}
__Argument\_dialogbox__ takes care about the *\-label* and *\-text*
attributes for all entry widgets\. For any data entry widget it creates a frame
into which the data entry widget components can be placed\. The path to this
frame is provided via the *W* argument\.
|
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 ... 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 ... 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 ... 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 ... 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 ... 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 ... 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 ... 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 ... 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 ... 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 ... 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 ... 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 ... 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 |
If the entered data have been rejected \(via the *Cancel* button\) the
__argument\_dialogbox__ returns __cancel__\.
A small example illustrates how the __argument\_dialogbox__ can be
employed:
> set DialogResult \[__tepam::argument\_dialogbox__ \\
> __\-title__ "Itinerary selection" \\
> __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} \\
> __\-frame__ \{*\-label "Itinerary start"*\} \\
> __\-comment__ \{*\-text "Specify your itinerary start location"*\} \\
> __\-entry__ \{*\-label "City" \-variable start\_city \-type string*\} \\
> __\-entry__ \{*\-label "Street" \-variable start\_street \-type string \-optional 1*\} \\
> __\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\
> __\-frame__ \{*\-label "Itinerary destination"*\} \\
> __\-comment__ \{*\-text "Specify your itinerary destination"*\} \\
> __\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\
> __\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\
> __\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\
> __\-frame__ \{\} \\
> __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}
\] This example opens a dialog box that has the title *Itinerary
selection*\. A first entry widget in this box allows selecting a report
file\. It follows two frames to define respectively an itinerary start and
end location\. Each of these locations that are described with a comment has
three entry widgets to specify respectively the city, street and the street
number\. Bellow the second frame there is a check button that allows
................................................................................
form of a single list to __argument\_dialogbox__, and not as individual
arguments\. The second format that is supported by __argument\_dialogbox__
corresponds exactly to the first one, except that all item definitions are
packed into a single list that is provided to __argument\_dialogbox__\.
The previous example can therefore also be written in the following way:
> set DialogResult \[__tepam::argument\_dialogbox \{__
> __\-title__ "Itinerary selection"
> __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\}
> \.\.\.
> __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}
__\}__\]
The commands __argument\_dialogbox__ as well as
__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the
namespace __tepam__\. To use these commands without the __tepam::__
namespace prefix, it is sufficient to import them into the main namespace:
> __namespace import tepam::\*__
>
> set DialogResult \[__argument\_dialogbox__ \\
> \-title "Itinerary selection"
> \.\.\.
The following subsections explain the different argument item types that are
accepted by the __argument\_dialogbox__, classified into three groups\. The
first data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument\_dialogbox__\.
................................................................................
## <a name='subsection1'></a>Context Definition Items
The first item group allows specifying some context aspects of an argument
dialog box\. These items are taking a simple character string as item attribute:
> tepam::argument\_dialogbox \\
> __\-<argument\_name>__ *string* \\
> \.\.\.
The following items are classified into this group:
- \-title *string*
The dialog box window title which is by default *Dialog* can be changed
with the *\-title* item:
> tepam::argument\_dialogbox \\
> __\-title__ "System configuration" \\
> \.\.\.
- \-window *string*
The argument dialog box uses by default *\.dialog* as dialog top level
window\. This path can be changed with the *\-window* item:
> tepam::argument\_dialogbox \\
> __\-window__ \.dialog \\
> \.\.\.
- \-parent *string*
By defining a parent window, the argument dialog box will be displayed
beside this one\. Without explicit parent window definition, the top\-level
window will be considered as parent window\.
> tepam::argument\_dialogbox \\
> __\-parent__ \.my\_appl \\
> \.\.\.
- \-context *string*
If a context is defined the dialog box state, e\.g\. the entered data as well
as the window size and position, is restored the next time the argument
dialog box is called\. The assignment of a context allows saving the dialog
box state in its context to distinguish between different usages of the
argument dialog box\.
> tepam::argument\_dialogbox \\
> __\-context__ destination\_definitions \\
> \.\.\.
## <a name='subsection2'></a>Formatting and Display Options
Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user\. A couple of items allow structuring
and commenting the dialog boxes\.
The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-<argument\_name>__ \{ *
> ?\-<attribute\_name> <attribute\_value>?
> ?\-<attribute\_name> <attribute\_value>?
> ?\.\.\.?*
> \}
> \.\.\.
The following items are classified into this group:
- \-frame *list*
The *\-frame* item allows packing all following entry widgets into a
labeled frame, until a next frame item is defined or until the last entry
................................................................................
* \-label *string*
An optional frame label can be specified with the *\-label* statement\.
Example:
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-frame__ \{*\-label "Destination address"*\}
> \.\.\.
To close an open frame without opening a new one, an empty list has to be
provided to the *\-frame* statement\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-frame__ \{\}
> \.\.\.
- \-sep \[const \{\{\}\}\]
Entry widgets can be separated with the *\-sep* statement which doesn't
require additional definitions\. The related definition list has to exist,
but its content is ignored\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-sep__ \{\}
> \.\.\.
- \-comment *string*
Comments and descriptions can be added with the *\-text* attribute of the
*\-comment* item\. Please note that each entry widget itself can also
contain a *\-text* attribute for comments and descriptions\. But the
*\-comment* item allows for example adding a description between two
frames\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-comment__ \{*\-text "Specify bellow the destination address"*\}
> \.\.\.
- \-yscroll __0__|__1__|__auto__
This attribute allows controlling an eventual vertical scrollbar\. Setting it
to __0__ will permanently disable the scrollbar, setting it to __1__
will enable it\. By default it is set to __auto__\. The scrollbar is
enabled in this mode only if the vertical data entry form size exceeds 66%
of the screen height\.
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-yscroll__ __auto__
> \.\.\.
## <a name='subsection3'></a>Global Custom Data Validation
This item group allows specifying global custom checks to validate the entered
data\.
- \-validatecommand *script*
Custom data checks can be performed via validation commands that are defined
with the *\-validatecommand* item\. Example:
> tepam::argument\_dialogbox \\
> \-entry \{\-label "Your comment" \-variable YourCom\} \\
> __\-validatecommand__ \{IllegalWordDetector $YourCom\}
The validation command is executed in the context of the calling procedure,
once all the basic data checks have been performed and data variables are
assigned\. All data is accessed via the data variables\. Note that there is
also an entry widget specific attribute *\-validatecommand* that allows
declaring custom checks for specific data entries\.
................................................................................
## <a name='subsection4'></a>Data Entry Widget Items
Data entry widgets are created with the widget items\. These items require as
item attributes a definition list, which contains itself attribute name and
value pairs:
> tepam::argument\_dialogbox \\
> \.\.\.
> __\-<argument\_name>__ \{ *
> ?\-<attribute\_name> <attribute\_value>?
> ?\-<attribute\_name> <attribute\_value>?
> ?\.\.\.?*
> \}
> \.\.\.
The attribute list can contain various attributes to describe and comment an
entry widget and to constrain its entered value\. All entry widgets are accepting
a common set of attributes that are described in the section [Entry Widget Item
Attributes](#subsection5)\.
TEPAM defines a rich set of entry widgets\. If necessary, this set can be
................................................................................
- \-entry *list*
The *\-entry* item generates the simplest but most universal data entry
widget\. It allows entering any kind of data in form of single line strings\.
> tepam::argument\_dialogbox \\
> __\-entry__ \{\-label Name \-variable Entry\}
- \-text *list*
The *\-text* item generates a multi line text entry widget\. The widget
height can be selected with the *\-height* attribute\.
> tepam::argument\_dialogbox \\
> __\-text__ \{\-label Name \-variable Text \-height 5\}
- \-checkbox *list*
A group of check boxes is created with the *\-checkbox* item\. The number of
check boxes and their option values are specified with a list assigned to
the *\-choices* attribute or via a variable declared with the
*\-choicevariable* attribute:
> tepam::argument\_dialogbox \\
> __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} \-default italic\}
If the labels of the check boxes should differ from the option values, their
labels can be defined with the *\-choicelabels* attribute:
> tepam::argument\_dialogbox \\
> __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} \\
> \-choicelabels \{Bold Italic Underline\} \\
> \-default italic\}
In contrast to a radio box group, a check box group allows selecting
simultaneously several choice options\. The selection is stored for this
reason inside the defined variable in form of a list, even if only one
choice option has been selected\.
- \-radiobox *list*
................................................................................
*\-choicevariable* attribute\.
In contrast to a check box group, a radio box group allows selecting
simultaneously only one choice option\. The selected option value is stored
directly, and not in form of a list, inside the defined variable\.
> tepam::argument\_dialogbox \\
> __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\
> \-choices \{left center right\} \-default left\}
If the labels of the radio boxes should differ from the option values, their
labels can be defined with the *\-choicelabels* attribute:
> tepam::argument\_dialogbox \\
> __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\
> \-choices \{left center right\} \\
> \-choicelabels \{Left Center Right\} \-default left\}
- \-checkbutton *list*
The *\-checkbutton* entry widget allows activating or deactivating a single
choice option\. The result written into the variable will either be __0__
if the check button was not activated or __1__ if it was activated\. An
eventually provided default value has also to be either __0__ or
__1__\.
> tepam::argument\_dialogbox \\
> __\-checkbutton__ \{\-label Capitalize \-variable Capitalize \-default 1\}
Several types of list and combo boxes are available to handle selection lists\.
- \-combobox *list*
The combobox is a combination of a normal entry widget together with a
drop\-down list box\. The combobox allows selecting from this drop\-down list
box a single element\. The list of the available elements can be provided
either as a list to the *\-choices* attribute, or via a variable that is
specified with the *\-choicevariable* attribute\.
> tepam::argument\_dialogbox \\
> __\-combobox__ \{\-label "Text size" \-variable Size \-choices \{8 9 10 12 15 18\} \-default 12\}
And here is an example of using a variable to define the selection list:
> set TextSizes \{8 9 10 12 15 18\}
> tepam::argument\_dialogbox \\
> __\-combobox__ \{\-label "Text size" \-variable Size \-choicevariable TextSizes \-default 12\}
- \-listbox *list*
In contrast to the combo box, the list box is always displayed by the
*listbox* entry widget\. Only one element is selectable unless the
*\-multiple\_selection* attribute is set\. The list box height can be
selected with the *\-height* attribute\. If the height is not explicitly
................................................................................
defined, the list box height is automatically adapted to the argument dialog
box size\. The first example uses a variable to define the available choices:
> set set AvailableSizes
> for \{set k 0\} \{$k<16\} \{incr k\} \{lappend AvailableSizes \[expr 1<<$k\]\}
>
> tepam::argument\_dialogbox \\
> __\-listbox__ \{\-label "Distance" \-variable Distance \\
> \-choicevariable AvailableSizes \-default 6 \-height 5\}
Here is a multi\-element selection example\. Please note that also the default
selection can contain multiple elements:
> tepam::argument\_dialogbox \\
> __\-listbox__ \{\-label "Text styles" \-variable Styles \\
> \-choices \{bold italic underline overstrike\} \\
> \-choicelabels \{Bold Italic Underline Overstrike\} \\
> \-default \{bold underline\} \-multiple\_selection 1 \\
> \-height 3\}
- \-disjointlistbox *list*
A disjoint list box has to be used instead of a normal list box if the
selection order is important\. The disjoint list box entry widget has in fact
two list boxes, one to select elements and one to display the selected
elements in the chosen order\.
................................................................................
Disjoint listboxes allow always selecting multiple elements\. With the
exception of the *\-multiple\_selection* attribute, disjointed list boxes
are accepting the same attributes as the normal listbox, e\.g\. *\-height,
\-choices, \-choicevariable, \-default*\.
> tepam::argument\_dialogbox \\
> __\-disjointlistbox__ \{\-label "Preferred scripting languages" \-variable Languages \\
> \-comment "Please select your preferred languages in the order" \\
> \-choices \{JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl\} \\
> \-default \{Tcl Perl Python\}\}
The file and directory selectors are building a next group of data entry
widgets\. A paragraph of section [Entry Widget Item
Attributes](#subsection5) explains the widget specific attributes that allow
specifying the targeted file types, active directory etc\.
- \-file *list*
................................................................................
The item *\-file* creates a group composed by an entry widget together with
a button that allows opening a file browser\. The data type *file* is
automatically selected for this entry if no data type has been explicitly
defined with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-file__ \{\-label "Image file" \-variable ImageF \\
> \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\
> \-initialfile "picture\.gif"\}
- \-existingfile *list*
The item *\-existingfile* creates a group composed by an entry widget
together with a button that allows opening a browser to select an existing
file\. The data type *existingfile* is automatically selected for this
entry if no data type has been explicitly defined with the *\-type*
attribute\.
> tepam::argument\_dialogbox \\
> __\-existingfile__ \{\-label "Image file" \-variable ImageF \\
> \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\
> \-initialfile "picture\.gif"\}
- \-directory *list*
The item *\-directory* creates a group composed by an entry widget together
with a button that allows opening a directory browser\. The data type
*directory* is automatically selected for this entry if no data type has
been explicitly defined with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-directory__ \{\-label "Report directory" \-variable ReportDir\}
- \-existingdirectory *list*
The item *\-existingdirectory* creates a group composed by an entry widget
together with a button that allows opening a browser to select an existing
directory\. The data type *existingdirectory* is automatically selected for
this entry if no data type has been explicitly defined with the *\-type*
attribute\.
> tepam::argument\_dialogbox \\
> __\-existingdirectory__ \{\-label "Report directory" \-variable ReportDir\}
Finally, there is a last group of some other special data entry widgets\.
- \-color *list*
The color selector is composed by an entry widget together with a button
that allows opening a color browser\. The data type *color* is
automatically selected for this entry widget type if no data type has been
explicitly defined with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-color__ \{\-label "Background color" \-variable Color \-default red\}
- \-font *list*
The font selector is composed by an entry widget together with a button that
allows opening a font browser\. The data type *font* is automatically
selected for this entry widget type if no data type has been explicitly
defined with the *\-type* attribute\. The entry widget displays an example
................................................................................
font of the label widget to display the selected font will be used as
default selected font\. If the font family of this label widget is not part
of the available families the first available family is used as default\. If
the font size of this label widget is not part of the available sizes the
next close available size is selected as default size\.
> tepam::argument\_dialogbox \\
> __\-font__ \{\-label "Font" \-variable Font \\
> \-font\_sizes \{8 10 12 16\} \\
> \-default \{Arial 20 italic\}\}
## <a name='subsection5'></a>Entry Widget Item Attributes
All the entry widget items are accepting the following attributes:
- \-text *string*
Eventual descriptions and comments specified with the *\-text* attribute
are displayed above the entry widget\.
> tepam::argument\_dialogbox \\
> \-entry \{__\-text "Please enter your name bellow"__ \-variable Name\}
- \-label *string*
The label attribute creates left to the entry widget a label using the
provided string as label text:
> tepam::argument\_dialogbox \\
> \-entry \{__\-label Name__ \-variable Name\}
- \-variable *string*
All entry widgets require a specified variable\. After accepting the entered
information with the OK button, the entry widget data is stored inside the
defined variables\.
> tepam::argument\_dialogbox \\
> \-existingdirectory \{\-label "Report directory" __\-variable ReportDir__\}
- \-default *string*
Eventual default data for the entry widgets can be provided via the
*\-default* attribute\. The default value is overridden if an argument
dialog box with a defined context is called another time\. The value
acknowledged in a previous call will be used in this case as default value\.
> tepam::argument\_dialogbox \\
> \-checkbox \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} __\-default italic__\}
- \-optional __0__|__1__
Data can be specified as optional or mandatory with the *\-optional*
attribute that requires either __0__ \(mandatory\) or __1__ \(optional\)
as attribute data\.
In case an entry is optional and no data has been entered, e\.g\. the entry
contains an empty character string, the entry will be considered as
undefined and the assigned variable will not be defined\.
> tepam::argument\_dialogbox \\
> \-entry \{\-label "City" \-variable start\_city \-type string\} \\
> \-entry \{\-label "Street" \-variable start\_street \-type string __\-optional 0__\} \\
> \-entry \{\-label "Street number" \-variable start\_street\_nbr \-type integer __\-optional 1__\} \\
- \-type *string*
If the data type is defined with the *\-type* attribute the argument dialog
box will automatically perform a data type check after acknowledging the
entered values and before the dialog box is closed\. If a type incompatible
value is found an error message box appears and the user can correct the
................................................................................
*tepam::procedure reference manual*\)\.
Some entry widgets like the file and directory widgets, as well as the color
and font widgets are specifying automatically the default data type if no
type has been specified explicitly with the *\-type* attribute\.
> tepam::argument\_dialogbox \\
> __\-entry__ \{\-label "Street number" \-variable start\_street\_nbr __\-type integer__\} \\
- \-range *string*
Values can be constrained with the *\-range* attribute\. The valid range is
defined with a list containing the minimum valid value and a maximum valid
value\.
The *\-range* attribute has to be used only for numerical arguments, like
integers and doubles\.
> tepam::argument\_dialogbox \\
> \-entry \{\-label Month \-variable Month \-type integer __\-range \{1 12\}__\}
- \-validatecommand *string*
Custom argument value validations can be performed via specific validation
commands that are defined with the *\-validatecommand* attribute\. The
provided validation command can be a complete script in which the pattern
*%P* is placeholder for the argument value that has to be validated\.
> tepam::argument\_dialogbox \\
> \-entry \{\-label "Your comment" \-variable YourCom \\
> __\-validatecommand__ "IllegalWordDetector %P"\}
While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global data validation
attribute *\-validatecommand* that allows performing validation that
involves multiple arguments\.
- \-validatecommand\_error\_text *string*
................................................................................
- \-choices *string*
Choice lists can directly be defined with the *\-choices* attribute\. This
way to define choice lists is especially adapted for smaller, fixed
selection lists\.
> tepam::argument\_dialogbox \\
> \-listbox \{\-label "Text styles" \-variable Styles \\
> __\-choices \{bold italic underline\}__ \-default underline
- \-choicelabels *string* *\(only check and radio buttons\)*
If the labels of the check and radio boxes should differ from the option
values, they can be defined with the *\-choicelabels* attribute:
> tepam::argument\_dialogbox \\
> \-checkbox \{\-label "Font sytle" \-variable FontStyle \\
> \-choices \{bold italic underline\} \\
> __\-choicelabels \{Bold Italic Underline\}__
- \-choicevariable *string*
Another way to define the choice lists is using the *\-choicevariable*
attribute\. This way to define choice lists is especially adapted for huge
and eventually variable selection lists\.
> set TextSizes \{8 9 10 12 15 18\}
> tepam::argument\_dialogbox \\
> \-combobox \{\-label "Text size" \-variable Size __\-choicevariable TextSizes__\}
- \-multiple\_selection __0__|__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\.
|
Changes to embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md.
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
...
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
|
Support for a new document format can be added by defining in the
__tepam::doc\_gen__ namespace a set of procedures that generate the different
document components\.
The following documentation listing contains tokens that refer to the different
document generation procedures:
> * <01>*
> *<03> <20s>* NAME*<20e>*
> * <30s>* message\_box \- Displays text in a message box*<30e>*
> * <20s>* SYNOPSYS*<20e>*
> * <40s>* message\_box \[\-mtype <mtype>\] <text>*<40e>*
> * <20s>* DESCRIPTION*<20e>*
> * <21s> message\_box<21e>*
> * <54s> message\_box \[\-mtype <mtype>\] <text><54e>*
> * <50s>* This procedure allows displaying a text in an message box\. The following
> * * message types are supported:*<50e>*
> *<51> <53s>* \* Info*<53e>*
> * <53s>* \* Warning*<53e>*
> * <53s>* \* Error*<53e>* *<52>*
> * <50s>* If the text parameter is use multiple times the different texts are
> * * concatenated to create the message text\.*<50e>*
> * <20s>* ARGUMENTS*<20e>*
> *<60> <62s>* \[\-mtype <mtype>\]*<62e>*
> *<63> <65s>* Message type*<65e>*
> * <66s>* Default: "Warning"*<66e>*
> * <66s>* Multiple: yes*<66e>*
> * <66s>* Choices: Info, Warning, Error*<66e>* *<64>*
> * <62s>* <text>*<62e>*
> *<63> <65s>* One or multiple text lines to display*<65e>*
> * <66s>* Type: string*<66e>*
> * <66s>* Multiple: yes*<66e>* *<64><61>*
> * <20s>* EXAMPLE*<20e>*
> *<70> <72s>* message\_box "Please save first the document"*<72e>*
> * <73s>* \-> 1*<73e>* *<71><04>*
> * <02>*
There are 2 types of document generation procedures:
- Content generation procedures \(e\.g\. <40s>\.\.\.<40e>\)
These procedures generate some document content based on the text that is
provided as procedure argument\. The listing above shows two tokens for these
................................................................................
of the referred procedures\. Since nonstandard placeholders are used,
__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ is called with an explicit
placeholder pattern definition \(argument *search\_pattern*\)\.
> *\# Define the HTML master document*
> set HtmlMasterDoc \{\\
> <html>
> <head>
> <title>tepam::doc\_gen</title>
> <link rel="stylesheet" href="tepam\_doc\_stylesheet\.css">
> <meta content="documentation" name="keywords"></meta>
> </head>
> <body>
> <h1>tepam::doc\_gen</h1>
> <h2>Generate</h2>
> __\{\*tepam::doc\_gen::generate\*\}__
> <h2>Patch</h2>
> __\{\*tepam::doc\_gen::patch\*\}__
> </body>
> <html>\\
> \}
> **
> *\# Patch the master document: This will replace the placeholders by the
> \# procedure documentation divisions:*
> __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\
> \-src\_string $HtmlMasterDoc \-dest\_file tepam\_doc\_gen\.html
>
# <a name='seealso'></a>SEE ALSO
[tepam\(n\)](tepam\_introduction\.md),
[tepam::procedure\(n\)](tepam\_procedure\.md)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
...
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
|
Support for a new document format can be added by defining in the __tepam::doc\_gen__ namespace a set of procedures that generate the different document components\. The following documentation listing contains tokens that refer to the different document generation procedures: > * <01>* > *<03> <20s>* NAME*<20e>* > * <30s>* message\_box \- Displays text in a message box*<30e>* > * <20s>* SYNOPSYS*<20e>* > * <40s>* message\_box \[\-mtype <mtype>\] <text>*<40e>* > * <20s>* DESCRIPTION*<20e>* > * <21s> message\_box<21e>* > * <54s> message\_box \[\-mtype <mtype>\] <text><54e>* > * <50s>* This procedure allows displaying a text in an message box\. The following > * * message types are supported:*<50e>* > *<51> <53s>* \* Info*<53e>* > * <53s>* \* Warning*<53e>* > * <53s>* \* Error*<53e>* *<52>* > * <50s>* If the text parameter is use multiple times the different texts are > * * concatenated to create the message text\.*<50e>* > * <20s>* ARGUMENTS*<20e>* > *<60> <62s>* \[\-mtype <mtype>\]*<62e>* > *<63> <65s>* Message type*<65e>* > * <66s>* Default: "Warning"*<66e>* > * <66s>* Multiple: yes*<66e>* > * <66s>* Choices: Info, Warning, Error*<66e>* *<64>* > * <62s>* <text>*<62e>* > *<63> <65s>* One or multiple text lines to display*<65e>* > * <66s>* Type: string*<66e>* > * <66s>* Multiple: yes*<66e>* *<64><61>* > * <20s>* EXAMPLE*<20e>* > *<70> <72s>* message\_box "Please save first the document"*<72e>* > * <73s>* \-> 1*<73e>* *<71><04>* > * <02>* There are 2 types of document generation procedures: - Content generation procedures \(e\.g\. <40s>\.\.\.<40e>\) These procedures generate some document content based on the text that is provided as procedure argument\. The listing above shows two tokens for these ................................................................................ of the referred procedures\. Since nonstandard placeholders are used, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ is called with an explicit placeholder pattern definition \(argument *search\_pattern*\)\. > *\# Define the HTML master document* > set HtmlMasterDoc \{\\ > <html> > <head> > <title>tepam::doc\_gen</title> > <link rel="stylesheet" href="tepam\_doc\_stylesheet\.css"> > <meta content="documentation" name="keywords"></meta> > </head> > <body> > <h1>tepam::doc\_gen</h1> > <h2>Generate</h2> > __\{\*tepam::doc\_gen::generate\*\}__ > <h2>Patch</h2> > __\{\*tepam::doc\_gen::patch\*\}__ > </body> > <html>\\ > \} > ** > *\# Patch the master document: This will replace the placeholders by the > \# procedure documentation divisions:* > __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\ > \-src\_string $HtmlMasterDoc \-dest\_file tepam\_doc\_gen\.html > # <a name='seealso'></a>SEE ALSO [tepam\(n\)](tepam\_introduction\.md), [tepam::procedure\(n\)](tepam\_procedure\.md) |
Changes to embedded/md/tcllib/files/modules/tepam/tepam_introduction.md.
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 ... 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 ... 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 ... 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 |
procedure name, the procedure header and the procedure body\.
The following example declares the subcommand
__[message](\.\./\.\./\.\./\.\./index\.md\#message)__ of the procedure
__display__\. This command has several named and unnamed arguments:
> __[tepam::procedure](tepam\_procedure\.md)__ \{display message\} \{
> \-return \-
> \-short\_description "Displays a simple message box"
> \-description "This procedure allows displaying a configurable message box\."
> \-args \{
> \{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}
> \{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}
> \{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}
> \{\-fg \-type color \-default black \-description "Message color"\}
> \{\-bg \-type color \-optional \-description "Background color"\}
> \{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\}
> \{\-log\_file \-type file \-optional \-description "Optional message log file"\}
> \{text \-type string \-multiple \-description "Multiple text lines to display"\}
> \}
> \} \{
> * puts "display message:"
> foreach var \{mtype font level fg bg no\_border log\_file text\} \{
> if \{\[info exists $var\]\} \{
> puts " $var=\[set $var\]"
> \}
> \}
> *\}
A call of procedure that has been declared in this way will first invoke the
TEPAM argument manager, before the procedure body is executed\. The argument
manager parses the provided arguments, validates them, completes them eventually
with some default values, and makes them finally available to the procedure body
as local variables\. In case an argument is missing or has a wrong type, the
................................................................................
# <a name='section5'></a>PROCEDURE CALL
The specified procedure can be called in many ways\. The following listing shows
some valid procedure calls:
> __display message__ "The document hasn't yet been saved\!"
> *\-> display message:
> mtype=Warning
> font=Arial 10 italic
> fg=black
> no\_border=0
> text=\{The document hasn't yet been saved\!\}*
>
> __display message__ \-fg red \-bg black "Please save first the document"
> *\-> display message:
> mtype=Warning
> font=Arial 10 italic
> fg=red
> bg=black
> no\_border=0
> text=\{Please save first the document\}*
>
> __display message__ \-mtype Error \-no\_border "Why is here no border?"
> *\-> display message:
> mtype=Error
> font=Arial 10 italic
> fg=black
> no\_border=1
> text=\{Why is here no border?\}*
>
> __display message__ \-font \{Courier 12\} \-level 10 \\
> "Is there enough space?" "Reduce otherwise the font size\!"
>
*\-> display message: mtype=Warning font=Courier 12 level=10 fg=black
no\_border=0 text=\{Is there enough space?\} \{Reduce otherwise the font size\!\}*
The next lines show how wrong arguments are recognized\. The *text* argument
that is mandatory is missing in the first procedure call:
................................................................................
destination folder as well as a checkbox that allows specifying if an eventual
existing file can be overwritten\. Comfortable browsers can be used to select
files and directories\. And finally, the form offers also the possibility to
accept and decline the selection\. Here is the code snippet that is doing all
this:
> __[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\
> __\-existingfile__ \{\-label "Source file" \-variable SourceFile\} \\
> __\-existingdirectory__ \{\-label "Destination folder" \-variable DestDir\} \\
> __\-checkbutton__ \{\-label "Overwrite existing file" \-variable Overwrite\}
The __argument\_dialogbox__ returns __ok__ if the entered data are
validated\. It will return __cancel__ if the data entry has been canceled\.
After the validation of the entered data, the __argument\_dialogbox__ defines
all the specified variables with the entered data inside the calling context\.
An __argument\_dialogbox__ requires a pair of arguments for each variable
................................................................................
about the different available entry widget types and parameter attributes\. The
example contains also some formatting instructions like *\-frame* and *\-sep*
which allows organizing the different entry widgets in frames and sections:
> set ChoiceList \{"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"\}
>
> set Result \[__[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\
> __\-title__ "System configuration" \\
> __\-context__ test\_1 \\
> __\-frame__ \{\-label "Entries"\} \\
> __\-entry__ \{\-label Entry1 \-variable Entry1\} \\
> __\-entry__ \{\-label Entry2 \-variable Entry2 \-default "my default"\} \\
> __\-frame__ \{\-label "Listbox & combobox"\} \\
> __\-listbox__ \{\-label "Listbox, single selection" \-variable Listbox1 \\
> \-choices \{1 2 3 4 5 6 7 8\} \-default 1 \-height 3\} \\
> __\-listbox__ \{\-label "Listbox, multiple selection" \-variable Listbox2
> \-choicevariable ChoiceList \-default \{"Choice 2" "Choice 3"\}
> \-multiple\_selection 1 \-height 3\} \\
> __\-disjointlistbox__ \{\-label "Disjoined listbox" \-variable DisJntListbox
> \-choicevariable ChoiceList \\
> \-default \{"Choice 3" "Choice 5"\} \-height 3\} \\
> __\-combobox__ \{\-label "Combobox" \-variable Combobox \\
> \-choices \{1 2 3 4 5 6 7 8\} \-default 3\} \\
> __\-frame__ \{\-label "Checkbox, radiobox and checkbutton"\} \\
> __\-checkbox__ \{\-label Checkbox \-variable Checkbox
> \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\
> \-default italic\} \\
> __\-radiobox__ \{\-label Radiobox \-variable Radiobox
> \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\
> \-default underline\} \\
> __\-checkbutton__ \{\-label CheckButton \-variable Checkbutton \-default 1\} \\
> __\-frame__ \{\-label "Files & directories"\} \\
> __\-existingfile__ \{\-label "Input file" \-variable InputFile\} \\
> __\-file__ \{\-label "Output file" \-variable OutputFile\} \\
> __\-sep__ \{\} \\
> __\-existingdirectory__ \{\-label "Input directory" \-variable InputDirectory\} \\
> __\-directory__ \{\-label "Output irectory" \-variable OutputDirectory\} \\
> __\-frame__ \{\-label "Colors and fonts"\} \\
> __\-color__ \{\-label "Background color" \-variable Color \-default red\} \\
> __\-sep__ \{\} \\
> __\-font__ \{\-label "Font" \-variable Font \-default \{Courier 12 italic\}\}
\] The __argument\_dialogbox__ defines all the specified variables with the
entered data and returns __ok__ if the data have been validated via the Ok
button\. If the data entry is cancelled by activating the Cancel button, the
__argument\_dialogbox__ returns __cancel__\.
if {$Result=="cancel"} {
|
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 ... 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 ... 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 ... 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 |
procedure name, the procedure header and the procedure body\.
The following example declares the subcommand
__[message](\.\./\.\./\.\./\.\./index\.md\#message)__ of the procedure
__display__\. This command has several named and unnamed arguments:
> __[tepam::procedure](tepam\_procedure\.md)__ \{display message\} \{
> \-return \-
> \-short\_description "Displays a simple message box"
> \-description "This procedure allows displaying a configurable message box\."
> \-args \{
> \{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}
> \{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}
> \{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}
> \{\-fg \-type color \-default black \-description "Message color"\}
> \{\-bg \-type color \-optional \-description "Background color"\}
> \{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\}
> \{\-log\_file \-type file \-optional \-description "Optional message log file"\}
> \{text \-type string \-multiple \-description "Multiple text lines to display"\}
> \}
> \} \{
> * puts "display message:"
> foreach var \{mtype font level fg bg no\_border log\_file text\} \{
> if \{\[info exists $var\]\} \{
> puts " $var=\[set $var\]"
> \}
> \}
> *\}
A call of procedure that has been declared in this way will first invoke the
TEPAM argument manager, before the procedure body is executed\. The argument
manager parses the provided arguments, validates them, completes them eventually
with some default values, and makes them finally available to the procedure body
as local variables\. In case an argument is missing or has a wrong type, the
................................................................................
# <a name='section5'></a>PROCEDURE CALL
The specified procedure can be called in many ways\. The following listing shows
some valid procedure calls:
> __display message__ "The document hasn't yet been saved\!"
> *\-> display message:
> mtype=Warning
> font=Arial 10 italic
> fg=black
> no\_border=0
> text=\{The document hasn't yet been saved\!\}*
>
> __display message__ \-fg red \-bg black "Please save first the document"
> *\-> display message:
> mtype=Warning
> font=Arial 10 italic
> fg=red
> bg=black
> no\_border=0
> text=\{Please save first the document\}*
>
> __display message__ \-mtype Error \-no\_border "Why is here no border?"
> *\-> display message:
> mtype=Error
> font=Arial 10 italic
> fg=black
> no\_border=1
> text=\{Why is here no border?\}*
>
> __display message__ \-font \{Courier 12\} \-level 10 \\
> "Is there enough space?" "Reduce otherwise the font size\!"
>
*\-> display message: mtype=Warning font=Courier 12 level=10 fg=black
no\_border=0 text=\{Is there enough space?\} \{Reduce otherwise the font size\!\}*
The next lines show how wrong arguments are recognized\. The *text* argument
that is mandatory is missing in the first procedure call:
................................................................................
destination folder as well as a checkbox that allows specifying if an eventual
existing file can be overwritten\. Comfortable browsers can be used to select
files and directories\. And finally, the form offers also the possibility to
accept and decline the selection\. Here is the code snippet that is doing all
this:
> __[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\
> __\-existingfile__ \{\-label "Source file" \-variable SourceFile\} \\
> __\-existingdirectory__ \{\-label "Destination folder" \-variable DestDir\} \\
> __\-checkbutton__ \{\-label "Overwrite existing file" \-variable Overwrite\}
The __argument\_dialogbox__ returns __ok__ if the entered data are
validated\. It will return __cancel__ if the data entry has been canceled\.
After the validation of the entered data, the __argument\_dialogbox__ defines
all the specified variables with the entered data inside the calling context\.
An __argument\_dialogbox__ requires a pair of arguments for each variable
................................................................................
about the different available entry widget types and parameter attributes\. The
example contains also some formatting instructions like *\-frame* and *\-sep*
which allows organizing the different entry widgets in frames and sections:
> set ChoiceList \{"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"\}
>
> set Result \[__[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\
> __\-title__ "System configuration" \\
> __\-context__ test\_1 \\
> __\-frame__ \{\-label "Entries"\} \\
> __\-entry__ \{\-label Entry1 \-variable Entry1\} \\
> __\-entry__ \{\-label Entry2 \-variable Entry2 \-default "my default"\} \\
> __\-frame__ \{\-label "Listbox & combobox"\} \\
> __\-listbox__ \{\-label "Listbox, single selection" \-variable Listbox1 \\
> \-choices \{1 2 3 4 5 6 7 8\} \-default 1 \-height 3\} \\
> __\-listbox__ \{\-label "Listbox, multiple selection" \-variable Listbox2
> \-choicevariable ChoiceList \-default \{"Choice 2" "Choice 3"\}
> \-multiple\_selection 1 \-height 3\} \\
> __\-disjointlistbox__ \{\-label "Disjoined listbox" \-variable DisJntListbox
> \-choicevariable ChoiceList \\
> \-default \{"Choice 3" "Choice 5"\} \-height 3\} \\
> __\-combobox__ \{\-label "Combobox" \-variable Combobox \\
> \-choices \{1 2 3 4 5 6 7 8\} \-default 3\} \\
> __\-frame__ \{\-label "Checkbox, radiobox and checkbutton"\} \\
> __\-checkbox__ \{\-label Checkbox \-variable Checkbox
> \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\
> \-default italic\} \\
> __\-radiobox__ \{\-label Radiobox \-variable Radiobox
> \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\
> \-default underline\} \\
> __\-checkbutton__ \{\-label CheckButton \-variable Checkbutton \-default 1\} \\
> __\-frame__ \{\-label "Files & directories"\} \\
> __\-existingfile__ \{\-label "Input file" \-variable InputFile\} \\
> __\-file__ \{\-label "Output file" \-variable OutputFile\} \\
> __\-sep__ \{\} \\
> __\-existingdirectory__ \{\-label "Input directory" \-variable InputDirectory\} \\
> __\-directory__ \{\-label "Output irectory" \-variable OutputDirectory\} \\
> __\-frame__ \{\-label "Colors and fonts"\} \\
> __\-color__ \{\-label "Background color" \-variable Color \-default red\} \\
> __\-sep__ \{\} \\
> __\-font__ \{\-label "Font" \-variable Font \-default \{Courier 12 italic\}\}
\] The __argument\_dialogbox__ defines all the specified variables with the
entered data and returns __ok__ if the data have been validated via the Ok
button\. If the data entry is cancelled by activating the Cancel button, the
__argument\_dialogbox__ returns __cancel__\.
if {$Result=="cancel"} {
|
Changes to embedded/md/tcllib/files/modules/tepam/tepam_procedure.md.
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 ... 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 ... 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 ... 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 ... 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 ... 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 ... 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 ... 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 ... 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 ... 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 ... 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 .... 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 .... 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 .... 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 |
__proc__ also 3 arguments:
- <a name='1'></a>__tepam::procedure__ *name* *attributes* *body*
The TEPAM procedure declaration syntax is demonstrated by the following example:
> __tepam::procedure__ \{display message\} \{
> \-short\_description
> "Displays a simple message box"
> \-description
> "This procedure allows displaying a configurable\\
> message box\. The default message type that is\\
> created is a warning, but also errors and info can\\
> be generated\.
> The procedure accepts multiple text lines\."
> \-example
> \{display message \-mtype Warning "Save first your job"\}
> \-args \{
> \{\-mtype \-choices \{Info Warning Error\} \\
> \-default Warning \-description "Message type"\}
> \{text \-type string \-multiple \\
> \-description "Multiple text lines to display"\}
> \}
> \} \{
> puts "Message type: $mtype"
> puts "Message: $text"
> \}
The 3 arguments of __procedure__ are:
- *name*
The procedure name can be used in very flexible ways\. Procedure names can
................................................................................
This is the normal procedure body\. The declared arguments will be available
to the procedure body in form of variables\.
The procedure body will only be executed if the provided set of arguments
could be validated by the TEPAM argument manager\.
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{\-__mtype__ \-default Warning \-choices \{Warning Error\}\}
> \{__text__ \-type string\}
> \}
> \} \{
> puts "Message type: __$mtype__"
> puts "Message: __$text__"
> \}
The commands __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ as well as
__argument\_dialogbox__ are exported from the namespace __tepam__\. To use
these commands without the __tepam::__ namespace prefix, it is sufficient to
import them into the main namespace:
> __namespace import tepam::\*__
>
> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{
> \-args \{
> \.\.\.
## <a name='subsection1'></a>Procedure Attributes
The first group of attributes affect the behavior of the declared procedure:
- \-named\_arguments\_first __0__|__1__
................................................................................
Custom argument validations can be performed via specific validation
commands that are defined with the *\-validatecommand* attribute\.
Validation command declaration example:
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{text \-type string \-description "Message text"\} \}
> __\-validatecommand \{IllegalWordDetector $text\}__
> \} \{
> \}
The validation command is executed in the context of the declared procedure
body\. The different argument values are accessed via the argument names\.
Note there is also an argument attribute *\-validatecommand* that allows
declaring custom checks for specific arguments\.
................................................................................
## <a name='subsection2'></a>Argument Declaration
The following example shows the structure that is used for the argument
definitions in the context of a procedure declaration:
> tepam::procedure \{display\_message\} \{
> \-args __\{
> \{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}
> \{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}
> \{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}
> \{\-fg \-type color \-optional \-description "Message color"\}
> \{\-log\_file \-type file \-optional \-description "Optional message log file"\}
> \{text \-type string \-multiple \-description "Multiple text lines to display"\}
> \}__
> \} \{
> \}
Each of the procedure arguments is declared with a list that has as first
element the argument name, followed by eventual attributes\. The argument
definition syntax can be formalized in the following way:
> tepam::procedure <name> \{
> \-args __\{
> \{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a> <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}
> \{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a> <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}
> \.\.\.
> \}__
> \} <body>
The argument names and attributes have to be used in the following way:
- Argument name \(*<argument\_name\_<n>>*\)
The provided argument name specifies whether the argument is an *unnamed
................................................................................
This is the simplest form of an argument name: An argument whose name is
not starting with '\-' is an *unnamed argument*\. The parameter provided
during a procedure call will be assigned to a variable with the name
*<Name>*\.
> tepam::procedure \{print\_string\} \{
> \-args \{
> \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\}
> \}
> \} \{
> puts __$text__
> \}
>
> print\_string __"Hello"__
>
* \-> Hello*
................................................................................
* *"\-<Name>"*
An argument whose name starts with '\-' is a *named argument* \(also
called *option*\)\. The parameter provided during a procedure call will
be assigned to a variable with the name *<Name>* \(not *\-<Name>*\)\.
> tepam::procedure \{print\_string\} \{
> \-args \{
> \{__\-text__ \-type string \-description "This is a named argument"\}
> \}
> \} \{
> puts __$text__
> \}
>
> print\_string __\-text "Hello"__
>
* \-> Hello*
................................................................................
* *"\-"* or *""*
A blank argument name \(either '\-' or *''*\) starts a comment for the
following arguments\.
> tepam::procedure \{print\_time\} \{
> \-interactive\_display\_format short
> \-args \{
> \{hours \-type integer \-description "Hour"\}
> \{minutes \-type integer \-description "Minute"\}
>
> __\{\- The following arguments are optional:\}__
> \{seconds \-type integer \-default 0 \-description "Seconds"\}
> \{milliseconds \-type integer \-default 0 \-description "Milliseconds"\}
> \}
> \} \{
> puts "$\{hour\}h$\{minutes\}:\[expr $seconds\+0\.001\*$milliseconds\]"
> \}
Argument comments are basically used in the graphical argument
definition forms that are created if a procedure is called
interactively\.
* *"\#\*"*
................................................................................
'\#' characters and the remaining string will be used as section comment\.
Section comments can be used to structure visually the argument
definition code\. Section comments are also used to structure the
generated help texts and the interactive argument definition forms\.
> tepam::procedure \{complex\_multiply\} \{
> \-description "This function perform a complex multiplication"
> \-args \{
> __\{\#\#\#\# First complex number \#\#\#\#\}__
> \{\-r0 \-type double \-description "First number real part"\}
> \{\-i0 \-type double \-description "First number imaginary part"\}
>
> __\{\#\#\#\# Second complex number \#\#\#\#\}__
> \{\-r1 \-type double \-description "Second number real part"\}
> \{\-i1 \-type double \-description "Second number imaginary part"\}
> \}
> \} \{
> return \[expr $r0\*$r1 \- $i0\*$i1\]
> \}
- Argument attributes \(*<arg\_attr\_name\_<mn>> <arg\_attr\_value\_<mn>>*\)
The following argument attributes are supported:
* \-description *string*
................................................................................
attribute\. The provided validation command can be a complete script in
which the pattern *%P* is replaced by the argument value that has to
be validated\.
Validation command declaration example:
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{text \-type string \-description "Message text" \\
> __\-validatecommand \{IllegalWordDetector %P\}__\}
> \} \{
> \}
While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global attribute
*\-validatecommand* that allows performing validation that involves
multiple arguments\.
................................................................................
For example, if a procedure takes as argument a file name it may be
beneficial to specify the required file type for the interactive
argument definition form\. This information can be provided via the
*\-auxargs* attribute to the argument definition form:
> tepam::procedure LoadPicture \{
> \-args \{
> \{FileName \-type existingfile \-description "Picture file" \\
> __\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\}
> \}
> \} \{
> \}
* \-auxargs\_commands *script*
If the auxiliary argument attributes are not static but have to be
dynamically adaptable, the *\-auxargs\_commands* allows defining them
................................................................................
be completed with application specific types if necessary\.
## <a name='subsection3'></a>Predefined Argument Types
To remember, a type can be assigned to each specified procedure argument:
> tepam::procedure \{warning\} \{
> \-args \{
> \{\-font __\-type font__ \-default \{Arial 10 italic\}\}
> \{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\}
> \{\-fg __\-type color__ \-optional \-description "Message color"\}
> \{text __\-type string__ \-multiple \-description "Multiple text lines to display"\}
> \}
> \} \{
> \.\.\.
> \}
There are some *special purpose types* that are building the first category of
predefined argument types:
- __none__ A *flag*, also called *switch*, is defined as a named
argument that has the type __none__\. Flags are always optional and the
default value of the assigned variable is set to __0__\. In contrast to
the \(normal\) named arguments, no argument value has to be provided to a
flag\.
> tepam::procedure flag\_test \{
> \-args \{
> __\{\-flag \-type none \-description "This is a flag"\}__
> \}
> \} \{
> puts __$flag__
> \}
>
> flag\_test
> *\-> 0*
>
> flag\_test \-flag
>
................................................................................
__tepam::named\_arguments\_first__ was set to 1, or with the procedure
attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\.
The following procedure declaration will be used in this section to illustrate
the meaning of this calling style:
> __set tepam::named\_arguments\_first 1__
> tepam::procedure my\_proc \{
> \-args \{
> \{\-n1 \-default ""\}
> \{\-n2 \-default ""\}
> \{u1 \-default ""\}
> \{u2 \-default ""\}
> \}
> \} \{
> puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
> \}
The unnamed arguments are placed at the end of procedure call, after the named
arguments:
> my\_proc __\-n1 N1 \-n2 N2 U1 U2__
>
................................................................................
The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute
*\-named\_arguments\_first* has been set to 0\. The following procedure will be
used in this section to illustrate this calling style:
> __set tepam::named\_arguments\_first 0__
> tepam::procedure my\_proc \{
> \-args \{
> \{\-n1 \-default ""\}
> \{\-n2 \-default ""\}
> \{u1\}
> \{u2 \-default "" \-multiple\}
> \}
> \} \{
> puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
> \}
The unnamed arguments have to be provided first in this case\. The named
arguments are provided afterwards:
> my\_proc __U1 U2 \-n1 N1 \-n2 N2__
>
................................................................................
## <a name='subsection11'></a>Raw Argument List
It may be necessary sometimes that the procedure body is able to access the
entire list of arguments provided during a procedure call\. This can happen via
the __args__ variable that contains always the unprocessed argument list:
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{\-mtype \-choices \{Warning Error\} \-default Warning\}
> \{text \-type string \-multiple\}
>
> \}
> \} \{
> puts "args: __$args__"
> \}
> display\_message \-mtype Warning "It is 7:00"
>
*\-> args: \-mtype Warning \{It is 7:00\}*
# <a name='seealso'></a>SEE ALSO
|
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 ... 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 ... 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 ... 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 ... 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 ... 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 ... 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 ... 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 ... 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 ... 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 ... 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 .... 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 .... 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 .... 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 |
__proc__ also 3 arguments:
- <a name='1'></a>__tepam::procedure__ *name* *attributes* *body*
The TEPAM procedure declaration syntax is demonstrated by the following example:
> __tepam::procedure__ \{display message\} \{
> \-short\_description
> "Displays a simple message box"
> \-description
> "This procedure allows displaying a configurable\\
> message box\. The default message type that is\\
> created is a warning, but also errors and info can\\
> be generated\.
> The procedure accepts multiple text lines\."
> \-example
> \{display message \-mtype Warning "Save first your job"\}
> \-args \{
> \{\-mtype \-choices \{Info Warning Error\} \\
> \-default Warning \-description "Message type"\}
> \{text \-type string \-multiple \\
> \-description "Multiple text lines to display"\}
> \}
> \} \{
> puts "Message type: $mtype"
> puts "Message: $text"
> \}
The 3 arguments of __procedure__ are:
- *name*
The procedure name can be used in very flexible ways\. Procedure names can
................................................................................
This is the normal procedure body\. The declared arguments will be available
to the procedure body in form of variables\.
The procedure body will only be executed if the provided set of arguments
could be validated by the TEPAM argument manager\.
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{\-__mtype__ \-default Warning \-choices \{Warning Error\}\}
> \{__text__ \-type string\}
> \}
> \} \{
> puts "Message type: __$mtype__"
> puts "Message: __$text__"
> \}
The commands __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ as well as
__argument\_dialogbox__ are exported from the namespace __tepam__\. To use
these commands without the __tepam::__ namespace prefix, it is sufficient to
import them into the main namespace:
> __namespace import tepam::\*__
>
> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{
> \-args \{
> \.\.\.
## <a name='subsection1'></a>Procedure Attributes
The first group of attributes affect the behavior of the declared procedure:
- \-named\_arguments\_first __0__|__1__
................................................................................
Custom argument validations can be performed via specific validation
commands that are defined with the *\-validatecommand* attribute\.
Validation command declaration example:
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{text \-type string \-description "Message text"\} \}
> __\-validatecommand \{IllegalWordDetector $text\}__
> \} \{
> \}
The validation command is executed in the context of the declared procedure
body\. The different argument values are accessed via the argument names\.
Note there is also an argument attribute *\-validatecommand* that allows
declaring custom checks for specific arguments\.
................................................................................
## <a name='subsection2'></a>Argument Declaration
The following example shows the structure that is used for the argument
definitions in the context of a procedure declaration:
> tepam::procedure \{display\_message\} \{
> \-args __\{
> \{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}
> \{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}
> \{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}
> \{\-fg \-type color \-optional \-description "Message color"\}
> \{\-log\_file \-type file \-optional \-description "Optional message log file"\}
> \{text \-type string \-multiple \-description "Multiple text lines to display"\}
> \}__
> \} \{
> \}
Each of the procedure arguments is declared with a list that has as first
element the argument name, followed by eventual attributes\. The argument
definition syntax can be formalized in the following way:
> tepam::procedure <name> \{
> \-args __\{
> \{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a> <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}
> \{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a> <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}
> \.\.\.
> \}__
> \} <body>
The argument names and attributes have to be used in the following way:
- Argument name \(*<argument\_name\_<n>>*\)
The provided argument name specifies whether the argument is an *unnamed
................................................................................
This is the simplest form of an argument name: An argument whose name is
not starting with '\-' is an *unnamed argument*\. The parameter provided
during a procedure call will be assigned to a variable with the name
*<Name>*\.
> tepam::procedure \{print\_string\} \{
> \-args \{
> \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\}
> \}
> \} \{
> puts __$text__
> \}
>
> print\_string __"Hello"__
>
* \-> Hello*
................................................................................
* *"\-<Name>"*
An argument whose name starts with '\-' is a *named argument* \(also
called *option*\)\. The parameter provided during a procedure call will
be assigned to a variable with the name *<Name>* \(not *\-<Name>*\)\.
> tepam::procedure \{print\_string\} \{
> \-args \{
> \{__\-text__ \-type string \-description "This is a named argument"\}
> \}
> \} \{
> puts __$text__
> \}
>
> print\_string __\-text "Hello"__
>
* \-> Hello*
................................................................................
* *"\-"* or *""*
A blank argument name \(either '\-' or *''*\) starts a comment for the
following arguments\.
> tepam::procedure \{print\_time\} \{
> \-interactive\_display\_format short
> \-args \{
> \{hours \-type integer \-description "Hour"\}
> \{minutes \-type integer \-description "Minute"\}
>
> __\{\- The following arguments are optional:\}__
> \{seconds \-type integer \-default 0 \-description "Seconds"\}
> \{milliseconds \-type integer \-default 0 \-description "Milliseconds"\}
> \}
> \} \{
> puts "$\{hour\}h$\{minutes\}:\[expr $seconds\+0\.001\*$milliseconds\]"
> \}
Argument comments are basically used in the graphical argument
definition forms that are created if a procedure is called
interactively\.
* *"\#\*"*
................................................................................
'\#' characters and the remaining string will be used as section comment\.
Section comments can be used to structure visually the argument
definition code\. Section comments are also used to structure the
generated help texts and the interactive argument definition forms\.
> tepam::procedure \{complex\_multiply\} \{
> \-description "This function perform a complex multiplication"
> \-args \{
> __\{\#\#\#\# First complex number \#\#\#\#\}__
> \{\-r0 \-type double \-description "First number real part"\}
> \{\-i0 \-type double \-description "First number imaginary part"\}
>
> __\{\#\#\#\# Second complex number \#\#\#\#\}__
> \{\-r1 \-type double \-description "Second number real part"\}
> \{\-i1 \-type double \-description "Second number imaginary part"\}
> \}
> \} \{
> return \[expr $r0\*$r1 \- $i0\*$i1\]
> \}
- Argument attributes \(*<arg\_attr\_name\_<mn>> <arg\_attr\_value\_<mn>>*\)
The following argument attributes are supported:
* \-description *string*
................................................................................
attribute\. The provided validation command can be a complete script in
which the pattern *%P* is replaced by the argument value that has to
be validated\.
Validation command declaration example:
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{text \-type string \-description "Message text" \\
> __\-validatecommand \{IllegalWordDetector %P\}__\}
> \} \{
> \}
While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global attribute
*\-validatecommand* that allows performing validation that involves
multiple arguments\.
................................................................................
For example, if a procedure takes as argument a file name it may be
beneficial to specify the required file type for the interactive
argument definition form\. This information can be provided via the
*\-auxargs* attribute to the argument definition form:
> tepam::procedure LoadPicture \{
> \-args \{
> \{FileName \-type existingfile \-description "Picture file" \\
> __\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\}
> \}
> \} \{
> \}
* \-auxargs\_commands *script*
If the auxiliary argument attributes are not static but have to be
dynamically adaptable, the *\-auxargs\_commands* allows defining them
................................................................................
be completed with application specific types if necessary\.
## <a name='subsection3'></a>Predefined Argument Types
To remember, a type can be assigned to each specified procedure argument:
> tepam::procedure \{warning\} \{
> \-args \{
> \{\-font __\-type font__ \-default \{Arial 10 italic\}\}
> \{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\}
> \{\-fg __\-type color__ \-optional \-description "Message color"\}
> \{text __\-type string__ \-multiple \-description "Multiple text lines to display"\}
> \}
> \} \{
> \.\.\.
> \}
There are some *special purpose types* that are building the first category of
predefined argument types:
- __none__ A *flag*, also called *switch*, is defined as a named
argument that has the type __none__\. Flags are always optional and the
default value of the assigned variable is set to __0__\. In contrast to
the \(normal\) named arguments, no argument value has to be provided to a
flag\.
> tepam::procedure flag\_test \{
> \-args \{
> __\{\-flag \-type none \-description "This is a flag"\}__
> \}
> \} \{
> puts __$flag__
> \}
>
> flag\_test
> *\-> 0*
>
> flag\_test \-flag
>
................................................................................
__tepam::named\_arguments\_first__ was set to 1, or with the procedure
attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\.
The following procedure declaration will be used in this section to illustrate
the meaning of this calling style:
> __set tepam::named\_arguments\_first 1__
> tepam::procedure my\_proc \{
> \-args \{
> \{\-n1 \-default ""\}
> \{\-n2 \-default ""\}
> \{u1 \-default ""\}
> \{u2 \-default ""\}
> \}
> \} \{
> puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
> \}
The unnamed arguments are placed at the end of procedure call, after the named
arguments:
> my\_proc __\-n1 N1 \-n2 N2 U1 U2__
>
................................................................................
The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute
*\-named\_arguments\_first* has been set to 0\. The following procedure will be
used in this section to illustrate this calling style:
> __set tepam::named\_arguments\_first 0__
> tepam::procedure my\_proc \{
> \-args \{
> \{\-n1 \-default ""\}
> \{\-n2 \-default ""\}
> \{u1\}
> \{u2 \-default "" \-multiple\}
> \}
> \} \{
> puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
> \}
The unnamed arguments have to be provided first in this case\. The named
arguments are provided afterwards:
> my\_proc __U1 U2 \-n1 N1 \-n2 N2__
>
................................................................................
## <a name='subsection11'></a>Raw Argument List
It may be necessary sometimes that the procedure body is able to access the
entire list of arguments provided during a procedure call\. This can happen via
the __args__ variable that contains always the unprocessed argument list:
> tepam::procedure \{display\_message\} \{
> \-args \{
> \{\-mtype \-choices \{Warning Error\} \-default Warning\}
> \{text \-type string \-multiple\}
>
> \}
> \} \{
> puts "args: __$args__"
> \}
> display\_message \-mtype Warning "It is 7:00"
>
*\-> args: \-mtype Warning \{It is 7:00\}*
# <a name='seealso'></a>SEE ALSO
|
Changes to embedded/md/tcllib/files/modules/try/tcllib_try.md.
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 |
# <a name='section2'></a>EXAMPLES
Ensure that a file is closed no matter what:
> set f \[open /some/file/name a\]
> __try__ \{
> puts \\$f "some message"
> \# \.\.\.
> \} __finally__ \{
> close \\$f
> \}
>
Handle different reasons for a file to not be openable for reading:
> __try__ \{
> set f \[open /some/file/name\]
> \} __trap__ \{POSIX EISDIR\} \{\} \{
> puts "failed to open /some/file/name: it's a directory"
> \} __trap__ \{POSIX ENOENT\} \{\} \{
> puts "failed to open /some/file/name: it doesn't exist"
> \}
>
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *try* of the [Tcllib
|
| | | | | | |
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 |
# <a name='section2'></a>EXAMPLES
Ensure that a file is closed no matter what:
> set f \[open /some/file/name a\]
> __try__ \{
> 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
|
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\&.3 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, ................................................................................ .. .BS .SH NAME doctools \- doctools - Processing documents .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp package require \fBdoctools ?1\&.5\&.3?\fR .sp \fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.? .sp \fB::doctools::help\fR .sp \fB::doctools::search\fR \fIpath\fR .sp |
|
|
|
1
2
3
4
5
6
7
8
9
10
11
12
...
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
'\" '\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net> '\" .TH "doctools" n 1\&.5\&.4 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, ................................................................................ .. .BS .SH NAME doctools \- doctools - Processing documents .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp package require \fBdoctools ?1\&.5\&.4?\fR .sp \fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.? .sp \fB::doctools::help\fR .sp \fB::doctools::search\fR \fIpath\fR .sp |
Changes to idoc/www/tcllib/files/modules/doctools/doctools.html.
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
| <a href="../../../toc.html">Table Of Contents</a> | <a href="../../../../index.html">Keyword Index</a> | <a href="../../../../toc0.html">Categories</a> | <a href="../../../../toc1.html">Modules</a> | <a href="../../../../toc2.html">Applications</a> ] <hr> <div class="doctools"> <h1 class="doctools_title">doctools(n) 1.5.3 tcllib "Documentation tools"</h1> <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> <p>doctools - doctools - Processing documents</p> </div> <div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> <ul class="doctools_toc"> <li class="doctools_section"><a href="#toc">Table Of Contents</a></li> <li class="doctools_section"><a href="#synopsis">Synopsis</a></li> ................................................................................ <li class="doctools_section"><a href="#copyright">Copyright</a></li> </ul> </div> <div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> <div class="doctools_synopsis"> <ul class="doctools_requirements"> <li>package require <b class="pkgname">Tcl 8.2</b></li> <li>package require <b class="pkgname">doctools <span class="opt">?1.5.3?</span></b></li> </ul> <ul class="doctools_syntax"> <li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li> <li><a href="#2"><b class="cmd">::doctools::help</b></a></li> <li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li> <li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li> <li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li> |
|
|
|
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
| <a href="../../../toc.html">Table Of Contents</a> | <a href="../../../../index.html">Keyword Index</a> | <a href="../../../../toc0.html">Categories</a> | <a href="../../../../toc1.html">Modules</a> | <a href="../../../../toc2.html">Applications</a> ] <hr> <div class="doctools"> <h1 class="doctools_title">doctools(n) 1.5.4 tcllib "Documentation tools"</h1> <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> <p>doctools - doctools - Processing documents</p> </div> <div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> <ul class="doctools_toc"> <li class="doctools_section"><a href="#toc">Table Of Contents</a></li> <li class="doctools_section"><a href="#synopsis">Synopsis</a></li> ................................................................................ <li class="doctools_section"><a href="#copyright">Copyright</a></li> </ul> </div> <div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> <div class="doctools_synopsis"> <ul class="doctools_requirements"> <li>package require <b class="pkgname">Tcl 8.2</b></li> <li>package require <b class="pkgname">doctools <span class="opt">?1.5.4?</span></b></li> </ul> <ul class="doctools_syntax"> <li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li> <li><a href="#2"><b class="cmd">::doctools::help</b></a></li> <li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li> <li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li> <li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li> |
Changes to modules/doctools/doctools.man.
1 2 3 4 5 6 7 8 9 |
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5.3]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]
|
| |
1 2 3 4 5 6 7 8 9 |
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5.4]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]
|
Changes to modules/doctools/doctools.tcl.
1354 1355 1356 1357 1358 1359 1360 1361 |
# => FOO/mpformats
#catch {search [file join $here lib doctools mpformats]}
#catch {search [file join [file dirname $here] lib doctools mpformats]}
catch {search [file join $here mpformats]}
}
package provide doctools 1.5.3
|
| |
1354 1355 1356 1357 1358 1359 1360 1361 |
# => FOO/mpformats
#catch {search [file join $here lib doctools mpformats]}
#catch {search [file join [file dirname $here] lib doctools mpformats]}
catch {search [file join $here mpformats]}
}
package provide doctools 1.5.4
|
Changes to modules/doctools/mpformats/fmt.latex.
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 .. 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 .. 78 79 80 81 82 83 84 85 86 87 88 89 90 91 ... 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 |
global _in_example
set _in_example 0
global _has_images
set _has_images 0
# Called to handle plain text from the input
proc fmt_plain_text {text} {
global _in_example
if {$_in_example} {
# NOTE: The example_begin/end combo allows for the example
# text to contain markup. The currently used verbatim
# environment will cause show the latex markup of the example,
# instead of formatting per that markup.
#
# TODO: Use a different environment to handle fixed font stuff
# while allowing for actual markup of parts.
set text [string map [list \\\\\n \\\n] $text]
return $text
}
return [texEscape $text]
}
proc Year {} {clock format [clock seconds] -format %Y}
................................................................................
}
################################################################
## Backend for LaTeX markup
c_pass 1 fmt_manpage_begin {title section version} NOP
c_pass 2 fmt_manpage_begin {title section version} {
global _has_images
set module [dt_module]
set shortdesc [c_get_module]
set description [c_get_title]
set copyright [c_get_copyright]
set hdr ""
................................................................................
append hdr \n
append hdr "\1\\documentclass\{article\}" \n
if {$_has_images} {
append hdr "\1\\usepackage{epsfig}" \n
append hdr "\1\\usepackage{epstopdf}" \n
}
append hdr "\1\\begin\{document\}" \n
append hdr "\1\\author\{[dt_user]\}" \n
set titletext ""
append titletext "$module / $title -- "
append titletext "$shortdesc : $description"
................................................................................
append text "Database Class: [Bold $dbclass]\\\\\n"
return "\n%\n\1\\item\[\] $text\n%\n"
}
################################################################
proc fmt_example_begin {} {
global _in_example
set _in_example 1
return {\begin{verbatim}}
}
proc fmt_example_end {} {
global _in_example
set _in_example 0
return {\end{verbatim}}
}
# No mapping of special characters
proc fmt_example {code} { return "\1\\begin\{verbatim\}\n${code}\n\1\\end\{verbatim\}\n" }
proc fmt_arg {text} {Underline $text}
proc fmt_cmd {text} {Bold $text}
proc fmt_emph {text} {Italic $text}
proc fmt_opt {text} {return ?$text?}
proc fmt_comment {text} {
|
> > > | < > | < < < < < < < | | > > > | > < > | | > > |
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 .. 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 .. 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 ... 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 |
global _in_example set _in_example 0 global _has_images set _has_images 0 global _has_examples set _has_examples 0 # Called to handle plain text from the input proc fmt_plain_text {text} { global _in_example if {$_in_example} { lappend map \\\\\n \1\\textbackslash\n lappend map \\\n \1\\textbackslash\n set text [string map $map $text] return $text } return [texEscape $text] } proc Year {} {clock format [clock seconds] -format %Y} ................................................................................ } ################################################################ ## Backend for LaTeX markup c_pass 1 fmt_manpage_begin {title section version} NOP c_pass 2 fmt_manpage_begin {title section version} { global _has_images _has_examples set module [dt_module] set shortdesc [c_get_module] set description [c_get_title] set copyright [c_get_copyright] set hdr "" ................................................................................ append hdr \n append hdr "\1\\documentclass\{article\}" \n if {$_has_images} { append hdr "\1\\usepackage{epsfig}" \n append hdr "\1\\usepackage{epstopdf}" \n } if {$_has_examples} { append hdr "\1\\usepackage{alltt}" \n } append hdr "\1\\begin\{document\}" \n append hdr "\1\\author\{[dt_user]\}" \n set titletext "" append titletext "$module / $title -- " append titletext "$shortdesc : $description" ................................................................................ append text "Database Class: [Bold $dbclass]\\\\\n" return "\n%\n\1\\item\[\] $text\n%\n" } ################################################################ proc fmt_example_begin {} { global _has_examples _in_example set _has_examples 1 set _in_example 1 return "\1\\begin{alltt}\n" } proc fmt_example_end {} { global _in_example set _in_example 0 return "\1\\end{alltt}\n" } # No mapping of special characters proc fmt_example {code} { return [fmt_example_begin][fmt_plain_text $code][fmt_example_end] } proc fmt_arg {text} {Underline $text} proc fmt_cmd {text} {Bold $text} proc fmt_emph {text} {Italic $text} proc fmt_opt {text} {return ?$text?} proc fmt_comment {text} { |
Changes to modules/doctools/mpformats/fmt.markdown.
366
367
368
369
370
371
372
373
374
375
376
377
378
379
...
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
|
CloseParagraph
if {[llength $sa]} { Special {SEE ALSO} seealso [join [XrefList [lsort $sa] sa] ", "] }
if {[llength $kw]} { Special KEYWORDS keywords [join [XrefList [lsort $kw] kw] ", "] }
if {$ca ne ""} { Special CATEGORY category $ca }
if {$ct != {}} { Special COPYRIGHT copyright $ct [Verbatim] }
return
}
c_pass 2 fmt_example_end {} {
#puts_stderr "AAA/fmt_example_end"
TextTrimLeadingSpace
# Check for protected markdown markup in the input. If present
# this is a complex example with highlighted parts.
................................................................................
# no such by default, thus must not be quoted. Mark them as
# protected from quoting. Further look for and convert
# continuation lines protected from Tcl substitution into a
# regular continuation line.
set t [Text?]
set t [string map [list \\\\\n \\\n] $t]
if {$complex} {
set tmp {}
foreach line [split $t \n] { append tmp $line[LB] }
set t $tmp
unset tmp
} else {
set t [Mark $t]
}
TextClear
Text $t
set penv [GetCurrent]
if {$penv != {}} {
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
|
|
|
>
|
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
|
CloseParagraph
if {[llength $sa]} { Special {SEE ALSO} seealso [join [XrefList [lsort $sa] sa] ", "] }
if {[llength $kw]} { Special KEYWORDS keywords [join [XrefList [lsort $kw] kw] ", "] }
if {$ca ne ""} { Special CATEGORY category $ca }
if {$ct != {}} { Special COPYRIGHT copyright $ct [Verbatim] }
return
}
proc Breaks {lines} {
set r {}
foreach line $lines { lappend r $line[LB] }
return $r
}
proc LeadSpaces {lines} {
set r {}
foreach line $lines { lappend r [LeadSpace $line] }
return $r
}
proc LeadSpace {line} {
# Split into leading and trailing whitespace, plus content
regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _
# Drop trailing spaces, make leading non-breaking, keep content (and inner spaces).
return [RepeatM " " $lead]$content
}
c_pass 2 fmt_example_end {} {
#puts_stderr "AAA/fmt_example_end"
TextTrimLeadingSpace
# Check for protected markdown markup in the input. If present
# this is a complex example with highlighted parts.
................................................................................
# no such by default, thus must not be quoted. Mark them as
# protected from quoting. Further look for and convert
# continuation lines protected from Tcl substitution into a
# regular continuation line.
set t [Text?]
set t [string map [list \\\\\n \\\n] $t]
if {$complex} {
# Process for block quote
# - make leading spaces non-breaking
# - force linebreaks
set t [join [Breaks [LeadSpaces [split $t \n]]] {}]
} else {
# Process for code block (verbatim)
set t [Mark $t]
}
TextClear
Text $t
set penv [GetCurrent]
if {$penv != {}} {
|
Changes to modules/doctools/pkgIndex.tcl.
1 2 3 4 5 6 |
if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools 1.5.3 [list source [file join $dir doctools.tcl]]
package ifneeded doctools::toc 1.2 [list source [file join $dir doctoc.tcl]]
package ifneeded doctools::idx 1.1 [list source [file join $dir docidx.tcl]]
package ifneeded doctools::cvs 1 [list source [file join $dir cvs.tcl]]
package ifneeded doctools::changelog 1.1 [list source [file join $dir changelog.tcl]]
|
| |
1 2 3 4 5 6 |
if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools 1.5.4 [list source [file join $dir doctools.tcl]]
package ifneeded doctools::toc 1.2 [list source [file join $dir doctoc.tcl]]
package ifneeded doctools::idx 1.1 [list source [file join $dir docidx.tcl]]
package ifneeded doctools::cvs 1 [list source [file join $dir cvs.tcl]]
package ifneeded doctools::changelog 1.1 [list source [file join $dir changelog.tcl]]
|
Changes to modules/doctools/tests/fmt/html/26.
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 |
<pre class="doctools_example"> Second \ Continuing Lines \ Done </pre> <p>............... Vorwaerts ..........</p> <pre class="doctools_example"> <b class="cmd">command</b> \ -- <b class="cmd">command</b> -- </pre> </div> <div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> <p>Copyright © .COPYRIGHT.</p> </div> </div></body></html> |
| |
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 |
<pre class="doctools_example"> Second \ Continuing Lines \ Done </pre> <p>............... Vorwaerts ..........</p> <pre class="doctools_example"> <b class="cmd">command</b> x \ -- <b class="cmd">command</b> -- </pre> </div> <div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> <p>Copyright © .COPYRIGHT.</p> </div> </div></body></html> |
Changes to modules/doctools/tests/fmt/latex/04.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\begin{document}
\author{@[email protected]}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
BEGINNE HIER
\begin{verbatim}
Example Block More Lines
\end{verbatim}
\begin{verbatim}
Inlined Example \
Next Line
\end{verbatim}
FERTIG
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | | | | | | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
BEGINNE HIER
\begin{alltt}
Example Block More Lines
\end{alltt}
\begin{alltt}
Inlined Example \textbackslash
Next Line
\end{alltt}
FERTIG
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/latex/08.
1
2
3
4
5
6
7
8
9
10
11
12
13
..
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) **Copyright**
% ALL.a
\documentclass{article}
\begin{document}
\author{@[email protected]}
\title{.MODULE. / ALL -- ..THE\_MODULE.. : ..THE\_TITLE..}
\maketitle
\section{Synopsis}\label{synopsis}
\begin{flushleft}
package require {\bf AAA}
package require {\bf BBB VVV}
package require {\bf CCC ?VVV?}
................................................................................
\item[] \underline{NAME} TYPE
%
DESCRIPTION ::{\bf Option}::
%
\item[] \underline{NAME} TYPE (MODE)
%
DESCRIPTION ::?Optional?::
\begin{verbatim}
THE ARGUMENT IS USED IN THIS
AND/OR THAT MANNER
\end{verbatim}
\end{itemize}
%
\item[] CMDNAME ...
%
DESCRIPTION ::{\bf Package}::
%
\item[] CMDNAME ...
|
>
|
|
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
..
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) **Copyright**
% ALL.a
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / ALL -- ..THE\_MODULE.. : ..THE\_TITLE..}
\maketitle
\section{Synopsis}\label{synopsis}
\begin{flushleft}
package require {\bf AAA}
package require {\bf BBB VVV}
package require {\bf CCC ?VVV?}
................................................................................
\item[] \underline{NAME} TYPE
%
DESCRIPTION ::{\bf Option}::
%
\item[] \underline{NAME} TYPE (MODE)
%
DESCRIPTION ::?Optional?::
\begin{alltt}
THE ARGUMENT IS USED IN THIS
AND/OR THAT MANNER
\end{alltt}
\end{itemize}
%
\item[] CMDNAME ...
%
DESCRIPTION ::{\bf Package}::
%
\item[] CMDNAME ...
|
Changes to modules/doctools/tests/fmt/latex/09.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\begin{document}
\author{@[email protected]}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
lorem
\begin{verbatim}
1 lorem ipsum dolores
\end{verbatim}
ipsum
\begin{verbatim} 2 lorem ipsum dolores \end{verbatim}
dolores
\begin{verbatim}
3 lorem ipsum dolores
\end{verbatim}
lorem
\begin{verbatim} 4 lorem ipsum dolores
\end{verbatim}
ipsum
\begin{verbatim}
5 lorem ipsum dolores \end{verbatim}
dolores
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | | | > | | | > | | | | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
lorem
\begin{alltt}
1 lorem ipsum dolores
\end{alltt}
ipsum
\begin{alltt}
2 lorem ipsum dolores \end{alltt}
dolores
\begin{alltt}
3 lorem ipsum dolores
\end{alltt}
lorem
\begin{alltt}
4 lorem ipsum dolores
\end{alltt}
ipsum
\begin{alltt}
5 lorem ipsum dolores \end{alltt}
dolores
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/latex/13.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-itemized-examples.1
\documentclass{article}
\begin{document}
\author{@[email protected]}
\title{.MODULE. / test-itemized-examples -- : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item
%
\begin{verbatim} A lorem ipsum dolores \end{verbatim}
%
\item
%
lorem ipsum dolores
\begin{verbatim} B lorem ipsum dolores \end{verbatim}
lorem ipsum dolores
%
\item
%
lorem ipsum dolores
\begin{verbatim} C lorem ipsum dolores \end{verbatim}
%
\item
%
lorem ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | > | > | > | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-itemized-examples.1
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / test-itemized-examples -- : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item
%
\begin{alltt}
A lorem ipsum dolores \end{alltt}
%
\item
%
lorem ipsum dolores
\begin{alltt}
B lorem ipsum dolores \end{alltt}
lorem ipsum dolores
%
\item
%
lorem ipsum dolores
\begin{alltt}
C lorem ipsum dolores \end{alltt}
%
\item
%
lorem ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/latex/14.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-enumerated-examples.1
\documentclass{article}
\begin{document}
\author{@[email protected]}
\title{.MODULE. / test-enumerated-examples -- : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{enumerate}
%
\item
%
\begin{verbatim} A1 lorem ipsum dolores \end{verbatim}
%
\item
%
lorem ipsum dolores
\begin{verbatim} B2 lorem ipsum dolores \end{verbatim}
lorem ipsum dolores
%
\item
%
lorem ipsum dolores
\begin{verbatim} C3 lorem ipsum dolores \end{verbatim}
%
\item
%
lorem ipsum dolores
\end{enumerate}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | > | > | > | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-enumerated-examples.1
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / test-enumerated-examples -- : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{enumerate}
%
\item
%
\begin{alltt}
A1 lorem ipsum dolores \end{alltt}
%
\item
%
lorem ipsum dolores
\begin{alltt}
B2 lorem ipsum dolores \end{alltt}
lorem ipsum dolores
%
\item
%
lorem ipsum dolores
\begin{alltt}
C3 lorem ipsum dolores \end{alltt}
%
\item
%
lorem ipsum dolores
\end{enumerate}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/latex/15.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-definition-examples.1
\documentclass{article}
\begin{document}
\author{@[email protected]}
\title{.MODULE. / test-definition-examples -- : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item[] lorem
%
\begin{verbatim} A1 lorem ipsum dolores \end{verbatim}
%
\item[] lorem
%
ipsum dolores
\begin{verbatim} B2 lorem ipsum dolores \end{verbatim}
lorem ipsum dolores
%
\item[] lorem
%
ipsum dolores
\begin{verbatim} C3 lorem ipsum dolores \end{verbatim}
%
\item[] lorem
%
ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | > | > | > | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% test-definition-examples.1
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / test-definition-examples -- : }
\maketitle
\section{Description}\label{section1}
lorem ipsum dolores
\begin{itemize}
%
\item[] lorem
%
\begin{alltt}
A1 lorem ipsum dolores \end{alltt}
%
\item[] lorem
%
ipsum dolores
\begin{alltt}
B2 lorem ipsum dolores \end{alltt}
lorem ipsum dolores
%
\item[] lorem
%
ipsum dolores
\begin{alltt}
C3 lorem ipsum dolores \end{alltt}
%
\item[] lorem
%
ipsum dolores
\end{itemize}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/latex/25.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\begin{document}
\author{aku}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
\begin{verbatim}
Special markdown __non-special__
\end{verbatim}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
\begin{alltt}
Special markdown __non-special__
\end{alltt}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/latex/26.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\begin{document}
\author{aku}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
\begin{verbatim}
Example Block More Lines \
Ever More
Never
\end{verbatim}
............... Weiter .............
\begin{verbatim}
Second \
Continuing Lines \
Done
\end{verbatim}
............... Vorwaerts ..........
\begin{verbatim}
{\bf command} \
-- {\bf command} --
\end{verbatim}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
> | | | | | | | | | | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
% Generated from file '.FILE.' by tcllib/doctools with format 'latex'
% Copyright (c) .COPYRIGHT.
% TEST.z
\documentclass{article}
\usepackage{alltt}
\begin{document}
\author{aku}
\title{.MODULE. / TEST -- : }
\maketitle
\section{Description}\label{section1}
\begin{alltt}
Example Block More Lines \textbackslash
Ever More
Never
\end{alltt}
............... Weiter .............
\begin{alltt}
Second \textbackslash
Continuing Lines \textbackslash
Done
\end{alltt}
............... Vorwaerts ..........
\begin{alltt}
{\bf command} x \textbackslash
-- {\bf command} --
\end{alltt}
\section{Copyright}\label{copyright}
\begin{flushleft}
Copyright (c) .COPYRIGHT.\linebreak
\end{flushleft}
\end{document}
|
Changes to modules/doctools/tests/fmt/man/26.
13 14 15 16 17 18 19 20 21 22 23 |
[example_begin] Second \ Continuing Lines \\ Done [example_end] ............... Vorwaerts .......... [example_begin] [cmd command] \\ -- [cmd command] -- [example_end] [manpage_end] |
| |
13 14 15 16 17 18 19 20 21 22 23 |
[example_begin] Second \ Continuing Lines \\ Done [example_end] ............... Vorwaerts .......... [example_begin] [cmd command] x \\ -- [cmd command] -- [example_end] [manpage_end] |
Changes to modules/doctools/tests/fmt/markdown/26.
26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
Second \
Continuing Lines \
Done
\.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\.
> __command__ \\
> \-\- __command__ \-\-
>
# <a name='copyright'></a>COPYRIGHT
Copyright © \.COPYRIGHT\.
|
| |
26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
Second \
Continuing Lines \
Done
\.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\.
> __command__ x \\
> \-\- __command__ \-\-
>
# <a name='copyright'></a>COPYRIGHT
Copyright © \.COPYRIGHT\.
|
Changes to modules/doctools/tests/fmt/nroff/26.
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 |
Done .CE \&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&. Vorwaerts \&.\&.\&.\&.\&.\&.\&.\&.\&.\&. .CS \fBcommand\fR \\ -- \fBcommand\fR -- .CE .SH COPYRIGHT .nf Copyright (c) \&.COPYRIGHT\&. .fi |
| |
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 |
Done .CE \&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&.\&. Vorwaerts \&.\&.\&.\&.\&.\&.\&.\&.\&.\&. .CS \fBcommand\fR x \\ -- \fBcommand\fR -- .CE .SH COPYRIGHT .nf Copyright (c) \&.COPYRIGHT\&. .fi |
Changes to modules/doctools/tests/fmt/text/26.
19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
| Second \ | Continuing Lines \ | Done ............... Vorwaerts .......... | command \ | -- command -- COPYRIGHT ========= Copyright (c) .COPYRIGHT. |
| |
19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
| Second \
| Continuing Lines \
| Done
............... Vorwaerts ..........
| command x \
| -- command --
COPYRIGHT
=========
Copyright (c) .COPYRIGHT.
|
Changes to modules/doctools/tests/fmt/tmml/26.
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
Continuing Lines \ Done </example> ............... Vorwaerts .......... <example> <cmd>command</cmd> \ -- <cmd>command</cmd> -- </example> </section> </manpage> |
| |
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
Continuing Lines \ Done </example> ............... Vorwaerts .......... <example> <cmd>command</cmd> x \ -- <cmd>command</cmd> -- </example> </section> </manpage> |
Changes to modules/doctools/tests/fmt/wiki/26.
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
Continuing Lines \ Done ====== ............... Vorwaerts .......... ====== '''command''' \ -- '''command''' -- ====== **COPYRIGHT** Copyright (c) .COPYRIGHT. |
| |
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
Continuing Lines \ Done ====== ............... Vorwaerts .......... ====== '''command''' x \ -- '''command''' -- ====== **COPYRIGHT** Copyright (c) .COPYRIGHT. |