Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Doctools - markdown - Tkt [c17f7019ec] Multiple fixes - Handling of multi-line input to emphasis and similar doctools markup. The markdown markup for these are limited to inline. Fixed by emitting markup for each line of the input. - Flush command results in example_end. Fixes the markup of such commands getting wrongly moved to after the example. Tweaked example formatting, dropping trailing linebreak and empty line in block quote. Version bump 1.5.5 - B (markdown, text) - T (markdown, text) - D (Various manpages affected by the issues, and tweak) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA3-256: |
f5786278a4add18519a3be833454aeb6 |
User & Date: | aku 2019-04-16 22:56:25.617 |
References
2019-04-16
| ||
22:57 | • Closed ticket [c17f7019ec]: TEPAM Introduction Documentation - Markdown generation errors plus 6 other changes artifact: a2bfa3ee12 user: aku | |
Context
2019-04-17
| ||
06:29 | Tkt [31868eeaff] Almost-identical path management utility package. (Differences due to 8.4 / 8.5 requirements) Removed doctools::paths (doctools2base, 8.4) Removed paths (pt, 8.5) Consolidated as fileutil::paths, Tcl 8.5 requirement. paths - No version bump. - T (NEW) - D (NEW) Updated internal users: - pt::peg::import 1.0.1 (I) - doctools::idx::import 0.2.1 (I) - Tcl 8.5 required - doctools::toc::import 0.2.1 (I) - Tcl 8.5 required check-in: d843b2df15 user: aku tags: ak-31868eeaff | |
2019-04-16
| ||
23:25 | oauth - oauth - Tkt [8fd2561785] Removed bogus '{' character at beginning of regexp for `Split` (on first separator character). Version bump 1.0.3 - B (oauth) check-in: a136e80afe user: aku tags: trunk | |
22:56 | Doctools - markdown - Tkt [c17f7019ec] Multiple fixes - Handling of multi-line input to emphasis and similar doctools markup. The markdown markup for these are limited to inline. Fixed by emitting markup for each line of the input. - Flush command results in example_end. Fixes the markup of such commands getting wrongly moved to after the example. Tweaked example formatting, dropping trailing linebreak and empty line in block quote. Version bump 1.5.5 - B (markdown, text) - T (markdown, text) - D (Various manpages affected by the issues, and tweak) check-in: f5786278a4 user: aku tags: trunk | |
2019-04-15
| ||
23:19 | math - math::exact - Tkt [30526e9027] - Fix version mismatch of code vs. index check-in: 068c2af6e8 user: aku tags: trunk | |
Changes
Changes to embedded/md/tcllib/files/modules/bench/bench_lang_intro.md.
︙ | ︙ | |||
82 83 84 85 86 87 88 | > bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{ > set key \[aes::Init ecb $k $i\] > \} \-body \{ > aes::Encrypt $key $p > \} __\-post__ \{ > aes::Final $key | | < | 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | > bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{ > set key \[aes::Init ecb $k $i\] > \} \-body \{ > aes::Encrypt $key $p > \} __\-post__ \{ > aes::Final $key > \} ## <a name='subsection4'></a>Advanced pre\- and postprocessing Our last example again deals with initialization and cleanup code\. To see the difference to the regular initialization and cleanup discussed in the last section it is necessary to know a bit more about how bench actually measures the speed of the the __\-body__\. |
︙ | ︙ | |||
135 136 137 138 139 140 141 | > 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 | | < | 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | > bench \-desc "set include, missing <SC> x$times $n" __\-ipre__ \{ > set A $sx\($times,$n\) > set B $A > \} \-body \{ > struct::set include A x > \} __\-ipost__ \{ > unset A B > \} # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of benchmarks, he should be fortified enough to be able to understand the formal *bench language specfication*\. It will also serve as the detailed specification and cheat sheet for all available commands and their syntax\. |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/docstrip/docstrip.md.
︙ | ︙ | |||
398 399 400 401 402 403 404 | > % \\iffalse > %<\*driver> > \\documentclass\{tclldoc\} > \\begin\{document\} > \\DocInput\{*filename\.dtx*\} > \\end\{document\} > %</driver> | | < | 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 | > % \\iffalse > %<\*driver> > \\documentclass\{tclldoc\} > \\begin\{document\} > \\DocInput\{*filename\.dtx*\} > \\end\{document\} > %</driver> > % \\fi or some variation thereof\. The trick is that the file gets read twice\. With normal LaTeX reading rules, the first two lines are comments and therefore ignored\. The third line is the document preamble, the fourth line begins the document body, and the sixth line ends the document, so LaTeX stops there — non\-comments below that point in the file are never subjected to the normal LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md.
︙ | ︙ | |||
81 82 83 84 85 86 87 | > \[index\_begin GROUPTITLE TITLE\] > \[__key markup__\] > \[__key \{semantic markup\}\]__\] > \[__key \{docidx markup\}__\] > \[__key \{docidx language\}__\] > \[__key \{docidx commands\}__\] | | < | 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | > \[index\_begin GROUPTITLE TITLE\] > \[__key markup__\] > \[__key \{semantic markup\}\]__\] > \[__key \{docidx markup\}__\] > \[__key \{docidx language\}__\] > \[__key \{docidx commands\}__\] > \[index\_end\] In the above example the command __key__ is used to declare the keyword phrases we wish to be part of the index\. However a truly useful index does not only list the keyword phrases, but will also contain references to documents associated with the keywords\. Here is a made\-up index for all the manpages in the module |
︙ | ︙ | |||
107 108 109 110 111 112 113 | > \[__manpage uuencode__\] > \[key yEnc\] > \[__manpage yencode__\] > \[key ydecode\] > \[__manpage yencode__\] > \[key yencode\] > \[__manpage yencode__\] | | < | 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | > \[__manpage uuencode__\] > \[key yEnc\] > \[__manpage yencode__\] > \[key ydecode\] > \[__manpage yencode__\] > \[key yencode\] > \[__manpage yencode__\] > \[index\_end\] In the above example the command __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ is used to insert references to documents, using symbolic file names, with each command belonging to the last __key__ command coming before it\. The other command to insert references is |
︙ | ︙ | |||
136 137 138 139 140 141 142 | configuration settings relevant to the table of contents\. I\.e\. it is possible to write > \[__include FILE__\] > \[__vset VAR VALUE__\] > \[index\_begin GROUPTITLE TITLE\] > \.\.\. | | < | < | 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | configuration settings relevant to the table of contents\. I\.e\. it is possible to write > \[__include FILE__\] > \[__vset VAR VALUE__\] > \[index\_begin GROUPTITLE TITLE\] > \.\.\. > \[index\_end\] Even more important, these two commands are allowed anywhere where a markup command is allowed, without regard for any other structure\. > \[index\_begin GROUPTITLE TITLE\] > \[__include FILE__\] > \[__vset VAR VALUE__\] > \.\.\. > \[index\_end\] The only restriction __include__ has to obey is that the contents of the included file must be valid at the place of the inclusion\. I\.e\. a file included before __index\_begin__ may contain only the templating commands __vset__ and __include__, a file included after a key may contain only manape or url references, and other keys, etc\. |
︙ | ︙ | |||
170 171 172 173 174 175 176 | 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\. | | < | 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\. From here on out the *[docidx language command |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md.
︙ | ︙ | |||
104 105 106 107 108 109 110 | > \[toc\_begin Doctoc \{Language Introduction\}\] > \[__item 1 DESCRIPTION__\] > \[__item 1\.1 \{Basic structure\}__\] > \[__item 1\.2 Items__\] > \[__item 1\.3 Divisions__\] > \[__item 2 \{FURTHER READING\}__\] | | < | 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | > \[toc\_begin Doctoc \{Language Introduction\}\] > \[__item 1 DESCRIPTION__\] > \[__item 1\.1 \{Basic structure\}__\] > \[__item 1\.2 Items__\] > \[__item 1\.3 Divisions__\] > \[__item 2 \{FURTHER READING\}__\] > \[toc\_end\] ## <a name='subsection4'></a>Divisions One thing of notice in the last example in the previous section is that the referenced sections actually had a nested structure, something which was expressed in the item labels, by using a common prefix for all the sections nested under section 1\. |
︙ | ︙ | |||
146 147 148 149 150 151 152 | > \[__division\_start DESCRIPTION__\] > \[item 1 \{Basic structure\}\] > \[item 2 Items\] > \[item 3 Divisions\] > \[__division\_end__\] > \[__division\_start \{FURTHER READING\}__\] > \[__division\_end__\] | | < | 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | > \[__division\_start DESCRIPTION__\] > \[item 1 \{Basic structure\}\] > \[item 2 Items\] > \[item 3 Divisions\] > \[__division\_end__\] > \[__division\_start \{FURTHER READING\}__\] > \[__division\_end__\] > \[toc\_end\] Or, to demonstrate deeper nesting > \[toc\_begin Doctoc \{Language Introduction\}\] > \[__division\_start DESCRIPTION__\] > \[__division\_start \{Basic structure\}__\] > \[item 1 Do\] |
︙ | ︙ | |||
169 170 171 172 173 174 175 | > \[__division\_start Divisions__\] > \[item 1 Sub\] > \[item 1 Zero\] > \[__division\_end__\] > \[__division\_end__\] > \[__division\_start \{FURTHER READING\}__\] > \[__division\_end__\] | | < | < | < | < | 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 | > \[__division\_start Divisions__\] > \[item 1 Sub\] > \[item 1 Zero\] > \[__division\_end__\] > \[__division\_end__\] > \[__division\_start \{FURTHER READING\}__\] > \[__division\_end__\] > \[toc\_end\] And do not forget, it is possible to freely mix items and divisions, and to have empty divisions\. > \[toc\_begin Doctoc \{Language Introduction\}\] > \[item 1 Do\] > \[__division\_start DESCRIPTION__\] > \[__division\_start \{Basic structure\}__\] > \[item 2 Re\] > \[__division\_end__\] > \[item a Fi\] > \[__division\_start Items__\] > \[item b Fo\] > \[item c Fa\] > \[__division\_end__\] > \[__division\_start Divisions__\] > \[__division\_end__\] > \[__division\_end__\] > \[__division\_start \{FURTHER READING\}__\] > \[__division\_end__\] > \[toc\_end\] ## <a name='subsection5'></a>Advanced structure In all previous examples we fudged a bit regarding the markup actually allowed to be used before the __toc\_begin__ command opening the document\. Instead of only whitespace the two templating commands __include__ and __vset__ are also allowed, to enable the writer to either set and/or import configuration settings relevant to the table of contents\. I\.e\. it is possible to write > \[__include FILE__\] > \[__vset VAR VALUE__\] > \[toc\_begin GROUPTITLE TITLE\] > \.\.\. > \[toc\_end\] Even more important, these two commands are allowed anywhere where a markup command is allowed, without regard for any other structure\. > \[toc\_begin GROUPTITLE TITLE\] > \[__include FILE__\] > \[__vset VAR VALUE__\] > \.\.\. > \[toc\_end\] The only restriction __include__ has to obey is that the contents of the included file must be valid at the place of the inclusion\. I\.e\. a file included before __toc\_begin__ may contain only the templating commands __vset__ and __include__, a file included in a division may contain only items or divisions commands, etc\. |
︙ | ︙ | |||
242 243 244 245 246 247 248 | 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\. | | < | 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 | Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\. From here on out the *[doctoc language command |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/doctools/doctools.md.
1 2 3 4 | [//000000001]: # (doctools \- Documentation tools) [//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © 2003\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) | | | 1 2 3 4 5 6 7 8 9 10 11 12 | [//000000001]: # (doctools \- Documentation tools) [//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © 2003\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) [//000000004]: # (doctools\(n\) 1\.5\.5 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> |
︙ | ︙ | |||
46 47 48 49 50 51 52 | - [Category](#category) - [Copyright](#copyright) # <a name='synopsis'></a>SYNOPSIS package require Tcl 8\.2 | | | 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | - [Category](#category) - [Copyright](#copyright) # <a name='synopsis'></a>SYNOPSIS package require Tcl 8\.2 package require doctools ?1\.5\.5? [__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1) [__::doctools::help__](#2) [__::doctools::search__ *path*](#3) [__objectName__ __method__ ?*arg arg \.\.\.*?](#4) [*objectName* __configure__](#5) [*objectName* __configure__ *option*](#6) |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md.
︙ | ︙ | |||
135 136 137 138 139 140 141 | > \[manpage\_begin NAME SECTION VERSION\] > \[__copyright \{YEAR AUTHOR\}__\] > \[__titledesc TITLE__\] > \[__moddesc MODULE\_TITLE__\] > \[__require PACKAGE VERSION__\] > \[__require PACKAGE__\] > \[description\] | | < | 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | > \[manpage\_begin NAME SECTION VERSION\] > \[__copyright \{YEAR AUTHOR\}__\] > \[__titledesc TITLE__\] > \[__moddesc MODULE\_TITLE__\] > \[__require PACKAGE VERSION__\] > \[__require PACKAGE__\] > \[description\] > \[manpage\_end\] Remember that the whitespace is optional\. The document [manpage_begin NAME SECTION VERSION] [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] [require PACKAGE VERSION][require PACKAGE][description] [vset CATEGORY doctools] |
︙ | ︙ | |||
163 164 165 166 167 168 169 | > \[copyright \{YEAR AUTHOR\}\] > \[titledesc TITLE\] > \[moddesc MODULE\_TITLE\]\[__comment \{ \.\.\. \}__\] > \[require PACKAGE VERSION\] > \[require PACKAGE\] > \[description\] > \[manpage\_end\] | | < | < | < | 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 | > \[copyright \{YEAR AUTHOR\}\] > \[titledesc TITLE\] > \[moddesc MODULE\_TITLE\]\[__comment \{ \.\.\. \}__\] > \[require PACKAGE VERSION\] > \[require PACKAGE\] > \[description\] > \[manpage\_end\] > \[__comment \{ \.\.\. \}__\] ## <a name='subsection3'></a>Advanced structure In the simple examples of the last section we fudged a bit regarding the markup actually allowed to be used before the __manpage\_begin__ command opening the document\. Instead of only whitespace the two templating commands __include__ and __vset__ are also allowed, to enable the writer to either set and/or import configuration settings relevant to the document\. I\.e\. it is possible to write > \[__include FILE__\] > \[__vset VAR VALUE__\] > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \[manpage\_end\] Even more important, these two commands are allowed anywhere where a markup command is allowed, without regard for any other structure\. I\.e\. for example in the header as well\. > \[manpage\_begin NAME SECTION VERSION\] > \[__include FILE__\] > \[__vset VAR VALUE__\] > \[description\] > \[manpage\_end\] The only restriction __include__ has to obey is that the contents of the included file must be valid at the place of the inclusion\. I\.e\. a file included before __manpage\_begin__ may contain only the templating commands __vset__ and __include__, a file included in the header may contain only header commands, etc\. |
︙ | ︙ | |||
224 225 226 227 228 229 230 | > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[__para__\] > \.\.\. > \[__para__\] > \.\.\. | | < | 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 | > \[manpage\_begin NAME SECTION VERSION\] > \[description\] > \.\.\. > \[__para__\] > \.\.\. > \[__para__\] > \.\.\. > \[manpage\_end\] Empty paragraphs are ignored\. A structure coarser than paragraphs are sections, which allow the writer to split a document into larger, and labeled, pieces\. The command for doing so is __section__\. Each occurrence of this command closes the previous section and automatically opens the next, including its first paragraph\. The first section |
︙ | ︙ | |||
249 250 251 252 253 254 255 | > \.\.\. > \[__section \{Section A\}__\] > \.\.\. > \[para\] > \.\.\. > \[__section \{Section B\}__\] > \.\.\. | | < | 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | > \.\.\. > \[__section \{Section A\}__\] > \.\.\. > \[para\] > \.\.\. > \[__section \{Section B\}__\] > \.\.\. > \[manpage\_end\] Between sections and paragraphs we have subsections, to split sections\. The command for doing so is __subsection__\. Each occurrence of this command closes the previous subsection and automatically opens the next, including its first paragraph\. A subsection is automatically opened at the beginning of the body, by __description__, and at the beginning of each section\. In the same manner the last subsection automatically ends at __manpage\_end__\. |
︙ | ︙ | |||
275 276 277 278 279 280 281 | > \.\.\. > \[para\] > \.\.\. > \[__subsection \{Sub 2\}__\] > \.\.\. > \[section \{Section B\}\] > \.\.\. | | < | 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 | > \.\.\. > \[para\] > \.\.\. > \[__subsection \{Sub 2\}__\] > \.\.\. > \[section \{Section B\}\] > \.\.\. > \[manpage\_end\] ## <a name='subsection5'></a>Text markup Having handled the overall structure a writer can impose on the document we now take a closer at the text in a paragraph\. While most often this is just the unadorned content of the document we do have |
︙ | ︙ | |||
389 390 391 392 393 394 395 | > \.\.\. > \[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\. | | < | < | 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 | > \.\.\. > \[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\] > > Text structure\. List element\. Argument list\. Automatically closes the > previous list element\. Specifies the data\-\[__arg type__\] of the described > argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The > latter is optional\. > \.\.\. ## <a name='subsection6'></a>Escapes Beyond the 20 commands for simple markup shown in the previous section we have two more available which are technically simple markup\. However their function is not the marking up of phrases as specific types of things, but the insertion of characters, namely __\[__ and __\]__\. These commands, __lb__ and __rb__ respectively, are required because our use of \[ and \] to bracket markup commands makes it impossible to directly use \[ and \] within the text\. Our example of their use are the sources of the last sentence in the previous paragraph, with some highlighting added\. > \.\.\. > These commands, \[cmd lb\] and \[cmd lb\] respectively, are required > because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it > impossible to directly use \[__lb__\] and \[__rb__\] within the text\. > \.\.\. ## <a name='subsection7'></a>Cross\-references The last two commands we have to discuss are for the declaration of cross\-references between documents, explicit and implicit\. They are __[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both take an arbitrary number of arguments, all of which have to be plain unmarked |
︙ | ︙ | |||
448 449 450 451 452 453 454 | > \.\.\. > \[__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\}__\] | | < | 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 | > \.\.\. > \[__see\_also doctools\_intro__\] > \[__see\_also doctools\_lang\_syntax__\] > \[__see\_also doctools\_lang\_cmdref__\] > \[__keywords markup \{semantic markup\}__\] > \[__keywords \{doctools markup\} \{doctools language\}__\] > \[__keywords \{doctools syntax\} \{doctools commands\}__\] > \[manpage\_end\] ## <a name='subsection8'></a>Examples Where ever we can write plain text we can write examples too\. For simple examples we have the command __example__ which takes a single argument, the text of the argument\. The example text must not contain markup\. If we wish to have markup within an example we have to use the 2\-command combination |
︙ | ︙ | |||
471 472 473 474 475 476 477 | \(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\] \.\.\. | | < | < | 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 | \(Remember section [Advanced structure](#subsection3)\)\. The source for the very first example in this document \(see section [Fundamentals](#subsection1)\), with some highlighting added, is > \[__example__ \{ > \.\.\. \[list\_begin enumerated\] \.\.\. > \}\] Using __example\_begin__ / __example\_end__ this would look like > \[__example\_begin__\] > \.\.\. \[list\_begin enumerated\] \.\.\. > \[__example\_end__\] ## <a name='subsection9'></a>Lists Where ever we can write plain text we can write lists too\. The main commands are __list\_begin__ to start a list, and __list\_end__ to close one\. The opening command takes an argument specifying the type of list started it, and this in turn determines which of the eight existing list item commands are |
︙ | ︙ | |||
564 565 566 567 568 569 570 | > > \(\[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__\] | | < | < | 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 | > > \(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It > is a specialized form of a definition list where the term is the name > of a configuration option for a widget, with its name and class in the > option database\. > > \[__list\_end__\] > \.\.\. Note that a list cannot begin in one \(sub\)section and end in another\. Differently said, \(sub\)section breaks are not allowed within lists and list items\. An example of this *illegal* construct is > \.\.\. > \[list\_begin itemized\] > \[item\] > \.\.\. > \[__section \{ILLEGAL WITHIN THE LIST\}__\] > \.\.\. > \[list\_end\] > \.\.\. # <a name='section2'></a>FURTHER READING Now that this document has been digested the reader, assumed to be a *writer* of documentation should be fortified enough to be able to understand the formal *[doctools language syntax](doctools\_lang\_syntax\.md)* specification as well\. From here on out the *[doctools language command |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/grammar_fa/fa.md.
︙ | ︙ | |||
165 166 167 168 169 170 171 | overwriting any existing definition\. This is the assignment operator for automatons\. It copies the automaton contained in the FA object *srcFA* over the automaton definition in *faName*\. The old contents of *faName* are deleted by this operation\. This operation is in effect equivalent to | | < | < | 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 | overwriting any existing definition\. This is the assignment operator for automatons\. It copies the automaton contained in the FA object *srcFA* over the automaton definition in *faName*\. The old contents of *faName* are deleted by this operation\. This operation is in effect equivalent to > *faName* __deserialize__ \[*srcFA* __serialize__\] - <a name='6'></a>*faName* __\-\->__ *dstFA* This is the reverse assignment operator for automatons\. It copies the automation contained in the object *faName* over the automaton definition in the object *dstFA*\. The old contents of *dstFA* are deleted by this operation\. This operation is in effect equivalent to > *dstFA* __deserialize__ \[*faName* __serialize__\] - <a name='7'></a>*faName* __serialize__ This method serializes the automaton stored in *faName*\. In other words it returns a tcl *value* completely describing that automaton\. This allows, for example, the transfer of automatons over arbitrary channels, persistence, etc\. This method is also the basis for both the copy |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/grammar_peg/peg.md.
︙ | ︙ | |||
219 220 221 222 223 224 225 | overwriting any existing definition\. This is the assignment operator for grammars\. It copies the grammar contained in the grammar object *srcPEG* over the grammar definition in *pegName*\. The old contents of *pegName* are deleted by this operation\. This operation is in effect equivalent to | | < | < | 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 | overwriting any existing definition\. This is the assignment operator for grammars\. It copies the grammar contained in the grammar object *srcPEG* over the grammar definition in *pegName*\. The old contents of *pegName* are deleted by this operation\. This operation is in effect equivalent to > *pegName* __deserialize__ \[*srcPEG* __serialize__\] - <a name='5'></a>*pegName* __\-\->__ *dstPEG* This is the reverse assignment operator for grammars\. It copies the automation contained in the object *pegName* over the grammar definition in the object *dstPEG*\. The old contents of *dstPEG* are deleted by this operation\. This operation is in effect equivalent to > *dstPEG* __deserialize__ \[*pegName* __serialize__\] - <a name='6'></a>*pegName* __serialize__ This method serializes the grammar stored in *pegName*\. In other words it returns a tcl *value* completely describing that grammar\. This allows, for example, the transfer of grammars over arbitrary channels, persistence, etc\. This method is also the basis for both the copy constructor and the |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/hook/hook.md.
︙ | ︙ | |||
78 79 80 81 82 83 84 | events, and via callback options like the text widget's __\-yscrollcommand__ option\. Tk events are available only in Tk, and callback options require tight coupling between the modules sending and receiving the notification\. Loose coupling between sender and receiver is often desirable, however\. In Model/View/Controller terms, a View can send a command \(stemming from user input\) to the Controller, which updates the Model\. The Model can then call a | | | | | | | 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | events, and via callback options like the text widget's __\-yscrollcommand__ option\. Tk events are available only in Tk, and callback options require tight coupling between the modules sending and receiving the notification\. Loose coupling between sender and receiver is often desirable, however\. In Model/View/Controller terms, a View can send a command \(stemming from user input\) to the Controller, which updates the Model\. The Model can then call a hook *to which all relevant* *Views subscribe\.* The Model is decoupled from the Views, and indeed need not know whether any Views actually exist\. At present, Tcl/Tk has no standard mechanism for implementing loose coupling of this kind\. This package defines a new command, __hook__, which implements just such a mechanism\. ## <a name='subsection2'></a>Bindings The __hook__ command manages a collection of hook bindings\. A hook binding has four elements: 1. A *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*: the name of the entity |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/pki/pki.md.
︙ | ︙ | |||
201 202 203 204 205 206 207 208 209 210 211 212 213 214 | to specify as a boolean value whether or not we can be used a certificate authority \(CA\)\. The *caDepth* argument indicates how many children CAs can be children of this CA in a depth\-wise fashion\. A value of "0" for the *caDepth* argument means that this CA cannot sign a CA certificate and have the result be valid\. A value of "\-1" indicates infinite depth\. # <a name='section3'></a>EXAMPLES # <a name='section4'></a>REFERENCES # <a name='section5'></a>AUTHORS Roy Keene | > > > > | 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | to specify as a boolean value whether or not we can be used a certificate authority \(CA\)\. The *caDepth* argument indicates how many children CAs can be children of this CA in a depth\-wise fashion\. A value of "0" for the *caDepth* argument means that this CA cannot sign a CA certificate and have the result be valid\. A value of "\-1" indicates infinite depth\. # <a name='section3'></a>EXAMPLES # <a name='section4'></a>REFERENCES # <a name='section5'></a>AUTHORS Roy Keene |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/pt/pt_peg_container.md.
︙ | ︙ | |||
187 188 189 190 191 192 193 | This method assigns the contents of the PEG object *source* to ourselves, overwriting the existing definition\. This is the assignment operator for grammars\. This operation is in effect equivalent to | | < | < | 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 | This method assigns the contents of the PEG object *source* to ourselves, overwriting the existing definition\. This is the assignment operator for grammars\. This operation is in effect equivalent to > *objectName* __deserialize =__ \[*source* __serialize__\] - <a name='9'></a>*objectName* __\-\->__ *destination* This method assigns our contents to the PEG object *destination*, overwriting the existing definition\. This is the reverse assignment operator for grammars\. This operation is in effect equivalent to > *destination* __deserialize =__ \[*objectName* __serialize__\] - <a name='10'></a>*objectName* __serialize__ ?*format*? This method returns our grammar in some textual form usable for transfer, persistent storage, etc\. If no *format* is not specified the returned result is the canonical serialization of the grammar, as specified in the section [PEG serialization format](#section2)\. |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/struct/graph.md.
︙ | ︙ | |||
194 195 196 197 198 199 200 | This is the *assignment* operator for graph objects\. It copies the graph contained in the graph object *sourcegraph* over the graph data in *graphName*\. The old contents of *graphName* are deleted by this operation\. This operation is in effect equivalent to | | < | < | 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 | This is the *assignment* operator for graph objects\. It copies the graph contained in the graph object *sourcegraph* over the graph data in *graphName*\. The old contents of *graphName* are deleted by this operation\. This operation is in effect equivalent to > *graphName* __deserialize__ \[*sourcegraph* __serialize__\] The operation assumes that the *sourcegraph* provides the method __serialize__ and that this method returns a valid graph serialization\. - <a name='4'></a>*graphName* __\-\->__ *destgraph* This is the *reverse assignment* operator for graph objects\. It copies the graph contained in the graph object *graphName* over the graph data in the object *destgraph*\. The old contents of *destgraph* are deleted by this operation\. This operation is in effect equivalent to > *destgraph* __deserialize__ \[*graphName* __serialize__\] The operation assumes that the *destgraph* provides the method __deserialize__ and that this method takes a graph serialization\. - <a name='5'></a>*graphName* __append__ *key* *value* Appends a *value* to one of the keyed values associated with the graph\. |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/struct/matrix.md.
︙ | ︙ | |||
147 148 149 150 151 152 153 | This is the assignment operator for matrix objects\. It copies the matrix contained in the matrix object *sourcematrix* over the matrix data in *matrixName*\. The old contents of *matrixName* are deleted by this operation\. This operation is in effect equivalent to | | < | < | 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 | This is the assignment operator for matrix objects\. It copies the matrix contained in the matrix object *sourcematrix* over the matrix data in *matrixName*\. The old contents of *matrixName* are deleted by this operation\. This operation is in effect equivalent to > *matrixName* __deserialize__ \[*sourcematrix* __serialize__\] - <a name='4'></a>*matrixName* __\-\->__ *destmatrix* This is the reverse assignment operator for matrix objects\. It copies the matrix contained in the matrix object *matrixName* over the matrix data in the object *destmatrix*\. The old contents of *destmatrix* are deleted by this operation\. This operation is in effect equivalent to > *destmatrix* __deserialize__ \[*matrixName* __serialize__\] - <a name='5'></a>*matrixName* __add column__ ?*values*? Extends the matrix by one column and then acts like __set column__ \(see below\) on this new column if there were *values* supplied\. Without *values* the new cells will be set to the empty string\. The new column is appended immediately behind the last existing column\. |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/struct/struct_tree.md.
︙ | ︙ | |||
194 195 196 197 198 199 200 | This is the assignment operator for tree objects\. It copies the tree contained in the tree object *sourcetree* over the tree data in *treeName*\. The old contents of *treeName* are deleted by this operation\. This operation is in effect equivalent to | | < | < | 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 | This is the assignment operator for tree objects\. It copies the tree contained in the tree object *sourcetree* over the tree data in *treeName*\. The old contents of *treeName* are deleted by this operation\. This operation is in effect equivalent to > *treeName* __deserialize__ \[*sourcetree* __serialize__\] - <a name='5'></a>*treeName* __\-\->__ *desttree* This is the reverse assignment operator for tree objects\. It copies the tree contained in the tree object *treeName* over the tree data in the object *desttree*\. The old contents of *desttree* are deleted by this operation\. This operation is in effect equivalent to > *desttree* __deserialize__ \[*treeName* __serialize__\] - <a name='6'></a>*treeName* __ancestors__ *node* This method extends the method __parent__ and returns a list containing all ancestor nodes to the specified *node*\. The immediate ancestor, in other words, parent node, is the first element in that list, its parent the second element, and so on until the root node is reached, making it the last |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md.
︙ | ︙ | |||
91 92 93 94 95 96 97 | > __\-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__ \{\} \\ | | | | | | | | | | < < | | | | | | | | | | > | | | | | | | | 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 | > __\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\ > __\-frame__ \{*\-label "Itinerary destination"*\} \\ > __\-comment__ \{*\-text "Specify your itinerary destination"*\} \\ > __\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\ > __\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\ > __\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\ > __\-frame__ \{\} \\ > __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}\] This example opens a dialog box that has the title *Itinerary selection*\. A first entry widget in this box allows selecting a report file\. It follows two frames to define respectively an itinerary start and end location\. Each of these locations that are described with a comment has three entry widgets to specify respectively the city, street and the street number\. Bellow the second frame there is a check button that allows specifying if eventual highways should be ignored\. - <a name='2'></a>__tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\} Sometimes it is simpler to provide all the data entry item definitions in form of a single list to __argument\_dialogbox__, and not as individual arguments\. The second format that is supported by __argument\_dialogbox__ corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to __argument\_dialogbox__\. The previous example can therefore also be written in the following way: > set DialogResult \[__tepam::argument\_dialogbox \{__ > __\-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 widget has been defined\. It recognizes the following attributes inside the item attribute list: * \-label *string* An optional frame label can be specified with the *\-label* statement\. Example: > tepam::argument\_dialogbox \\ > \.\.\. > __\-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\. |
︙ | ︙ | |||
318 319 320 321 322 323 324 | 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 \\ > \.\.\. | | | | | > | | | | | | | | | | | | | | | | | | | 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 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 | 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 extended with additional application specific entry widgets \(see [APPLICATION SPECIFIC ENTRY WIDGETS](#section3)\): - \-entry *list* The *\-entry* item generates the simplest but most universal data entry widget\. It allows entering any kind of data in form of single line strings\. > tepam::argument\_dialogbox \\ > __\-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* A group of radio boxes is created with the *\-radiobox* item\. The number of radio boxes and their option values are specified with a list assigned to the *\-choices* attribute or via a variable declared with the *\-choicevariable* attribute\. In contrast to a check box group, a radio box group allows selecting simultaneously only one choice option\. The selected option value is stored directly, and not in form of a list, inside the defined variable\. > tepam::argument\_dialogbox \\ > __\-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 |
︙ | ︙ | |||
559 560 561 562 563 564 565 | 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\} \\ | | | | | | | | | | | 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 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 | 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 value\. The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by __[tepam::procedure](tepam\_procedure\.md)__ \(see the *tepam::procedure reference manual*\)\. Some entry widgets like the file and directory widgets, as well as the color and font widgets are specifying automatically the default data type if no type has been specified explicitly with the *\-type* attribute\. > tepam::argument\_dialogbox \\ > __\-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* |
︙ | ︙ | |||
680 681 682 683 684 685 686 | 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 \\ | | | | | | | | | | | 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 | 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\. The entry widget procedure has to support 3 mandatory and an optional command |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md.
︙ | ︙ | |||
240 241 242 243 244 245 246 | 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: | | | | | | | | | | | | | | | | | | | | | | | | | 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 | 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 |
︙ | ︙ | |||
428 429 430 431 432 433 434 | * *IsOptional* If true \(=__1__\) the argument is optional which should be indicated by the generated string \(for example by putting the argument into brackets \{\[\]\} or into question marks '?'\): | | < < | | < < | < < | | | | | | < | 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 | * *IsOptional* If true \(=__1__\) the argument is optional which should be indicated by the generated string \(for example by putting the argument into brackets \{\[\]\} or into question marks '?'\): > gen\(TXT,ArgumentString\) mtype 1 0 string \-> *"\[mtype\]"* * *IsNamed* If true \(=__1__\) an argument is a named argument \(option\)\. The generated string should in this case contain the argument/option name, followed by the argument itself: > gen\(TXT,ArgumentString\) mtype 0 1 string \-> *"\-mtype <mtype>"* Named arguments can also be optional: > gen\(TXT,ArgumentString\) mtype 1 1 string \-> *"\[\-mtype <mtype>\]"* * *Type* Indicates the type of the argument\. If the type is set to __none__ the argument is a flag, which needs to be indicated by the generated string\. Example: > gen\(TXT,ArgumentString\) close 1 1 none \-> *"\[\-close\]"* # <a name='section5'></a>EXAMPLES ## <a name='subsection5'></a>tepam::doc\_gen::generate The __TEPAM Doc Gen__ package can be explored by generating the documentation of the command __tepam::doc\_gen::generate__\. The following example generates the document in text format \(default format\): > __tepam::doc\_gen::generate__ tepam::doc\_gen::generate The next example generates the documentation in HTML format: > __tepam::doc\_gen::generate__ \-format HTML tepam::doc\_gen::generate The flag ?header\_footer? adds also the file header and footer: > __tepam::doc\_gen::generate__ \-format HTML \-header\_footer tepam::doc\_gen::generate The documentation can directly be stored in a file\. The file header and footer are automatically generated in this way: > __tepam::doc\_gen::generate__ \-format HTML \-dest\_file doc\_gen\.html tepam::doc\_gen::generate The generated HTML file refers a CSS stylesheet file \(default: tepam\_doc\_stylesheet\.css\)\. To display the HTML file correctly this CSS stylesheet file needs to be copied into the directory of the generated HTML file\. The Tcl DOC Tools format can be used as intermediate format to generate other formats, for example HTML: > *\# Generate the documentation in Tcl Doc Tool format* > set dt \[__tepam::doc\_gen::generate__ \-format DT \-header\_footer tepam::doc\_gen::generate\] > ** > *\# Create a new doc tools object \(HTML format\)* > package require doctools > ::doctools::new myDoc \-format html > ** > *\# Open the HTML file, and write the HTML formatted documentation* > set fHtml \[open doc\_gen\.dt\.html w\] > puts $fHtml \[myDoc format $dt\] > close $fHtml ## <a name='subsection6'></a>tepam::doc\_gen::patch While __generate__ provides a limited number of possibilities to vary the document structure, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ offers more flexibility\. Multiple documentations for different procedures and meta information can for example be added\. |
︙ | ︙ | |||
534 535 536 537 538 539 540 | > __\{\*tepam::doc\_gen::generate\*\}__ > <h2>Patch</h2> > __\{\*tepam::doc\_gen::patch\*\}__ > </body> > <html>\\ > \} > ** | | | > | < | 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 | > __\{\*tepam::doc\_gen::generate\*\}__ > <h2>Patch</h2> > __\{\*tepam::doc\_gen::patch\*\}__ > </body> > <html>\\ > \} > ** > *\# Patch the master document: This will replace the placeholders by the * > *\# procedure documentation divisions:* > > __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\ > \-src\_string $HtmlMasterDoc \-dest\_file tepam\_doc\_gen\.html # <a name='seealso'></a>SEE ALSO [tepam\(n\)](tepam\_introduction\.md), [tepam::procedure\(n\)](tepam\_procedure\.md) # <a name='keywords'></a>KEYWORDS |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/tepam/tepam_introduction.md.
︙ | ︙ | |||
145 146 147 148 149 150 151 | > \{\-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"\} > \} > \} \{ | | | | | | | | | 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | > \{\-fg \-type color \-default black \-description "Message color"\} > \{\-bg \-type color \-optional \-description "Background color"\} > \{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\} > \{\-log\_file \-type file \-optional \-description "Optional message log file"\} > \{text \-type string \-multiple \-description "Multiple text lines to display"\} > \} > \} \{ > *puts "display message:"* > *foreach var \{mtype font level fg bg no\_border log\_file text\} \{* > *if \{\[info exists $var\]\} \{* > *puts " $var=\[set $var\]"* > *\}* > *\}* > \} A call of procedure that has been declared in this way will first invoke the TEPAM argument manager, before the procedure body is executed\. The argument manager parses the provided arguments, validates them, completes them eventually with some default values, and makes them finally available to the procedure body as local variables\. In case an argument is missing or has a wrong type, the argument manager generates an error message that explains the reason for the |
︙ | ︙ | |||
202 203 204 205 206 207 208 | # <a name='section4'></a>PROCEDURE HELP The declared procedure can simply be called with the *\-help* option to get the information about the usage of the procedure and its arguments: > __display message__ \-help | | | | > > > | > | > | > | > > > | > | > > | | | | | | | | > | | | | | | | > | | | | | | > | | | > > > | > | < | > | < < | | > | < < | > | < < | < < | | | 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 | # <a name='section4'></a>PROCEDURE HELP The declared procedure can simply be called with the *\-help* option to get the information about the usage of the procedure and its arguments: > __display message__ \-help > *\->* > *NAME* > *display message \- Displays a simple message box* > *SYNOPSYS* > *display message* > *\[\-mtype <mtype>\] :* > *Message type, default: "Warning", choices: \{Info Warning Error\}* > *\[\-font <font>\] :* > *Message text font, type: font, default: Arial 10 italic* > *\[\-level <level>\] :* > *Message level, type: integer, range: 1\.\.10* > *\[\-fg <fg>\] :* > *Message color, type: color, default: black* > *\[\-bg <bg>\] :* > *Background color, type: color* > *\[\-no\_border \] :* > *Use a splash window style \(no border\)* > *\[\-log\_file <log\_file>\] :* > *Optional message log file, type: file* > *<text> :* > *Multiple text lines to display, type: string* > *DESCRIPTION* > *This procedure allows displaying a configurable message box\.* # <a name='section5'></a>PROCEDURE CALL The specified procedure can be called in many ways\. The following listing shows some valid procedure calls: > __display message__ "The document hasn't yet been saved\!" > *\-> display message:* > *mtype=Warning* > *font=Arial 10 italic* > *fg=black* > *no\_border=0* > *text=\{The document hasn't yet been saved\!\}* > > > __display message__ \-fg red \-bg black "Please save first the document" > *\-> display message:* > *mtype=Warning* > *font=Arial 10 italic* > *fg=red* > *bg=black* > *no\_border=0* > *text=\{Please save first the document\}* > > > __display message__ \-mtype Error \-no\_border "Why is here no border?" > *\-> display message:* > *mtype=Error* > *font=Arial 10 italic* > *fg=black* > *no\_border=1* > *text=\{Why is here no border?\}* > > > __display message__ \-font \{Courier 12\} \-level 10 \\ > "Is there enough space?" "Reduce otherwise the font size\!" > *\-> display message:* > *mtype=Warning* > *font=Courier 12* > *level=10* > *fg=black* > *no\_border=0* > *text=\{Is there enough space?\} \{Reduce otherwise the font size\!\}* The next lines show how wrong arguments are recognized\. The *text* argument that is mandatory is missing in the first procedure call: > __display message__ \-font \{Courier 12\} > *\-> display message: Required argument is missing: text* Only known arguments are accepted: > __display message__ \-category warning Hello > *\-> display message: Argument '\-category' not known* Argument types are automatically checked and an error message is generated in case the argument value has not the expected type: > __display message__ \-fg MyColor "Hello" > *\-> display message: Argument 'fg' requires type 'color'\. Provided value: 'MyColor'* Selection choices have to be respected \.\.\. > __display message__ \-mtype Fatal Hello > *\-> display message: Argument \(mtype\) has to be one of the following elements: Info, Warning, Error* \.\.\. as well as valid value ranges: > __display message__ \-level 12 Hello > *\-> display message: Argument \(level\) has to be between 1 and 10* # <a name='section6'></a>INTERACTIVE PROCEDURE CALLS The most intuitive way to call the procedure is using an form that allows specifying all arguments interactively\. This form will automatically be generated if the declared procedure is called with the *\-interactive* flag\. To use this feature the Tk library has to be loaded\. > __display message__ \-interactive The generated form contains for each argument a data entry widget that is adapted to the argument type\. Check buttons are used to specify flags, radio boxes for tiny choice lists, disjoint list boxes for larger choice lists and files, directories, fonts and colors can be selected with dedicated browsers\. After acknowledging the specified argument data via an OK button, the entered |
︙ | ︙ | |||
324 325 326 327 328 329 330 | 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\} \\ | | | 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 | 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 |
︙ | ︙ | |||
389 390 391 392 393 394 395 | > __\-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__ \{\} \\ | | | | | | | | | | | | | | | < < | > > | > > > | > > | > > | > | > | | 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 | > __\-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"\} \{ > puts "Canceled" > \} else \{ \# $Result=="ok" > puts "Arguments: " > foreach Var \{ > Entry1 Entry2 > Listbox1 Listbox2 DisJntListbox > Combobox Checkbox Radiobox Checkbutton > InputFile OutputFile InputDirectory OutputDirectory > Color Font > \} \{ > puts " $Var: '\[set $Var\]'" > \} > \} > *\-> Arguments:* > *Entry1: 'Hello, this is a trial'* > *Entry2: 'my default'* > *Listbox1: '1'* > *Listbox2: '\{Choice 2\} \{Choice 3\}'* > *DisJntListbox: '\{Choice 3\} \{Choice 5\}'* > *Combobox: '3'* > *Checkbox: 'italic'* > *Radiobox: 'underline'* > *Checkbutton: '1'* > *InputFile: 'c:\\tepam\\in\.txt'* > *OutputFile: 'c:\\tepam\\out\.txt'* > *InputDirectory: 'c:\\tepam\\input'* > *OutputDirectory: 'c:\\tepam\\output'* > *Color: 'red'* > *Font: 'Courier 12 italic'* # <a name='seealso'></a>SEE ALSO [tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md), [tepam::procedure\(n\)](tepam\_procedure\.md) # <a name='keywords'></a>KEYWORDS |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/tepam/tepam_procedure.md.
︙ | ︙ | |||
109 110 111 112 113 114 115 | The __string__ command is an example of such a command that implements for example subcommands to check a character string length, to compare strings, to extract substrings, etc: > __string length__ *string* > __string compare__ *string* *string* > __string range__ *string* *first* *last* | | | | < | | 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | The __string__ command is an example of such a command that implements for example subcommands to check a character string length, to compare strings, to extract substrings, etc: > __string length__ *string* > __string compare__ *string* *string* > __string range__ *string* *first* *last* > \.\.\. TEPAM provides a framework that allows implementing easily such subcommands in form of Tcl procedures\. It allows not only defining a first level of subcommands, but also a higher level of subcommands\. The __string__ command class check could be implemented as independent sub\-sub\-commands of the __string__ command: > __string is alnum__ *string* > __string is integer__ *string* > __string is double__ *string* > \.\.\. - *Procedure attribute* TEPAM allows attaching to a declared procedure different kind of attributes\. Some of these attributes are *just* used for documentation purposes, but other attributes specify the way how the procedure has to be called\. Also the procedure arguments are defined in form of a procedure attribute\. - *Argument* TEPAM uses the term *argument* for the parameters of a procedure\. The following example calls the subcommand __string compare__ with several arguments: > __string compare__ *\-nocase \-length 3 "emphasized" "emphasised"* The following paragraphs discuss these different argument types\. - *Named argument* Some parameters, as *\-length 3* of the subcommand __string compare__ have to be provided as pairs of argument names and argument values\. This parameter type is often also called *option*\. |
︙ | ︙ | |||
181 182 183 184 185 186 187 | - *Named arguments first, unnamed arguments later* The __string compare__ command of the previous example requires that the *named arguments* \(options, flags\) are provided first\. The two mandatory \(unnamed\) arguments have to be provided as last argument\. | | | | | | | | < | 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 | - *Named arguments first, unnamed arguments later* The __string compare__ command of the previous example requires that the *named arguments* \(options, flags\) are provided first\. The two mandatory \(unnamed\) arguments have to be provided as last argument\. > __string compare__ *\-nocase \-length 3 Water $Text* This is the usual Tcl style \(exceptions exist\) which is referred in the TEPAM documentation as *named arguments first, unnamed arguments later style*\. - *Unnamed arguments first, named arguments later* In contrast to most Tcl commands, Tk uses generally \(exceptions exist also here\) a different calling style where the *unnamed arguments* have to be provided first, before the *named arguments* have to be provided: > __pack__ *\.ent1 \.ent2 \-fill x \-expand yes \-side left* This style is referred in the TEPAM documentation as *unnamed arguments first, named arguments later style*\. # <a name='section3'></a>PROCEDURE DECLARATION TEPAM allows declaring new Tcl procedures with the command __tepam::procedure__ that has similar to the standard Tcl command __proc__ also 3 arguments: |
︙ | ︙ | |||
229 230 231 232 233 234 235 | > \-default Warning \-description "Message type"\} > \{text \-type string \-multiple \\ > \-description "Multiple text lines to display"\} > \} > \} \{ > puts "Message type: $mtype" > puts "Message: $text" | | | 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 | > \-default Warning \-description "Message type"\} > \{text \-type string \-multiple \\ > \-description "Multiple text lines to display"\} > \} > \} \{ > puts "Message type: $mtype" > puts "Message: $text" > \} The 3 arguments of __procedure__ are: - *name* The procedure name can be used in very flexible ways\. Procedure names can have namespace qualifiers\. By providing a two element name list as procedure |
︙ | ︙ | |||
254 255 256 257 258 259 260 | > *\# Procedure declared in the main namespace:* > tepam::procedure __::display\_message__ \{\} \{\} > ** > *\# Procedure in the namespace* __::ns__*:* > tepam::procedure __::ns::display\_message__ \{\} \{\} > ** > *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:* | | | 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 | > *\# Procedure declared in the main namespace:* > tepam::procedure __::display\_message__ \{\} \{\} > ** > *\# Procedure in the namespace* __::ns__*:* > tepam::procedure __::ns::display\_message__ \{\} \{\} > ** > *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:* > tepam::procedure __\{display message\}__ \{\} \{\} - *attributes* All procedure attributes are provided in form of an option list that contains pairs of option names and option values\. The example above has as procedure attribute a short and a normal description, but also the procedure arguments are defined in form of a procedure attribute\. |
︙ | ︙ | |||
292 293 294 295 296 297 298 | > \-args \{ > \{\-__mtype__ \-default Warning \-choices \{Warning Error\}\} > \{__text__ \-type string\} > \} > \} \{ > puts "Message type: __$mtype__" > puts "Message: __$text__" | | | | 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 | > \-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__ |
︙ | ︙ | |||
368 369 370 371 372 373 374 | Validation command declaration example: > tepam::procedure \{display\_message\} \{ > \-args \{ > \{text \-type string \-description "Message text"\} \} > __\-validatecommand \{IllegalWordDetector $text\}__ > \} \{ | | | 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 | Validation command declaration example: > tepam::procedure \{display\_message\} \{ > \-args \{ > \{text \-type string \-description "Message text"\} \} > __\-validatecommand \{IllegalWordDetector $text\}__ > \} \{ > \} The validation command is executed in the context of the declared procedure body\. The different argument values are accessed via the argument names\. Note there is also an argument attribute *\-validatecommand* that allows declaring custom checks for specific arguments\. The attribute *\-validatecommand* can be repeated to declare multiple |
︙ | ︙ | |||
434 435 436 437 438 439 440 | ## <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\} \{ | | | | | | | | | > | | | | | | > | | 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 | ## <a name='subsection2'></a>Argument Declaration The following example shows the structure that is used for the argument definitions in the context of a procedure declaration: > tepam::procedure \{display\_message\} \{ > \-args __\{__ > __\{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}__ > __\{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}__ > __\{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}__ > __\{\-fg \-type color \-optional \-description "Message color"\}__ > __\{\-log\_file \-type file \-optional \-description "Optional message log file"\}__ > __\{text \-type string \-multiple \-description "Multiple text lines to display"\}__ > __\}__ > > \} \{ > \} Each of the procedure arguments is declared with a list that has as first element the argument name, followed by eventual attributes\. The argument definition syntax can be formalized in the following way: > tepam::procedure <name> \{ > \-args __\{__ > __\{<argument\_name\_1> <arg\_attr\_name\_1a> <arg\_attr\_value\_1a> <arg\_attr\_name\_1b> <arg\_attr\_value\_1b> \.\.\.\}__ > __\{<argument\_name\_2> <arg\_attr\_name\_2a> <arg\_attr\_value\_2a> <arg\_attr\_name\_2b> <arg\_attr\_value\_2b> \.\.\.\}__ > __\.\.\.__ > __\}__ > > \} <body> The argument names and attributes have to be used in the following way: - Argument name \(*<argument\_name\_<n>>*\) The provided argument name specifies whether the argument is an *unnamed argument* or a *named argument*\. In addition to this, an argument name |
︙ | ︙ | |||
482 483 484 485 486 487 488 | > \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\} > \} > \} \{ > puts __$text__ > \} > > print\_string __"Hello"__ | < < | < < | | 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 | > \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\} > \} > \} \{ > puts __$text__ > \} > > print\_string __"Hello"__ > *\-> Hello* * *"\-<Name>"* An argument whose name starts with '\-' is a *named argument* \(also called *option*\)\. The parameter provided during a procedure call will be assigned to a variable with the name *<Name>* \(not *\-<Name>*\)\. > tepam::procedure \{print\_string\} \{ > \-args \{ > \{__\-text__ \-type string \-description "This is a named argument"\} > \} > \} \{ > puts __$text__ > \} > > print\_string __\-text "Hello"__ > *\-> Hello* * *"\-\-"* This flag allows clearly specifying the end of the named arguments and the beginning of the unnamed arguments, in case the *named arguments first, unnamed arguments later style \(Tcl\)* has been selected\. |
︙ | ︙ | |||
533 534 535 536 537 538 539 | > > __\{\- 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\]" | | | 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 | > > __\{\- 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\. * *"\#\*"* |
︙ | ︙ | |||
562 563 564 565 566 567 568 | > > __\{\#\#\#\# 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\] | | | 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 | > > __\{\#\#\#\# 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* |
︙ | ︙ | |||
658 659 660 661 662 663 664 | Validation command declaration example: > tepam::procedure \{display\_message\} \{ > \-args \{ > \{text \-type string \-description "Message text" \\ > __\-validatecommand \{IllegalWordDetector %P\}__\} > \} \{ | | | 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 | Validation command declaration example: > tepam::procedure \{display\_message\} \{ > \-args \{ > \{text \-type string \-description "Message text" \\ > __\-validatecommand \{IllegalWordDetector %P\}__\} > \} \{ > \} While the purpose of this custom argument validation attribute is the validation of a specific argument, there is also a global attribute *\-validatecommand* that allows performing validation that involves multiple arguments\. * \-validatecommand\_error\_text *string* |
︙ | ︙ | |||
700 701 702 703 704 705 706 | > tepam::procedure LoadPicture \{ > \-args \{ > \{FileName \-type existingfile \-description "Picture file" \\ > __\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\} > \} > \} \{ | | | 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 | > tepam::procedure LoadPicture \{ > \-args \{ > \{FileName \-type existingfile \-description "Picture file" \\ > __\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\} > \} > \} \{ > \} * \-auxargs\_commands *script* If the auxiliary argument attributes are not static but have to be dynamically adaptable, the *\-auxargs\_commands* allows defining them via commands that are executed during a procedure call\. A list of pairs of auxiliary attribute names and commands has to be provided to the |
︙ | ︙ | |||
819 820 821 822 823 824 825 | > \{\-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"\} > \} > \} \{ > \.\.\. | | | 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 | > \{\-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 |
︙ | ︙ | |||
842 843 844 845 846 847 848 | > puts __$flag__ > \} > > flag\_test > *\-> 0* > > flag\_test \-flag | < < | | 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 | > puts __$flag__ > \} > > flag\_test > *\-> 0* > > flag\_test \-flag > *\-> 1* Since no argument value has to be provided to a flag, also no data check is performed for this argument type\. - __string__ __String__ is a generic argument data type\. Any data string can be provided to a string type argument and no data type checks are therefore performed\. The string type allows defining single line strings |
︙ | ︙ | |||
872 873 874 875 876 877 878 | Several *numerical types* are defined by TEPAM\. The type validation procedures are using the __string is <type> \-strict__ commands to check the validity of the provided arguments, which assures that no empty strings are accepted as argument value\. The type validation expression for the numerical types and the argument types to which this expression is applied are: | | < < | < < | 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 | Several *numerical types* are defined by TEPAM\. The type validation procedures are using the __string is <type> \-strict__ commands to check the validity of the provided arguments, which assures that no empty strings are accepted as argument value\. The type validation expression for the numerical types and the argument types to which this expression is applied are: > string is __<type\_to\_check>__ \-strict *<argument\_value>* - *boolean* - *integer* - *double* Empty strings are accepted as argument value for all the alpha numeric argument types\. The argument types that are falling into this category and validation expression used for them are: > string is *<type\_to\_check>* *<argument\_value>* - *alnum* - *alpha* - *ascii* |
︙ | ︙ | |||
922 923 924 925 926 927 928 | In addition to the data types checked with the __string is <type>__ commands, TEPAM specifies some other useful data types: - *char* Each string that has a length of 1 character meets the *character* type\. The type check is made with the following expression: | | | < < | < < | < < | 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 | In addition to the data types checked with the __string is <type>__ commands, TEPAM specifies some other useful data types: - *char* Each string that has a length of 1 character meets the *character* type\. The type check is made with the following expression: > expr \[string length *<argument\_value>*\]==1 - *color* Any character strings that are accepted by Tk as a color are considered as valid color argument\. Please note that the Tk package has to be loaded to use the type *color*\. TEPAM is using the following command to validate the color type: > expr \!\[catch \{winfo rgb \. *<argument\_value>*\}\] - *font* Any character strings that are accepted by Tk as a font are considered as valid font argument\. Please note that the Tk package has to be loaded to use the *font* type\. TEPAM is using the following command to validate the color type: expr ![catch {font measure <argument_value> ""}] - *file* Any strings that are not containing one of the following characters are considered as valid file names: \* ? " < >\. It is not necessary that the file and its containing directory exist\. Zero\-length strings are not considered as valid file names\. The following expression is used to validate the file names: expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>] - *existingfile* The argument is valid if it matches with an existing file\. The following check is performed to validate the arguments of this type: file exists <argument_value> - *directory* The directory argument is validated exactly in the same way as |
︙ | ︙ | |||
997 998 999 1000 1001 1002 1003 | print a generated help text to *stdout* and will then return without performing any additional actions\. Taking the first procedure declared in [PROCEDURE CALLS](#section6), the help request and the printed help text would be: > __display message \-help__ | | | | > > > | > | > | | > | > > > | | | | > | < | | | > | | | | | < < | 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 | print a generated help text to *stdout* and will then return without performing any additional actions\. Taking the first procedure declared in [PROCEDURE CALLS](#section6), the help request and the printed help text would be: > __display message \-help__ > *\->* > *NAME* > *display message \- Displays a simple message box* > *SYNOPSIS* > *display message* > *\[\-mtype <mtype>\]* > *Message type, default: "Warning", choices: \{Info, Warning, Error\}* > *<text>* > *Multiple text lines to display, type: string* > *DESCRIPTION* > *This procedure allows displaying a configurable message box\. The default* > *message type that is created is a warning, but also errors and info can* > *be generated\.* > *The procedure accepts multiple text lines\.* > *EXAMPLE* > *display message \-mtype Warning "Save first your job"* The argument manager is checking if the last provided argument is *\-help* and generates the requested help message if this is the case\. So, also the following example will print the help message: > __display message \-mtype Info "It is 7:00" \-help__ On the other hand, the following call will result in an error: > __display message \-help \-mtype Info "It is 7:00"__ > *\->* > *display message: Argument '\-help' not known* ## <a name='subsection6'></a>Interactive Procedure Call If Tk has been loaded a procedure can be called with the *\-interactive* flag to open a graphical form that allows specifying interactively all procedure arguments\. The following example assures that the Tk library is loaded and shows the command line to call interactively the procedure declared in [PROCEDURE CALLS](#section6): > package require Tk > __display message \-interactive__ Also the *\-interactive* flag has to be placed at the last argument position as this is also required for the *\-help* flag\. Arguments defined before the *\-interactive* flag will be ignored\. The following example is therefore also a valid interactive procedure call: > __display message__ \-mtype Info "It is 7:00" __\-interactive__ ## <a name='subsection7'></a>Unnamed Arguments Unnamed arguments are typically provided to the called procedure as simple parameters\. This procedure calling form requires that the provided arguments are strictly following the order of the specified arguments\. Several parameters can be assigned to the last argument if this one has the *\-multiple* attribute\. |
︙ | ︙ | |||
1059 1060 1061 1062 1063 1064 1065 | \.\.\. can for example be called in the following ways: > __display\_message Info "It is PM 7:00\."__ > *\-> Info: It is PM 7:00\.* > > __display\_message Info "It is PM 7:00\." "You should go home\."__ | | < | | > < < | | 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 | \.\.\. can for example be called in the following ways: > __display\_message Info "It is PM 7:00\."__ > *\-> Info: It is PM 7:00\.* > > __display\_message Info "It is PM 7:00\." "You should go home\."__ > *\-> Info: It is PM 7:00\. You should go home\.* The nice thing is that unnamed arguments can also be called as named arguments, which can be handy, for example if the exact specified argument order is not known to a user: > __display\_message \-mtype Info \-text "It is PM 7:00\."__ > *\-> Info: It is PM 7:00\.* > > __display\_message \-text "It is PM 7:00\." \-mtype Info__ > *\-> Info: It is PM 7:00\.* > > __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ > *\-> Info: It is PM 7:00\. You should go home\.* > > __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ > *\-> Info: It is PM 7:00\. You should go home\.* ## <a name='subsection8'></a>Named Arguments Named arguments have to be provided to a procedure in form of a parameter pairs composed by the argument names and the argument values\. The order how they are provided during a procedure call is irrelevant and has not to match with the argument specification order\. |
︙ | ︙ | |||
1109 1110 1111 1112 1113 1114 1115 | > __display\_message \-text "It is PM 7:00\." \-mtype Info__ > *\-> Info: It is PM 7:00\.* > > __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ > *\-> Info: It is PM 7:00\. You should go home\.* > > __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ | | < | | < < | | | < | | > | < | | | < > | < < | | | | | < < | | | < | | | | > < | | | | | < > | < | | | | > | < < | | | | > < > | < | | > | < | < > | < < | | > > | < | | < < | < < | | 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 | > __display\_message \-text "It is PM 7:00\." \-mtype Info__ > *\-> Info: It is PM 7:00\.* > > __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ > *\-> Info: It is PM 7:00\. You should go home\.* > > __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ > *\-> Info: It is PM 7:00\. You should go home\.* Also named arguments that have not the *\-multiple* attribute can be provided multiple times\. Only the last provided argument will be retained in such a case: > __display\_message \-mtype Info \-text "It is PM 7:00\." \-mtype Warning__ > *\-> Warning: It is PM 7:00\.* ## <a name='subsection9'></a>Unnamed Arguments First, Named Arguments Later \(Tk Style\) A procedure that has been defined while the variable __tepam::named\_arguments\_first__ was set to 1, or with the procedure attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\. The following procedure declaration will be used in this section to illustrate the meaning of this calling style: > __set tepam::named\_arguments\_first 1__ > tepam::procedure my\_proc \{ > \-args \{ > \{\-n1 \-default ""\} > \{\-n2 \-default ""\} > \{u1 \-default ""\} > \{u2 \-default ""\} > \} > \} \{ > puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" > \} The unnamed arguments are placed at the end of procedure call, after the named arguments: > my\_proc __\-n1 N1 \-n2 N2 U1 U2__ > *\-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'* The argument parser considers the first argument that doesn't start with the '\-' character as well as all following arguments as unnamed argument: > my\_proc __U1 U2__ > *\-> n1:'', n2:'', u1:'U1', u2:'U2'* Named arguments can be defined multiple times\. If the named argument has the *\-multiply* attribute, all argument values will be collected in a list\. Otherwise, only the last provided attribute value will be retained: > my\_proc __\-n1 N1 \-n2 N2 \-n1 M1 U1 U2__ > *\-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'* The name of the first unnamed argument has therefore not to start with the '\-' character\. The unnamed argument is otherwise considered as name of another named argument\. This is especially important if the first unnamed argument is given by a variable that can contain any character strings: > my\_proc __\-n1 N1 \-n2 N2 "\->" "<\-"__ > *\-> my\_proc: Argument '\->' not known* > > set U1 "\->" > my\_proc __\-n1 N1 \-n2 N2 $U1 U2__ > my\_proc: Argument '\->' not known The '\-\-' flag allows separating unambiguously the unnamed arguments from the named arguments\. All data after the '\-\-' flag will be considered as unnamed argument: > my\_proc __\-n1 N1 \-n2 N2 \-\- "\->" "<\-"__ > *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'* > > set U1 "\->" > my\_proc __\-n1 N1 \-n2 N2 \-\- $U1 U2__ > *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'* ## <a name='subsection10'></a>Named Arguments First, Unnamed Arguments Later \(Tcl Style\) The Tk calling style will be chosen if a procedure is defined while the variable __tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute *\-named\_arguments\_first* has been set to 0\. The following procedure will be used in this section to illustrate this calling style: > __set tepam::named\_arguments\_first 0__ > tepam::procedure my\_proc \{ > \-args \{ > \{\-n1 \-default ""\} > \{\-n2 \-default ""\} > \{u1\} > \{u2 \-default "" \-multiple\} > \} > \} \{ > puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" > \} The unnamed arguments have to be provided first in this case\. The named arguments are provided afterwards: > my\_proc __U1 U2 \-n1 N1 \-n2 N2__ > *\-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* The argument parser will assign to each defined unnamed argument a value before it switches to read the named arguments\. This default behavior changes a bit if there are unnamed arguments that are optional or that can take multiple values\. An argument value will only be assigned to an unnamed argument that is optional \(that has either the *\-optional* attribute or that has a default value\), if the value is not beginning with the '\-' character or if no named arguments are defined\. The value that starts with '\-' is otherwise considered as the name of a named argument\. Argument values are assigned to an argument that has the *\-multiple* attribute as long as the parameter value doesn't starts with the '\-' character\. Values that start with the '\-' character can therefore not be assigned to optional unnamed arguments, which restricts the usage of the Tcl procedure calling style\. The Tk style may be preferable in some cases, since it allows separating unambiguously the named arguments from the unnamed ones with the '\-\-' flag\. Let's explore in a bit less theoretically the ways how the previously defined procedure can be called: The first example calls the procedure without any parameters, which leads to an error since *u1* is a mandatory argument: > my\_proc > *\-> my\_proc: Required argument is missing: u1* The procedure call is valid if one parameter is provided for *u1*: > my\_proc __U1__ > *\-> n1:'', n2:'', u1:'U1', u2:''* If more parameters are provided that are not starting with the '\-' character, they will be attributed to the unnamed arguments\. *U2* will receive 3 of these parameters, since it accepts multiple values: > my\_proc __U1 U2 U3 U4__ > *\-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'* As soon as one parameter starts with '\-' and all unnamed arguments have been assigned, the argument manager tries to interpret the parameter as name of a named argument\. The procedure call will fail if a value beginning with '\-' is assigned to an unnamed argument: > my\_proc __U1 U2 U3 U4 \-U5__ > *\-> my\_proc: Argument '\-U5' not known* The attribution of a parameter to a named argument will fail if there are undefined unnamed \(non optional\) arguments\. The name specification will in this case simply be considered as a parameter value that is attributed to the *next* unnamed argument\. This was certainly not the intention in the following example: > my\_proc __\-n1 N1__ > *\-> n1:'', n2:'', u1:'\-n1', u2:'N1'* The situation is completely different if values have already been assigned to all mandatory unnamed arguments\. A parameter beginning with the '\-' character will in this case be considered as a name identifier for a named argument: > my\_proc __U1 \-n1 N1__ > *\-> n1:'N1', n2:'', u1:'U1', u2:''* No unnamed arguments are allowed behind the named arguments: > my\_proc __U1 \-n1 N1 U2__ > *\-> my\_proc: Argument 'U2' is not an option* The '\-\-' flag has no special meaning if not all mandatory arguments have got assigned a value\. This flag will simply be attributed to one of the unnamed arguments: > my\_proc __\-\- \-n1 N1__ > *\-> n1:'N1', n2:'', u1:'\-\-', u2:''* But the '\-\-' flag is simply ignored if the argument parser has started to handle the named arguments: > my\_proc __U1 \-\- \-n1 N1__ > *\-> n1:'N1', n2:'', u1:'U1', u2:''* > > my\_proc __U1 \-n1 N1 \-\- \-n2 N2__ > *\-> n1:'N1', n2:'N2', u1:'U1', u2:''* ## <a name='subsection11'></a>Raw Argument List It may be necessary sometimes that the procedure body is able to access the entire list of arguments provided during a procedure call\. This can happen via the __args__ variable that contains always the unprocessed argument list: > tepam::procedure \{display\_message\} \{ > \-args \{ > \{\-mtype \-choices \{Warning Error\} \-default Warning\} > \{text \-type string \-multiple\} > > \} > \} \{ > puts "args: __$args__" > \} > display\_message \-mtype Warning "It is 7:00" > *\-> args: \-mtype Warning \{It is 7:00\}* # <a name='seealso'></a>SEE ALSO [tepam\(n\)](tepam\_introduction\.md), [tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md) # <a name='keywords'></a>KEYWORDS |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/textutil/expander.md.
︙ | ︙ | |||
126 127 128 129 130 131 132 | The command creates a new expander object with an associated Tcl command whose name is *expanderName*\. This command may be used to invoke various operations on the graph\. If the *expanderName* is not fully qualified it is interpreted as relative to the current namespace\. The command has the following general form: | | < | 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | The command creates a new expander object with an associated Tcl command whose name is *expanderName*\. This command may be used to invoke various operations on the graph\. If the *expanderName* is not fully qualified it is interpreted as relative to the current namespace\. The command has the following general form: > *expanderName* option ?*arg arg \.\.\.*? *Option* and the *arg*s determine the exact behavior of the command\. The following commands are possible for expander objects: - <a name='2'></a>*expanderName* __cappend__ *text* |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/try/tcllib_throw.md.
︙ | ︙ | |||
51 52 53 54 55 56 57 | - <a name='1'></a>__::throw__ *error\_code* *error\_message* throw is merely a reordering of the arguments of the error command\. It throws an error with the indicated error code and error message\. # <a name='section2'></a>EXAMPLES | | < | 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | - <a name='1'></a>__::throw__ *error\_code* *error\_message* throw is merely a reordering of the arguments of the error command\. It throws an error with the indicated error code and error message\. # <a name='section2'></a>EXAMPLES > __throw__ \{MYERROR CODE\} "My error message" # <a name='section3'></a>Bugs, Ideas, Feedback This document, and the package it describes, will undoubtedly contain bugs and other problems\. Please report such in the category *try* of the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas for enhancements you may have for either package and/or documentation\. |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/try/tcllib_try.md.
︙ | ︙ | |||
112 113 114 115 116 117 118 | > set f \[open /some/file/name a\] > __try__ \{ > puts \\$f "some message" > \# \.\.\. > \} __finally__ \{ > close \\$f | | < | < | 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 | > set f \[open /some/file/name a\] > __try__ \{ > puts \\$f "some message" > \# \.\.\. > \} __finally__ \{ > close \\$f > \} Handle different reasons for a file to not be openable for reading: > __try__ \{ > set f \[open /some/file/name\] > \} __trap__ \{POSIX EISDIR\} \{\} \{ > puts "failed to open /some/file/name: it's a directory" > \} __trap__ \{POSIX ENOENT\} \{\} \{ > puts "failed to open /some/file/name: it doesn't exist" > \} # <a name='section3'></a>Bugs, Ideas, Feedback This document, and the package it describes, will undoubtedly contain bugs and other problems\. Please report such in the category *try* of the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas for enhancements you may have for either package and/or documentation\. |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/units/units.md.
︙ | ︙ | |||
178 179 180 181 182 183 184 | 30second 30.0 second 30 second 30.0 second 30 seconds 30.0 second 200*meter/20.5*second 9.75609756098 meter / second # <a name='section4'></a>SI UNITS | | | | | | 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | 30second 30.0 second 30 second 30.0 second 30 seconds 30.0 second 200*meter/20.5*second 9.75609756098 meter / second # <a name='section4'></a>SI UNITS The standard SI units are predefined according to *NIST Special* *Publication 330* \. Standard units for both SI Base Units \(Table 1\) and SI Derived Units with Special Names \(Tables 3a and 3b\) are included here for reference\. Each standard unit name and abbreviation are included in this package\. ## <a name='subsection2'></a>SI Base Units Quantity Unit Name Abbr. --------------------------------------------- Length meter m Mass kilogram kg |
︙ | ︙ | |||
235 236 237 238 239 240 241 | \(kelvins\) to absolute degrees Celsius or Farenheit\. Conversion of thermodynamic quantities, such as thermal expansion \(per unit temperature\), however, are easy to add to the units library\. SI Units can have a multiple or sub\-multiple prefix\. The prefix or its abbreviation should appear before the unit, without spaces\. Compound prefixes are not allowed, and a prefix should never be used alone\. These prefixes are | | | 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 | \(kelvins\) to absolute degrees Celsius or Farenheit\. Conversion of thermodynamic quantities, such as thermal expansion \(per unit temperature\), however, are easy to add to the units library\. SI Units can have a multiple or sub\-multiple prefix\. The prefix or its abbreviation should appear before the unit, without spaces\. Compound prefixes are not allowed, and a prefix should never be used alone\. These prefixes are defined in Table 5 of *Special Publication* *330* \. ## <a name='subsection4'></a>SI Prefixes Prefix Name Abbr. Factor --------------------------------------- yotta Y 1e24 zetta Z 1e21 |
︙ | ︙ | |||
337 338 339 340 341 342 343 | types \(e\.g\., *typedef float Length*\), and target units \(expected by the C application code\) are specified in an associative array\. Default units are also defined for each quantity type, and are applied to any unit\-less quantity strings\. A units system enhanced with quantity type checking might benefit from inclusion of other derived types which are expressed in terms of special units, as | | | | | | | | 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 | types \(e\.g\., *typedef float Length*\), and target units \(expected by the C application code\) are specified in an associative array\. Default units are also defined for each quantity type, and are applied to any unit\-less quantity strings\. A units system enhanced with quantity type checking might benefit from inclusion of other derived types which are expressed in terms of special units, as illustrated in Table 2 of *NIST Publication* *330* \. The quantity *area*, for example, could be defined as units properly reducing to *meter^2*, although the utility of defining a unit named *square meter* is arguable\. # <a name='section5'></a>REFERENCES The unit names, abbreviations, and conversion values are derived from those published by the United States Department of Commerce Technology Administration, National Institute of Standards and Technology \(NIST\) in *NIST Special Publication 330: The International System of* *Units \(SI\)* and *NIST Special Publication 811: Guide for* *the Use of the International System of Units \(SI\)* \. Both of these publications are available \(as of December 2000\) from [http://physics\.nist\.gov/cuu/Reference/contents\.html](http://physics\.nist\.gov/cuu/Reference/contents\.html) The ideas behind implementation of this package is based in part on code written in 1993 by Adrian Mariano which performed dimensional analysis of unit strings using fixed size tables of C structs\. After going missing in the late 1990's, Adrian's code has reappeared in the GNU Units program at [http://www\.gnu\.org/software/units/](http://www\.gnu\.org/software/units/) |
︙ | ︙ |
Changes to embedded/md/tcllib/files/modules/zip/mkzip.md.
︙ | ︙ | |||
58 59 60 61 62 63 64 | particularly on Windows the __info\-zip__ and the Windows built\-in zip view have rather poor support for this part of the ZIP file specification\. The __7\-Zip__ program does correctly display utf8 filenames however and the __vfs::zip__ package will use these of course\. If you use | | | 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 | particularly on Windows the __info\-zip__ and the Windows built\-in zip view have rather poor support for this part of the ZIP file specification\. The __7\-Zip__ program does correctly display utf8 filenames however and the __vfs::zip__ package will use these of course\. If you use > __::mkzip::mkzip__ mystuff\.tm \-zipkit \-directory mystuff\.vfs it will pack your "mystuff\.vfs/" virtual filesystem tree into a zip archive with a suitable header such that on unix you may mark it executable and it should run with tclkit\. Or you can run it with __tclsh__ or __wish__ 8\.6 if you like\. To change the executable header, specify the __\-runtime__ "preface" |
︙ | ︙ |
Changes to idoc/man/files/modules/doctools/doctools.n.
1 2 3 4 | '\" '\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net> '\" | | | 1 2 3 4 5 6 7 8 9 10 11 12 | '\" '\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net> '\" .TH "doctools" n 1\&.5\&.5 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, |
︙ | ︙ | |||
272 273 274 275 276 277 278 | .. .BS .SH NAME doctools \- doctools - Processing documents .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp | | | 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 | .. .BS .SH NAME doctools \- doctools - Processing documents .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp package require \fBdoctools ?1\&.5\&.5?\fR .sp \fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.? .sp \fB::doctools::help\fR .sp \fB::doctools::search\fR \fIpath\fR .sp |
︙ | ︙ |
Changes to idoc/www/tcllib/files/modules/doctools/doctools.html.
︙ | ︙ | |||
103 104 105 106 107 108 109 | | <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"> | | | 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | | <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.5 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> |
︙ | ︙ | |||
133 134 135 136 137 138 139 | <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> | | | 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | <li class="doctools_section"><a href="#copyright">Copyright</a></li> </ul> </div> <div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> <div class="doctools_synopsis"> <ul class="doctools_requirements"> <li>package require <b class="pkgname">Tcl 8.2</b></li> <li>package require <b class="pkgname">doctools <span class="opt">?1.5.5?</span></b></li> </ul> <ul class="doctools_syntax"> <li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li> <li><a href="#2"><b class="cmd">::doctools::help</b></a></li> <li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li> <li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li> <li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li> |
︙ | ︙ |
Changes to modules/doctools/checker.tcl.
︙ | ︙ | |||
612 613 614 615 616 617 618 | } set pid $sect($fid) } } } # If we have no text take the section title as text, if we | | | 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 | } set pid $sect($fid) } } } # If we have no text take the section title as text, if we # can. Last fallback for text is the id. if {$title == {}} { if {$pid != {}} { set title $sectt($fid) } else { set title $id } } |
︙ | ︙ |
Changes to modules/doctools/doctools.man.
1 | [comment {-*- tcl -*- doctools manpage}] | | | 1 2 3 4 5 6 7 8 9 | [comment {-*- tcl -*- doctools manpage}] [vset PACKAGE_VERSION 1.5.5] [manpage_begin doctools n [vset PACKAGE_VERSION]] [see_also doctools_intro] [see_also doctools_lang_cmdref] [see_also doctools_lang_intro] [see_also doctools_lang_syntax] [see_also doctools_plugin_apiref] [keywords conversion] |
︙ | ︙ |
Changes to modules/doctools/doctools.tcl.
︙ | ︙ | |||
1354 1355 1356 1357 1358 1359 1360 | # => 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]} } | | | 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.5 |
Changes to modules/doctools/mpformats/_markdown.tcl.
︙ | ︙ | |||
30 31 32 33 34 35 36 | proc Sub4Title {lb title} { upvar 1 $lb lines lappend lines "[Hash][Hash][Hash][Hash] $title" return } | | | | 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | proc Sub4Title {lb title} { upvar 1 $lb lines lappend lines "[Hash][Hash][Hash][Hash] $title" return } proc _Strong {text} { return [Undr][Undr]${text}[Undr][Undr] } proc _Em {text} { return [Star]${text}[Star] } ## # # ## ### ##### ######## ## set __comments 0 |
︙ | ︙ |
Changes to modules/doctools/mpformats/_text.tcl.
︙ | ︙ | |||
117 118 119 120 121 122 123 | upvar 1 $lb lines #lappend lines "" lappend lines $title lappend lines [RepeatM - $title] return } | > > > | | > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | upvar 1 $lb lines #lappend lines "" lappend lines $title lappend lines [RepeatM - $title] return } proc Strong {text} { SplitLine $text _Strong } proc Em {text} { SplitLine $text _Em } proc _Strong {text} { return *${text}* } proc _Em {text} { return _${text}_ } proc SplitLine {text cmd} { #puts_stderr AAA/SLI=[string map [list \1 \\1 \t \\t { } \\s] <<[join [split $text \n] >>\n<<]>>] if {![string match *\n* $text]} { foreach {lead content} [LeadSplit $text] break return ${lead}[uplevel 1 [list $cmd $content]] } set r {} foreach line [split $text \n] { foreach {lead content} [LeadSplit $line] break if {$content == {}} { lappend r {} continue } lappend r ${lead}[uplevel 1 [list $cmd $content]] } set text [string trimright [join $r \n]]\n #puts_stderr AAA/SLE=[string map [list \1 \\1 \t \\t { } \\s] <<[join [split $text \n] >>\n<<]>>] return $text } proc LeadSplit {line} { regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _ list $lead $content } # # ## ### ##### ######## ## Bulleting # # itembullet = index of the bullet to use in the next itemized list # enumbullet = index of the bullet to use in the next enumerated list |
︙ | ︙ |
Changes to modules/doctools/mpformats/_text_para.tcl.
︙ | ︙ | |||
20 21 22 23 24 25 26 | return } proc Text? {} { global __currentp ; return $__currentp } proc TextClear {} { global __currentp ; set __currentp "" } proc TextTrimLeadingSpace {} { global __currentp | | > > > > > > > < < > > | 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | return } proc Text? {} { global __currentp ; return $__currentp } proc TextClear {} { global __currentp ; set __currentp "" } proc TextTrimLeadingSpace {} { global __currentp regsub {^([ \t\v\f]*\x01?\n)*} $__currentp {} __currentp return } proc TextTrimTrailingSpace {} { global __currentp regsub {([ \t\v\f]*\x01?\n)*$} $__currentp {} __currentp append __currentp \n return } proc TextPlain {text} { if {[IsOff]} {return} # Note: Whenever we get plain text it is possible that a macro for # visual markup actually generated output before the expander got # to the current text. This output was captured by the expander in # its current context. Given the current organization of the # engine we have to retrieve this formatted text from the expander # or it will be lost. This is the purpose of the 'ctopandclear', # which retrieves the data and also clears the capture buffer. The # latter to prevent us from retrieving it again later, after the # next macro added more data. set text [ex_ctopandclear]$text #puts_stderr "<<text_plain_text>>=<<[string map [list \t \\t { } \\s \n \\n \r \\r \v \\v \f \\f \1 \\1] $text]>>" # ... TODO ... Handling of example => verbatim if {[string length [string trim $text]] == 0} return Text $text return |
︙ | ︙ |
Changes to modules/doctools/mpformats/fmt.markdown.
︙ | ︙ | |||
388 389 390 391 392 393 394 395 396 397 398 399 400 401 | regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _ # Drop trailing spaces, make leading non-breaking, keep content (and inner spaces). return [RepeatM " " $lead]$content } c_pass 2 fmt_example_end {} { #puts_stderr "AAA/fmt_example_end" TextTrimLeadingSpace # Check for protected markdown markup in the input. If present # this is a complex example with highlighted parts. set complex [string match *\1* [Text?]] #puts_stderr "AAA/fmt_example_end/$complex" | > > > | 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 | regexp {^([ \t]*)(.*)([ \t]*)$} $line -> lead content _ # Drop trailing spaces, make leading non-breaking, keep content (and inner spaces). return [RepeatM " " $lead]$content } c_pass 2 fmt_example_end {} { #puts_stderr "AAA/fmt_example_end" # Flush markup from preceding commands into the text buffer. TextPlain "" TextTrimLeadingSpace # Check for protected markdown markup in the input. If present # this is a complex example with highlighted parts. set complex [string match *\1* [Text?]] #puts_stderr "AAA/fmt_example_end/$complex" |
︙ | ︙ | |||
414 415 416 417 418 419 420 421 422 423 424 425 426 427 | set t [join [Breaks [LeadSpaces [split $t \n]]] {}] } else { # Process for code block (verbatim) set t [Mark $t] } TextClear Text $t set penv [GetCurrent] if {$penv != {}} { # In a list we save the current list context, activate the # proper paragraph context and create its example # variant. After closing the paragraph using the example we # restore and reactivate the list context. | > | 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | set t [join [Breaks [LeadSpaces [split $t \n]]] {}] } else { # Process for code block (verbatim) set t [Mark $t] } TextClear Text $t TextTrimTrailingSpace set penv [GetCurrent] if {$penv != {}} { # In a list we save the current list context, activate the # proper paragraph context and create its example # variant. After closing the paragraph using the example we # restore and reactivate the list context. |
︙ | ︙ |
Changes to modules/doctools/mpformats/fmt.text.
︙ | ︙ | |||
461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 | #puts_stderr "AAA/fmt_example_begin/Done" return } c_pass 1 fmt_example_end {} NOP c_pass 2 fmt_example_end {} { #puts_stderr "AAA/fmt_example_end" TextTrimLeadingSpace # Look for and convert continuation lines protected from Tcl # substitution into a regular continuation line. set t [string map [list \\\\\n \\\n] [Text?]] TextClear Text $t set penv [GetCurrent] if {$penv != {}} { # In a list we save the current list context, activate the # proper paragraph context and create its example # variant. After closing the paragraph using the example we # restore and reactivate the list context. ContextPush | > > > > > > > | 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 | #puts_stderr "AAA/fmt_example_begin/Done" return } c_pass 1 fmt_example_end {} NOP c_pass 2 fmt_example_end {} { #puts_stderr "AAA/fmt_example_end" #puts_stderr AAA/EIN=[string map [list \1 \\1 \t \\t { } \\s] <<[join [split [Text?] \n] >>\n<<]>>] # Flush markup from preceding commands into the text buffer. TextPlain "" TextTrimLeadingSpace # Look for and convert continuation lines protected from Tcl # substitution into a regular continuation line. set t [string map [list \\\\\n \\\n] [Text?]] TextClear Text $t #puts_stderr AAA/EFT=[string map [list \1\\1 \t \\t { } \\s] <<[join [split [Text?] \n] >>\n<<]>>] set penv [GetCurrent] if {$penv != {}} { # In a list we save the current list context, activate the # proper paragraph context and create its example # variant. After closing the paragraph using the example we # restore and reactivate the list context. ContextPush |
︙ | ︙ |
Changes to modules/doctools/pkgIndex.tcl.
1 | if {![package vsatisfies [package provide Tcl] 8.2]} {return} | | | 1 2 3 4 5 6 | if {![package vsatisfies [package provide Tcl] 8.2]} {return} package ifneeded doctools 1.5.5 [list source [file join $dir doctools.tcl]] package ifneeded doctools::toc 1.2 [list source [file join $dir doctoc.tcl]] package ifneeded doctools::idx 1.1 [list source [file join $dir docidx.tcl]] package ifneeded doctools::cvs 1 [list source [file join $dir cvs.tcl]] package ifneeded doctools::changelog 1.1 [list source [file join $dir changelog.tcl]] |
Added modules/doctools/tests/fmt/desc/27.
Added modules/doctools/tests/fmt/html/27.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | <!DOCTYPE html><html><head> <title>TEST - </title> <style type="text/css"><!-- HTML { background: #FFFFFF; color: black; } BODY { background: #FFFFFF; color: black; } DIV.doctools { margin-left: 10%; margin-right: 10%; } DIV.doctools H1,DIV.doctools H2 { margin-left: -5%; } H1, H2, H3, H4 { margin-top: 1em; font-family: sans-serif; font-size: large; color: #005A9C; background: transparent; text-align: left; } H1.doctools_title { text-align: center; } UL,OL { margin-right: 0em; margin-top: 3pt; margin-bottom: 3pt; } UL LI { list-style: disc; } OL LI { list-style: decimal; } DT { padding-top: 1ex; } UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { font: normal 12pt/14pt sans-serif; list-style: none; } LI.doctools_section, LI.doctools_subsection { list-style: none; margin-left: 0em; text-indent: 0em; padding: 0em; } PRE { display: block; font-family: monospace; white-space: pre; margin: 0%; padding-top: 0.5ex; padding-bottom: 0.5ex; padding-left: 1ex; padding-right: 1ex; width: 100%; } PRE.doctools_example { color: black; background: #f5dcb3; border: 1px solid black; } UL.doctools_requirements LI, UL.doctools_syntax LI { list-style: none; margin-left: 0em; text-indent: 0em; padding: 0em; } DIV.doctools_synopsis { color: black; background: #80ffff; border: 1px solid black; font-family: serif; margin-top: 1em; margin-bottom: 1em; } UL.doctools_syntax { margin-top: 1em; border-top: 1px solid black; } UL.doctools_requirements { margin-bottom: 1em; border-bottom: 1px solid black; } --></style> </head> <!-- Generated from file '.FILE.' by tcllib/doctools with format 'html' --> <!-- Copyright &copy; .COPYRIGHT. --> <!-- TEST.T --> <body><div class="doctools"> <h1 class="doctools_title">TEST(T) 0 .MODULE. ""</h1> <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> <p>TEST -</p> </div> <div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> <ul class="doctools_toc"> <li class="doctools_section"><a href="#toc">Table Of Contents</a></li> <li class="doctools_section"><a href="#section1">Description</a></li> <li class="doctools_section"><a href="#copyright">Copyright</a></li> </ul> </div> <div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> <p>= = == === ===== ======== =============</p> <pre class="doctools_example">[<b class="cmd">bar</b> \ foo]</pre> <p>= = == === ===== ======== =============</p> <pre class="doctools_example"> <em> many lines highlighted </em> </pre> <p>= = == === ===== ======== =============</p> </div> <div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> <p>Copyright © .COPYRIGHT.</p> </div> </div></body></html> |
Added modules/doctools/tests/fmt/latex/27.
> > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | % Generated from file '.FILE.' by tcllib/doctools with format 'latex' % Copyright (c) .COPYRIGHT. % TEST.T \documentclass{article} \usepackage{alltt} \begin{document} \author{aku} \title{.MODULE. / TEST -- : } \maketitle \section{Description}\label{section1} = = == === ===== ======== ============= \begin{alltt} [{\bf bar} \textbackslash foo]\end{alltt} = = == === ===== ======== ============= \begin{alltt} {\it many lines highlighted } \end{alltt} = = == === ===== ======== ============= \section{Copyright}\label{copyright} \begin{flushleft} Copyright (c) .COPYRIGHT.\linebreak \end{flushleft} \end{document} |
Added modules/doctools/tests/fmt/list/27.
> | 1 | manpage {seealso {} keywords {} file .FILE. section T category {} module .MODULE. version 0 title TEST shortdesc {} desc {} fid .FILE} |
Changes to modules/doctools/tests/fmt/man/25.
|
| | | 1 2 3 4 5 6 7 | [comment { -- Example 2 }] [manpage_begin TEST z 3.14.15.926] [description] [example { Special markdown __non-special__ }] [manpage_end] |
Changes to modules/doctools/tests/fmt/man/26.
|
| | | 1 2 3 4 5 6 7 8 | [comment { -- Example 3 }] [manpage_begin TEST z 3.14.15.926] [description] [example { Example Block \ More Lines \\ Ever More Never |
︙ | ︙ |
Added modules/doctools/tests/fmt/man/27.
> > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 | [comment { -- Example 4 }] [manpage_begin TEST T 0] [description] = = == === ===== ======== ============= [example_begin][lb][cmd bar] \ foo[rb][example_end] = = == === ===== ======== ============= [example_begin] [emph { many lines highlighted }] [example_end] = = == === ===== ======== ============= [manpage_end] |
Changes to modules/doctools/tests/fmt/markdown/26.
︙ | ︙ | |||
27 28 29 30 31 32 33 | Second \ Continuing Lines \ Done \.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\. > __command__ x \\ | | < | 27 28 29 30 31 32 33 34 35 36 37 38 | Second \ Continuing Lines \ Done \.\.\.\.\.\.\.\.\.\.\.\.\.\.\. Vorwaerts \.\.\.\.\.\.\.\.\.\. > __command__ x \\ > \-\- __command__ \-\- # <a name='copyright'></a>COPYRIGHT Copyright © \.COPYRIGHT\. |
Added modules/doctools/tests/fmt/markdown/27.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | [//000000001]: # (TEST \- ) [//000000002]: # (Generated from file '\.FILE\.' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © \.COPYRIGHT\.) [//000000004]: # (TEST\(T\) 0 \.MODULE\. "") # NAME TEST \- # <a name='toc'></a>Table Of Contents - [Table Of Contents](#toc) - [Description](#section1) - [Copyright](#copyright) # <a name='description'></a>DESCRIPTION = = == === ===== ======== ============= > \[__bar__ \\ > foo\] = = == === ===== ======== ============= > *many lines* > *highlighted* = = == === ===== ======== ============= # <a name='copyright'></a>COPYRIGHT Copyright © \.COPYRIGHT\. |
Added modules/doctools/tests/fmt/nroff/27.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | '\" '\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' '\" Copyright (c) \&.COPYRIGHT\&. '\" .TH "TEST" T 0 \&.MODULE\&. "" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, .\" and indent is equivalent to second arg of .IP (shouldn't ever be .\" needed; use .AS below instead) .\" .\" .AS ?type? ?name? .\" Give maximum sizes of arguments for setting tab stops. Type and .\" name are examples of largest possible arguments that will be passed .\" to .AP later. If args are omitted, default tab stops are used. .\" .\" .BS .\" Start box enclosure. From here until next .BE, everything will be .\" enclosed in one large box. .\" .\" .BE .\" End of box enclosure. .\" .\" .CS .\" Begin code excerpt. .\" .\" .CE .\" End code excerpt. .\" .\" .VS ?version? ?br? .\" Begin vertical sidebar, for use in marking newly-changed parts .\" of man pages. The first argument is ignored and used for recording .\" the version when the .VS was added, so that the sidebars can be .\" found and removed when they reach a certain age. If another argument .\" is present, then a line break is forced before starting the sidebar. .\" .\" .VE .\" End of vertical sidebar. .\" .\" .DS .\" Begin an indented unfilled display. .\" .\" .DE .\" End of indented unfilled display. .\" .\" .SO ?manpage? .\" Start of list of standard options for a Tk widget. The manpage .\" argument defines where to look up the standard options; if .\" omitted, defaults to "options". The options follow on successive .\" lines, in three columns separated by tabs. .\" .\" .SE .\" End of list of standard options for a Tk widget. .\" .\" .OP cmdName dbName dbClass .\" Start of description of a specific option. cmdName gives the .\" option's name as specified in the class command, dbName gives .\" the option's name in the option database, and dbClass gives .\" the option's class in the option database. .\" .\" .UL arg1 arg2 .\" Print arg1 underlined, then print arg2 normally. .\" .\" .QW arg1 ?arg2? .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). .\" .\" .PQ arg1 ?arg2? .\" Print an open parenthesis, arg1 in quotes, then arg2 normally .\" (for trailing punctuation) and then a closing parenthesis. .\" .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b .\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ta \\n()Au \\n()Bu .ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. .\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out .\" # BS - start boxed text .\" # ^y = starting y location .\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. .\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. .\" # VS - start vertical sidebar .\" # ^Y = starting y location .\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"\\$2"" .br .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. .\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. .\" # Special macro to handle page bottom: finish off current .\" # box/sidebar if in box/sidebar mode, then invoked standard .\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. .\" # DS - begin display .de DS .RS .nf .sp .. .\" # DE - end display .de DE .fi .RE .sp .. .\" # SO - start of list of standard options .de SO 'ie '\\$1'' .ds So \\fBoptions\\fR 'el .ds So \\fB\\$1\\fR .SH "STANDARD OPTIONS" .LP .nf .ta 5.5c 11c .ft B .. .\" # SE - end of list of standard options .de SE .fi .ft R .LP See the \\*(So manual entry for details on the standard options. .. .\" # OP - start of full description for a single option .de OP .LP .nf .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi .IP .. .\" # CS - begin code excerpt .de CS .RS .nf .ta .25i .5i .75i 1i .. .\" # CE - end code excerpt .de CE .fi .RE .. .\" # UL - underline word .de UL \\$1\l'|0\(ul'\\$2 .. .\" # QW - apply quotation marks to word .de QW .ie '\\*(lq'"' ``\\$1''\\$2 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\$2 .. .\" # PQ - apply parens and quotation marks to word .de PQ .ie '\\*(lq'"' (``\\$1''\\$2)\\$3 .\"" fix emacs highlighting .el (\\*(lq\\$1\\*(rq\\$2)\\$3 .. .\" # QR - quoted range .de QR .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 .. .\" # MT - "empty" string .de MT .QW "" .. .BS .SH NAME TEST \- .SH DESCRIPTION = = == === ===== ======== ============= .CS [\fBbar\fR \\ foo] .CE = = == === ===== ======== ============= .CS \fI many lines highlighted \fR .CE = = == === ===== ======== ============= .SH COPYRIGHT .nf Copyright (c) \&.COPYRIGHT\&. .fi |
Added modules/doctools/tests/fmt/null/27.
Added modules/doctools/tests/fmt/text/27.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | TEST - Generated from file '.FILE.' by tcllib/doctools with format 'text' TEST(T) 0 .MODULE. "" NAME ==== TEST - DESCRIPTION =========== = = == === ===== ======== ============= | [bar \ | foo] = = == === ===== ======== ============= | _many lines_ | _highlighted_ = = == === ===== ======== ============= COPYRIGHT ========= Copyright (c) .COPYRIGHT. |
Added modules/doctools/tests/fmt/tmml/27.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 'tmml' --> <manpage id='.FILE' cat='cmd' title='TEST' version='0' package='.MODULE.'> <head> <info key='copyright' value='Copyright (c) .COPYRIGHT.'/> </head> <namesection> <name>TEST</name> <desc></desc> </namesection> <section id='section1'> <title>DESCRIPTION</title> = = == === ===== ======== ============= <example>[<cmd>bar</cmd> \ foo] </example> = = == === ===== ======== ============= <example> <emph> many lines highlighted </emph> </example> = = == === ===== ======== ============= </section> </manpage> |
Added modules/doctools/tests/fmt/wiki/27.
> > > > > > > > > > > > > > > > > > > > > > > > > | 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 | '''TEST 0''' '''.MODULE.''' **DESCRIPTION** = = == === ===== ======== ============= ====== ['''bar''' \ foo] ====== = = == === ===== ======== ============= ====== '' many lines highlighted '' ====== = = == === ===== ======== ============= **COPYRIGHT** Copyright (c) .COPYRIGHT. |