Tcl Library Source Code

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

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

Overview
Comment:Doctools: - Extended testsuite, nesting of different list types. - Fixed issues in text/markdown engines with this kind of nesting. (Context creation did not clear inherited type markers, and paragraph handling took def markers over other list markers) Regenerated package docs (version, bump, fixes making changes) Version bump - doctools 1.5.1 B (text, markdown) T (text, markdown)
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 3ddb294ff05af1c5992db8a69dab0cc1e36a126e116240851afc09314a3b464f
User & Date: aku 2019-03-29 04:14:49
Context
2019-04-10
20:46
Doctools: - Extended testsuite, markdown special character example. - Fixed issue in markdown engine with handling of its special characters in verbatim blocks. Should not emit them as quoted, they are not special in such blocks. Regenerated package docs (version bump & fixes making changes) Version bump - doctools 1.5.2 B (markdown) T (markdown) check-in: c74461e613 user: aku tags: trunk
2019-04-08
07:19
Begin adding argparse package check-in: ef01ec1300 user: andy tags: amg-argparse
2019-03-29
04:16
Brought md list fixes into the work on the guides check-in: d821fa1849 user: aku tags: doc-overhaul
04:14
Doctools: - Extended testsuite, nesting of different list types. - Fixed issues in text/markdown engines with this kind of nesting. (Context creation did not clear inherited type markers, and paragraph handling took def markers over other list markers) Regenerated package docs (version, bump, fixes making changes) Version bump - doctools 1.5.1 B (text, markdown) T (text, markdown) check-in: 3ddb294ff0 user: aku tags: trunk
2019-03-22
19:19
Brought markdown doctools work into the trunk. check-in: 11efa65aed user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to embedded/md/tcllib/files/modules/amazon-s3/xsxp.md.

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
  - <a name='1'></a>__xsxp::parse__ *xml*

    This parses an XML document \(using the standard xml tcllib module in a SAX
    sort of way\) and builds a data structure which it returns if the parsing
    succeeded\. The return value is referred to herein as a "pxml", or "parsed
    xml"\. The list consists of two or more elements:

    The first element is the name of the tag\.

    The second element is an array\-get formatted list of key/value pairs\. The
    keys are attribute names and the values are attribute values\. This is an
    empty list if there are no attributes on the tag\.

    The third through end elements are the children of the node, if any\. Each
    child is, recursively, a pxml\.

    Note that if the zero'th element, i\.e\. the tag name, is "%PCDATA", then the
    attributes will be empty and the third element will be the text of the
    element\. In addition, if an element's contents consists only of PCDATA, it
    will have only one child, and all the PCDATA will be concatenated\. In other
    words, this parser works poorly for XML with elements that contain both
    child tags and PCDATA\. Since Amazon S3 does not do this \(and for that matter
    most uses of XML where XML is a poor choice don't do this\), this is probably
    not a serious limitation\.

  - <a name='2'></a>__xsxp::fetch__ *pxml* *path* ?*part*?

    *pxml* is a parsed XML, as returned from xsxp::parse\. *path* is a list
    of element tag names\. Each element is the name of a child to look up,
    optionally followed by a hash \("\#"\) and a string of digits\. An empty list or
    an initial empty element selects *pxml*\. If no hash sign is present, the






|

|
|
|

|
|

|
|
|
|
|
|
|
|







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
  - <a name='1'></a>__xsxp::parse__ *xml*

    This parses an XML document \(using the standard xml tcllib module in a SAX
    sort of way\) and builds a data structure which it returns if the parsing
    succeeded\. The return value is referred to herein as a "pxml", or "parsed
    xml"\. The list consists of two or more elements:

      * The first element is the name of the tag\.

      * The second element is an array\-get formatted list of key/value pairs\.
        The keys are attribute names and the values are attribute values\. This
        is an empty list if there are no attributes on the tag\.

      * The third through end elements are the children of the node, if any\.
        Each child is, recursively, a pxml\.

      * Note that if the zero'th element, i\.e\. the tag name, is "%PCDATA", then
        the attributes will be empty and the third element will be the text of
        the element\. In addition, if an element's contents consists only of
        PCDATA, it will have only one child, and all the PCDATA will be
        concatenated\. In other words, this parser works poorly for XML with
        elements that contain both child tags and PCDATA\. Since Amazon S3 does
        not do this \(and for that matter most uses of XML where XML is a poor
        choice don't do this\), this is probably not a serious limitation\.

  - <a name='2'></a>__xsxp::fetch__ *pxml* *path* ?*part*?

    *pxml* is a parsed XML, as returned from xsxp::parse\. *path* is a list
    of element tag names\. Each element is the name of a child to look up,
    optionally followed by a hash \("\#"\) and a string of digits\. An empty list or
    an initial empty element selects *pxml*\. If no hash sign is present, the

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

65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
    Note that while the encoder will generate only uppercase characters this
    decoder accepts input in lowercase as well\.

    The command will always throw an error whenever encountering conditions
    which signal some type of bogus input, namely if

    the input contains characters which are not valid output of a base32
    encoder,

    the length of the input is not a multiple of eight,

    padding appears not at the end of input, but in the middle,

    the padding has not of length six, four, three, or one characters,

# <a name='section3'></a>Code map

The code map used to convert 5\-bit sequences is shown below, with the numeric id
of the bit sequences to the left and the character used to encode it to the
right\. It should be noted that the characters "0" and "1" are not used by the
encoding\. This is done as these characters can be easily confused with "O", "o"






|
|

|

|

|







65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
    Note that while the encoder will generate only uppercase characters this
    decoder accepts input in lowercase as well\.

    The command will always throw an error whenever encountering conditions
    which signal some type of bogus input, namely if

      1. the input contains characters which are not valid output of a base32
         encoder,

      1. the length of the input is not a multiple of eight,

      1. padding appears not at the end of input, but in the middle,

      1. the padding has not of length six, four, three, or one characters,

# <a name='section3'></a>Code map

The code map used to convert 5\-bit sequences is shown below, with the numeric id
of the bit sequences to the left and the character used to encode it to the
right\. It should be noted that the characters "0" and "1" are not used by the
encoding\. This is done as these characters can be easily confused with "O", "o"

Changes to embedded/md/tcllib/files/modules/base32/base32core.md.

71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
    valid *string*, and __False__ otherwise\. In the latter case an error
    message describing the problem with the input is stored into the variable
    named by *mvar*\. The variable is not touched if the input was found to be
    valid\.

    The rules checked by the command, beyond rejection of bad characters, are:

    The length of the input is not a multiple of eight,

    The padding appears not at the end of input, but in the middle,

    The padding has not of length six, four, three, or one characters,

# <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 *base32* 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\.






|

|

|







71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
    valid *string*, and __False__ otherwise\. In the latter case an error
    message describing the problem with the input is stored into the variable
    named by *mvar*\. The variable is not touched if the input was found to be
    valid\.

    The rules checked by the command, beyond rejection of bad characters, are:

      1. The length of the input is not a multiple of eight,

      1. The padding appears not at the end of input, but in the middle,

      1. The padding has not of length six, four, three, or one characters,

# <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 *base32* 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/base32/base32hex.md.

66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
    Note that while the encoder will generate only uppercase characters this
    decoder accepts input in lowercase as well\.

    The command will always throw an error whenever encountering conditions
    which signal some type of bogus input, namely if

    the input contains characters which are not valid output of a extended hex
    base32 encoder,

    the length of the input is not a multiple of eight,

    padding appears not at the end of input, but in the middle,

    the padding has not of length six, four, three, or one characters,

# <a name='section3'></a>Code map

The code map used to convert 5\-bit sequences is shown below, with the numeric id
of the bit sequences to the left and the character used to encode it to the
right\. The important feature of the extended hex mapping is that the first 16
codes map to the digits and hex characters\.






|
|

|

|

|







66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
    Note that while the encoder will generate only uppercase characters this
    decoder accepts input in lowercase as well\.

    The command will always throw an error whenever encountering conditions
    which signal some type of bogus input, namely if

      1. the input contains characters which are not valid output of a extended
         hex base32 encoder,

      1. the length of the input is not a multiple of eight,

      1. padding appears not at the end of input, but in the middle,

      1. the padding has not of length six, four, three, or one characters,

# <a name='section3'></a>Code map

The code map used to convert 5\-bit sequences is shown below, with the numeric id
of the bit sequences to the left and the character used to encode it to the
right\. The important feature of the extended hex mapping is that the first 16
codes map to the digits and hex characters\.

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

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
    Formally the results for the various types of bee\-values are:

      * string

        A list containing three elements:

        The constant string __string__, denoting the type of the value\.

        An integer number greater than or equal to zero\. This is the index of
        the first character of the bee\-value in the input *string*\.

        An integer number greater than or equal to zero\. This is the index of
        the last character of the bee\-value in the input *string*\.

        *Note* that this information is present in the results for all four
        types of bee\-values, with only the first element changing according to
        the type of the value\.

      * integer







|

|
|

|
|







140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
    Formally the results for the various types of bee\-values are:

      * string

        A list containing three elements:

          + The constant string __string__, denoting the type of the value\.

          + An integer number greater than or equal to zero\. This is the index
            of the first character of the bee\-value in the input *string*\.

          + An integer number greater than or equal to zero\. This is the index
            of the last character of the bee\-value in the input *string*\.

        *Note* that this information is present in the results for all four
        types of bee\-values, with only the first element changing according to
        the type of the value\.

      * integer

Changes to embedded/md/tcllib/files/modules/cache/async.md.

86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    not yet known the command prefix specified during construction of the cache
    object is used to ask for this information\.

    Whenever the information is/becomes available the *donecmdprefix* will be
    run to transfer the result to the caller\. This command prefix is invoked
    with either 2 or 3 arguments, i\.e\.

    The string __set__, the *key*, and the value\.

    The string __unset__, and the *key*\.

    These two possibilities are used to either signal the value for the *key*,
    or that the *key* has no value defined for it\. The latter is distinct from
    the cache not knowing about the *key*\.

    For a cache object configured to be fully asynchronous \(default\) the
    *donecmdprefix* is always run in an idle\-handler, decoupling it from the






|

|







86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    not yet known the command prefix specified during construction of the cache
    object is used to ask for this information\.

    Whenever the information is/becomes available the *donecmdprefix* will be
    run to transfer the result to the caller\. This command prefix is invoked
    with either 2 or 3 arguments, i\.e\.

      1. The string __set__, the *key*, and the value\.

      1. The string __unset__, and the *key*\.

    These two possibilities are used to either signal the value for the *key*,
    or that the *key* has no value defined for it\. The latter is distinct from
    the cache not knowing about the *key*\.

    For a cache object configured to be fully asynchronous \(default\) the
    *donecmdprefix* is always run in an idle\-handler, decoupling it from the

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

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
...
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
    result, as is if the script caused the error\. Any other return will evaluate
    the script in *buffer* as normal\. For compatibility with 3\.2,
    __break__ and __return \-code break__ *result* is supported, acting
    similarly to __return \{\}__ and __return \-code return__ *result*\.

    Examples:

    augmenting a command

    % ::comm::comm send \[::comm::comm self\] pid
    5013
    % ::comm::comm hook eval \{puts "going to execute $buffer"\}
    % ::comm::comm send \[::comm::comm self\] pid
    going to execute pid
    5013

    short circuiting a command

    % ::comm::comm hook eval \{puts "would have executed $buffer"; return 0\}
    % ::comm::comm send \[::comm::comm self\] pid
    would have executed pid
    0

    Replacing double eval semantics

    % ::comm::comm send \[::comm::comm self\] llength \{a b c\}
    wrong \# args: should be "llength list"
    % ::comm::comm hook eval \{return \[uplevel \#0 $buffer\]\}
    return \[uplevel \#0 $buffer\]
    % ::comm::comm send \[::comm::comm self\] llength \{a b c\}
    3

    Using a slave interpreter

    % interp create foo
    % ::comm::comm hook eval \{return \[foo eval $buffer\]\}
    % ::comm::comm send \[::comm::comm self\] set myvar 123
    123
    % set myvar
    can't read "myvar": no such variable
    % foo eval set myvar
    123

    Using a slave interpreter \(double eval\)

    % ::comm::comm hook eval \{return \[eval foo eval $buffer\]\}

    Subverting the script to execute

    % ::comm::comm hook eval \{
        switch \-\- $buffer \{
            a \{return A\-OK\}
            b \{return B\-OK\}
            default \{error "$buffer is a no\-no"\}
        \}
................................................................................
    __return\(\)__\.

    This hook is invoked after collecting a complete reply script from a remote
    but *before* evaluating it\. This allows complete control over the
    processing of replies to sent commands\. The reply *buffer* is in one of
    the following forms

    return result

    return \-code code result

    return \-code code \-errorinfo info \-errorcode ecode msg

    For safety reasons, this is decomposed\. The return result is in *ret*, and
    the return switches are in the return array:

    *return\(\-code\)*

    *return\(\-errorinfo\)*

    *return\(\-errorcode\)*

    Any of these may be the empty string\. Modifying these four variables can
    change the return value, whereas modifying *buffer* has no effect\.

  - __callback__

    Variables: __chan__, __id__, __buffer__, __ret__, and






|








|






|








|










|



|







 







|

|

|




|

|

|







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
...
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
    result, as is if the script caused the error\. Any other return will evaluate
    the script in *buffer* as normal\. For compatibility with 3\.2,
    __break__ and __return \-code break__ *result* is supported, acting
    similarly to __return \{\}__ and __return \-code return__ *result*\.

    Examples:

      1. augmenting a command

    % ::comm::comm send \[::comm::comm self\] pid
    5013
    % ::comm::comm hook eval \{puts "going to execute $buffer"\}
    % ::comm::comm send \[::comm::comm self\] pid
    going to execute pid
    5013

      1. short circuiting a command

    % ::comm::comm hook eval \{puts "would have executed $buffer"; return 0\}
    % ::comm::comm send \[::comm::comm self\] pid
    would have executed pid
    0

      1. Replacing double eval semantics

    % ::comm::comm send \[::comm::comm self\] llength \{a b c\}
    wrong \# args: should be "llength list"
    % ::comm::comm hook eval \{return \[uplevel \#0 $buffer\]\}
    return \[uplevel \#0 $buffer\]
    % ::comm::comm send \[::comm::comm self\] llength \{a b c\}
    3

      1. Using a slave interpreter

    % interp create foo
    % ::comm::comm hook eval \{return \[foo eval $buffer\]\}
    % ::comm::comm send \[::comm::comm self\] set myvar 123
    123
    % set myvar
    can't read "myvar": no such variable
    % foo eval set myvar
    123

      1. Using a slave interpreter \(double eval\)

    % ::comm::comm hook eval \{return \[eval foo eval $buffer\]\}

      1. Subverting the script to execute

    % ::comm::comm hook eval \{
        switch \-\- $buffer \{
            a \{return A\-OK\}
            b \{return B\-OK\}
            default \{error "$buffer is a no\-no"\}
        \}
................................................................................
    __return\(\)__\.

    This hook is invoked after collecting a complete reply script from a remote
    but *before* evaluating it\. This allows complete control over the
    processing of replies to sent commands\. The reply *buffer* is in one of
    the following forms

      * return result

      * return \-code code result

      * return \-code code \-errorinfo info \-errorcode ecode msg

    For safety reasons, this is decomposed\. The return result is in *ret*, and
    the return switches are in the return array:

      * *return\(\-code\)*

      * *return\(\-errorinfo\)*

      * *return\(\-errorcode\)*

    Any of these may be the empty string\. Modifying these four variables can
    change the return value, whereas modifying *buffer* has no effect\.

  - __callback__

    Variables: __chan__, __id__, __buffer__, __ret__, and

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

1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5 tcllib "Documentation tools")

<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../../toc.md">Table Of Contents</a> &#124; <a
href="../../../../index.md">Keyword Index</a> &#124; <a
href="../../../../toc0.md">Categories</a> &#124; <a
href="../../../../toc1.md">Modules</a> &#124; <a
href="../../../../toc2.md">Applications</a> ] <hr>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

# <a name='synopsis'></a>SYNOPSIS

package require Tcl 8\.2  
package require doctools ?1\.5?  

[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1)  
[__::doctools::help__](#2)  
[__::doctools::search__ *path*](#3)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#4)  
[*objectName* __configure__](#5)  
[*objectName* __configure__ *option*](#6)  



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5\.1 tcllib "Documentation tools")

<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../../toc.md">Table Of Contents</a> &#124; <a
href="../../../../index.md">Keyword Index</a> &#124; <a
href="../../../../toc0.md">Categories</a> &#124; <a
href="../../../../toc1.md">Modules</a> &#124; <a
href="../../../../toc2.md">Applications</a> ] <hr>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

# <a name='synopsis'></a>SYNOPSIS

package require Tcl 8\.2  
package require doctools ?1\.5\.1?  

[__::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/doctools2idx/export_docidx.md.

149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
...
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
...
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
...
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
...
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_container.md.

326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
...
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
...
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
...
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
...
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_export.md.

356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
...
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
...
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
...
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
...
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_export_html.md.

247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
...
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
...
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
...
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
...
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_export_json.md.

156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
...
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
...
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
...
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
...
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_export_nroff.md.

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
...
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
...
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_export_text.md.

95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_export_wiki.md.

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
...
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
...
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_import.md.

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
...
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
...
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
...
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

         A boolean flag indicating the success \(__True__\) or failure
         \(__False__\) of the operation\.

         In case of success the contents of the included file, and the empty
         string otherwise\.

         The resolved, i\.e\. absolute path of the included file, if possible, or
         the unchanged *path* argument\. This is for display in an error
         message, or as the *currentfile* argument of another call to
         __IncludeFile__ should this file contain more files\.

         In case of success an empty string, and for failure a code indicating
         the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

         An empty string in case of success of a __notfound__ failure, and
         an additional error message describing the reason for a __notread__
         error in more detail\.

  1. A plugin has to provide one command, with the signature shown below\.

       - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*

         Whenever an import manager of
         __[doctools::idx](idx\_container\.md)__ has to parse input for an
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|
|

|
|

|
|
|
|

|
|









|
|
|







 







|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







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
...
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
...
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
...
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

           1) A boolean flag indicating the success \(__True__\) or failure
              \(__False__\) of the operation\.

           1) In case of success the contents of the included file, and the
              empty string otherwise\.

           1) The resolved, i\.e\. absolute path of the included file, if
              possible, or the unchanged *path* argument\. This is for display
              in an error message, or as the *currentfile* argument of another
              call to __IncludeFile__ should this file contain more files\.

           1) In case of success an empty string, and for failure a code
              indicating the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

           1) An empty string in case of success of a __notfound__ failure,
              and an additional error message describing the reason for a
              __notread__ error in more detail\.

  1. A plugin has to provide one command, with the signature shown below\.

       - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*

         Whenever an import manager of
         __[doctools::idx](idx\_container\.md)__ has to parse input for an
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_import_json.md.

128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
...
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
...
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
...
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_parse.md.

205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
...
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
...
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
...
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
...
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/idx_structure.md.

131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
...
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
...
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2idx/import_docidx.md.

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
...
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
...
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

    An index serialization is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::idx__, and its value\.
    This value holds the contents of the index\.

    The contents of the index are a Tcl dictionary holding the title of the
    index, a label, and the keywords and references\. The relevant keys and their
    values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

    The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one of
    two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The references listed for each keyword of the index, if any, are listed in
    ascending dictionary order of their *labels*, as generated by Tcl's
    builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|







 







|
|
|

|
|
|







107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
...
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
...
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
We distinguish between *regular* and *canonical* serializations\. While a
keyword index may have more than one regular serialization only exactly one of
them will be *canonical*\.

  - regular serialization

      1. An index serialization is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::idx__, and its
         value\. This value holds the contents of the index\.

      1. The contents of the index are a Tcl dictionary holding the title of the
         index, a label, and the keywords and references\. The relevant keys and
         their values are

           * __title__

             The value is a string containing the title of the index\.

           * __label__

................................................................................
             this order\.

             Any key here has to be associated with at least one keyword, i\.e\.
             occur in at least one of the reference lists which are the values
             in the __keywords__ dictionary, see previous item for its
             definition\.

      1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one
         of two values,

           * __manpage__

             The identifier of the reference is interpreted as symbolic file
             name, referring to one of the documents the index was made for\.

           * __url__
................................................................................
  - canonical serialization

    The canonical serialization of a keyword index has the format as specified
    in the previous item, and then additionally satisfies the constraints below,
    which make it unique among all the possible serializations of the keyword
    index\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The references listed for each keyword of the index, if any, are listed
         in ascending dictionary order of their *labels*, as generated by
         Tcl's builtin command __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/export_doctoc.md.

148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
...
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
...
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/import_doctoc.md.

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
...
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
...
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_container.md.

374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
...
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
...
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_export.md.

341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
...
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
...
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_export_html.md.

207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
...
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
...
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_export_json.md.

176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
...
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
...
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_export_nroff.md.

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
...
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
...
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_export_text.md.

95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
...
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
...
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_export_wiki.md.

105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
...
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
...
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_import.md.

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
...
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
...
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

         A boolean flag indicating the success \(__True__\) or failure
         \(__False__\) of the operation\.

         In case of success the contents of the included file, and the empty
         string otherwise\.

         The resolved, i\.e\. absolute path of the included file, if possible, or
         the unchanged *path* argument\. This is for display in an error
         message, or as the *currentfile* argument of another call to
         __IncludeFile__ should this file contain more files\.

         In case of success an empty string, and for failure a code indicating
         the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

         An empty string in case of success of a __notfound__ failure, and
         an additional error message describing the reason for a __notread__
         error in more detail\.

  1. A plugin has to provide one command, with the signature shown below\.

       - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*

         Whenever an import manager of
         __[doctools::toc](\.\./doctools/doctoc\.md)__ has to parse input
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|
|

|
|

|
|
|
|

|
|









|
|
|







 







|

|
|

|
|
|







 







|
|
|







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
...
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
...
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

           1) A boolean flag indicating the success \(__True__\) or failure
              \(__False__\) of the operation\.

           1) In case of success the contents of the included file, and the
              empty string otherwise\.

           1) The resolved, i\.e\. absolute path of the included file, if
              possible, or the unchanged *path* argument\. This is for display
              in an error message, or as the *currentfile* argument of another
              call to __IncludeFile__ should this file contain more files\.

           1) In case of success an empty string, and for failure a code
              indicating the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

           1) An empty string in case of success of a __notfound__ failure,
              and an additional error message describing the reason for a
              __notread__ error in more detail\.

  1. A plugin has to provide one command, with the signature shown below\.

       - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*

         Whenever an import manager of
         __[doctools::toc](\.\./doctools/doctoc\.md)__ has to parse input
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_import_json.md.

148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
...
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
...
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_parse.md.

205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
...
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|

|
|

|
|
|







 







|
|
|







205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
...
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/doctools2toc/toc_structure.md.

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
...
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
...
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
    canonical serialization of this unified table of contents\.

    Title and label of the resulting table are taken from the table contained in
    *serialb*\.

    The whole table and its divisions are merged recursively in the same manner:

    All reference elements which occur in both divisions \(identified by their
    label\) are unified with document id's and descriptions taken from the second
    table\.

    All division elements which occur in both divisions \(identified by their
    label\) are unified with the optional document id taken from the second
    table, if any, or from the first if none is in the second\. The elements in
    the division are merged recursively using the same algorithm as described in
    this list\.

    Type conflicts between elements, i\.e\. finding two elements with the same
    label but different types result in a merge error\.

    All elements found in the second division but not in the first are added to
    the end of the list of elements in the merge result\.

    For the specification of regular and canonical serializations see the
    section [ToC serialization format](#section3)\.

# <a name='section3'></a>ToC serialization format

Here we specify the format used by the doctools v2 packages to serialize tables
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

    The serialization of any table of contents is a nested Tcl dictionary\.

    This dictionary holds a single key, __doctools::toc__, and its value\.
    This value holds the contents of the table of contents\.

    The contents of the table of contents are a Tcl dictionary holding the title
    of the table of contents, a label, and its elements\. The relevant keys and
    their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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\.






|
|
|

|
|
|
|
|

|
|

|
|







 







|

|
|

|
|
|







 







|
|
|







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
...
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
...
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
    canonical serialization of this unified table of contents\.

    Title and label of the resulting table are taken from the table contained in
    *serialb*\.

    The whole table and its divisions are merged recursively in the same manner:

      1. All reference elements which occur in both divisions \(identified by
         their label\) are unified with document id's and descriptions taken from
         the second table\.

      1. All division elements which occur in both divisions \(identified by
         their label\) are unified with the optional document id taken from the
         second table, if any, or from the first if none is in the second\. The
         elements in the division are merged recursively using the same
         algorithm as described in this list\.

      1. Type conflicts between elements, i\.e\. finding two elements with the
         same label but different types result in a merge error\.

      1. All elements found in the second division but not in the first are
         added to the end of the list of elements in the merge result\.

    For the specification of regular and canonical serializations see the
    section [ToC serialization format](#section3)\.

# <a name='section3'></a>ToC serialization format

Here we specify the format used by the doctools v2 packages to serialize tables
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
table of contents may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - regular serialization

      1. The serialization of any table of contents is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __doctools::toc__, and its
         value\. This value holds the contents of the table of contents\.

      1. The contents of the table of contents are a Tcl dictionary holding the
         title of the table of contents, a label, and its elements\. The relevant
         keys and their values are

           * __title__

             The value is a string containing the title of the table of
             contents\.

           * __label__
................................................................................
  - canonical serialization

    The canonical serialization of a table of contents has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this table of contents\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *doctools* 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/fileutil/fileutil.md.

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
  - <a name='22'></a>__::fileutil::tempdir__

    The command returns the path of a directory where the caller can place
    temporary files, such as "/tmp" on Unix systems\. The algorithm we use to
    find the correct directory is as follows:

    The directory set by an invokation of __::fileutil::tempdir__ with an
    argument\. If this is present it is tried exclusively and none of the
    following item are tried\.

    The directory named in the TMPDIR environment variable\.

    The directory named in the TEMP environment variable\.

    The directory named in the TMP environment variable\.

    A platform specific location:

           * Windows

             "C:\\TEMP", "C:\\TMP", "\\TEMP", and "\\TMP" are tried in that order\.

           * \(classic\) Macintosh







|
|
|

|

|

|

|







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
  - <a name='22'></a>__::fileutil::tempdir__

    The command returns the path of a directory where the caller can place
    temporary files, such as "/tmp" on Unix systems\. The algorithm we use to
    find the correct directory is as follows:

      1. The directory set by an invokation of __::fileutil::tempdir__ with
         an argument\. If this is present it is tried exclusively and none of the
         following item are tried\.

      1. The directory named in the TMPDIR environment variable\.

      1. The directory named in the TEMP environment variable\.

      1. The directory named in the TMP environment variable\.

      1. A platform specific location:

           * Windows

             "C:\\TEMP", "C:\\TMP", "\\TEMP", and "\\TMP" are tried in that order\.

           * \(classic\) Macintosh

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

188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
  - <a name='3'></a>__::ftp::Cd__ *handle* *directory*

    This command changes the current working directory on the ftp server to a
    specified target *directory*\. The command returns 1 if the current working
    directory was successfully changed to the specified directory or 0 if it
    fails\. The target directory can be

    a subdirectory of the current directory,

    Two dots, __\.\.__ \(as an indicator for the parent directory of the
    current directory\)

    or a fully qualified path to a new working directory\.

  - <a name='4'></a>__::ftp::Pwd__ *handle*

    This command returns the complete path of the current working directory on
    the ftp server, or an empty string in case of an error\.

  - <a name='5'></a>__::ftp::Type__ *handle* ?__ascii&#124;binary&#124;tenex__?






|

|
|

|







188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
  - <a name='3'></a>__::ftp::Cd__ *handle* *directory*

    This command changes the current working directory on the ftp server to a
    specified target *directory*\. The command returns 1 if the current working
    directory was successfully changed to the specified directory or 0 if it
    fails\. The target directory can be

      * a subdirectory of the current directory,

      * Two dots, __\.\.__ \(as an indicator for the parent directory of the
        current directory\)

      * or a fully qualified path to a new working directory\.

  - <a name='4'></a>__::ftp::Pwd__ *handle*

    This command returns the complete path of the current working directory on
    the ftp server, or an empty string in case of an error\.

  - <a name='5'></a>__::ftp::Type__ *handle* ?__ascii&#124;binary&#124;tenex__?

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

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
    The result of this method has to be semantically identical over all
    implementations of the __grammar::fa__ interface\. This is what will
    enable us to copy automatons between different implementations of the same
    interface\.

    The result is a list of three elements with the following structure:

    The constant string __grammar::fa__\.

    A list containing the names of all known input symbols\. The order of
    elements in this list is not relevant\.

    The last item in the list is a dictionary, however the order of the keys is
    important as well\. The keys are the states of the serialized FA, and their
    order is the order in which to create the states when deserializing\. This is
    relevant to preserve the order relationship between states\.


    The value of each dictionary entry is a list of three elements describing
    the state in more detail\.

    A boolean flag\. If its value is __true__ then the state is a start
    state, otherwise it is not\.

    A boolean flag\. If its value is __true__ then the state is a final
    state, otherwise it is not\.

    The last element is a dictionary describing the transitions for the state\.
    The keys are symbols \(or the empty string\), and the values are sets of
    successor states\.

    Assuming the following FA \(which describes the life of a truck driver in a
    very simple way :\)

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







|

|
|

|
|
|
|
>

|
|

|
|

|
|

|
|
|







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
    The result of this method has to be semantically identical over all
    implementations of the __grammar::fa__ interface\. This is what will
    enable us to copy automatons between different implementations of the same
    interface\.

    The result is a list of three elements with the following structure:

      1. The constant string __grammar::fa__\.

      1. A list containing the names of all known input symbols\. The order of
         elements in this list is not relevant\.

      1. The last item in the list is a dictionary, however the order of the
         keys is important as well\. The keys are the states of the serialized
         FA, and their order is the order in which to create the states when
         deserializing\. This is relevant to preserve the order relationship
         between states\.

         The value of each dictionary entry is a list of three elements
         describing the state in more detail\.

           1) A boolean flag\. If its value is __true__ then the state is a
              start state, otherwise it is not\.

           1) A boolean flag\. If its value is __true__ then the state is a
              final state, otherwise it is not\.

           1) The last element is a dictionary describing the transitions for
              the state\. The keys are symbols \(or the empty string\), and the
              values are sets of successor states\.

    Assuming the following FA \(which describes the life of a truck driver in a
    very simple way :\)

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

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

406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
  - <a name='19'></a>__::grammar::fa::op::simplifyRegexp__ *regexp*

    This command simplifies a regular expression by applying the following
    algorithm first to the main expression and then recursively to all
    sub\-expressions:

    Convert the expression into a finite automaton\.

    Minimize the automaton\.

    Convert the automaton back to a regular expression\.

    Choose the shorter of original expression and expression from the previous
    step\.

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

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *grammar\_fa* of the






|

|

|

|
|







406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
  - <a name='19'></a>__::grammar::fa::op::simplifyRegexp__ *regexp*

    This command simplifies a regular expression by applying the following
    algorithm first to the main expression and then recursively to all
    sub\-expressions:

      1. Convert the expression into a finite automaton\.

      1. Minimize the automaton\.

      1. Convert the automaton back to a regular expression\.

      1. Choose the shorter of original expression and expression from the
         previous step\.

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

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *grammar\_fa* of the

Changes to embedded/md/tcllib/files/modules/grammar_me/gasm.md.

291
292
293
294
295
296
297
298
299
300

301
302
303
304
305
306
307
308
309
310
311
312
313
  - <a name='6'></a>__::grammar::me::cpu::gasm::Inline__ *t* *node* *label*

    This command links an instruction sequence created by an earlier begin/done
    pair into the current instruction sequence\.

    To this end it

    reads the instruction references from the attributes __gas::entry__,
    __gas::exit::ok__, and __gas::exit::fail__ from the node *n* of
    the tree *t* and makes them available to assembler und the labels

    *label*/entry, *label*/exit::ok, and *label*/exit::fail respectively\.

    Creates an arc from the *anchor* to the node labeled *label*/entry, and
    tags it with the current condition code\.

    Makes the node labeled *label*/exit/ok the new *anchor*\.

    The command returns the empty string as its result\.

  - <a name='7'></a>__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*\.\.\.?

    This is the basic command to add instructions to the graph\. It creates a new
    instruction of type *cmd* with the given arguments *arg*\.\.\. If the






|
|
|
>
|

|
|

|







291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
  - <a name='6'></a>__::grammar::me::cpu::gasm::Inline__ *t* *node* *label*

    This command links an instruction sequence created by an earlier begin/done
    pair into the current instruction sequence\.

    To this end it

      1. reads the instruction references from the attributes
         __gas::entry__, __gas::exit::ok__, and __gas::exit::fail__
         from the node *n* of the tree *t* and makes them available to
         assembler und the labels *label*/entry, *label*/exit::ok, and
         *label*/exit::fail respectively\.

      1. Creates an arc from the *anchor* to the node labeled *label*/entry,
         and tags it with the current condition code\.

      1. Makes the node labeled *label*/exit/ok the new *anchor*\.

    The command returns the empty string as its result\.

  - <a name='7'></a>__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*\.\.\.?

    This is the basic command to add instructions to the graph\. It creates a new
    instruction of type *cmd* with the given arguments *arg*\.\.\. If the

Changes to embedded/md/tcllib/files/modules/grammar_me/me_cpu.md.

251
252
253
254
255
256
257
258
259
260
261
262

263
264
265
266
267
268
269
    and the line/col information is computed based on the characters encountered
    and the data in the variables *lvar* and *cvar*\.

  - <a name='24'></a>*meName* __run__ ?*n*?

    This methods causes the engine to execute match instructions until either

    *n* instructions have been executed, or

    a halt instruction was executed, or

    the input queue is empty and the code is asking for more tokens to process\.


    If no limit *n* was set only the last two conditions are checked for\.

  - <a name='25'></a>*meName* __pull__ *nextcmd*

    This method implements pull\-style operation of the machine\. It causes it to
    execute match instructions until either a halt instruction is reached, or






|

|

|
>







251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
    and the line/col information is computed based on the characters encountered
    and the data in the variables *lvar* and *cvar*\.

  - <a name='24'></a>*meName* __run__ ?*n*?

    This methods causes the engine to execute match instructions until either

      * *n* instructions have been executed, or

      * a halt instruction was executed, or

      * the input queue is empty and the code is asking for more tokens to
        process\.

    If no limit *n* was set only the last two conditions are checked for\.

  - <a name='25'></a>*meName* __pull__ *nextcmd*

    This method implements pull\-style operation of the machine\. It causes it to
    execute match instructions until either a halt instruction is reached, or

Changes to embedded/md/tcllib/files/modules/grammar_me/me_cpucore.md.

256
257
258
259
260
261
262
263
264
265
266
267

268
269
270
271
272
273
274
    This method takes the state value of a ME virtual machine as stored in the
    variable named by *statevar*, executes a number of instructions and stores
    the state resulting from their modifications back into the variable\.

    The execution loop will run until either

    *n* instructions have been executed, or

    a halt instruction was executed, or

    the input queue is empty and the code is asking for more tokens to process\.


    If no limit *n* was set only the last two conditions are checked for\.

## <a name='subsection1'></a>MATCH PROGRAM REPRESENTATION

A match program is represented by nested Tcl list\. The first element, *asm*,
is a list of integer numbers, the instructions to execute, and their arguments\.






|

|

|
>







256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
    This method takes the state value of a ME virtual machine as stored in the
    variable named by *statevar*, executes a number of instructions and stores
    the state resulting from their modifications back into the variable\.

    The execution loop will run until either

      * *n* instructions have been executed, or

      * a halt instruction was executed, or

      * the input queue is empty and the code is asking for more tokens to
        process\.

    If no limit *n* was set only the last two conditions are checked for\.

## <a name='subsection1'></a>MATCH PROGRAM REPRESENTATION

A match program is represented by nested Tcl list\. The first element, *asm*,
is a list of integer numbers, the instructions to execute, and their arguments\.

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

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
    The result of this method has to be semantically identical over all
    implementations of the __grammar::peg__ interface\. This is what will
    enable us to copy grammars between different implementations of the same
    interface\.

    The result is a list of four elements with the following structure:

    The constant string __grammar::peg__\.

    A dictionary\. Its keys are the names of all known nonterminal symbols, and
    their associated values are the parsing expressions describing their
    sentennial structure\.

    A dictionary\. Its keys are the names of all known nonterminal symbols, and
    their associated values hints to a matcher regarding the semantic values
    produced by the symbol\.

    The last item is a parsing expression, the *start expression* of the
    grammar\.

    Assuming the following PEG for simple mathematical expressions

    Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
    Sign       <\- '\+' / '\-'
    Number     <\- Sign? Digit\+
    Expression <\- '\(' Expression '\)' / \(Factor \(MulOp Factor\)\*\)






|

|
|
|

|
|
|

|
|







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
    The result of this method has to be semantically identical over all
    implementations of the __grammar::peg__ interface\. This is what will
    enable us to copy grammars between different implementations of the same
    interface\.

    The result is a list of four elements with the following structure:

      1. The constant string __grammar::peg__\.

      1. A dictionary\. Its keys are the names of all known nonterminal symbols,
         and their associated values are the parsing expressions describing
         their sentennial structure\.

      1. A dictionary\. Its keys are the names of all known nonterminal symbols,
         and their associated values hints to a matcher regarding the semantic
         values produced by the symbol\.

      1. The last item is a parsing expression, the *start expression* of the
         grammar\.

    Assuming the following PEG for simple mathematical expressions

    Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
    Sign       <\- '\+' / '\-'
    Number     <\- Sign? Digit\+
    Expression <\- '\(' Expression '\)' / \(Factor \(MulOp Factor\)\*\)

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

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
...
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
...
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
        hook bind $s $h $o $binding

    is called during the execution of

        hook call $s $h

    No binding is ever called after it is deleted\.

    When a binding is called, the most recently given command prefix is always
    used\.

    The set of observers whose bindings are to be called is determined when this
    method begins to execute, and does not change thereafter, except that
    deleted bindings are not called\.

    In particular:

    If __$o__s binding to __$s__ and __$h__ is deleted, and
    __$o__s binding has not yet been called during this execution of

        hook call $s $h

    it will not be called\. \(Note that it might already have been called; and in
    all likelihood, it is probably deleting itself\.\)

    If __$o__ changes the command prefix that's bound to __$s__ and
    __$h__, and if __$o__s binding has not yet been called during this
    execution of

        hook call $s $h

    the new binding will be called when the time comes\. \(But again, it is
    probably __$o__s binding that is is making the change\.\)

    If a new observer is bound to __$s__ and __$h__, its binding will
    not be called until the next invocation of

        hook call $s $h

  - <a name='2'></a>__hook__ __call__ *subject* *hook* ?*args*\.\.\.?

    This command is called when the named *subject* wishes to call the named
    *hook*\. All relevant bindings are called with the specified arguments in
    the global namespace\. Note that the bindings are called synchronously,
    before the command returns; this allows the *args* to include references
................................................................................
    among observers must be preserved, define one observer and have its bindings
    call the other callbacks directly in the proper sequence\.

    Because the __hook__ mechanism is intended to support loose coupling, it
    is presumed that the *subject* has no knowledge of the observers, nor any
    expectation regarding return values\. This has a number of implications:

    __hook call__ returns the empty string\.

    Normal return values from observer bindings are ignored\.

    Errors and other exceptional returns propagate normally by default\. This
    will rarely be what is wanted, because the subjects usually have no
    knowledge of the observers and will therefore have no particular competence
    at handling their errors\. That makes it an application issue, and so
    applications will usually want to define an __\-errorcommand__\.


    If the __\-errorcommand__ configuration option has a non\-empty value, its
    value will be invoked for all errors and other exceptional returns in
    observer bindings\. See __hook configure__, below, for more information
    on configuration options\.

  - <a name='3'></a>__hook__ __forget__ *object*

    This command deletes any existing bindings in which the named *object*
    appears as either the *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)* or the
    *[observer](\.\./\.\./\.\./\.\./index\.md\#observer)*\. Bindings deleted by this
    method will never be called again\. In particular,

    If an observer is forgotten during a call to __hook call__, any uncalled
    binding it might have had to the relevant subject and hook will *not* be
    called subsequently\.

    If a subject __$s__ is forgotten during a call to

        hook call $s $h

    then __hook call__ will return as soon as the current binding returns\.
    No further bindings will be called\.

  - <a name='4'></a>__hook__ __cget__ *option*

    This command returns the value of one of the __hook__ command's
    configuration options\.

  - <a name='5'></a>__hook__ __configure__ __option__ *value* \.\.\.
................................................................................
      * __\-errorcommand__ *cmdPrefix*

        If the value of this option is the empty string, "", then errors and
        other exception returns in binding scripts are propagated normally\.
        Otherwise, it must be a command prefix taking three additional
        arguments:

        a 4\-element list \{subject hook arglist observer\},

        the result string, and

        the return options dictionary\.

        Given this information, the __\-errorcommand__ can choose to log the
        error, call __interp bgerror__, delete the errant binding \(thus
        preventing the error from arising a second time\) and so forth\.

      * __\-tracecommand__ *cmdPrefix*

        The option's value should be a command prefix taking four arguments:

        a *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*,

        a *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)*,

        a list of the hook's argument values, and

        a list of *objects* the hook was called for\.

        The command will be called for each hook that is called\. This allows the
        application to trace hook execution for debugging purposes\.

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

The __::model__ module calls the <Update> hook in response to commands that






|

|
|

|
|
|



|
|

|

|
|

|
|
|

|

|
|

|
|

|







 







|

|

|
|
|
|
|
>













|
|
|

|

|

|
|







 







|

|

|









|

|

|

|







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
...
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
...
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
        hook bind $s $h $o $binding

    is called during the execution of

        hook call $s $h

      1. No binding is ever called after it is deleted\.

      1. When a binding is called, the most recently given command prefix is
         always used\.

      1. The set of observers whose bindings are to be called is determined when
         this method begins to execute, and does not change thereafter, except
         that deleted bindings are not called\.

    In particular:

      1. If __$o__s binding to __$s__ and __$h__ is deleted, and
         __$o__s binding has not yet been called during this execution of

             hook call $s $h

         it will not be called\. \(Note that it might already have been called;
         and in all likelihood, it is probably deleting itself\.\)

      1. If __$o__ changes the command prefix that's bound to __$s__ and
         __$h__, and if __$o__s binding has not yet been called during
         this execution of

             hook call $s $h

         the new binding will be called when the time comes\. \(But again, it is
         probably __$o__s binding that is is making the change\.\)

      1. If a new observer is bound to __$s__ and __$h__, its binding
         will not be called until the next invocation of

             hook call $s $h

  - <a name='2'></a>__hook__ __call__ *subject* *hook* ?*args*\.\.\.?

    This command is called when the named *subject* wishes to call the named
    *hook*\. All relevant bindings are called with the specified arguments in
    the global namespace\. Note that the bindings are called synchronously,
    before the command returns; this allows the *args* to include references
................................................................................
    among observers must be preserved, define one observer and have its bindings
    call the other callbacks directly in the proper sequence\.

    Because the __hook__ mechanism is intended to support loose coupling, it
    is presumed that the *subject* has no knowledge of the observers, nor any
    expectation regarding return values\. This has a number of implications:

      1. __hook call__ returns the empty string\.

      1. Normal return values from observer bindings are ignored\.

      1. Errors and other exceptional returns propagate normally by default\.
         This will rarely be what is wanted, because the subjects usually have
         no knowledge of the observers and will therefore have no particular
         competence at handling their errors\. That makes it an application
         issue, and so applications will usually want to define an
         __\-errorcommand__\.

    If the __\-errorcommand__ configuration option has a non\-empty value, its
    value will be invoked for all errors and other exceptional returns in
    observer bindings\. See __hook configure__, below, for more information
    on configuration options\.

  - <a name='3'></a>__hook__ __forget__ *object*

    This command deletes any existing bindings in which the named *object*
    appears as either the *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)* or the
    *[observer](\.\./\.\./\.\./\.\./index\.md\#observer)*\. Bindings deleted by this
    method will never be called again\. In particular,

      1. If an observer is forgotten during a call to __hook call__, any
         uncalled binding it might have had to the relevant subject and hook
         will *not* be called subsequently\.

      1. If a subject __$s__ is forgotten during a call to

             hook call $s $h

         then __hook call__ will return as soon as the current binding
         returns\. No further bindings will be called\.

  - <a name='4'></a>__hook__ __cget__ *option*

    This command returns the value of one of the __hook__ command's
    configuration options\.

  - <a name='5'></a>__hook__ __configure__ __option__ *value* \.\.\.
................................................................................
      * __\-errorcommand__ *cmdPrefix*

        If the value of this option is the empty string, "", then errors and
        other exception returns in binding scripts are propagated normally\.
        Otherwise, it must be a command prefix taking three additional
        arguments:

          1. a 4\-element list \{subject hook arglist observer\},

          1. the result string, and

          1. the return options dictionary\.

        Given this information, the __\-errorcommand__ can choose to log the
        error, call __interp bgerror__, delete the errant binding \(thus
        preventing the error from arising a second time\) and so forth\.

      * __\-tracecommand__ *cmdPrefix*

        The option's value should be a command prefix taking four arguments:

          1. a *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*,

          1. a *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)*,

          1. a list of the hook's argument values, and

          1. a list of *objects* the hook was called for\.

        The command will be called for each hook that is called\. This allows the
        application to trace hook execution for debugging purposes\.

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

The __::model__ module calls the <Update> hook in response to commands that

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

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
  - <a name='62'></a>__::html::doctype__ *id*

    This procedure can be used to build the standard DOCTYPE declaration string\.
    It will return the standard declaration string for the id, or throw an error
    if the id is not known\. The following id's are defined:

    HTML32

    HTML40

    HTML40T

    HTML40F

    HTML401

    HTML401T

    HTML401F

    XHTML10S

    XHTML10T

    XHTML10F

    XHTML11

    XHTMLB

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *html* 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\.






|

|

|

|

|

|

|

|

|

|

|

|







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
  - <a name='62'></a>__::html::doctype__ *id*

    This procedure can be used to build the standard DOCTYPE declaration string\.
    It will return the standard declaration string for the id, or throw an error
    if the id is not known\. The following id's are defined:

      1. HTML32

      1. HTML40

      1. HTML40T

      1. HTML40F

      1. HTML401

      1. HTML401T

      1. HTML401F

      1. XHTML10S

      1. XHTML10T

      1. XHTML10F

      1. XHTML11

      1. XHTMLB

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

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *html* 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/ldap/ldapx.md.

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
    modifications are handled by specialized methods such as __apply__ or
    __commit__\. Detailed format should not be used directly by programs\.

    Internally, modifications are represented as a list of elements, each
    element has one of the following formats \(which match the corresponding LDAP
    operations\):

    \{__add__ \{attr1 \{val1\.\.\.valn\} attr2 \{\.\.\.\} \.\.\.\}\}

    Addition of a new entry\.

    \{__mod__ \{modop \{attr1 ?val1\.\.\.valn?\} attr2 \.\.\.\} \{modop \.\.\.\} \.\.\.\}

    Modification of one or more attributes and/or values, where <modop> can be
    __modadd__, __moddel__ or __modrepl__ \(see the LDAP modify
    operation\)\.

    \{__del__\}

    Deletion of an old entry\.

    \{__modrdn__ newrdn deleteoldrdn ?newsuperior?\}

    Renaming of an entry\.

## <a name='subsection2'></a>Entry Options

No option is defined by this class\.

## <a name='subsection3'></a>Methods for all kinds of entries







|

|

|

|
|
|

|

|

|

|







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
    modifications are handled by specialized methods such as __apply__ or
    __commit__\. Detailed format should not be used directly by programs\.

    Internally, modifications are represented as a list of elements, each
    element has one of the following formats \(which match the corresponding LDAP
    operations\):

      1. \{__add__ \{attr1 \{val1\.\.\.valn\} attr2 \{\.\.\.\} \.\.\.\}\}

         Addition of a new entry\.

      1. \{__mod__ \{modop \{attr1 ?val1\.\.\.valn?\} attr2 \.\.\.\} \{modop \.\.\.\} \.\.\.\}

         Modification of one or more attributes and/or values, where <modop> can
         be __modadd__, __moddel__ or __modrepl__ \(see the LDAP
         modify operation\)\.

      1. \{__del__\}

         Deletion of an old entry\.

      1. \{__modrdn__ newrdn deleteoldrdn ?newsuperior?\}

         Renaming of an entry\.

## <a name='subsection2'></a>Entry Options

No option is defined by this class\.

## <a name='subsection3'></a>Methods for all kinds of entries

Changes to embedded/md/tcllib/files/modules/log/logger.md.

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
    $\{log\}::logproc notice logtoserver

    Trace logs are slightly different: instead of a plain text argument, the
    argument provided to the logproc is a dictionary consisting of the
    __enter__ or __leave__ keyword along with another dictionary of
    details about the trace\. These include:

    __proc__ \- Name of the procedure being traced\.

    __level__ \- The stack level for the procedure invocation \(from
    __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ __level__\)\.

    __script__ \- The name of the file in which the procedure is defined, or
    an empty string if defined in interactive mode\.

    __caller__ \- The name of the procedure calling the procedure being
    traced, or an empty string if the procedure was called from the global scope
    \(stack level 0\)\.

    __procargs__ \- A dictionary consisting of the names of arguments to the
    procedure paired with values given for those arguments \(__enter__ traces
    only\)\.

    __status__ \- The Tcl return code \(e\.g\. __ok__, __continue__,
    etc\.\) \(__leave__ traces only\)\.

    __result__ \- The value returned by the procedure \(__leave__ traces
    only\)\.

  - <a name='26'></a>__$\{log\}::services__

    Returns a list of the registered logging services which are children of this
    service\.

  - <a name='27'></a>__$\{log\}::servicename__






|

|
|

|
|

|
|
|

|
|
|

|
|

|
|







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
    $\{log\}::logproc notice logtoserver

    Trace logs are slightly different: instead of a plain text argument, the
    argument provided to the logproc is a dictionary consisting of the
    __enter__ or __leave__ keyword along with another dictionary of
    details about the trace\. These include:

      * __proc__ \- Name of the procedure being traced\.

      * __level__ \- The stack level for the procedure invocation \(from
        __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ __level__\)\.

      * __script__ \- The name of the file in which the procedure is defined,
        or an empty string if defined in interactive mode\.

      * __caller__ \- The name of the procedure calling the procedure being
        traced, or an empty string if the procedure was called from the global
        scope \(stack level 0\)\.

      * __procargs__ \- A dictionary consisting of the names of arguments to
        the procedure paired with values given for those arguments
        \(__enter__ traces only\)\.

      * __status__ \- The Tcl return code \(e\.g\. __ok__, __continue__,
        etc\.\) \(__leave__ traces only\)\.

      * __result__ \- The value returned by the procedure \(__leave__
        traces only\)\.

  - <a name='26'></a>__$\{log\}::services__

    Returns a list of the registered logging services which are children of this
    service\.

  - <a name='27'></a>__$\{log\}::servicename__

Changes to embedded/md/tcllib/files/modules/map/map_slippy_cache.md.

80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
    *tile* from the cache\. The tile identifier is a list containing three
    elements, the zoom level, row, and column number of the tile, in this order\.

    The command refix *donecmd* will be invoked when the cache either knows
    the image for the tile or that no image will forthcoming\. It will be invoked
    with either 2 or 3 arguments, i\.e\.

    The string __set__, the *tile*, and the image\.

    The string __unset__, and the *tile*\.

    These two possibilities are used to either signal the image for the
    *tile*, or that the *tile* has no image defined for it\.

    When the cache has no information about the tile it will invoke the
    *provider* command prefix specified during its construction, adding three
    arguments: The string __get__, the *tile*, and a callback into the






|

|







80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
    *tile* from the cache\. The tile identifier is a list containing three
    elements, the zoom level, row, and column number of the tile, in this order\.

    The command refix *donecmd* will be invoked when the cache either knows
    the image for the tile or that no image will forthcoming\. It will be invoked
    with either 2 or 3 arguments, i\.e\.

      1. The string __set__, the *tile*, and the image\.

      1. The string __unset__, and the *tile*\.

    These two possibilities are used to either signal the image for the
    *tile*, or that the *tile* has no image defined for it\.

    When the cache has no information about the tile it will invoke the
    *provider* command prefix specified during its construction, adding three
    arguments: The string __get__, the *tile*, and a callback into the

Changes to embedded/md/tcllib/files/modules/map/map_slippy_fetcher.md.

80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
    specified *tile*\. The tile identifier is a list containing three elements,
    the zoom level, row, and column number of the tile, in this order\.

    The command refix *donecmd* will be invoked when the fetcher either knows
    the image for the tile or that no image will forthcoming\. It will be invoked
    with either 2 or 3 arguments, i\.e\.

    The string __set__, the *tile*, and the image\.

    The string __unset__, and the *tile*\.

    These two possibilities are used to either signal the image for the
    *tile*, or that the *tile* has no image defined for it\.

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

  1. [http://wiki\.openstreetmap\.org/wiki/Main\_Page](http://wiki\.openstreetmap\.org/wiki/Main\_Page)






|

|







80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
    specified *tile*\. The tile identifier is a list containing three elements,
    the zoom level, row, and column number of the tile, in this order\.

    The command refix *donecmd* will be invoked when the fetcher either knows
    the image for the tile or that no image will forthcoming\. It will be invoked
    with either 2 or 3 arguments, i\.e\.

      1. The string __set__, the *tile*, and the image\.

      1. The string __unset__, and the *tile*\.

    These two possibilities are used to either signal the image for the
    *tile*, or that the *tile* has no image defined for it\.

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

  1. [http://wiki\.openstreetmap\.org/wiki/Main\_Page](http://wiki\.openstreetmap\.org/wiki/Main\_Page)

Changes to embedded/md/tcllib/files/modules/math/bigfloat.md.

246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
# <a name='section4'></a>COMPARISONS

  - <a name='16'></a>__iszero__ *x*

    Returns 1 if *x* is :

    a BigFloat close enough to zero to raise "divide by zero"\.

    the integer 0\.

    See here how numbers that are close to zero are converted to strings:

        tostr \[fromstr 0\.001\] ; \# \-> 0\.e\-2
        tostr \[fromstr 0\.000000\] ; \# \-> 0\.e\-5
        tostr \[fromstr \-0\.000001\] ; \# \-> 0\.e\-5
        tostr \[fromstr 0\.0\] ; \# \-> 0\.






|

|







246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
# <a name='section4'></a>COMPARISONS

  - <a name='16'></a>__iszero__ *x*

    Returns 1 if *x* is :

      * a BigFloat close enough to zero to raise "divide by zero"\.

      * the integer 0\.

    See here how numbers that are close to zero are converted to strings:

        tostr \[fromstr 0\.001\] ; \# \-> 0\.e\-2
        tostr \[fromstr 0\.000000\] ; \# \-> 0\.e\-5
        tostr \[fromstr \-0\.000001\] ; \# \-> 0\.e\-5
        tostr \[fromstr 0\.0\] ; \# \-> 0\.

Changes to embedded/md/tcllib/files/modules/math/calculus.md.

149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
  - <a name='8'></a>__::math::calculus::qk15\_detailed__ *xstart* *xend* *func* *nosteps*

    Determine the integral of the given function using the Gauss\-Kronrod 15
    points quadrature rule\. The interval for the integration is \[*xstart*,
    *xend*\]\. The procedure returns a list of four values:

    The estimate of the integral over the specified interval \(I\)\.

    An estimate of the absolute error in I\.

    The estimate of the integral of the absolute value of the function over the
    interval\.

    The estimate of the integral of the absolute value of the function minus its
    mean over the interval\.

    The remaining arguments are:

      * *func*

        Function to be integrated\. It should take one single argument\.







|

|

|
|

|
|







149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
  - <a name='8'></a>__::math::calculus::qk15\_detailed__ *xstart* *xend* *func* *nosteps*

    Determine the integral of the given function using the Gauss\-Kronrod 15
    points quadrature rule\. The interval for the integration is \[*xstart*,
    *xend*\]\. The procedure returns a list of four values:

      * The estimate of the integral over the specified interval \(I\)\.

      * An estimate of the absolute error in I\.

      * The estimate of the integral of the absolute value of the function over
        the interval\.

      * The estimate of the integral of the absolute value of the function minus
        its mean over the interval\.

    The remaining arguments are:

      * *func*

        Function to be integrated\. It should take one single argument\.

Changes to embedded/md/tcllib/files/modules/math/decimal.md.

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
    Convert *decimal* into a string representing the number in base 10\.

  - <a name='3'></a>__::math::decimal::setVariable__ *variable* *setting*

    Sets the *variable* to *setting*\. Valid variables are:

    *rounding* \- Method of rounding to use during rescale\. Valid methods are
    round\_half\_even, round\_half\_up, round\_half\_down, round\_down, round\_up,
    round\_floor, round\_ceiling\.

    *precision* \- Maximum number of digits allowed in mantissa\.

    *extended* \- Set to 1 for extended mode\. 0 for simplified mode\.

    *maxExponent* \- Maximum value for the exponent\. Defaults to 999\.

    *minExponent* \- Minimum value for the exponent\. Default to \-998\.

  - <a name='4'></a>__::math::decimal::add__ *a* *b*

  - <a name='5'></a>__::math::decimal::\+__ *a* *b*

    Return the sum of the two decimals *a* and *b*\.







|
|
|

|

|

|

|







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
    Convert *decimal* into a string representing the number in base 10\.

  - <a name='3'></a>__::math::decimal::setVariable__ *variable* *setting*

    Sets the *variable* to *setting*\. Valid variables are:

      * *rounding* \- Method of rounding to use during rescale\. Valid methods
        are round\_half\_even, round\_half\_up, round\_half\_down, round\_down,
        round\_up, round\_floor, round\_ceiling\.

      * *precision* \- Maximum number of digits allowed in mantissa\.

      * *extended* \- Set to 1 for extended mode\. 0 for simplified mode\.

      * *maxExponent* \- Maximum value for the exponent\. Defaults to 999\.

      * *minExponent* \- Minimum value for the exponent\. Default to \-998\.

  - <a name='4'></a>__::math::decimal::add__ *a* *b*

  - <a name='5'></a>__::math::decimal::\+__ *a* *b*

    Return the sum of the two decimals *a* and *b*\.

Changes to embedded/md/tcllib/files/modules/math/linalg.md.

407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
...
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
    Checks if two objects \(vector or matrix\) have conforming shapes, that is if
    they can be applied in an operation like addition or matrix multiplication\.

      * string *type*

        Type of check:

        "shape" \- the two objects have the same shape \(for all element\-wise
        operations\)

        "rows" \- the two objects have the same number of rows \(for use as A and
        b in a system of linear equations *Ax = b*

        "matmul" \- the first object has the same number of columns as the number
        of rows of the second object\. Useful for matrix\-matrix or matrix\-vector
        multiplication\.

      * list *obj1*

        First vector or matrix \(left operand\)

      * list *obj2*

................................................................................
        A column vector

      * list *scope*

        If not provided, the operation is performed on all rows/columns of A if
        provided, it is expected to be the list \{imin imax jmin jmax\} where:

        *imin* Minimum row index

        *imax* Maximum row index

        *jmin* Minimum column index

        *jmax* Maximum column index

  - <a name='59'></a>__::math::linearalgebra::dgetrf__ *matrix*

    Computes an LU factorization of a general matrix, using partial, pivoting
    with row interchanges\. Returns the permutation vector\.

    The factorization has the form






|
|

|
|

|
|
|







 







|

|

|

|







407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
...
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
    Checks if two objects \(vector or matrix\) have conforming shapes, that is if
    they can be applied in an operation like addition or matrix multiplication\.

      * string *type*

        Type of check:

          + "shape" \- the two objects have the same shape \(for all element\-wise
            operations\)

          + "rows" \- the two objects have the same number of rows \(for use as A
            and b in a system of linear equations *Ax = b*

          + "matmul" \- the first object has the same number of columns as the
            number of rows of the second object\. Useful for matrix\-matrix or
            matrix\-vector multiplication\.

      * list *obj1*

        First vector or matrix \(left operand\)

      * list *obj2*

................................................................................
        A column vector

      * list *scope*

        If not provided, the operation is performed on all rows/columns of A if
        provided, it is expected to be the list \{imin imax jmin jmax\} where:

          + *imin* Minimum row index

          + *imax* Maximum row index

          + *jmin* Minimum column index

          + *jmax* Maximum column index

  - <a name='59'></a>__::math::linearalgebra::dgetrf__ *matrix*

    Computes an LU factorization of a general matrix, using partial, pivoting
    with row interchanges\. Returns the permutation vector\.

    The factorization has the form

Changes to embedded/md/tcllib/files/modules/math/machineparameters.md.

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
    Computes the machine parameters\.

  - <a name='6'></a>*objectname* __get__ *key*

    Returns the value corresponding with given key\. The following is the list of
    available keys\.

    \-epsilon : smallest value so that 1\+epsilon>1 is false

    \-rounding : The rounding mode used on the machine\. The rounding occurs when
    more than t digits would be required to represent the number\. Two modes can
    be determined with the current system : "chop" means than only t digits are
    kept, no matter the value of the number "proper" means that another rounding
    mode is used, be it "round to nearest", "round up", "round down"\.


    \-basis : the basis of the floating\-point representation\. The basis is
    usually 2, i\.e\. binary representation \(for example IEEE 754 machines\), but
    some machines \(like HP calculators for example\) uses 10, or 16, etc\.\.\.


    \-mantissa : the number of bits in the mantissa

    \-exponentmax : the largest positive exponent before overflow occurs

    \-exponentmin : the largest negative exponent before \(gradual\) underflow
    occurs

    \-vmax : largest positive value before overflow occurs

    \-vmin : largest negative value before \(gradual\) underflow occurs

  - <a name='7'></a>*objectname* __tostring__

    Return a report for machine parameters\.

  - <a name='8'></a>*objectname* __print__







|

|
|
|
|
|
>

|
|
|
>

|

|

|
|

|

|







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
    Computes the machine parameters\.

  - <a name='6'></a>*objectname* __get__ *key*

    Returns the value corresponding with given key\. The following is the list of
    available keys\.

      * \-epsilon : smallest value so that 1\+epsilon>1 is false

      * \-rounding : The rounding mode used on the machine\. The rounding occurs
        when more than t digits would be required to represent the number\. Two
        modes can be determined with the current system : "chop" means than only
        t digits are kept, no matter the value of the number "proper" means that
        another rounding mode is used, be it "round to nearest", "round up",
        "round down"\.

      * \-basis : the basis of the floating\-point representation\. The basis is
        usually 2, i\.e\. binary representation \(for example IEEE 754 machines\),
        but some machines \(like HP calculators for example\) uses 10, or 16,
        etc\.\.\.

      * \-mantissa : the number of bits in the mantissa

      * \-exponentmax : the largest positive exponent before overflow occurs

      * \-exponentmin : the largest negative exponent before \(gradual\) underflow
        occurs

      * \-vmax : largest positive value before overflow occurs

      * \-vmin : largest negative value before \(gradual\) underflow occurs

  - <a name='7'></a>*objectname* __tostring__

    Return a report for machine parameters\.

  - <a name='8'></a>*objectname* __print__

Changes to embedded/md/tcllib/files/modules/math/math_geometry.md.

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
    or > 1 extrapolate along the line between the two point\.

  - <a name='11'></a>__::math::geometry::octant__ *point*

    Compute the octant of the circle the point is in and return it as the result
    of the command\. The possible results are

    east

    northeast

    north

    northwest

    west

    southwest

    south

    southeast

    Each octant is the arc of the circle \+/\- 22\.5 degrees from the cardinal
    direction the octant is named for\.

  - <a name='12'></a>__::math::geometry::rect__ *nw* *se*

    Construct a rectangle from its northwest and southeast corners and return it






|

|

|

|

|

|

|

|







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
    or > 1 extrapolate along the line between the two point\.

  - <a name='11'></a>__::math::geometry::octant__ *point*

    Compute the octant of the circle the point is in and return it as the result
    of the command\. The possible results are

      1. east

      1. northeast

      1. north

      1. northwest

      1. west

      1. southwest

      1. south

      1. southeast

    Each octant is the arc of the circle \+/\- 22\.5 degrees from the cardinal
    direction the octant is named for\.

  - <a name='12'></a>__::math::geometry::rect__ *nw* *se*

    Construct a rectangle from its northwest and southeast corners and return it

Changes to embedded/md/tcllib/files/modules/math/romberg.md.

243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
    These procedures operate by making the change of variable u=\(x\-a\)\*\*\(1\-gamma\)
    \(__romberg\_powerLawLower__\) or u=\(b\-x\)\*\*\(1\-gamma\)
    \(__romberg\_powerLawUpper__\)\.

    To summarize the meaning of gamma:

    If f\(x\) ~ x\*\*\(\-a\) \(0 < a < 1\), use gamma = a

    If f'\(x\) ~ x\*\*\(\-b\) \(0 < b < 1\), use gamma = b

  - __romberg\_sqrtSingLower__ and __romberg\_sqrtSingUpper__

    These procedures behave identically to __romberg\_powerLawLower__ and
    __romberg\_powerLawUpper__ for the common case of *gamma*=0\.5; that is,
    they integrate a function with an inverse square root singularity at one end
    of the interval\. They have a simpler implementation involving square roots






|

|







243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
    These procedures operate by making the change of variable u=\(x\-a\)\*\*\(1\-gamma\)
    \(__romberg\_powerLawLower__\) or u=\(b\-x\)\*\*\(1\-gamma\)
    \(__romberg\_powerLawUpper__\)\.

    To summarize the meaning of gamma:

      * If f\(x\) ~ x\*\*\(\-a\) \(0 < a < 1\), use gamma = a

      * If f'\(x\) ~ x\*\*\(\-b\) \(0 < b < 1\), use gamma = b

  - __romberg\_sqrtSingLower__ and __romberg\_sqrtSingUpper__

    These procedures behave identically to __romberg\_powerLawLower__ and
    __romberg\_powerLawUpper__ for the common case of *gamma*=0\.5; that is,
    they integrate a function with an inverse square root singularity at one end
    of the interval\. They have a simpler implementation involving square roots

Changes to embedded/md/tcllib/files/modules/math/statistics.md.

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
....
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
      * boolean *intercept*

        \- \(Optional\) compute the intercept \(1, default\) or fit to a line through
        the origin \(0\)

        The result consists of the following list:

        \(Estimate of\) Intercept A

        \(Estimate of\) Slope B

        Standard deviation of Y relative to fit

        Correlation coefficient R2

        Number of degrees of freedom df

        Standard error of the intercept A

        Significance level of A

        Standard error of the slope B

        Significance level of B

  - <a name='29'></a>__::math::statistics::linear\-residuals__ *xdata* *ydata* *intercept*

    Determine the difference between actual data and predicted from the linear
    model\.

    Returns a list of the differences between the actual data and the predicted
................................................................................

    and each point satisfies

        yi = b0 \+ b1 \* xi1 \+ b2 \* xi2 \+ \.\.\. \+ bN \* xiN \+ Residual\_i

    The procedure returns a list with the following elements:

    The r\-squared statistic

    The adjusted r\-squared statistic

    A list containing the estimated coefficients b1, \.\.\. bN, b0 \(The constant b0
    comes last in the list\.\)

    A list containing the standard errors of the coefficients

    A list containing the 95% confidence bounds of the coefficients, with each
    set of bounds returned as a list with two values

    Arguments:

      * list *weights\_and\_values*

        A list consisting of: the weight for the first observation, the data for
        the first observation \(as a sublist\), the weight for the second






|

|

|

|

|

|

|

|

|







 







|

|

|
|

|

|
|







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
....
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
      * boolean *intercept*

        \- \(Optional\) compute the intercept \(1, default\) or fit to a line through
        the origin \(0\)

        The result consists of the following list:

          + \(Estimate of\) Intercept A

          + \(Estimate of\) Slope B

          + Standard deviation of Y relative to fit

          + Correlation coefficient R2

          + Number of degrees of freedom df

          + Standard error of the intercept A

          + Significance level of A

          + Standard error of the slope B

          + Significance level of B

  - <a name='29'></a>__::math::statistics::linear\-residuals__ *xdata* *ydata* *intercept*

    Determine the difference between actual data and predicted from the linear
    model\.

    Returns a list of the differences between the actual data and the predicted
................................................................................

    and each point satisfies

        yi = b0 \+ b1 \* xi1 \+ b2 \* xi2 \+ \.\.\. \+ bN \* xiN \+ Residual\_i

    The procedure returns a list with the following elements:

      * The r\-squared statistic

      * The adjusted r\-squared statistic

      * A list containing the estimated coefficients b1, \.\.\. bN, b0 \(The
        constant b0 comes last in the list\.\)

      * A list containing the standard errors of the coefficients

      * A list containing the 95% confidence bounds of the coefficients, with
        each set of bounds returned as a list with two values

    Arguments:

      * list *weights\_and\_values*

        A list consisting of: the weight for the first observation, the data for
        the first observation \(as a sublist\), the weight for the second

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

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
The __mime__ library package provides the commands to create and manipulate
MIME body parts\.

  - <a name='1'></a>__::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* &#124; __\-string__ *value* &#124; __\-parts__ \{*token1* \.\.\. *tokenN*\}\)

    This command creates a MIME part and returns a token representing it\.

    If the __\-canonical__ option is present, then the body is in canonical
    \(raw\) form and is found by consulting either the __\-file__,
    __\-string__, or __\-parts__ option\.

    In addition, both the __\-param__ and __\-header__ options may occur
    zero or more times to specify __Content\-Type__ parameters \(e\.g\.,
    __charset__\) and header keyword/values \(e\.g\.,
    __Content\-Disposition__\), respectively\.

    Also, __\-encoding__, if present, specifies the
    __Content\-Transfer\-Encoding__ when copying the body\.

    If the __\-canonical__ option is not present, then the MIME part
    contained in either the __\-file__ or the __\-string__ option is
    parsed, dynamically generating subordinates as appropriate\.

  - <a name='2'></a>__::mime::finalize__ *token* ?__\-subordinates__ __all__ &#124; __dynamic__ &#124; __none__?

    This command destroys the MIME part represented by *token*\. It returns an
    empty string\.

    If the __\-subordinates__ option is present, it specifies which






|
|
|

|
|
|
|

|
|

|
|
|







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
The __mime__ library package provides the commands to create and manipulate
MIME body parts\.

  - <a name='1'></a>__::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* &#124; __\-string__ *value* &#124; __\-parts__ \{*token1* \.\.\. *tokenN*\}\)

    This command creates a MIME part and returns a token representing it\.

      * If the __\-canonical__ option is present, then the body is in
        canonical \(raw\) form and is found by consulting either the
        __\-file__, __\-string__, or __\-parts__ option\.

        In addition, both the __\-param__ and __\-header__ options may
        occur zero or more times to specify __Content\-Type__ parameters
        \(e\.g\., __charset__\) and header keyword/values \(e\.g\.,
        __Content\-Disposition__\), respectively\.

        Also, __\-encoding__, if present, specifies the
        __Content\-Transfer\-Encoding__ when copying the body\.

      * If the __\-canonical__ option is not present, then the MIME part
        contained in either the __\-file__ or the __\-string__ option is
        parsed, dynamically generating subordinates as appropriate\.

  - <a name='2'></a>__::mime::finalize__ *token* ?__\-subordinates__ __all__ &#124; __dynamic__ &#124; __none__?

    This command destroys the MIME part represented by *token*\. It returns an
    empty string\.

    If the __\-subordinates__ option is present, it specifies which

Changes to embedded/md/tcllib/files/modules/page/page_util_norm_peg.md.

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
    This command assumes the *tree* object contains for a parsing expression
    grammar\. It normalizes this tree in place\. The result is called a
    *Normalized PE Grammar Tree*\.

    The following operations are performd

    The data for all terminals is stored in their grandparental nodes\. The
    terminal nodes and their parents are removed\. Type information is dropped\.


    All nodes which have exactly one child are irrelevant and are removed, with
    the exception of the root node\. The immediate child of the root is
    irrelevant as well, and removed as well\.

    The name of the grammar is moved from the tree node it is stored in to an
    attribute of the root node, and the tree node removed\.

    The node keeping the start expression separate is removed as irrelevant and
    the root node of the start expression tagged with a marker attribute, and
    its handle saved in an attribute of the root node for quick access\.


    Nonterminal hint information is moved from nodes into attributes, and the
    now irrelevant nodes are deleted\.

    *Note:* This transformation is dependent on the removal of all nodes with
    exactly one child, as it removes the all 'Attribute' nodes already\.
    Otherwise this transformation would have to put the information into the
    grandparental node\.

    The default mode given to the nonterminals is __value__\.

    Like with the global metadata definition specific information is moved out
    out of nodes into attributes, the now irrelevant nodes are deleted, and the
    root nodes of all definitions are tagged with marker attributes\. This
    provides us with a mapping from nonterminal names to their defining nodes as
    well, which is saved in an attribute of the root node for quick reference\.


    At last the range in the input covered by a definition is computed\. The left
    extent comes from the terminal for the nonterminal symbol it defines\. The
    right extent comes from the rightmost child under the definition\. While this
    not an expression tree yet the location data is sound already\.


    The remaining nodes under all definitions are transformed into proper
    expression trees\. First character ranges, followed by unary operations,
    characters, and nonterminals\. At last the tree is flattened by the removal
    of superfluous inner nodes\.

    The order matters, to shed as much nodes as possible early, and to avoid
    unnecessary work later\.

# <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 *page* 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\.






|
|
>

|
|
|

|
|

|
|
|
>

|
|

|
|
|
|

|

|
|
|
|
|
>

|
|
|
|
>

|
|
|
|

|
|







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
    This command assumes the *tree* object contains for a parsing expression
    grammar\. It normalizes this tree in place\. The result is called a
    *Normalized PE Grammar Tree*\.

    The following operations are performd

      1. The data for all terminals is stored in their grandparental nodes\. The
         terminal nodes and their parents are removed\. Type information is
         dropped\.

      1. All nodes which have exactly one child are irrelevant and are removed,
         with the exception of the root node\. The immediate child of the root is
         irrelevant as well, and removed as well\.

      1. The name of the grammar is moved from the tree node it is stored in to
         an attribute of the root node, and the tree node removed\.

         The node keeping the start expression separate is removed as irrelevant
         and the root node of the start expression tagged with a marker
         attribute, and its handle saved in an attribute of the root node for
         quick access\.

      1. Nonterminal hint information is moved from nodes into attributes, and
         the now irrelevant nodes are deleted\.

         *Note:* This transformation is dependent on the removal of all nodes
         with exactly one child, as it removes the all 'Attribute' nodes
         already\. Otherwise this transformation would have to put the
         information into the grandparental node\.

         The default mode given to the nonterminals is __value__\.

         Like with the global metadata definition specific information is moved
         out out of nodes into attributes, the now irrelevant nodes are deleted,
         and the root nodes of all definitions are tagged with marker
         attributes\. This provides us with a mapping from nonterminal names to
         their defining nodes as well, which is saved in an attribute of the
         root node for quick reference\.

         At last the range in the input covered by a definition is computed\. The
         left extent comes from the terminal for the nonterminal symbol it
         defines\. The right extent comes from the rightmost child under the
         definition\. While this not an expression tree yet the location data is
         sound already\.

      1. The remaining nodes under all definitions are transformed into proper
         expression trees\. First character ranges, followed by unary operations,
         characters, and nonterminals\. At last the tree is flattened by the
         removal of superfluous inner nodes\.

         The order matters, to shed as much nodes as possible early, and to
         avoid unnecessary work later\.

# <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 *page* 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/pki/pki.md.

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
    specified multiple times, the last one specified is used\. The input to
    encrypt is specified as *input*\. The *key* parameter, holding the key to
    use, is a return value from either __::pki::pkcs::parse\_key__,
    __::pki::x509::parse\_cert__, or __::pki::rsa::generate__\.

    Mapping to OpenSSL's __openssl__ application:

    "openssl rsautl \-encrypt" == "::pki::encrypt \-binary \-pub"

    "openssl rsautl \-sign" == "::pki::encrypt \-binary \-priv"

  - <a name='2'></a>__::pki::decrypt__ ?*\-binary*? ?*\-hex*? ?*\-unpad*? ?*\-nounpad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key*

    Decrypt a message using PKI \(probably RSA\)\. See __::pki::encrypt__ for
    option handling\.

    Mapping to OpenSSL's __openssl__ application:

    "openssl rsautl \-decrypt" == "::pki::decrypt \-binary \-priv"

    "openssl rsautl \-verify" == "::pki::decrypt \-binary \-pub"

  - <a name='3'></a>__::pki::sign__ *input* *key* ?*algo*?

    Digitally sign message *input* using the private *key*\. If *algo* is
    ommited "sha1" is assumed\. Possible values for *algo* include "md5",
    "sha1", "sha256", and "raw"\. Specifyin "raw" for *algo* will inhibit the
    building of an ASN\.1 structure to encode which hashing algorithm was chosen\.






|

|








|

|







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
    specified multiple times, the last one specified is used\. The input to
    encrypt is specified as *input*\. The *key* parameter, holding the key to
    use, is a return value from either __::pki::pkcs::parse\_key__,
    __::pki::x509::parse\_cert__, or __::pki::rsa::generate__\.

    Mapping to OpenSSL's __openssl__ application:

      1. "openssl rsautl \-encrypt" == "::pki::encrypt \-binary \-pub"

      1. "openssl rsautl \-sign" == "::pki::encrypt \-binary \-priv"

  - <a name='2'></a>__::pki::decrypt__ ?*\-binary*? ?*\-hex*? ?*\-unpad*? ?*\-nounpad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key*

    Decrypt a message using PKI \(probably RSA\)\. See __::pki::encrypt__ for
    option handling\.

    Mapping to OpenSSL's __openssl__ application:

      1. "openssl rsautl \-decrypt" == "::pki::decrypt \-binary \-priv"

      1. "openssl rsautl \-verify" == "::pki::decrypt \-binary \-pub"

  - <a name='3'></a>__::pki::sign__ *input* *key* ?*algo*?

    Digitally sign message *input* using the private *key*\. If *algo* is
    ommited "sha1" is assumed\. Possible values for *algo* include "md5",
    "sha1", "sha256", and "raw"\. Specifyin "raw" for *algo* will inhibit the
    building of an ASN\.1 structure to encode which hashing algorithm was chosen\.

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

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
...
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
    applicable plugins and their API\.

  - <a name='2'></a>__::pluginmgr::paths__ *objectName* *name*\.\.\.

    This utility command adds a set of paths to the specified object, based on
    the given *name*s\. It will search for:

    The environment variable __*name*\_PLUGINS__\. Its contents will be
    interpreted as a list of package paths\. The entries have to be separated by
    either __:__ \(unix\) or __;__ \(windows\)\.

    The name will be converted to upper\-case letters\.

    The registry entry "HKEY\_LOCAL\_MACHINE\\SOFTWARE\\*name*\\PLUGINS"\. Its
    contents will be interpreted as a list of package paths\. The entries have to
    be separated by __;__\. This item is considered only when on Windows
    \(tm\)\.

    The casing of letters is not changed\.

    The registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\*name*\\PLUGINS"\. Its
    contents will be interpreted as a list of package paths\. The entries have to
    be separated by __;__\. This item is considered only when on Windows
    \(tm\)\.

    The casing of letters is not changed\.

    The directory "~/\.*name*/plugin"\.

    The directory "~/\.*name*/plugins"\.

    The casing of letters is not changed\.

    and add all the paths found that way to the list of package paths maintained
    by the object\.

    If *name* is namespaced each item in the list will be repeated per prefix
    of *name*, with conversion of :\-sequences into the proper separator
    \(underscore for environment variables, backslash for registry entries, and /
................................................................................
  - <a name='13'></a>*objectName* __load__ *string*

    This method loads, validates, and initializes a named plugin into the
    manager object\.

    The algorithm to locate and load the plugin employed is:

    If the *string* contains the path to an existing file then this file is
    taken as the implementation of the plugin\.

    Otherwise the plugin name is translated into a package name via the value of
    the option __\-pattern__ and then loaded through the regular package
    management\.

    The load fails\.

    The algorithm to validate and initialize the loaded code is:

    If the option __\-api__ is non\-empty introspection commands are used to
    ascertain that the plugin provides the listed commands\.

    If the option __\-check__ is non\-empty the specified command prefix is
    called\.

    If either of the above fails the candidate plugin is unloaded again

    Otherwise all the commands specified via the option __\-cmds__ are
    installed in the plugin\.

    A previously loaded plugin is discarded, but only if the new plugin was
    found and sucessfully validated and initialized\. Note that there will be no
    intereference between old and new plugin as both will be put into separate
    safe interpreters\.

  - <a name='14'></a>*objectName* __unload__






|
|
|

|

|
|
|
|

|

|
|
|
|

|

|

|

|







 







|
|

|
|
|

|



|
|

|
|

|

|
|







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
...
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
    applicable plugins and their API\.

  - <a name='2'></a>__::pluginmgr::paths__ *objectName* *name*\.\.\.

    This utility command adds a set of paths to the specified object, based on
    the given *name*s\. It will search for:

      1. The environment variable __*name*\_PLUGINS__\. Its contents will be
         interpreted as a list of package paths\. The entries have to be
         separated by either __:__ \(unix\) or __;__ \(windows\)\.

         The name will be converted to upper\-case letters\.

      1. The registry entry "HKEY\_LOCAL\_MACHINE\\SOFTWARE\\*name*\\PLUGINS"\. Its
         contents will be interpreted as a list of package paths\. The entries
         have to be separated by __;__\. This item is considered only when on
         Windows \(tm\)\.

         The casing of letters is not changed\.

      1. The registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\*name*\\PLUGINS"\. Its
         contents will be interpreted as a list of package paths\. The entries
         have to be separated by __;__\. This item is considered only when on
         Windows \(tm\)\.

         The casing of letters is not changed\.

      1. The directory "~/\.*name*/plugin"\.

      1. The directory "~/\.*name*/plugins"\.

         The casing of letters is not changed\.

    and add all the paths found that way to the list of package paths maintained
    by the object\.

    If *name* is namespaced each item in the list will be repeated per prefix
    of *name*, with conversion of :\-sequences into the proper separator
    \(underscore for environment variables, backslash for registry entries, and /
................................................................................
  - <a name='13'></a>*objectName* __load__ *string*

    This method loads, validates, and initializes a named plugin into the
    manager object\.

    The algorithm to locate and load the plugin employed is:

      1. If the *string* contains the path to an existing file then this file
         is taken as the implementation of the plugin\.

      1. Otherwise the plugin name is translated into a package name via the
         value of the option __\-pattern__ and then loaded through the
         regular package management\.

      1. The load fails\.

    The algorithm to validate and initialize the loaded code is:

      1. If the option __\-api__ is non\-empty introspection commands are used
         to ascertain that the plugin provides the listed commands\.

      1. If the option __\-check__ is non\-empty the specified command prefix
         is called\.

      1. If either of the above fails the candidate plugin is unloaded again

      1. Otherwise all the commands specified via the option __\-cmds__ are
         installed in the plugin\.

    A previously loaded plugin is discarded, but only if the new plugin was
    found and sucessfully validated and initialized\. Note that there will be no
    intereference between old and new plugin as both will be put into separate
    safe interpreters\.

  - <a name='14'></a>*objectName* __unload__

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

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
We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

    The serialization of any AST is the serialization of its root node\.

    The serialization of any node is a Tcl list containing at least three
    elements\.

    The first element is the name of the nonterminal symbol stored in the node\.


    The second and third element are the locations of the first and last token
    in the token stream the node represents \(covers\)\.

    Locations are provided as non\-negative integer offsets from the beginning of
    the token stream, with the first token found in the stream located at offset
    0 \(zero\)\.

    The end location has to be equal to or larger than the start location\.


    All elements after the first three represent the children of the node, which
    are themselves nodes\. This means that the serializations of nodes without

    children, i\.e\. leaf nodes, have exactly three elements\. The children are
    stored in the list with the leftmost child first, and the rightmost child
    last\.

  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;






|

|
|

|
>

|
|

|
|
|

|
>

|
|
>
|
|
<








|
|







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
We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

      1. The serialization of any AST is the serialization of its root node\.

      1. The serialization of any node is a Tcl list containing at least three
         elements\.

           1) The first element is the name of the nonterminal symbol stored in
              the node\.

           1) The second and third element are the locations of the first and
              last token in the token stream the node represents \(covers\)\.

                1. Locations are provided as non\-negative integer offsets from
                   the beginning of the token stream, with the first token found
                   in the stream located at offset 0 \(zero\)\.

                1. The end location has to be equal to or larger than the start
                   location\.

           1) All elements after the first three represent the children of the
              node, which are themselves nodes\. This means that the
              serializations of nodes without children, i\.e\. leaf nodes, have
              exactly three elements\. The children are stored in the list with
              the leftmost child first, and the rightmost child last\.


  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;

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

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
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
...
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
...
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
           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

         A boolean flag indicating the success \(__True__\) or failure
         \(__False__\) of the operation\.

         In case of success the contents of the included file, and the empty
         string otherwise\.

         The resolved, i\.e\. absolute path of the included file, if possible, or
         the unchanged *path* argument\. This is for display in an error
         message, or as the *currentfile* argument of another call to
         __IncludeFile__ should this file contain more files\.

         In case of success an empty string, and for failure a code indicating
         the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

         An empty string in case of success of a __notfound__ failure, and
         an additional error message describing the reason for a __notread__
         error in more detail\.

  1. A plugin has to provide a single command, in the global namespace, with the
     signature shown below\. Plugins are allowed to provide more commands of
     their own, but not less, and they may not provide different semantics for
     the standardized command\.

       - <a name='3'></a>__::import__ *text*
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|
|

|
|

|
|
|
|

|
|









|
|
|







 







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
...
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
           * string *path*

             The path of the include file as specified in the include directive
             being processed\.

         The result of the command will be a 5\-element list containing

           1) A boolean flag indicating the success \(__True__\) or failure
              \(__False__\) of the operation\.

           1) In case of success the contents of the included file, and the
              empty string otherwise\.

           1) The resolved, i\.e\. absolute path of the included file, if
              possible, or the unchanged *path* argument\. This is for display
              in an error message, or as the *currentfile* argument of another
              call to __IncludeFile__ should this file contain more files\.

           1) In case of success an empty string, and for failure a code
              indicating the reason for it, one of

                * notfound

                  The specified file could not be found\.

                * notread

                  The specified file was found, but not be read into memory\.

           1) An empty string in case of success of a __notfound__ failure,
              and an additional error message describing the reason for a
              __notread__ error in more detail\.

  1. A plugin has to provide a single command, in the global namespace, with the
     signature shown below\. Plugins are allowed to provide more commands of
     their own, but not less, and they may not provide different semantics for
     the standardized command\.

       - <a name='3'></a>__::import__ *text*
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
...
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
...
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
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

         The value for each symbol is a JSON object itself\. The relevant keys
         and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section3)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section3)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section3)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|

|
|







 







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
...
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
...
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
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

           1) Each nonterminal symbol may occur only once\.

           1) The empty string is not a legal nonterminal symbol\.

           1) The value for each symbol is a JSON object itself\. The relevant
              keys and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section3)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section3)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section3)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
  - __error\_pop\_merge__

    This instruction takes the topmost entry of ES and merges the error status
    it contains with ES, making the result the new ES\.

    The merge is governed by four rules, with the merge result

    Empty if both states are empty\.

    The non\-empty state if only one of the two states is non\-empty\.

    The state with the larger location, if the two states specify different
    locations\.

    The pair of the location shared by the two states, and the set\-union of
    their messages for states at the same location\.

  - __error\_nonterminal__ *symbol*

    This is a guarded instruction\. It does nothing if either ES is empty, or if
    the location in ES is not just past the last location saved in LS\. Otherwise
    it sets the pair of that location and the nonterminal *symbol* as the new
    ES\.






|

|

|
|

|
|







423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
  - __error\_pop\_merge__

    This instruction takes the topmost entry of ES and merges the error status
    it contains with ES, making the result the new ES\.

    The merge is governed by four rules, with the merge result

      1. Empty if both states are empty\.

      1. The non\-empty state if only one of the two states is non\-empty\.

      1. The state with the larger location, if the two states specify different
         locations\.

      1. The pair of the location shared by the two states, and the set\-union of
         their messages for states at the same location\.

  - __error\_nonterminal__ *symbol*

    This is a guarded instruction\. It does nothing if either ES is empty, or if
    the location in ES is not just past the last location saved in LS\. Otherwise
    it sets the pair of that location and the nonterminal *symbol* as the new
    ES\.

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

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
    for validation of the tree's basic structure, printing it for debugging, and
    walking it either from the bottom up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

    The string __pt::rde__ identifying it as parser runtime error\.

    The location of the parse error, as character offset from the beginning of
    the parsed input\.

    The location of parse error, now as a 2\-element list containing line\-number
    and column in the line\.

    A set of atomic parsing expressions indicating encoding the characters
    and/or nonterminal symbols the parser expected to see at the location of the
    parse error, but did not get\. For the specification of atomic parsing
    expressions please see the section __PE serialization format__\.


  - <a name='4'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

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






|

|
|

|
|

|
|
|
|
>







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
    for validation of the tree's basic structure, printing it for debugging, and
    walking it either from the bottom up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

      1. The string __pt::rde__ identifying it as parser runtime error\.

      1. The location of the parse error, as character offset from the beginning
         of the parsed input\.

      1. The location of parse error, now as a 2\-element list containing
         line\-number and column in the line\.

      1. A set of atomic parsing expressions indicating encoding the characters
         and/or nonterminal symbols the parser expected to see at the location
         of the parse error, but did not get\. For the specification of atomic
         parsing expressions please see the section __PE serialization
         format__\.

  - <a name='4'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

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

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

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
...
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
...
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
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
    structure, printing it for debugging, and walking it either from the bottom
    up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

    The string __pt::rde__ identifying it as parser runtime error\.

    The location of the parse error, as character offset from the beginning of
    the parsed input\.

    The location of parse error, now as a 2\-element list containing line\-number
    and column in the line\.

    A set of atomic parsing expressions indicating encoding the characters
    and/or nonterminal symbols the parser expected to see at the location of the
    parse error, but did not get\. For the specification of atomic parsing
    expressions please see the section [PE serialization
    format](#section6)\.

  - <a name='4'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

# <a name='section4'></a>Usage
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

    The serialization of any AST is the serialization of its root node\.

    The serialization of any node is a Tcl list containing at least three
    elements\.

    The first element is the name of the nonterminal symbol stored in the node\.


    The second and third element are the locations of the first and last token
    in the token stream the node represents \(covers\)\.

    Locations are provided as non\-negative integer offsets from the beginning of
    the token stream, with the first token found in the stream located at offset
    0 \(zero\)\.

    The end location has to be equal to or larger than the start location\.


    All elements after the first three represent the children of the node, which
    are themselves nodes\. This means that the serializations of nodes without

    children, i\.e\. leaf nodes, have exactly three elements\. The children are
    stored in the list with the leftmost child first, and the rightmost child
    last\.

  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|

|
|
|
|
|







 







|

|
|

|
>

|
|

|
|
|

|
>

|
|
>
|
|
<








|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
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
    structure, printing it for debugging, and walking it either from the bottom
    up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

      1. The string __pt::rde__ identifying it as parser runtime error\.

      1. The location of the parse error, as character offset from the beginning
         of the parsed input\.

      1. The location of parse error, now as a 2\-element list containing
         line\-number and column in the line\.

      1. A set of atomic parsing expressions indicating encoding the characters
         and/or nonterminal symbols the parser expected to see at the location
         of the parse error, but did not get\. For the specification of atomic
         parsing expressions please see the section [PE serialization
         format](#section6)\.

  - <a name='4'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

# <a name='section4'></a>Usage
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

      1. The serialization of any AST is the serialization of its root node\.

      1. The serialization of any node is a Tcl list containing at least three
         elements\.

           1) The first element is the name of the nonterminal symbol stored in
              the node\.

           1) The second and third element are the locations of the first and
              last token in the token stream the node represents \(covers\)\.

                1. Locations are provided as non\-negative integer offsets from
                   the beginning of the token stream, with the first token found
                   in the stream located at offset 0 \(zero\)\.

                1. The end location has to be equal to or larger than the start
                   location\.

           1) All elements after the first three represent the children of the
              node, which are themselves nodes\. This means that the
              serializations of nodes without children, i\.e\. leaf nodes, have
              exactly three elements\. The children are stored in the list with
              the leftmost child first, and the rightmost child last\.


  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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

548
549
550
551
552
553
554
555

556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573

574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section3)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section3)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection3'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

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

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574

575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section3)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section3)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection3'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

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

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
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
318
319
320
321
322
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

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

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection5'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
318
319
320
321
322
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

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

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection5'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
...
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
...
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
318
...
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
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

         The value for each symbol is a JSON object itself\. The relevant keys
         and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section6)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|

|
|







 







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
...
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
318
...
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
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

           1) Each nonterminal symbol may occur only once\.

           1) The empty string is not a legal nonterminal symbol\.

           1) The value for each symbol is a JSON object itself\. The relevant
              keys and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section6)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
...
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
...
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

         The value for each symbol is a JSON object itself\. The relevant keys
         and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section5)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|

|
|







 







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
...
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
...
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

           1) Each nonterminal symbol may occur only once\.

           1) The empty string is not a legal nonterminal symbol\.

           1) The value for each symbol is a JSON object itself\. The relevant
              keys and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section5)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

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

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection5'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

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

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection5'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
...
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
...
316
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
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

         The value for each symbol is a JSON object itself\. The relevant keys
         and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section5)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|

|
|







 







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
...
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
...
316
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
...
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
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

           1) Each nonterminal symbol may occur only once\.

           1) The empty string is not a legal nonterminal symbol\.

           1) The value for each symbol is a JSON object itself\. The relevant
              keys and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section5)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section5)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section5)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
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
...
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
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
    structure, printing it for debugging, and walking it either from the bottom
    up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

    The string __pt::rde__ identifying it as parser runtime error\.

    The location of the parse error, as character offset from the beginning of
    the parsed input\.

    The location of parse error, now as a 2\-element list containing line\-number
    and column in the line\.

    A set of atomic parsing expressions indicating encoding the characters
    and/or nonterminal symbols the parser expected to see at the location of the
    parse error, but did not get\. For the specification of atomic parsing
    expressions please see the section [PE serialization
    format](#section3)\.

  - <a name='5'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

# <a name='section2'></a>AST serialization format
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

    The serialization of any AST is the serialization of its root node\.

    The serialization of any node is a Tcl list containing at least three
    elements\.

    The first element is the name of the nonterminal symbol stored in the node\.


    The second and third element are the locations of the first and last token
    in the token stream the node represents \(covers\)\.

    Locations are provided as non\-negative integer offsets from the beginning of
    the token stream, with the first token found in the stream located at offset
    0 \(zero\)\.

    The end location has to be equal to or larger than the start location\.


    All elements after the first three represent the children of the node, which
    are themselves nodes\. This means that the serializations of nodes without

    children, i\.e\. leaf nodes, have exactly three elements\. The children are
    stored in the list with the leftmost child first, and the rightmost child
    last\.

  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection3'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

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

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|

|
|
|
|
|







 







|

|
|

|
>

|
|

|
|
|

|
>

|
|
>
|
|
<








|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
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
    structure, printing it for debugging, and walking it either from the bottom
    up, or top down\.

    When encountering a syntax error the command will throw an error instead\.
    This error will be a 4\-element Tcl\-list, containing, in the order listed
    below:

      1. The string __pt::rde__ identifying it as parser runtime error\.

      1. The location of the parse error, as character offset from the beginning
         of the parsed input\.

      1. The location of parse error, now as a 2\-element list containing
         line\-number and column in the line\.

      1. A set of atomic parsing expressions indicating encoding the characters
         and/or nonterminal symbols the parser expected to see at the location
         of the parse error, but did not get\. For the specification of atomic
         parsing expressions please see the section [PE serialization
         format](#section3)\.

  - <a name='5'></a>*objectName* __parset__ *text*

    This method runs the parser using the string in *text* as input\. In all
    other ways it behaves like the method __parse__, shown above\.

# <a name='section2'></a>AST serialization format
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a
tree may have more than one regular serialization only exactly one of them will
be *canonical*\.

  - Regular serialization

      1. The serialization of any AST is the serialization of its root node\.

      1. The serialization of any node is a Tcl list containing at least three
         elements\.

           1) The first element is the name of the nonterminal symbol stored in
              the node\.

           1) The second and third element are the locations of the first and
              last token in the token stream the node represents \(covers\)\.

                1. Locations are provided as non\-negative integer offsets from
                   the beginning of the token stream, with the first token found
                   in the stream located at offset 0 \(zero\)\.

                1. The end location has to be equal to or larger than the start
                   location\.

           1) All elements after the first three represent the children of the
              node, which are themselves nodes\. This means that the
              serializations of nodes without children, i\.e\. leaf nodes, have
              exactly three elements\. The children are stored in the list with
              the leftmost child first, and the rightmost child last\.


  - Canonical serialization

    The canonical serialization of an abstract syntax tree has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this tree\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection3'></a>Example

Assuming the parsing expression grammar below

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

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

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
    package __[pt::peg::container](pt\_peg\_container\.md)__\.

  - <a name='7'></a>__::peg::peg::op__ __modeopt__ *container*

    This command optimizes the semantic modes of non\-terminal symbols according
    to the two rules below\.

    If a symbol X with mode __value__ calls no other symbols, i\.e\. uses only
    terminal symbols in whatever combination, then this can be represented
    simpler by using mode __leaf__\.

    If a symbol X is only called from symbols with modes __leaf__ or
    __void__ then this symbol should have mode __void__ also, as any AST
    it could generate will be discarded anyway\.

    The result of the command is the empty string\.

    The grammar in the container is directly modified\. If that is not wanted, a
    copy of the original container has to be used\.

    The *container* instance has to expose a method API as is provided by the






|
|
|

|
|
|







158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
    package __[pt::peg::container](pt\_peg\_container\.md)__\.

  - <a name='7'></a>__::peg::peg::op__ __modeopt__ *container*

    This command optimizes the semantic modes of non\-terminal symbols according
    to the two rules below\.

      1. If a symbol X with mode __value__ calls no other symbols, i\.e\. uses
         only terminal symbols in whatever combination, then this can be
         represented simpler by using mode __leaf__\.

      1. If a symbol X is only called from symbols with modes __leaf__ or
         __void__ then this symbol should have mode __void__ also, as
         any AST it could generate will be discarded anyway\.

    The result of the command is the empty string\.

    The grammar in the container is directly modified\. If that is not wanted, a
    copy of the original container has to be used\.

    The *container* instance has to expose a method API as is provided by the

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

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
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

316
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
...
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
...
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
548
549
550
551
552
553
554
555
556
557
558
559
560
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







316
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
...
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
...
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
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
...
315
316
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
...
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
...
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
548
549
550
551
552
553
554
555
556
557
558
559
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

         Each nonterminal symbol may occur only once\.

         The empty string is not a legal nonterminal symbol\.

         The value for each symbol is a JSON object itself\. The relevant keys
         and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section6)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|

|
|







 







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
...
315
316
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
...
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
...
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
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
     their values are

       - __rules__

         The value is a JSON object whose keys are the names of the nonterminal
         symbols known to the grammar\.

           1) Each nonterminal symbol may occur only once\.

           1) The empty string is not a legal nonterminal symbol\.

           1) The value for each symbol is a JSON object itself\. The relevant
              keys and their values in this dictionary are

                * __is__

                  The value is a JSON string holding the Tcl serialization of
                  the parsing expression describing the symbols sentennial
                  structure, as specified in the section [PE serialization
                  format](#section6)\.
................................................................................

We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
....
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
....
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117

1118
1119
1120
1121
1122
1123
1124
1125

1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143

1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178

1179
1180
1181

1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
....
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
....
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144

1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
...
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
...
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
548
549
550
551
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection2'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection3'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
318
319
320
321
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
318
319
320
321
...
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
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section6)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section6)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
...
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
...
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
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
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
...
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
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section4)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section4)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

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
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection1'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
...
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

    The serialization of any PEG is a nested Tcl dictionary\.

    This dictionary holds a single key, __pt::grammar::peg__, and its value\.
    This value holds the contents of the grammar\.

    The contents of the grammar are a Tcl dictionary holding the set of
    nonterminal symbols and the starting expression\. The relevant keys and their
    values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

             Each nonterminal symbol may occur only once\.

             The empty string is not a legal nonterminal symbol\.

             The value for each symbol is a Tcl dictionary itself\. The relevant
             keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section7)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section7)\.

    The terminal symbols of the grammar are specified implicitly as the set of
    all terminal symbols used in the start expression and on the RHS of the
    grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

    The keys found in all the nested Tcl dictionaries are sorted in ascending
    dictionary order, as generated by Tcl's builtin command __lsort
    \-increasing \-dict__\.

    The string representation of the value is the canonical representation of a
    Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

        The string __epsilon__ is an atomic parsing expression\. It matches
        the empty string\.

        The string __dot__ is an atomic parsing expression\. It matches any
        character\.

        The string __alnum__ is an atomic parsing expression\. It matches any
        Unicode alphabet or digit character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __alpha__ is an atomic parsing expression\. It matches any
        Unicode alphabet character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __ascii__ is an atomic parsing expression\. It matches any
        Unicode character below U0080\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __control__ is an atomic parsing expression\. It matches
        any Unicode control character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __digit__ is an atomic parsing expression\. It matches any
        Unicode digit character\. Note that this includes characters outside of
        the \[0\.\.9\] range\. This is a custom extension of PEs based on Tcl's
        builtin command __string is__\.

        The string __graph__ is an atomic parsing expression\. It matches any
        Unicode printing character, except for space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __lower__ is an atomic parsing expression\. It matches any
        Unicode lower\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __print__ is an atomic parsing expression\. It matches any
        Unicode printing character, including space\. This is a custom extension
        of PEs based on Tcl's builtin command __string is__\.


        The string __punct__ is an atomic parsing expression\. It matches any
        Unicode punctuation character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __space__ is an atomic parsing expression\. It matches any
        Unicode space character\. This is a custom extension of PEs based on
        Tcl's builtin command __string is__\.

        The string __upper__ is an atomic parsing expression\. It matches any
        Unicode upper\-case alphabet character\. This is a custom extension of PEs
        based on Tcl's builtin command __string is__\.

        The string __wordchar__ is an atomic parsing expression\. It matches
        any Unicode word character\. This is any alphanumeric character \(see
        alnum\), and any connector punctuation characters \(e\.g\. underscore\)\. This
        is a custom extension of PEs based on Tcl's builtin command __string
        is__\.


        The string __xdigit__ is an atomic parsing expression\. It matches
        any hexadecimal digit character\. This is a custom extension of PEs based
        on Tcl's builtin command __string is__\.

        The string __ddigit__ is an atomic parsing expression\. It matches
        any decimal digit character\. This is a custom extension of PEs based on
        Tcl's builtin command __regexp__\.

        The expression \[list t __x__\] is an atomic parsing expression\. It
        matches the terminal string __x__\.

        The expression \[list n __A__\] is an atomic parsing expression\. It
        matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        / __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *ordered choice*, aka *prioritized choice*\.

        For parsing expressions __e1__, __e2__, \.\.\. the result of \[list
        x __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is
        the *sequence*\.

        For a parsing expression __e__ the result of \[list \* __e__\] is a
        parsing expression as well\. This is the *kleene closure*, describing
        zero or more repetitions\.

        For a parsing expression __e__ the result of \[list \+ __e__\] is a
        parsing expression as well\. This is the *positive kleene closure*,
        describing one or more repetitions\.

        For a parsing expression __e__ the result of \[list & __e__\] is a
        parsing expression as well\. This is the *and lookahead predicate*\.


        For a parsing expression __e__ the result of \[list \! __e__\] is a
        parsing expression as well\. This is the *not lookahead predicate*\.


        For a parsing expression __e__ the result of \[list ? __e__\] is a
        parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

    The string representation of the value is the canonical representation of a
    pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

    Terminals are *not* encoded as ranges \(where start and end of the range
    are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*







|

|
|

|
|
|






|

|

|
|







 







|
|
|







|
|
|

|
|







 







|
|

|
|

|
|
|

|
|
|

|
|
|

|
|
|

|
|
|
|

|
|
|
>

|
|
|

|
|
|
>

|
|
|

|
|
|

|
|
|

|
|
|
|
<
>

|
|
|

|
|
|

|
|

|
|



|
|
|

|
|
|

|
|
|

|
|
|

|
|
>

|
|
>

|
|








|
|

|
|







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
...
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
...
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
We distinguish between *regular* and *canonical* serializations\. While a PEG
may have more than one regular serialization only exactly one of them will be
*canonical*\.

  - regular serialization

      1. The serialization of any PEG is a nested Tcl dictionary\.

      1. This dictionary holds a single key, __pt::grammar::peg__, and its
         value\. This value holds the contents of the grammar\.

      1. The contents of the grammar are a Tcl dictionary holding the set of
         nonterminal symbols and the starting expression\. The relevant keys and
         their values are

           * __rules__

             The value is a Tcl dictionary whose keys are the names of the
             nonterminal symbols known to the grammar\.

               1) Each nonterminal symbol may occur only once\.

               1) The empty string is not a legal nonterminal symbol\.

               1) The value for each symbol is a Tcl dictionary itself\. The
                  relevant keys and their values in this dictionary are

                    + __is__

                      The value is the serialization of the parsing expression
                      describing the symbols sentennial structure, as specified
                      in the section [PE serialization format](#section7)\.

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

           * __start__

             The value is the serialization of the start parsing expression of
             the grammar, as specified in the section [PE serialization
             format](#section7)\.

      1. The terminal symbols of the grammar are specified implicitly as the set
         of all terminal symbols used in the start expression and on the RHS of
         the grammar rules\.

  - canonical serialization

    The canonical serialization of a grammar has the format as specified in the
    previous item, and then additionally satisfies the constraints below, which
    make it unique among all the possible serializations of this grammar\.

      1. The keys found in all the nested Tcl dictionaries are sorted in
         ascending dictionary order, as generated by Tcl's builtin command
         __lsort \-increasing \-dict__\.

      1. The string representation of the value is the canonical representation
         of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\.

## <a name='subsection1'></a>Example

Assuming the following PEG for simple mathematical expressions

    PEG calculator \(Expression\)
        Digit      <\- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
................................................................................
parsing expression may have more than one regular serialization only exactly one
of them will be *canonical*\.

  - Regular serialization

      * __Atomic Parsing Expressions__

          1. The string __epsilon__ is an atomic parsing expression\. It
             matches the empty string\.

          1. The string __dot__ is an atomic parsing expression\. It matches
             any character\.

          1. The string __alnum__ is an atomic parsing expression\. It
             matches any Unicode alphabet or digit character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __alpha__ is an atomic parsing expression\. It
             matches any Unicode alphabet character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ascii__ is an atomic parsing expression\. It
             matches any Unicode character below U0080\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __control__ is an atomic parsing expression\. It
             matches any Unicode control character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __digit__ is an atomic parsing expression\. It
             matches any Unicode digit character\. Note that this includes
             characters outside of the \[0\.\.9\] range\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __graph__ is an atomic parsing expression\. It
             matches any Unicode printing character, except for space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __lower__ is an atomic parsing expression\. It
             matches any Unicode lower\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __print__ is an atomic parsing expression\. It
             matches any Unicode printing character, including space\. This is a
             custom extension of PEs based on Tcl's builtin command __string
             is__\.

          1. The string __punct__ is an atomic parsing expression\. It
             matches any Unicode punctuation character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __space__ is an atomic parsing expression\. It
             matches any Unicode space character\. This is a custom extension of
             PEs based on Tcl's builtin command __string is__\.

          1. The string __upper__ is an atomic parsing expression\. It
             matches any Unicode upper\-case alphabet character\. This is a custom
             extension of PEs based on Tcl's builtin command __string is__\.

          1. The string __wordchar__ is an atomic parsing expression\. It
             matches any Unicode word character\. This is any alphanumeric
             character \(see alnum\), and any connector punctuation characters
             \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's

             builtin command __string is__\.

          1. The string __xdigit__ is an atomic parsing expression\. It
             matches any hexadecimal digit character\. This is a custom extension
             of PEs based on Tcl's builtin command __string is__\.

          1. The string __ddigit__ is an atomic parsing expression\. It
             matches any decimal digit character\. This is a custom extension of
             PEs based on Tcl's builtin command __regexp__\.

          1. The expression \[list t __x__\] is an atomic parsing expression\.
             It matches the terminal string __x__\.

          1. The expression \[list n __A__\] is an atomic parsing expression\.
             It matches the nonterminal __A__\.

      * __Combined Parsing Expressions__

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *ordered choice*, aka *prioritized choice*\.

          1. For parsing expressions __e1__, __e2__, \.\.\. the result of
             \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as
             well\. This is the *sequence*\.

          1. For a parsing expression __e__ the result of \[list \* __e__\]
             is a parsing expression as well\. This is the *kleene closure*,
             describing zero or more repetitions\.

          1. For a parsing expression __e__ the result of \[list \+ __e__\]
             is a parsing expression as well\. This is the *positive kleene
             closure*, describing one or more repetitions\.

          1. For a parsing expression __e__ the result of \[list & __e__\]
             is a parsing expression as well\. This is the *and lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list \! __e__\]
             is a parsing expression as well\. This is the *not lookahead
             predicate*\.

          1. For a parsing expression __e__ the result of \[list ? __e__\]
             is a parsing expression as well\. This is the *optional input*\.

  - Canonical serialization

    The canonical serialization of a parsing expression has the format as
    specified in the previous item, and then additionally satisfies the
    constraints below, which make it unique among all the possible
    serializations of this parsing expression\.

      1. The string representation of the value is the canonical representation
         of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\.

      1. Terminals are *not* encoded as ranges \(where start and end of the
         range are identical\)\.

## <a name='subsection2'></a>Example

Assuming the parsing expression shown on the right\-hand side of the rule

    Expression <\- Term \(AddOp Term\)\*

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

927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
...
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
            types \(e\.g\., stacks and queues\) more efficient\.

            If false \(the default\), instance methods are dispatched normally\. If
            true, a faster dispatching scheme is used instead\. The speed comes
            at a price; with __\-simpledispatch yes__ you get the following
            limitations:

            Methods cannot be delegated\.

            __uplevel__ and __upvar__ do not work as expected: the
            caller's scope is two levels up rather than one\.

            The option\-handling methods \(__cget__, __configure__, and
            __configurelist__\) are very slightly slower\.

      * <a name='25'></a>__expose__ *comp*

      * <a name='26'></a>__expose__ *comp* __as__ *method*

        __Deprecated\.__ To expose component *comp* publicly, use
        __component__'s __\-public__ option\.
................................................................................

  - <a name='29'></a>__snit::widget__ *name* *definition*

    This command defines a Snit megawidget type with the specified *name*\. The
    *definition* is defined as for __snit::type__\. A __snit::widget__
    differs from a __snit::type__ in these ways:

    Every instance of a __snit::widget__ has an automatically\-created
    component called __hull__, which is normally a Tk frame widget\. Other
    widgets created as part of the megawidget will be created within this
    widget\.

    The hull component is initially created with the requested widget name; then
    Snit does some magic, renaming the hull component and installing its own
    instance command in its place\. The hull component's new name is saved in an
    instance variable called __hull__\.

    The name of an instance must be valid Tk window name, and the parent window
    must exist\.

    A __snit::widget__ definition can include any of statements allowed in a
    __snit::type__ definition, and may also include the following:

      * <a name='30'></a>__widgetclass__ *name*

        Sets the __snit::widget__'s widget class to *name*, overriding the






|

|
|

|
|







 







|
|
|
|

|
|
|
|

|
|







927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
...
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
            types \(e\.g\., stacks and queues\) more efficient\.

            If false \(the default\), instance methods are dispatched normally\. If
            true, a faster dispatching scheme is used instead\. The speed comes
            at a price; with __\-simpledispatch yes__ you get the following
            limitations:

              - Methods cannot be delegated\.

              - __uplevel__ and __upvar__ do not work as expected: the
                caller's scope is two levels up rather than one\.

              - The option\-handling methods \(__cget__, __configure__,
                and __configurelist__\) are very slightly slower\.

      * <a name='25'></a>__expose__ *comp*

      * <a name='26'></a>__expose__ *comp* __as__ *method*

        __Deprecated\.__ To expose component *comp* publicly, use
        __component__'s __\-public__ option\.
................................................................................

  - <a name='29'></a>__snit::widget__ *name* *definition*

    This command defines a Snit megawidget type with the specified *name*\. The
    *definition* is defined as for __snit::type__\. A __snit::widget__
    differs from a __snit::type__ in these ways:

      * Every instance of a __snit::widget__ has an automatically\-created
        component called __hull__, which is normally a Tk frame widget\.
        Other widgets created as part of the megawidget will be created within
        this widget\.

        The hull component is initially created with the requested widget name;
        then Snit does some magic, renaming the hull component and installing
        its own instance command in its place\. The hull component's new name is
        saved in an instance variable called __hull__\.

      * The name of an instance must be valid Tk window name, and the parent
        window must exist\.

    A __snit::widget__ definition can include any of statements allowed in a
    __snit::type__ definition, and may also include the following:

      * <a name='30'></a>__widgetclass__ *name*

        Sets the __snit::widget__'s widget class to *name*, overriding the

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

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
    The result is a list containing a multiple of three items, plus one\! In
    other words, '\[llength $serial\] % 3 == 1'\. Valid values include 1, 4, 7, \.\.\.

    The last element of the list is a dictionary containing the attributes
    associated with the whole graph\. Regarding the other elements; each triple
    consists of

    The name of the node to be described,

    A dictionary containing the attributes associated with the node,

    And a list describing all the arcs starting at that node\.

    The elements of the arc list are lists containing three or four elements
    each, i\.e\.

    The name of the arc described by the element,

    A reference to the destination node of the arc\. This reference is an integer
    number given the index of that node in the main serialization list\. As that
    it is greater than or equal to zero, less than the length of the
    serialization, and a multiple of three\. *Note:* For internal consistency
    no arc name may be used twice, whether in the same node, or at some other
    node\. This is a global consistency requirement for the serialization\.


    And a dictionary containing the attributes associated with the arc\.

    The weight associated with the arc\. This value is optional\. Its non\-presence
    means that the arc in question has no weight associated with it\.


    *Note:* This information is new, compared to the serialization of
    __[graph](\.\./\.\./\.\./\.\./index\.md\#graph)__ 2\.3 and earlier\. By making
    it an optional element the new format is maximally compatible with the old\.
    This means that any graph not using weights will generate a serialization
    which is still understood by the older graph package\. A serialization will
    not be understood any longer by the older packages if, and only if the graph
    it was generated from actually has arcs with weights\.


    For all attribute dictionaries they keys are the names of the attributes,
    and the values are the values for each name\.

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







|

|

|




|

|
|
|
|
|
|
>

|

|
|
>

|
|
|
|
|
|
|
>







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
    The result is a list containing a multiple of three items, plus one\! In
    other words, '\[llength $serial\] % 3 == 1'\. Valid values include 1, 4, 7, \.\.\.

    The last element of the list is a dictionary containing the attributes
    associated with the whole graph\. Regarding the other elements; each triple
    consists of

      1. The name of the node to be described,

      1. A dictionary containing the attributes associated with the node,

      1. And a list describing all the arcs starting at that node\.

    The elements of the arc list are lists containing three or four elements
    each, i\.e\.

      1. The name of the arc described by the element,

      1. A reference to the destination node of the arc\. This reference is an
         integer number given the index of that node in the main serialization
         list\. As that it is greater than or equal to zero, less than the length
         of the serialization, and a multiple of three\. *Note:* For internal
         consistency no arc name may be used twice, whether in the same node, or
         at some other node\. This is a global consistency requirement for the
         serialization\.

      1. And a dictionary containing the attributes associated with the arc\.

      1. The weight associated with the arc\. This value is optional\. Its
         non\-presence means that the arc in question has no weight associated
         with it\.

         *Note:* This information is new, compared to the serialization of
         __[graph](\.\./\.\./\.\./\.\./index\.md\#graph)__ 2\.3 and earlier\. By
         making it an optional element the new format is maximally compatible
         with the old\. This means that any graph not using weights will generate
         a serialization which is still understood by the older graph package\. A
         serialization will not be understood any longer by the older packages
         if, and only if the graph it was generated from actually has arcs with
         weights\.

    For all attribute dictionaries they keys are the names of the attributes,
    and the values are the values for each name\.

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

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

1060
1061
1062
1063
1064
1065
1066
1067
1068

1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
....
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114

1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154

1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185

1186
1187
1188
1189

1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
....
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221

1222
1223
1224
1225
1226
1227
1228
....
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275

1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286

1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
    *[E](\.\./\.\./\.\./\.\./index\.md\#e)* a set of edges\), and one vertice *v*
    of *V*, find a path *P* from *v* to a *v'* of V so that the sum of
    weights on edges along the path is minimal among all paths connecting v to
    v'\.

  - Generalizations:

    *The single\-source shortest path problem*, in which we have to find
    shortest paths from a source vertex v to all other vertices in the graph\.


    *The single\-destination shortest path problem*, in which we have to find
    shortest paths from all vertices in the graph to a single destination vertex
    v\. This can be reduced to the single\-source shortest path problem by
    reversing the edges in the graph\.

    *The all\-pairs shortest path problem*, in which we have to find shortest
    paths between every pair of vertices v, v' in the graph\.

    *Note:* The result of *Shortest Path problem* can be *Shortest Path
    tree*, which is a subgraph of a given \(possibly weighted\) graph constructed
    so that the distance between a selected root node and all other nodes is
    minimal\. It is a tree because if there are two paths between the root node
    and some vertex v \(i\.e\. a cycle\), we can delete the last edge of the longer
    path without increasing the distance from the root node to any node in the
................................................................................

    For given edge\-weighted \(weights on edges should be positive\) graph the goal
    is to find the cycle that visits each node in graph exactly once
    \(*Hamiltonian cycle*\)\.

  - Generalizations:

    *Metric TSP* \- A very natural restriction of the *TSP* is to require
    that the distances between cities form a *metric*, i\.e\., they satisfy
    *the triangle inequality*\. That is, for any 3 cities *A*, *B* and
    *[C](\.\./\.\./\.\./\.\./index\.md\#c)*, the distance between *A* and
    *[C](\.\./\.\./\.\./\.\./index\.md\#c)* must be at most the distance from *A*
    to *B* plus the distance from *B* to
    *[C](\.\./\.\./\.\./\.\./index\.md\#c)*\. Most natural instances of *TSP*
    satisfy this constraint\.

    *Euclidean TSP* \- Euclidean TSP, or *planar TSP*, is the *TSP* with
    the distance being the ordinary *Euclidean distance*\. *Euclidean TSP* is
    a particular case of *TSP* with *triangle inequality*, since distances
    in plane obey triangle inequality\. However, it seems to be easier than
    general *TSP* with *triangle inequality*\. For example, *the minimum
    spanning tree* of the graph associated with an instance of *Euclidean
    TSP* is a *Euclidean minimum spanning tree*, and so can be computed in
    expected *O\(n log n\)* time for *n* points \(considerably less than the
    number of edges\)\. This enables the simple *2\-approximation algorithm* for
    TSP with triangle inequality above to operate more quickly\.


    *Asymmetric TSP* \- In most cases, the distance between two nodes in the
    *TSP* network is the same in both directions\. The case where the distance
    from *A* to *B* is not equal to the distance from *B* to *A* is
    called *asymmetric TSP*\. A practical application of an *asymmetric TSP*
    is route optimisation using street\-level routing \(asymmetric due to one\-way
    streets, slip\-roads and motorways\)\.

## <a name='subsection3'></a>Matching Problem

  - Definition:

    Given a graph *G = \(V,E\)*, a matching or *edge\-independent set* *M* in
    *G* is a set of pairwise non\-adjacent edges, that is, no two edges share a
    common vertex\. A vertex is *matched* if it is incident to an edge in the
    *matching M*\. Otherwise the vertex is *unmatched*\.

  - Generalizations:

    *Maximal matching* \- a matching *M* of a graph G with the property that
    if any edge not in *M* is added to *M*, it is no longer a
    *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*, that is, *M* is maximal
    if it is not a proper subset of any other
    *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* in graph G\. In other
    words, a *matching M* of a graph G is maximal if every edge in G has a
    non\-empty intersection with at least one edge in *M*\.

    *Maximum matching* \- a matching that contains the largest possible number
    of edges\. There may be many *maximum matchings*\. The *matching number*
    of a graph G is the size of a *maximum matching*\. Note that every
    *maximum matching* is *maximal*, but not every *maximal matching* is a
    *maximum matching*\.

    *Perfect matching* \- a matching which matches all vertices of the graph\.
    That is, every vertex of the graph is incident to exactly one edge of the
    matching\. Every *perfect matching* is
    *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)* and hence *maximal*\. In
    some literature, the term *complete matching* is used\. A *perfect
    matching* is also a *minimum\-size edge cover*\. Moreover, the size of a
    *maximum matching* is no larger than the size of a *minimum edge cover*\.


    *Near\-perfect matching* \- a matching in which exactly one vertex is
    unmatched\. This can only occur when the graph has an odd number of vertices,
    and such a *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* must be
    *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)*\. If, for every vertex in a
    graph, there is a near\-perfect matching that omits only that vertex, the
    graph is also called *factor\-critical*\.

  - Related terms:

    *Alternating path* \- given a matching *M*, an *alternating path* is a
    path in which the edges belong alternatively to the matching and not to the
    matching\.

    *[Augmenting path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* \- given a
    matching *M*, an *[augmenting
    path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* is an *alternating path*
    that starts from and ends on free \(unmatched\) vertices\.

## <a name='subsection4'></a>Cut Problems

  - Definition:

    A *cut* is a partition of the vertices of a graph into two *disjoint
    subsets*\. The *cut\-set* of the *cut* is the set of edges whose end
    points are in different subsets of the partition\. Edges are said to be
    crossing the cut if they are in its *cut\-set*\.

    Formally:

    a *cut* *C = \(S,T\)* is a partition of *V* of a graph *G = \(V, E\)*\.


    an *s\-t cut* *C = \(S,T\)* of a *[flow
    network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)* *N = \(V, E\)* is a cut of
    *N* such that *s* is included in *S* and *t* is included in *T*,

    where *s* and *t* are the *[source](\.\./\.\./\.\./\.\./index\.md\#source)*
    and the *sink* of *N* respectively\.

    The *cut\-set* of a *cut C = \(S,T\)* is such set of edges from graph *G =
    \(V, E\)* that each edge *\(u, v\)* satisfies condition that *u* is
    included in *S* and *v* is included in *T*\.

    In an *unweighted undirected* graph, the size or weight of a cut is the
    number of edges crossing the cut\. In a *weighted graph*, the same term is
    defined by the sum of the weights of the edges crossing the cut\.

    In a *[flow network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*, an *s\-t
    cut* is a cut that requires the
................................................................................
    defined by the sum of capacity of each edge in the *cut\-set*\.

    The *cut* of a graph can sometimes refer to its *cut\-set* instead of the
    partition\.

  - Generalizations:

    *Minimum cut* \- A cut is minimum if the size of the cut is not larger than
    the size of any other cut\.

    *Maximum cut* \- A cut is maximum if the size of the cut is not smaller
    than the size of any other cut\.

    *Sparsest cut* \- The *Sparsest cut problem* is to bipartition the
    vertices so as to minimize the ratio of the number of edges across the cut
    divided by the number of vertices in the smaller half of the partition\.


## <a name='subsection5'></a>K\-Center Problem

  - Definitions:

      * *Unweighted K\-Center*

................................................................................
        \}\}* has the smallest possible worth \( *v* is a node in *V* and
        *u* is a node in *S* \)\.

## <a name='subsection6'></a>Flow Problems

  - Definitions:

    *the maximum flow problem* \- the goal is to find a feasible flow through a
    single\-source, single\-sink flow network that is maximum\. The *maximum flow
    problem* can be seen as a special case of more complex network flow
    problems, such as the *circulation problem*\. The maximum value of an *s\-t
    flow* is equal to the minimum capacity of an *s\-t cut* in the network, as
    stated in the *max\-flow min\-cut theorem*\.

    More formally for flow network *G = \(V,E\)*, where for each edge *\(u, v\)*
    we have its throuhgput *c\(u,v\)* defined\. As
    *[flow](\.\./\.\./\.\./\.\./index\.md\#flow)* *F* we define set of
    non\-negative integer attributes *f\(u,v\)* assigned to edges, satisfying
    such conditions:

    for each edge *\(u, v\)* in *G* such condition should be satisfied: 0 <=
    f\(u,v\) <= c\(u,v\)

    Network *G* has source node *s* such that the flow *F* is equal to the
    sum of outcoming flow decreased by the sum of incoming flow from that source
    node *s*\.

    Network *G* has sink node *t* such that the the *\-F* value is equal to
    the sum of the incoming flow decreased by the sum of outcoming flow from
    that sink node *t*\.


    For each node that is not a *[source](\.\./\.\./\.\./\.\./index\.md\#source)* or
    *sink* the sum of incoming flow and sum of outcoming flow should be equal\.

    *the minimum cost flow problem* \- the goal is finding the cheapest
    possible way of sending a certain amount of flow through a *[flow
    network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*\.

    *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* \- a *[blocking
    flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* for a *residual network*
    *Gf* we name such flow *b* in *Gf* that:


    Each path from *sink* to *[source](\.\./\.\./\.\./\.\./index\.md\#source)* is
    the shortest path in *Gf*\.

    Each shortest path in *Gf* contains an edge with fully used throughput in
    *Gf\+b*\.

    *residual network* \- for a flow network *G* and flow *f* *residual
    network* is built with those edges, which can send larger flow\. It contains
    only those edges, which can send flow larger than 0\.

    *level network* \- it has the same set of nodes as *[residual
    graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)*, but has only those edges
    *\(u,v\)* from *Gf* for which such equality is satisfied:
    *distance\(s,u\)\+1 = distance\(s,v\)*\.

    *[augmenting network](\.\./\.\./\.\./\.\./index\.md\#augmenting\_network)* \- it
    is a modification of *residual network* considering the new flow values\.
    Structure stays unchanged but values of throughputs and costs at edges are
    different\.

## <a name='subsection7'></a>Approximation algorithm

  - k\-approximation algorithm:

    Algorithm is a k\-approximation, when for *ALG* \(solution returned by
    algorithm\) and *OPT* \(optimal solution\), such inequality is true:

    for minimalization problems: *ALG/OPT <= k*

    for maximalization problems: *OPT/ALG <= k*

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

  1. [Adjacency matrix](http://en\.wikipedia\.org/wiki/Adjacency\_matrix)

  1. [Adjacency list](http://en\.wikipedia\.org/wiki/Adjacency\_list)







|
|
>

|
|
|
|

|
|







 







|
|
|
|
|
|
|
|

|
|
|
|
|
|
|
|
|
|
>

|
|
|
|
|
|












|
|
|
|
|
|
|

|
|
|
|
|

|
|
|
|
|
|
|
>

|
|
|
|
|
|



|
|
|

|
|
|
|












|
>

|
|
|
>
|
|

|
|
|







 







|
|

|
|

|
|
|
>







 







|
|
|
|
|
|

|
|
|
|
|

|
|

|
|
|

|
|
|

>
|
|

|
|
|

|
|
|

>
|
|

|
|

|
|
|

|
|
|
|

|
|
|
|








|

|







1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
....
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
....
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
....
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
    *[E](\.\./\.\./\.\./\.\./index\.md\#e)* a set of edges\), and one vertice *v*
    of *V*, find a path *P* from *v* to a *v'* of V so that the sum of
    weights on edges along the path is minimal among all paths connecting v to
    v'\.

  - Generalizations:

      * *The single\-source shortest path problem*, in which we have to find
        shortest paths from a source vertex v to all other vertices in the
        graph\.

      * *The single\-destination shortest path problem*, in which we have to
        find shortest paths from all vertices in the graph to a single
        destination vertex v\. This can be reduced to the single\-source shortest
        path problem by reversing the edges in the graph\.

      * *The all\-pairs shortest path problem*, in which we have to find
        shortest paths between every pair of vertices v, v' in the graph\.

    *Note:* The result of *Shortest Path problem* can be *Shortest Path
    tree*, which is a subgraph of a given \(possibly weighted\) graph constructed
    so that the distance between a selected root node and all other nodes is
    minimal\. It is a tree because if there are two paths between the root node
    and some vertex v \(i\.e\. a cycle\), we can delete the last edge of the longer
    path without increasing the distance from the root node to any node in the
................................................................................

    For given edge\-weighted \(weights on edges should be positive\) graph the goal
    is to find the cycle that visits each node in graph exactly once
    \(*Hamiltonian cycle*\)\.

  - Generalizations:

      * *Metric TSP* \- A very natural restriction of the *TSP* is to require
        that the distances between cities form a *metric*, i\.e\., they satisfy
        *the triangle inequality*\. That is, for any 3 cities *A*, *B* and
        *[C](\.\./\.\./\.\./\.\./index\.md\#c)*, the distance between *A* and
        *[C](\.\./\.\./\.\./\.\./index\.md\#c)* must be at most the distance from
        *A* to *B* plus the distance from *B* to
        *[C](\.\./\.\./\.\./\.\./index\.md\#c)*\. Most natural instances of *TSP*
        satisfy this constraint\.

      * *Euclidean TSP* \- Euclidean TSP, or *planar TSP*, is the *TSP*
        with the distance being the ordinary *Euclidean distance*\. *Euclidean
        TSP* is a particular case of *TSP* with *triangle inequality*,
        since distances in plane obey triangle inequality\. However, it seems to
        be easier than general *TSP* with *triangle inequality*\. For
        example, *the minimum spanning tree* of the graph associated with an
        instance of *Euclidean TSP* is a *Euclidean minimum spanning tree*,
        and so can be computed in expected *O\(n log n\)* time for *n* points
        \(considerably less than the number of edges\)\. This enables the simple
        *2\-approximation algorithm* for TSP with triangle inequality above to
        operate more quickly\.

      * *Asymmetric TSP* \- In most cases, the distance between two nodes in
        the *TSP* network is the same in both directions\. The case where the
        distance from *A* to *B* is not equal to the distance from *B* to
        *A* is called *asymmetric TSP*\. A practical application of an
        *asymmetric TSP* is route optimisation using street\-level routing
        \(asymmetric due to one\-way streets, slip\-roads and motorways\)\.

## <a name='subsection3'></a>Matching Problem

  - Definition:

    Given a graph *G = \(V,E\)*, a matching or *edge\-independent set* *M* in
    *G* is a set of pairwise non\-adjacent edges, that is, no two edges share a
    common vertex\. A vertex is *matched* if it is incident to an edge in the
    *matching M*\. Otherwise the vertex is *unmatched*\.

  - Generalizations:

      * *Maximal matching* \- a matching *M* of a graph G with the property
        that if any edge not in *M* is added to *M*, it is no longer a
        *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*, that is, *M* is
        maximal if it is not a proper subset of any other
        *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* in graph G\. In other
        words, a *matching M* of a graph G is maximal if every edge in G has a
        non\-empty intersection with at least one edge in *M*\.

      * *Maximum matching* \- a matching that contains the largest possible
        number of edges\. There may be many *maximum matchings*\. The *matching
        number* of a graph G is the size of a *maximum matching*\. Note that
        every *maximum matching* is *maximal*, but not every *maximal
        matching* is a *maximum matching*\.

      * *Perfect matching* \- a matching which matches all vertices of the
        graph\. That is, every vertex of the graph is incident to exactly one
        edge of the matching\. Every *perfect matching* is
        *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)* and hence *maximal*\.
        In some literature, the term *complete matching* is used\. A *perfect
        matching* is also a *minimum\-size edge cover*\. Moreover, the size of
        a *maximum matching* is no larger than the size of a *minimum edge
        cover*\.

      * *Near\-perfect matching* \- a matching in which exactly one vertex is
        unmatched\. This can only occur when the graph has an odd number of
        vertices, and such a *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*
        must be *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)*\. If, for every
        vertex in a graph, there is a near\-perfect matching that omits only that
        vertex, the graph is also called *factor\-critical*\.

  - Related terms:

      * *Alternating path* \- given a matching *M*, an *alternating path*
        is a path in which the edges belong alternatively to the matching and
        not to the matching\.

      * *[Augmenting path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* \- given
        a matching *M*, an *[augmenting
        path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* is an *alternating
        path* that starts from and ends on free \(unmatched\) vertices\.

## <a name='subsection4'></a>Cut Problems

  - Definition:

    A *cut* is a partition of the vertices of a graph into two *disjoint
    subsets*\. The *cut\-set* of the *cut* is the set of edges whose end
    points are in different subsets of the partition\. Edges are said to be
    crossing the cut if they are in its *cut\-set*\.

    Formally:

      * a *cut* *C = \(S,T\)* is a partition of *V* of a graph *G = \(V,
        E\)*\.

      * an *s\-t cut* *C = \(S,T\)* of a *[flow
        network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)* *N = \(V, E\)* is a cut
        of *N* such that *s* is included in *S* and *t* is included in
        *T*, where *s* and *t* are the
        *[source](\.\./\.\./\.\./\.\./index\.md\#source)* and the *sink* of *N*
        respectively\.

      * The *cut\-set* of a *cut C = \(S,T\)* is such set of edges from graph
        *G = \(V, E\)* that each edge *\(u, v\)* satisfies condition that *u*
        is included in *S* and *v* is included in *T*\.

    In an *unweighted undirected* graph, the size or weight of a cut is the
    number of edges crossing the cut\. In a *weighted graph*, the same term is
    defined by the sum of the weights of the edges crossing the cut\.

    In a *[flow network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*, an *s\-t
    cut* is a cut that requires the
................................................................................
    defined by the sum of capacity of each edge in the *cut\-set*\.

    The *cut* of a graph can sometimes refer to its *cut\-set* instead of the
    partition\.

  - Generalizations:

      * *Minimum cut* \- A cut is minimum if the size of the cut is not larger
        than the size of any other cut\.

      * *Maximum cut* \- A cut is maximum if the size of the cut is not smaller
        than the size of any other cut\.

      * *Sparsest cut* \- The *Sparsest cut problem* is to bipartition the
        vertices so as to minimize the ratio of the number of edges across the
        cut divided by the number of vertices in the smaller half of the
        partition\.

## <a name='subsection5'></a>K\-Center Problem

  - Definitions:

      * *Unweighted K\-Center*

................................................................................
        \}\}* has the smallest possible worth \( *v* is a node in *V* and
        *u* is a node in *S* \)\.

## <a name='subsection6'></a>Flow Problems

  - Definitions:

      * *the maximum flow problem* \- the goal is to find a feasible flow
        through a single\-source, single\-sink flow network that is maximum\. The
        *maximum flow problem* can be seen as a special case of more complex
        network flow problems, such as the *circulation problem*\. The maximum
        value of an *s\-t flow* is equal to the minimum capacity of an *s\-t
        cut* in the network, as stated in the *max\-flow min\-cut theorem*\.

        More formally for flow network *G = \(V,E\)*, where for each edge *\(u,
        v\)* we have its throuhgput *c\(u,v\)* defined\. As
        *[flow](\.\./\.\./\.\./\.\./index\.md\#flow)* *F* we define set of
        non\-negative integer attributes *f\(u,v\)* assigned to edges, satisfying
        such conditions:

          1. for each edge *\(u, v\)* in *G* such condition should be
             satisfied: 0 <= f\(u,v\) <= c\(u,v\)

          1. Network *G* has source node *s* such that the flow *F* is
             equal to the sum of outcoming flow decreased by the sum of incoming
             flow from that source node *s*\.

          1. Network *G* has sink node *t* such that the the *\-F* value is
             equal to the sum of the incoming flow decreased by the sum of
             outcoming flow from that sink node *t*\.

          1. For each node that is not a
             *[source](\.\./\.\./\.\./\.\./index\.md\#source)* or *sink* the sum
             of incoming flow and sum of outcoming flow should be equal\.

      * *the minimum cost flow problem* \- the goal is finding the cheapest
        possible way of sending a certain amount of flow through a *[flow
        network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*\.

      * *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* \- a
        *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* for a
        *residual network* *Gf* we name such flow *b* in *Gf* that:

          1. Each path from *sink* to
             *[source](\.\./\.\./\.\./\.\./index\.md\#source)* is the shortest path
             in *Gf*\.

          1. Each shortest path in *Gf* contains an edge with fully used
             throughput in *Gf\+b*\.

      * *residual network* \- for a flow network *G* and flow *f*
        *residual network* is built with those edges, which can send larger
        flow\. It contains only those edges, which can send flow larger than 0\.

      * *level network* \- it has the same set of nodes as *[residual
        graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)*, but has only those
        edges *\(u,v\)* from *Gf* for which such equality is satisfied:
        *distance\(s,u\)\+1 = distance\(s,v\)*\.

      * *[augmenting network](\.\./\.\./\.\./\.\./index\.md\#augmenting\_network)* \-
        it is a modification of *residual network* considering the new flow
        values\. Structure stays unchanged but values of throughputs and costs at
        edges are different\.

## <a name='subsection7'></a>Approximation algorithm

  - k\-approximation algorithm:

    Algorithm is a k\-approximation, when for *ALG* \(solution returned by
    algorithm\) and *OPT* \(optimal solution\), such inequality is true:

      * for minimalization problems: *ALG/OPT <= k*

      * for maximalization problems: *OPT/ALG <= k*

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

  1. [Adjacency matrix](http://en\.wikipedia\.org/wiki/Adjacency\_matrix)

  1. [Adjacency list](http://en\.wikipedia\.org/wiki/Adjacency\_list)

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

237
238
239
240
241
242
243
244
245
246
247
248
249
250

251
252
253
254
255
256
257
  - <a name='10'></a>*poolName* __request__ itemVar ?options?

    Handles a request for an item, taking into account a possible preference for
    a particular item\. There are two possible outcomes depending on the
    availability of items:

    The request is honoured, an item is allocated and the variable whose name is
    passed with the argument *itemVar* will be set to the name of the item
    that was allocated\. The command returns 1\.

    The request is denied\. No item is allocated\. The variable whose name is
    itemVar is not set\. Attempts to read *itemVar* may raise an error if the
    variable was not defined before issuing the request\. The command returns 0\.


    The return values from this command are meant to be inspected\. The examples
    below show how to do this\. Failure to check the return value may result in
    erroneous behaviour\. If no preference for a particular item is supplied
    through the option __\-prefer__ \(see below\), then all requests are
    honoured as long as items are available\.







|
|
|

|
|
|
>







237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
  - <a name='10'></a>*poolName* __request__ itemVar ?options?

    Handles a request for an item, taking into account a possible preference for
    a particular item\. There are two possible outcomes depending on the
    availability of items:

      1. The request is honoured, an item is allocated and the variable whose
         name is passed with the argument *itemVar* will be set to the name of
         the item that was allocated\. The command returns 1\.

      1. The request is denied\. No item is allocated\. The variable whose name is
         itemVar is not set\. Attempts to read *itemVar* may raise an error if
         the variable was not defined before issuing the request\. The command
         returns 0\.

    The return values from this command are meant to be inspected\. The examples
    below show how to do this\. Failure to check the return value may result in
    erroneous behaviour\. If no preference for a particular item is supplied
    through the option __\-prefer__ \(see below\), then all requests are
    honoured as long as items are available\.

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

172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
        Inversion  = \{\{deleted  \{0  0\} \{\-1 0\}\}
                      \{changed  \{3  3\}  \{2 2\}\}
                      \{deleted  \{6  7\}  \{4 5\}\}
                      \{added   \{10 11\}  \{8 8\}\}\}

    *Notes:*

    An index of __\-1__ in a *deleted* chunk refers to just before the
    first element of the second sequence\.

    Also an index equal to the length of the first sequence in an *added*
    chunk refers to just behind the end of the sequence\.

  - <a name='4'></a>__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*

    Similar to __lcsInvert__\. Instead of directly taking the result of a
    call to __longestCommonSubsequence__ this subcommand expects the indices
    for the two sequences in two separate lists\.







|
|

|
|







172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
        Inversion  = \{\{deleted  \{0  0\} \{\-1 0\}\}
                      \{changed  \{3  3\}  \{2 2\}\}
                      \{deleted  \{6  7\}  \{4 5\}\}
                      \{added   \{10 11\}  \{8 8\}\}\}

    *Notes:*

      * An index of __\-1__ in a *deleted* chunk refers to just before the
        first element of the second sequence\.

      * Also an index equal to the length of the first sequence in an *added*
        chunk refers to just behind the end of the sequence\.

  - <a name='4'></a>__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*

    Similar to __lcsInvert__\. Instead of directly taking the result of a
    call to __longestCommonSubsequence__ this subcommand expects the indices
    for the two sequences in two separate lists\.

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

101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# <a name='section2'></a>ARGUMENTS

  - ?\-format *format*?

    Specifies the documentation format\. __TEPAM Doc Gen__ provides support
    for the following formats:

    TXT \- Text format \(default\)

    HTML

    POD \- Perl Plain Old Documentation format \(PerlPOD\)

    DT \- TclLib DocTool format

    Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how
    support for additional formats can be added\.

  - ?\-style *style*?

    The documentation is by default generated in Tcl style \(e\.g\. __command






|

|

|

|







101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# <a name='section2'></a>ARGUMENTS

  - ?\-format *format*?

    Specifies the documentation format\. __TEPAM Doc Gen__ provides support
    for the following formats:

      * TXT \- Text format \(default\)

      * HTML

      * POD \- Perl Plain Old Documentation format \(PerlPOD\)

      * DT \- TclLib DocTool format

    Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how
    support for additional formats can be added\.

  - ?\-style *style*?

    The documentation is by default generated in Tcl style \(e\.g\. __command

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

788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
  - __command\_log__

    Procedure calls can be logged inside the list variable
    __tepam::ProcedureCallLogList__\. The variable __tepam::command\_log__
    controls the default logging settings for any procedures\. The following
    configurations are supported:

    *0*: Disables any procedure call loggings

    *1*: Enables any procedure call loggings

    *"interactive"*: Will log any procedures called interactively \(e\.g\.
    procedures called with the \-interactive flag\)\. This is the default
    configuration\.

    This default logging configuration can be changed individually for each
    procedure with the *\-command\_log* attribute\.

# <a name='section5'></a>ARGUMENT TYPES

TEPAM provides a comprehensive set of procedure argument types\. They can easily






|

|

|
|
|







788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
  - __command\_log__

    Procedure calls can be logged inside the list variable
    __tepam::ProcedureCallLogList__\. The variable __tepam::command\_log__
    controls the default logging settings for any procedures\. The following
    configurations are supported:

      * *0*: Disables any procedure call loggings

      * *1*: Enables any procedure call loggings

      * *"interactive"*: Will log any procedures called interactively \(e\.g\.
        procedures called with the \-interactive flag\)\. This is the default
        configuration\.

    This default logging configuration can be changed individually for each
    procedure with the *\-command\_log* attribute\.

# <a name='section5'></a>ARGUMENT TYPES

TEPAM provides a comprehensive set of procedure argument types\. They can easily

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

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
    *Note* that uncaught errors will leave the *node set* of the object in
    an intermediate state, per the TreeQL operators which were executed
    successfully before the error occurred\.

    The above means in detail that:

    The first argument is interpreted as the name of a query operator, the
    number of arguments required by that operator is then determined, and taken
    from the immediately following arguments\.

    Because of this operators cannot have optional arguments, all arguments have
    to be present as defined\. Failure to do this will, at least, confuse the
    query interpreter, but more likely cause errors\.

    The operator is applied to the current node set, yielding a new node set,
    and/or manipulating the tree object the query object is connected to\.


    The arguments used \(i\.e\. operator name and arguments\) are removed from the
    list of method arguments, and then the whole process is repeated from step
    \[1\], until the list of arguments is empty or an error occurred\.


            \# q is the query object\.

            q query root children get data

            \# The above query
            \# \- Resets the node set to the root node \- root






|
|
|

|
|
|

|
|
>

|
|
|
>







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
    *Note* that uncaught errors will leave the *node set* of the object in
    an intermediate state, per the TreeQL operators which were executed
    successfully before the error occurred\.

    The above means in detail that:

      1. The first argument is interpreted as the name of a query operator, the
         number of arguments required by that operator is then determined, and
         taken from the immediately following arguments\.

         Because of this operators cannot have optional arguments, all arguments
         have to be present as defined\. Failure to do this will, at least,
         confuse the query interpreter, but more likely cause errors\.

      1. The operator is applied to the current node set, yielding a new node
         set, and/or manipulating the tree object the query object is connected
         to\.

      1. The arguments used \(i\.e\. operator name and arguments\) are removed from
         the list of method arguments, and then the whole process is repeated
         from step \[1\], until the list of arguments is empty or an error
         occurred\.

            \# q is the query object\.

            q query root children get data

            \# The above query
            \# \- Resets the node set to the root node \- root

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

1
2
3
4
5
6
7
8
9
10
11
12
...
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5 tcllib "Documentation tools"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
doctools \- doctools - Processing documents
.SH SYNOPSIS
package require \fBTcl  8\&.2\fR
.sp
package require \fBdoctools  ?1\&.5?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
...
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
'\"
'\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003-2019 Andreas Kupries <[email protected]\&.sourceforge\&.net>
'\"
.TH "doctools" n 1\&.5\&.1 tcllib "Documentation tools"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
doctools \- doctools - Processing documents
.SH SYNOPSIS
package require \fBTcl  8\&.2\fR
.sp
package require \fBdoctools  ?1\&.5\&.1?\fR
.sp
\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.?
.sp
\fB::doctools::help\fR
.sp
\fB::doctools::search\fR \fIpath\fR
.sp

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

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.5 tcllib &quot;Documentation tools&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>






|







 







|







103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.5.1 tcllib &quot;Documentation tools&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.5.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>

Changes to modules/doctools/doctools.man.

1
2
3
4
5
6
7
8
9
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]
|







1
2
3
4
5
6
7
8
9
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 1.5.1]
[manpage_begin doctools n [vset PACKAGE_VERSION]]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_intro]
[see_also doctools_lang_syntax]
[see_also doctools_plugin_apiref]
[keywords conversion]

Changes to modules/doctools/doctools.tcl.

1354
1355
1356
1357
1358
1359
1360
1361
    # => FOO/mpformats

    #catch {search [file join $here                lib doctools mpformats]}
    #catch {search [file join [file dirname $here] lib doctools mpformats]}
    catch {search [file join $here                             mpformats]}
}

package provide doctools 1.5






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

Changes to modules/doctools/mpformats/_text_dlist.tcl.

188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
    # reuse the current context and accessors to hold and query the
    # context of each paragraph.
    
    foreach {env text} $arguments break
    ContextSet $env

    #puts_stderr "PARA $env [CAttrName $env]"
    #parray_stderr ::currentEnv
    #puts_stderr "    (($text))"
    #puts_stderr ""

    # Use the information in the referenced context to format the
    # paragraph.

    set lm    [Margin?]






|







188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
    # reuse the current context and accessors to hold and query the
    # context of each paragraph.
    
    foreach {env text} $arguments break
    ContextSet $env

    #puts_stderr "PARA $env [CAttrName $env]"
    #parray_stderr ::currentContext ;# consider capsulation
    #puts_stderr "    (($text))"
    #puts_stderr ""

    # Use the information in the referenced context to format the
    # paragraph.

    set lm    [Margin?]

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

42
43
44
45
46
47
48

49
50
51
52
53
54
55
..
78
79
80
81
82
83
84

85
86
87
88
89
90
91
...
118
119
120
121
122
123
124

125
126
127
128
129
130
131
    # 3. All other paragraphs.
    ContextPush

    #puts_stderr "UL [CAttrName]"
    #puts_stderr "UL |[string map {{ } _} [In?]]|outer"

    set base [ContextNew Itemized {

	set bullet "[In?]  [IBullet]"
	set ws     "[BlankM $bullet] "
	In! $ws
    }] ; # {}

    #puts_stderr "UL |[string map {{ } _} $bullet]|[string length $bullet]"
    #puts_stderr "UL |[string map {{ } _} $ws]|[string length $ws]"
................................................................................
    # 3. All other paragraphs.
    ContextPush

    #puts_stderr "OL [CAttrName]"
    #puts_stderr "OL |[string map {{ } _} [In?]]|outer"

    set base [ContextNew Enumerated {

	set bullet "[In?]  [EBullet]"
	set ws     "[BlankM $bullet] "
	In! $ws
    }] ; # {}

    #puts_stderr "OL |[string map {{ } _} $bullet]|[string length $bullet]"
    #puts_stderr "OL |[string map {{ } _} $ws]|[string length $ws]"
................................................................................
    # itemized lists, rendering the term part as the first paragraph
    # of each entry, and the definition as all following.

    #puts_stderr "DL [CAttrName]"
    #puts_stderr "DL |[string map {{ } _} [In?]]|outer"

    set base [ContextNew Definitions {

	set bullet "[In?]  [IBullet]"
	set ws "[BlankM $bullet] "
	In! $ws
    }] ; # {}

    #puts_stderr "DL |[string map {{ } _} $bullet]|[string length $bullet]"
    #puts_stderr "DL |[string map {{ } _} $ws]|[string length $ws]"






>







 







>







 







>







42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
..
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
...
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
    # 3. All other paragraphs.
    ContextPush

    #puts_stderr "UL [CAttrName]"
    #puts_stderr "UL |[string map {{ } _} [In?]]|outer"

    set base [ContextNew Itemized {
	LC
	set bullet "[In?]  [IBullet]"
	set ws     "[BlankM $bullet] "
	In! $ws
    }] ; # {}

    #puts_stderr "UL |[string map {{ } _} $bullet]|[string length $bullet]"
    #puts_stderr "UL |[string map {{ } _} $ws]|[string length $ws]"
................................................................................
    # 3. All other paragraphs.
    ContextPush

    #puts_stderr "OL [CAttrName]"
    #puts_stderr "OL |[string map {{ } _} [In?]]|outer"

    set base [ContextNew Enumerated {
	LC
	set bullet "[In?]  [EBullet]"
	set ws     "[BlankM $bullet] "
	In! $ws
    }] ; # {}

    #puts_stderr "OL |[string map {{ } _} $bullet]|[string length $bullet]"
    #puts_stderr "OL |[string map {{ } _} $ws]|[string length $ws]"
................................................................................
    # itemized lists, rendering the term part as the first paragraph
    # of each entry, and the definition as all following.

    #puts_stderr "DL [CAttrName]"
    #puts_stderr "DL |[string map {{ } _} [In?]]|outer"

    set base [ContextNew Definitions {
	LC
	set bullet "[In?]  [IBullet]"
	set ws "[BlankM $bullet] "
	In! $ws
    }] ; # {}

    #puts_stderr "DL |[string map {{ } _} $bullet]|[string length $bullet]"
    #puts_stderr "DL |[string map {{ } _} $ws]|[string length $ws]"

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

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
..
83
84
85
86
87
88
89

90
91
92
93
94
95
96
...
111
112
113
114
115
116
117

118
119
120
121
122
123
124
...
132
133
134
135
136
137
138








139
140
141
142
143
144
145
	ContextCommit
    }
    return [CAttrGet exenv]
}

proc NewList {what} {
    # List contexts
    # Per list several contexts are required.


    switch -exact -- $what {
	enumerated {NewOrderedList}
	itemized   {NewUnorderedList}
	arguments -
	commands  -
	options   -
	tkoptions -
	definitions {NewDefinitionList}
    }


    return
}

proc NewUnorderedList {} {
    # Itemized list - unordered list - bullet
    # 1. Base context provides indentation.
    # 2. First paragraph in a list item.
    # 3. All other paragraphs.
    ContextPush

    set base [ContextNew Itemized {

	MarginIn
	set bullet [IBullet]
    }] ; # {}

    set first [ContextNew First {
	List! bullet $bullet [BlankMargin]
    }] ; ContextSet $base ; # {}
................................................................................
    # Ordered list - enumeration - enum
    # 1. Base context provides indentation.
    # 2. First paragraph in a list item.
    # 3. All other paragraphs.
    ContextPush
    
    set base [ContextNew Enumerated {

	MarginIn
	set bullet [EBullet]
    }] ; # {}

    set first [ContextNew First {
	List! enum $bullet [BlankMargin]
    }] ; ContextSet $base ; # {}
................................................................................
    # Definition list - terms & definitions
    # 1. Base context provides indentation.
    # 2. Term context
    # 3. Definition context
    ContextPush

    set base [ContextNew Definitions {

	MarginIn
    }] ; # {}

    set term [ContextNew Term {
	VerbatimOn
    }] ; ContextSet $base ; # {}

................................................................................
    ContextPop
    ContextSet $base
    return
}

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









proc OUL {f n} {
    CAttrSet _first $f
    CAttrSet _next  $n
}

proc TD {t d} {






|
>
>









>
>











>







 







>







 







>







 







>
>
>
>
>
>
>
>







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
..
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
...
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
...
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
	ContextCommit
    }
    return [CAttrGet exenv]
}

proc NewList {what} {
    # List contexts
    # Per list type several contexts are required.
    #puts_stderr "LIST OUT [CAttrName] NewList $what"
    
    switch -exact -- $what {
	enumerated {NewOrderedList}
	itemized   {NewUnorderedList}
	arguments -
	commands  -
	options   -
	tkoptions -
	definitions {NewDefinitionList}
    }

    #puts_stderr "LIST INN [CAttrName]"
    return
}

proc NewUnorderedList {} {
    # Itemized list - unordered list - bullet
    # 1. Base context provides indentation.
    # 2. First paragraph in a list item.
    # 3. All other paragraphs.
    ContextPush

    set base [ContextNew Itemized {
	LC
	MarginIn
	set bullet [IBullet]
    }] ; # {}

    set first [ContextNew First {
	List! bullet $bullet [BlankMargin]
    }] ; ContextSet $base ; # {}
................................................................................
    # Ordered list - enumeration - enum
    # 1. Base context provides indentation.
    # 2. First paragraph in a list item.
    # 3. All other paragraphs.
    ContextPush
    
    set base [ContextNew Enumerated {
	LC
	MarginIn
	set bullet [EBullet]
    }] ; # {}

    set first [ContextNew First {
	List! enum $bullet [BlankMargin]
    }] ; ContextSet $base ; # {}
................................................................................
    # Definition list - terms & definitions
    # 1. Base context provides indentation.
    # 2. Term context
    # 3. Definition context
    ContextPush

    set base [ContextNew Definitions {
	LC
	MarginIn
    }] ; # {}

    set term [ContextNew Term {
	VerbatimOn
    }] ; ContextSet $base ; # {}

................................................................................
    ContextPop
    ContextSet $base
    return
}

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

proc LC {} {
    # Clear inherited list type information from the current context
    CAttrUnset _first
    CAttrUnset _next
    CAttrUnset _term
    CAttrUnset _definition
}

proc OUL {f n} {
    CAttrSet _first $f
    CAttrSet _next  $n
}

proc TD {t d} {

Changes to modules/doctools/pkgIndex.tcl.

1
2
3
4
5
6
if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools            1.5  [list source [file join $dir doctools.tcl]]
package ifneeded doctools::toc       1.2  [list source [file join $dir doctoc.tcl]]
package ifneeded doctools::idx       1.1  [list source [file join $dir docidx.tcl]]
package ifneeded doctools::cvs       1    [list source [file join $dir cvs.tcl]]
package ifneeded doctools::changelog 1.1  [list source [file join $dir changelog.tcl]]
|
|
|
|
|
1
2
3
4
5
6
if {![package vsatisfies [package provide Tcl] 8.2]} {return}
package ifneeded doctools            1.5.1 [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/19.

Added modules/doctools/tests/fmt/desc/20.

Added modules/doctools/tests/fmt/desc/21.

Added modules/doctools/tests/fmt/desc/22.

Added modules/doctools/tests/fmt/desc/23.

Added modules/doctools/tests/fmt/desc/24.

Added modules/doctools/tests/fmt/html/19.






























































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<!DOCTYPE html><html><head>
<title>test-itemized-enumerated - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- test-itemized-enumerated.1
   -->
<body><div class="doctools">
<h1 class="doctools_title">test-itemized-enumerated(1) n .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>test-itemized-enumerated -</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>lorem ipsum dolores</p>
<ul class="doctools_itemized">
<li><p>lorem ipsum dolores</p>
<ol class="doctools_enumerated">
<li><p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
</ol>
</li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<ol class="doctools_enumerated">
<li><p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
</ol>
<p>lorem ipsum dolores</p></li>
</ul>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; .COPYRIGHT.</p>
</div>
</div></body></html>

Added modules/doctools/tests/fmt/html/20.






























































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<!DOCTYPE html><html><head>
<title>test-enumerated-itemized - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- test-enumerated-itemized.1
   -->
<body><div class="doctools">
<h1 class="doctools_title">test-enumerated-itemized(1) n .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>test-enumerated-itemized -</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>lorem ipsum dolores</p>
<ol class="doctools_enumerated">
<li><p>lorem ipsum dolores</p>
<ul class="doctools_itemized">
<li><p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
</ul>
</li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<ul class="doctools_itemized">
<li><p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
</ul>
<p>lorem ipsum dolores</p></li>
</ol>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; .COPYRIGHT.</p>
</div>
</div></body></html>

Added modules/doctools/tests/fmt/html/21.


































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<!DOCTYPE html><html><head>
<title>test-definitions-itemized - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- test-definitions-itemized.1
   -->
<body><div class="doctools">
<h1 class="doctools_title">test-definitions-itemized(1) n .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>test-definitions-itemized -</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>lorem ipsum dolores</p>
<dl class="doctools_definitions">
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<ul class="doctools_itemized">
<li><p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
</ul></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p>
<ul class="doctools_itemized">
<li><p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
</ul>
<p>lorem ipsum dolores</p></dd>
</dl>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; .COPYRIGHT.</p>
</div>
</div></body></html>

Added modules/doctools/tests/fmt/html/22.










































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<!DOCTYPE html><html><head>
<title>test-itemized-definitions - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- test-itemized-definitions.1
   -->
<body><div class="doctools">
<h1 class="doctools_title">test-itemized-definitions(1) n .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>test-itemized-definitions -</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>lorem ipsum dolores</p>
<ul class="doctools_itemized">
<li><p>lorem ipsum dolores</p>
<dl class="doctools_definitions">
<dt>lorem</dt>
<dd><p>ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
</dl>
</li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<dl class="doctools_definitions">
<dt>lorem</dt>
<dd><p>ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
</dl>
<p>lorem ipsum dolores</p></li>
</ul>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; .COPYRIGHT.</p>
</div>
</div></body></html>

Added modules/doctools/tests/fmt/html/23.










































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<!DOCTYPE html><html><head>
<title>test-enumerated-definitions - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file '.FILE.' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; .COPYRIGHT.
   -->
<!-- test-enumerated-definitions.1
   -->
<body><div class="doctools">
<h1 class="doctools_title">test-enumerated-definitions(1) n .MODULE. &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>test-enumerated-definitions -</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>lorem ipsum dolores</p>
<ol class="doctools_enumerated">
<li><p>lorem ipsum dolores</p>
<dl class="doctools_definitions">
<dt>lorem</dt>
<dd><p>ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
</dl>
</li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></li>
<li><p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p>
<dl class="doctools_definitions">
<dt>lorem</dt>
<dd><p>ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
<dt>lorem</dt>
<dd><p>ipsum dolores</p>
<p>lorem ipsum dolores</p>
<p>lorem ipsum dolores</p></dd>
</dl>
<p>lorem ipsum dolores</p></li>
</ol>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; .COPYRIGHT.</p>
</div>
</div></body></html>

Added modules/doctools/tests/fmt/html/24.


































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<!DOCTYPE html><html><head>
<title>test-definitions-enumerated - </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;