Check-in [9f0c27f8d1]

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Sep 9.

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

Overview
Comment:Converted TIPs to Markdown
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:9f0c27f8d14faef5e50a194ccd93f0f562007dd158ef901bad2deb0f1fd63be0
User & Date: mjanssen 2017-09-06 14:15:49
Context
2017-09-06
14:15
Added script to generate index check-in: e62d322a99 user: mjanssen tags: trunk
14:15
Converted TIPs to Markdown check-in: 9f0c27f8d1 user: mjanssen tags: trunk
14:15
Clean-up CVS import check-in: dce4aef4b9 user: mjanssen tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Name change from tip/0.tip to tip/0.md.

     1         -TIP:            0
     2         -Title:          Tcl Core Team Basic Rules
     3         -Version:        $Revision: 2.6 $
     4         -Author:         John Ousterhout <ouster@pacbell.net>
     5         -State:          Final
     6         -Type:           Process
     7         -Vote:           Done
     8         -Created:        11-Dec-2000
     9         -Post-History:
            1  +# TIP 0: Tcl Core Team Basic Rules
            2  +	Author:         John Ousterhout <ouster@pacbell.net>
            3  +	State:          Final
            4  +	Type:           Process
            5  +	Vote:           Done
            6  +	Created:        11-Dec-2000
            7  +	Post-History:
            8  +-----
    10      9   
    11         -~ Abstract
           10  +# Abstract
    12     11   
    13     12   This TIP describes the mission, structure, and operating procedures
    14         -of the Tcl Core Team (TCT).  When in doubt about how the TCT works,
           13  +of the Tcl Core Team \(TCT\).  When in doubt about how the TCT works,
    15     14   consult this document as the final authority.
    16     15   
    17         -~ Introduction
           16  +# Introduction
    18     17   
    19     18   The Tcl Core Team is a self-organizing group of Tcl experts who are
    20     19   responsible for the evolution and management of the Tcl core.  The
    21     20   Tcl Core Team decides what goes into releases; it implements, tests,
    22     21   and documents new features and bug fixes; it manages the release
    23     22   process; and it also manages the Tcl Developer Exchange Web site.
    24     23   
    25         -~ Scope: the Tcl core
           24  +# Scope: the Tcl core
    26     25   
    27     26   The phrase "Tcl core" refers to the Tcl interpreter and the Tk
    28         -toolkit (the packages previously released by Sun, Scriptics, and
    29         -Ajuba).  We also include the Tcl Developer Exchange Web site and
           27  +toolkit \(the packages previously released by Sun, Scriptics, and
           28  +Ajuba\).  We also include the Tcl Developer Exchange Web site and
    30     29   the Tcl bug database in the Tcl core.  The Tcl Core Team may also
    31     30   choose to take on additional responsibilities such as the creation
    32     31   of more comprehensive "batteries included" releases.  We expect
    33     32   other Tcl development teams to form independently from the Tcl
    34     33   Core Team to manage additional projects, such as popular extensions.
    35     34   The Tcl Core Team may eventually spin off some of its activities
    36     35   into separate teams.
    37     36   
    38         -~ Team membership
           37  +# Team membership
    39     38   
    40     39   The Tcl Core Team is a small group of people who are making major
    41     40   contributions to the development of the Tcl core and who are highly
    42     41   respected and trusted by the Tcl community.  Team members are expected
    43     42   to invest significant amounts of their time to improve the Tcl core.
    44     43   
    45     44   The original group of Team members was elected by the Tcl community,
................................................................................
    51     50   participating in development projects under the auspices of an
    52     51   existing team member.
    53     52   
    54     53   Inactive or disruptive members of the team can be removed by a vote
    55     54   of other Team members: a 2/3 majority of those voting is required to
    56     55   remove a Team member.
    57     56   
    58         -~ Communication
           57  +# Communication
    59     58   
    60     59   The primary mechanism for communicating with the Tcl Core Team is the
    61     60   mail alias tcl-core@lists.sourceforge.net.  This is a public mailing
    62     61   list;  anyone interested in following the discussions of the TCT is
    63     62   welcome to join the mailing list.  Email sent to this alias is
    64     63   archived, so you can review previous discussions at SourceForge.
    65     64   
    66         -~ Basic organizational structure
           65  +# Basic organizational structure
    67     66   
    68     67   The team structure is simple and flat.  All members have equal
    69     68   standing: there is no Chairman.  The Tcl Core Team makes its own
    70     69   rules and chooses its own members as described in this document.
    71     70   Anyone on the Tcl Core Team can propose a change in the rules;
    72     71   after discussion, the change is voted on by the Team and must
    73     72   receive 2/3 of the votes cast.  The person proposing a rules change
    74     73   is responsible for making sure that the change is properly
    75         -implemented after it has been approved (e.g. by modifying this
    76         -TIP, creating additional tools, etc.).
           74  +implemented after it has been approved \(e.g. by modifying this
           75  +TIP, creating additional tools, etc.\).
    77     76   
    78         -~ 2/3 vote
           77  +# 2/3 vote
    79     78   
    80     79   Wherever a 2/3 vote is called for in this document, it means that a
    81         -proposal must receive ''at least two-thirds of the votes cast'', not
           80  +proposal must receive _at least two-thirds of the votes cast_, not
    82     81   votes from at least two-thirds of all TCT members.
    83     82   
    84         -~ Projects and maintainers
           83  +# Projects and maintainers
    85     84   
    86         -Tcl improvements are organized around two key ideas: ''projects''
    87         -and ''maintainers''.  Most of the activities of the Tcl Core
           85  +Tcl improvements are organized around two key ideas: _projects_
           86  +and _maintainers_.  Most of the activities of the Tcl Core
    88     87   Team consist of projects.  A project can consist of a bug
    89     88   fix, a new feature in the Tcl core, a new facility in the Tcl
    90     89   Developer Exchange, or anything else except a change to this
    91     90   TIP.  We divide projects into two general categories: bug
    92     91   fixes and feature changes.  In general, if a project requires
    93     92   manual entries to be updated then it is a feature change;  when
    94     93   in doubt, a project is a feature change .  Bug fixes use a
................................................................................
    95     94   more streamlined process for implementation, whereas feature
    96     95   changes require discussion and approval in advance.
    97     96   
    98     97   A maintainer is someone who has taken primary responsibility for
    99     98   a portion of the Tcl sources.  Many maintainers will be members of
   100     99   the Tcl Core Team, but the Team may also select maintainers from
   101    100   outside the Tcl Core Team.  We hope to find enough maintainers to
   102         -cover all of the Tcl sources, but we will appoint a ''default
   103         -maintainer'' to handle the parts of Tcl for which no other maintainer
          101  +cover all of the Tcl sources, but we will appoint a _default
          102  +maintainer_ to handle the parts of Tcl for which no other maintainer
   104    103   has volunteered.  We'll also try to have backup maintainers who
   105    104   can step in when the primary maintainers are on vacation or
   106    105   otherwise unavailable.
   107    106   
   108    107   A maintainer accepts several responsibilities, including the
   109    108   following:
   110    109   
................................................................................
   113    112        * Arranging for bugs to be fixed, either by doing it
   114    113          himself/herself or finding someone else to do it.
   115    114   
   116    115        * Coordinating and reviewing all modifications to his/her area.
   117    116   
   118    117        * Providing assistance to other people working in his/her area.
   119    118   
   120         -~ Project life-cycle: approval, implementation, integration; TYANNOTT
          119  +# Project life-cycle: approval, implementation, integration; TYANNOTT
   121    120   
   122    121   The project for a feature change goes through three stages: approval,
   123    122   implementation, and integration.
   124    123   
   125    124   A project starts when a member of the Tcl Core Team proposes it to
   126         -the Team.  Proposals are submitted by emailing TIPs (Tcl Improvement
   127         -Proposals) to the Tcl Core Team.  The format of TIPs is described
          125  +the Team.  Proposals are submitted by emailing TIPs \(Tcl Improvement
          126  +Proposals\) to the Tcl Core Team.  The format of TIPs is described
   128    127   in a separate TIP.  Whoever proposes a project is responsible for
   129    128   making sure it is properly implemented.  A proposal without a
   130    129   committed implementor cannot be approved.
   131    130   
   132         -Project approval is done through a process called ''TYANNOTT'':
          131  +Project approval is done through a process called _TYANNOTT_:
   133    132   Two Yesses And No No's Or Two Thirds.  In order for a project to be
   134    133   approved it must have support from at least one other member of the
   135    134   Tcl Core Team besides the proposer.  Once a project has been proposed
   136    135   and discussed, if there are no objections and there is a vote of
   137         -confidence from a second team member ("Two Yesses And No No's"),
          136  +confidence from a second team member \("Two Yesses And No No's"\),
   138    137   then the project is approved.  If objections remain after the
   139    138   discussion, then the proposer must summarize the objections and
   140    139   call for a vote of the TCT; a 2/3 vote is required for approval.
   141    140   The idea here is that most projects will be no-brainers and we want
   142    141   a simple decision process that doesn't get in the way of progress.
   143    142   On the other hand, the Tcl Core Team can only work effectively if
   144    143   it is highly collegial; if the Team can't reach pretty clear
   145         -agreement on a project (i.e more than 1/3 of the TCT objects to it)
          144  +agreement on a project \(i.e more than 1/3 of the TCT objects to it\)
   146    145   then the project needs to be rethought.
   147    146   
   148    147   The second phase of a project is implementation.  The proposer is
   149    148   responsible for the implementation, either doing it himself/herself
   150    149   or arranging for someone else to do it.  The implementation is done
   151    150   in a private work area and may not be integrated with the official
   152    151   sources until the third phase, below.
   153    152   
   154    153   The third phase of a project is integrating the results back into
   155    154   the official Tcl repository.  This is where maintainers come in.
   156    155   First, before any change can be applied to the official Tcl sources,
   157    156   the implementor must post it as a patch to the SourceForge patch
   158         -manager.  This rule applies regardless of the type of change (anything
   159         -from a 1-line bug fix to a major new feature) and regardless of who
          157  +manager.  This rule applies regardless of the type of change \(anything
          158  +from a 1-line bug fix to a major new feature\) and regardless of who
   160    159   is proposing the change.  We use the SourceForge patch manager to
   161    160   record all changes and also to facilitate discussion about the
   162    161   changes before they are applied.
   163    162   
   164    163   When a patch arrives in the SourceForge patch manager, the
   165    164   appropriate maintainer reviews it and works with the proposer
   166    165   to revise it as necessary.  Other people can also review the
   167    166   patch, since it is public.  If changes are needed, a revised
   168         -patch is logged in the patch manager (the final version of
   169         -the patch must always appear in the SourceForge patch manager).
          167  +patch is logged in the patch manager \(the final version of
          168  +the patch must always appear in the SourceForge patch manager\).
   170    169   Once the maintainer is satisfied with the patch, it can be applied
   171    170   to the Tcl sources.  If the patch implementor has write access
   172    171   to the sources that he or she can apply the patch once the
   173    172   maintainer has approved it.  If the patch implementor doesn't
   174    173   have write access to the sources than the maintainer applies
   175    174   the patch.
   176    175   
................................................................................
   180    179   
   181    180   If the implementor of a patch is the maintainer, then he/she can
   182    181   apply the patch to the Tcl sources immediately after logging it in
   183    182   the SourceForge patch manager, without waiting for additional
   184    183   approval.  However, if someone objects to the patch then the
   185    184   maintainer must be prepared to revise it after the fact.
   186    185   
   187         -~ Fast path for bug fixes
          186  +# Fast path for bug fixes
   188    187   
   189    188   For a bug fix, no initial proposal or approval is required.  The
   190    189   only approval needed is for the maintainer to review the patch
   191    190   before it is applied to the sources.  For example, we invite everyone
   192    191   in the Tcl community to fix bugs and submit patches to the SourceForge
   193    192   patch manager.
   194    193   
   195         -~ Implementors outside the Tcl Core Team
          194  +# Implementors outside the Tcl Core Team
   196    195   
   197    196   We encourage people outside the Tcl Core Team to get involved with
   198    197   Tcl development.  For example, anyone can submit patches for bug
   199    198   fixes.  It's also fine for someone outside the Tcl core team to
   200    199   propose a feature change and then implement it, but there must be
   201    200   a sponsor on the Tcl Core Team who will take personal responsibility
   202    201   for it.  Typically the sponsor will be the maintainer for the area
   203    202   of the change.  It is the sponsor's responsibility to provide whatever
   204    203   level of supervision is appropriate to ensure that the project is
   205    204   executed well.  If the implementor for a project is not a TCT member
   206    205   then they cannot vote for approval: TYANNOTT requires the sponsor
   207    206   plus one other Team member.
   208    207   
   209         -~ Raising concerns
          208  +# Raising concerns
   210    209   
   211    210   If you have concerns about a project, the best time to raise them is
   212    211   during the initial discussion.  Once a project has been approved, the
   213    212   best approach is to raise the issue directly with the implementor;
   214    213   most issues should get resolved quickly this way.  If you can't find
   215    214   the implementor or can't reach agreement, and if the implementor is
   216    215   not a member of the Tcl Core Team, the next person to talk to is the
   217    216   Tcl Core Team member in charge of the project.  If you still can't get
   218    217   satisfaction, then raise the issue with the entire Tcl Core Team by
   219    218   leading a discussion.  Once all the issues are out, you can either
   220         -withdraw your objection or summarize the issues (on both sides!) and
          219  +withdraw your objection or summarize the issues \(on both sides!\) and
   221    220   call for a vote.  If you aren't a member of the Tcl Core Team
   222    221   you will need to convince a Team member to manage the discussion
   223    222   and vote.
   224    223   
   225    224   Even if a project has received initial approval, a Team member can
   226         -object to the project later (e.g. if they believe it hasn't been
   227         -implemented properly).  If the objection isn't resolved there will
          225  +object to the project later \(e.g. if they believe it hasn't been
          226  +implemented properly\).  If the objection isn't resolved there will
   228    227   be an additional vote of the Team, and the project cannot be applied
   229    228   to the official sources unless it receives a 2/3 majority of
   230    229   the votes cast.  At the same time, Team members are expected to
   231    230   raise their objections as early as possible; it would be somewhat
   232    231   anti-social to raise a basic design objection late in the
   233    232   implementation of a project when it could have been raised during
   234    233   the initial approval.
   235    234   
   236         -~ Disagreements over patches
          235  +# Disagreements over patches
   237    236   
   238    237   Normally, patches are not reviewed by the entire TCT; once the
   239    238   relevant maintainer has reviewed and approved them then they can
   240    239   be integrated.  However, everyone is invited to review as many
   241    240   patches as they wish.  If someone on the TCT objects to a patch
   242    241   and can't resolve the objection with the implementor and/or
   243    242   maintainer, then it gets discussed by the entire Tcl Core Team with
................................................................................
   248    247   Or, if someone on the Tcl Core Team objects to a patch applied by
   249    248   a maintainer, they too can start a discussion in the whole team.
   250    249   The goal of the maintainer mechanism is to simplify and speed up
   251    250   improvements in the common case where everyone is in agreement,
   252    251   while still allowing the entire Tcl Core Team to offer input and
   253    252   resolve disagreements.
   254    253   
   255         -~ Changes that span areas
          254  +# Changes that span areas
   256    255   
   257    256   If a change involves several different areas of the Tcl sources,
   258    257   with different maintainers, then one of the maintainers acts as
   259         -coordinator (presumably the one whose area has the most changes).
          258  +coordinator \(presumably the one whose area has the most changes\).
   260    259   It is their responsibility to consult with other maintainers whose
   261    260   areas are affected, so that all relevant maintainers are happy
   262    261   before the patch is applied to the sources.
   263    262   
   264         -~ Write access to the Tcl sources and the Web site
          263  +# Write access to the Tcl sources and the Web site
   265    264   
   266    265   Everyone in the Tcl Core Team has write access to all the sources
   267    266   and the Web site, but they may only make changes consistent with
   268    267   approved projects.  The Tcl Core Team can also give access to other
   269    268   people who are working on projects.  For example, as part of a project
   270    269   proposal a Tcl Core Team member can propose that the work will be
   271    270   done by someone outside the team, and that that person should have
................................................................................
   272    271   write access for putting back changes.  Giving out write access is
   273    272   part of a project decision, with the associated rules for approval.
   274    273   However, if someone outside the Tcl Core Team has write access, it
   275    274   must be under the auspices of a Tcl Core Team member; the Tcl
   276    275   Core Team member is personally responsible for making sure the
   277    276   project is completed satisfactorily and/or cleaning up any messes.
   278    277   
   279         -~ Deadlock resolution
          278  +# Deadlock resolution
   280    279   
   281    280   If something should go wrong with the TCT organization and the
   282    281   Tcl Core Team deadlocks to a point where it can't make meaningful
   283    282   progress, then John Ousterhout will step in as benevolent dictator
   284    283   and make enough unilateral decisions to break the deadlock.
   285    284   
   286         -~ Copyright
          285  +# Copyright
   287    286   
   288    287   This document has been placed in the public domain.
          288  +

Name change from tip/1.tip to tip/1.md.

     1         -TIP:            1
     2         -Title:          TIP Index
     3         -Version:        $Revision: 1.6 $
     4         -Author:         TIP Editor <donal.fellows@cs.man.ac.uk>
     5         -State:          Active
     6         -Type:           Informational
     7         -Vote:           No voting
     8         -Created:        14-Sep-2000
     9         -Post-History:
            1  +# TIP 1: TIP Index
            2  +	Author:         TIP Editor <donal.fellows@cs.man.ac.uk>
            3  +	State:          Active
            4  +	Type:           Informational
            5  +	Vote:           No voting
            6  +	Created:        14-Sep-2000
            7  +	Post-History:
            8  +-----
    10      9   
    11         -~ Abstract
           10  +# Abstract
    12     11   
    13     12   This TIP contains the index of all TIPs published over the lifetime of
    14     13   the TCT. It will be continually and automatically updated.
    15     14   
    16         -~ Index
           15  +# Index
    17     16   
    18         -#index:
           17  +\#index:
    19     18   
    20     19   White backgrounds indicate that the TIP is still a draft, yellow
    21     20   backgrounds highlight TIPs being voted on, and where a TIP has been
    22     21   rejected, withdrawn or obsoleted its index entry has a dark grey
    23     22   background.  Blue backgrounds indicate a TIP has been accepted,
    24     23   but still needs an implementation approved by maintainers.  Green
    25     24   backgrounds indicate that the TIP is deferred, waiting for someone
    26     25   to work on it.
    27     26   
    28         -~ Explanations and How To Submit New TIPs
           27  +# Explanations and How To Submit New TIPs
    29     28   
    30         -See [2] for a description of the editorial process a TIP has to go
    31         -through and [3] for a description of their structure and the commands
           29  +See [[2]](2.md) for a description of the editorial process a TIP has to go
           30  +through and [[3]](3.md) for a description of their structure and the commands
    32     31   used to write them. You submit a TIP to this archive by emailing it
    33         -(preferably in source form) to the TIP editor <donal.fellows@man.ac.uk>
           32  +\(preferably in source form\) to the TIP editor <donal.fellows@man.ac.uk>
    34     33   who will check it for following of the guidelines, style and general
    35     34   relevance to Tcl/Tk before checking it into the CVS archive and notifying
    36     35   the author, the rest of the Tcl Core Team, and the relevant newsgroups.
    37     36   
    38         -~ Copyright
           37  +# Copyright
    39     38   
    40     39   This document has been placed in the public domain.
           40  +

Name change from tip/10.tip to tip/10.md.

     1         -TIP:            10
     2         -Title:          Tcl I/O Enhancement: Thread-Aware Channels
     3         -Version:        $Revision: 1.6 $
     4         -Author:         Andreas Kupries <a.kupries@westend.com>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        08-Nov-2000
     9         -Post-History:   
    10         -Tcl-Version:    8.4
            1  +# TIP 10: Tcl I/O Enhancement: Thread-Aware Channels
            2  +	Author:         Andreas Kupries <a.kupries@westend.com>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        08-Nov-2000
            7  +	Post-History:   
            8  +	Tcl-Version:    8.4
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP describes how to change the generic I/O layer in the Tcl core
    15     14   to make channels aware of the thread they are managed by.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19     18   To explain the motives behind this TIP first a short look at the
    20     19   history of channels and threading.
    21     20   
    22     21   In ancient times the Tcl core was not thread safe and did not employ
    23     22   threads.  All channels belonged to a single interpreter. Later on
    24     23   interpreter hierarchies were introduced and the ability to move or
    25     24   share a channel between the interpreters in a hierarchy. When the Tcl
    26     25   core was made thread safe a short time after the ability to move
    27         -channels between threads was added (Helper APIs in the core, main
    28         -functionality in the Thread extension).  The goal behind these
           26  +channels between threads was added \(Helper APIs in the core, main
           27  +functionality in the Thread extension\).  The goal behind these
    29     28   modifications was to enable the creation of stream-like communication
    30     29   paths between threads to complement the message based facilities
    31         -(thread send). The modifications were only a partial success because
           30  +\(thread send\). The modifications were only a partial success because
    32     31   an in-depth analysis of the relevant data structures showed that the
    33     32   sharing of a channel between threads is not possible with the current
    34     33   design, only moving. This was implemented to allow at least the
    35     34   dispatcher- / worker-thread pattern for structuring a threaded
    36     35   application.
    37     36   
    38     37   In further pursuit of the original goal the currently chosen approach
    39     38   is to define a channeltype where two channels are connected internally
    40     39   through in-memory fifo buffers where access to these shared structures
    41     40   is protected by mutexes.
    42     41   
    43     42   During the implementation of fileevents for this channeltype it was
    44         -discovered that an efficient implementation of this part is ''not''
           43  +discovered that an efficient implementation of this part is _not_
    45     44   possible because of the inability to post file events to the
    46     45   eventqueue of the thread the other channel of the pair resides in. An
    47         -API to post such events is available (''Tcl_ThreadQueueEvent''), but
           46  +API to post such events is available \(_Tcl\_ThreadQueueEvent_\), but
    48     47   not the information which thread actually manages the other
    49     48   channel. Because of this the current implementation of the channeltype
    50     49   uses polling based upon timer events posted by each side/thread to
    51     50   itself to manage file events in a rather inefficient way.
    52     51   
    53         -~ Reference implementation
           52  +# Reference implementation
    54     53   
    55     54   This TIP now proposes to change the internals of the generic I/O
    56     55   layers in the core so that
    57     56   
    58     57      1. Channels know the thread they are managed by, and
    59     58   
    60     59      1. are able to deliver this information to an extension querying
................................................................................
    62     61   
    63     62   This then allows the two sides of the channeltype mentioned above to
    64     63   post events to each other, facilitating an efficient implementation of
    65     64   fileevents.
    66     65   
    67     66   The changes necessary to accomplish this are:
    68     67   
    69         -   1. Extend the structure ''ChannelState'' in tclIO.h with a new
    70         -      field of type ''Tcl_ThreadId'' to hold the id of the thread
           68  +   1. Extend the structure _ChannelState_ in tclIO.h with a new
           69  +      field of type _Tcl\_ThreadId_ to hold the id of the thread
    71     70         currently managing all channels with this state. Note: This
    72     71         structure is shared by all channels in a stack of
    73     72         transformations.
    74     73   
    75         -   1. Modify the procedure ''Tcl_CreateChannel'' to store the Id of
    76         -      the current thread in the ''ChannelState'' of the new channel.
    77         -      This information can be obtained with ''Tcl_GetCurrentThread''.
    78         -      It is ''not'' necessary to modify ''Tcl_StackChannel'' as the
           74  +   1. Modify the procedure _Tcl\_CreateChannel_ to store the Id of
           75  +      the current thread in the _ChannelState_ of the new channel.
           76  +      This information can be obtained with _Tcl\_GetCurrentThread_.
           77  +      It is _not_ necessary to modify _Tcl\_StackChannel_ as the
    79     78         thread information is already part of the state when it is
    80     79         called, and won't be changed by the call.
    81     80   
    82     81      1. If some sort of NIL/NULL value meaning "No thread" is available
    83         -      for ''Tcl_ThreadId'', then we should modify ''Tcl_CutChannel''
           82  +      for _Tcl\_ThreadId_, then we should modify _Tcl\_CutChannel_
    84     83         to insert this value into the state of the channel it is called
    85     84         with, as this channel will not be managed by any thread
    86         -      afterward (the procedure removes the channel from the list of
    87         -      all channels managed by the current thread).
           85  +      afterward \(the procedure removes the channel from the list of
           86  +      all channels managed by the current thread\).
    88     87   
    89         -   1. Modify ''Tcl_SpliceChannel'' in the same manner as
    90         -      ''Tcl_CreateChannel'' as the channel will be managed by the
    91         -      current thread afterward (The procedure adds the channel to the
    92         -      list of all channels managed by the current thread).
           88  +   1. Modify _Tcl\_SpliceChannel_ in the same manner as
           89  +      _Tcl\_CreateChannel_ as the channel will be managed by the
           90  +      current thread afterward \(The procedure adds the channel to the
           91  +      list of all channels managed by the current thread\).
    93     92   
    94     93      1. Declare a new API function to retrieve the Id of the managing
    95     94         thread from a channel. Add this declaration to generic/tcl.decls
    96     95         and implement the function in the file generic/tclIO.c.  I
    97         -      propose ''Tcl_GetChannelThread'' as the name of this new API
           96  +      propose _Tcl\_GetChannelThread_ as the name of this new API
    98     97         function.
    99     98   
   100     99   A patch implementing all of the changes described above and
   101    100   additionally extending the documentation and the test-suite
   102    101   is available here:
   103         -http://www.cs.man.ac.uk/fellowsd-bin/TIP/10.patch
          102  +<http://www.cs.man.ac.uk/fellowsd-bin/TIP/10.patch>
   104    103   
   105         -~ Copyright
          104  +# Copyright
   106    105   
   107    106   This document has been placed in the public domain.
          107  +

Name change from tip/100.tip to tip/100.md.

     1         -TIP:            100
     2         -Title:          Add Support for Unloading Dynamic Libraries Loaded with [load]
     3         -Version:        $Revision: 1.10 $
     4         -Author:         George Petasis <petasis@iit.demokritos.gr>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        11-Jun-2002
     9         -Post-History:   
    10         -Discussions-To: news:comp.lang.tcl
    11         -Keywords:       load,unload,dynamic library
    12         -Tcl-Version:    8.5
            1  +# TIP 100: Add Support for Unloading Dynamic Libraries Loaded with [load]
            2  +	Author:         George Petasis <petasis@iit.demokritos.gr>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        11-Jun-2002
            7  +	Post-History:   
            8  +	Discussions-To: news:comp.lang.tcl
            9  +	Keywords:       load,unload,dynamic library
           10  +	Tcl-Version:    8.5
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16     15   Tcl already provides facilities for loading dynamic libraries, through
    17         -the ''load'' command.  However no facilities are currently offered in
    18         -order to ''unload'' dynamic libraries already loaded with the ''load''
           16  +the _load_ command.  However no facilities are currently offered in
           17  +order to _unload_ dynamic libraries already loaded with the _load_
    19     18   command.  This TIP tries to add support for unloading libraries, by
    20         -introducing a new Tcl command (''unload'') and the guidelines that
           19  +introducing a new Tcl command \(_unload_\) and the guidelines that
    21     20   dynamic libraries must follow, in order to be unloadable.  Note that
    22         -the ''unload'' command will operate only on libraries that are
           21  +the _unload_ command will operate only on libraries that are
    23     22   designed to be unloadable by their developers.  This way backward
    24     23   compatibility with older extensions is maintained, as unload will
    25     24   never try to unload libraries unaware of this new functionality.
    26     25   
    27         -~ Rationale
           26  +# Rationale
    28     27   
    29     28   Tcl is an ideal language for component-based applications.  Usually
    30     29   these applications offer a framework in which components developed by
    31     30   the users of the application can be embedded, in order to extend the
    32     31   functionality of the framework.  Usually, these extensions are
    33         -implemented as C/C++ dynamic libraries that are loaded through the
    34         -''load'' Tcl command.
           32  +implemented as C/C\+\+ dynamic libraries that are loaded through the
           33  +_load_ Tcl command.
    35     34   
    36     35   However the development of such components can be a time-consuming
    37     36   process, as developers have to restart the framework application in
    38     37   order to be able to reload the library into it and test its altered
    39         -functionality.  And this can be quite annoying (depending on the
    40         -application of course), as usually processing within the application
           38  +functionality.  And this can be quite annoying \(depending on the
           39  +application of course\), as usually processing within the application
    41     40   is required in order to bring it into a proper state before testing
    42     41   the library.
    43     42   
    44     43   The development cycle can be significantly shortened if Tcl provides a
    45     44   mechanism for unloading a dynamic library.  A new version of the
    46     45   library can be created, as its object file can now be written, and the
    47     46   updated library can be re-loaded.
    48     47   
    49     48   However, this is not the only application of unload.
    50     49   Services running for long periods of time and want to unload
    51     50   no longer needed functionality, replacing parts of an applications
    52         -(i.e. from an automatic update procedure) or functionality
    53         -temporarily needed (i.e. a web browser that loads a plugin
    54         -to display a file of a particular file type) are some
           51  +\(i.e. from an automatic update procedure\) or functionality
           52  +temporarily needed \(i.e. a web browser that loads a plugin
           53  +to display a file of a particular file type\) are some
    55     54   additional fields of application.
    56     55   
    57         -~ Introduction
           56  +# Introduction
    58     57   
    59     58   Unload functionality has been left out of the Tcl core, mainly because
    60     59   library unloading was poorly implemented in many operating systems.
    61     60   But almost all operating systems have been improved in the meantime,
    62     61   and as a result most modern operating systems now support library
    63     62   unloading.
    64     63   
    65     64   The main idea of this TIP is to enable dynamic library unloading at
    66         -the Tcl level, in the same sense ''load'' provides dynamic library
           65  +the Tcl level, in the same sense _load_ provides dynamic library
    67     66   loading.  However, library unloading will be provided only when the
    68         -underlying operating system support this feature (as is also the case
    69         -for ''load'') and only when the library to be unloaded provides a set
           67  +underlying operating system support this feature \(as is also the case
           68  +for _load_\) and only when the library to be unloaded provides a set
    70     69   of functions that can "undo" the changes the library has made to the
    71     70   interpreter.  In all other cases, unloading a library will result in
    72     71   an error.
    73     72   
    74         -This TIP proposes the insertion of a new Tcl command named ''unload''
    75         -and two functions ''pkg_Unload'' and ''pkg_SafeUnload'', modelled
    76         -after ''pkg_Init'' and ''pkg_SafeInit'', that libraries which can be
           73  +This TIP proposes the insertion of a new Tcl command named _unload_
           74  +and two functions _pkg\_Unload_ and _pkg\_SafeUnload_, modelled
           75  +after _pkg\_Init_ and _pkg\_SafeInit_, that libraries which can be
    77     76   unloaded should implement.
    78     77   
    79         -~ Unloadable Libraries
           78  +# Unloadable Libraries
    80     79   
    81     80   A main concern is related to when a shared library can be "unloadable".
    82     81   An unloadable library is a library characterised as such by its
    83     82   developer. The developer of the library must export a function
    84     83   from the library, similar to the library's initialisation
    85     84   function. The unload command will never try to unload a library
    86     85   that does not provide such a function. This makes old libraries
    87         -(before the introduction of the unload functionality) safe.
           86  +\(before the introduction of the unload functionality\) safe.
    88     87   
    89     88   There is a category of libraries that
    90         -can never be unloaded (i.e. libraries that register new
    91         -tcl object types). However, the choice is upon the developer:
           89  +can never be unloaded \(i.e. libraries that register new
           90  +tcl object types\). However, the choice is upon the developer:
    92     91   the developer knows if the library can be unloadable. The simpler
    93     92   case, libraries that only register new commands are the most
    94     93   probable libraries to be unloadable.
    95     94   Libraries that export functions through a stub mechanism cannot be
    96     95   unloaded, as the were meant for having dependencies with
    97     96   other libraries that use the exported API. There is no way for
    98     97   the provider library to know wether it is used or not.
    99     98   
   100         -~ Specification
           99  +# Specification
   101    100   
   102    101   Actually, all the facilities for unloading dynamic libraries already
   103    102   exist in the Tcl core and simply they are not yet exposed at the Tcl
   104    103   level.  As a result, the implementation of the unload command should
   105    104   be fairly easy.
   106    105   
   107         -''load'' as it is currently implemented loads a dynamic library only
          106  +_load_ as it is currently implemented loads a dynamic library only
   108    107   the first time this library is loaded.  It keeps an internal cache of
   109    108   all loaded libraries and if an already loaded library is requested
   110    109   again, only its initialisation function is called.  This cache should
   111    110   be extended to keep some additional information:
   112    111   
   113    112      1.  Two reference counts, counting how many times a specific
   114    113          library has been loaded.  This reference count should be
   115         -       increased by each ''load'' and decreased for each ''unload''.
          114  +       increased by each _load_ and decreased for each _unload_.
   116    115          When it reaches 0, the library can be unloaded.  Safe
   117    116          interpreters and normal interpreters should have different
   118    117          reference counts.  Both should be 0 in order for a library to
   119    118          be unloaded.
   120    119   
   121         -   2.  The addresses of the ''pkg_Unload'' and ''pkg_SafeUnload''
          120  +   2.  The addresses of the _pkg\_Unload_ and _pkg\_SafeUnload_
   122    121          functions, if these are implemented by the library.  If both of
   123    122          these functions are missing, the library will never be
   124         -       unloaded.  If only ''pkg_Unload'' is implemented, the library
          123  +       unloaded.  If only _pkg\_Unload_ is implemented, the library
   125    124          can be unloaded if it never has been loaded in a safe
   126         -       interpreter.  Finally, if ''pkg_SafeUnload'' is implemented,
          125  +       interpreter.  Finally, if _pkg\_SafeUnload_ is implemented,
   127    126          the library can be unloaded if it has never been loaded in a
   128    127          normal interpreter.
   129    128   
   130         -The ''unload'' command will always return an error, if the operating
          129  +The _unload_ command will always return an error, if the operating
   131    130   system does not support library unloading.  In case the operating
   132    131   system supports library unloading:
   133    132   
   134         -   1.  ''unload'' will examine the cache of ''load'' to locate the
          133  +   1.  _unload_ will examine the cache of _load_ to locate the
   135    134          entry for the library to be unloaded.  It is an error to unload
   136         -       a library that has not been loaded with ''load''.
          135  +       a library that has not been loaded with _load_.
   137    136   
   138         -   2.  If the entry in the cache is found, ''unload'' checks whether
          137  +   2.  If the entry in the cache is found, _unload_ checks whether
   139    138          the corresponding for the interpreter type unload function
   140    139          pointer is NULL or not.  If it is NULL, the library cannot be
   141    140          unloaded under this interpreter and again an error is returned.
   142    141   
   143    142      3.  If the unload function pointer is not NULL, it is executed.  If
   144         -       an error is returned by this function, ''unload'' also returns
          143  +       an error is returned by this function, _unload_ also returns
   145    144          an error.
   146    145   
   147    146      4.  If the unload function finishes without errors, the reference
   148    147          count corresponding to the interpreter type is decreased.  If
   149    148          both reference counts reach 0, the library is unloaded.
   150    149   
   151         -~ Responsibilities of the Unload Functions
          150  +# Responsibilities of the Unload Functions
   152    151   
   153    152   Its up to the developer of the library to decide if its library can be
   154    153   unloaded or not.  A library can be unloaded if the function
   155         -''pkg_Unload'' is implemented and exported as a symbol from the
          154  +_pkg\_Unload_ is implemented and exported as a symbol from the
   156    155   library, and the library will never be loaded in a safe interpreter.
   157    156   A library that can be also loaded in safe interpreters is unloadable
   158         -if the function ''pkg_SafeUnload'' is also available.  These two
          157  +if the function _pkg\_SafeUnload_ is also available.  These two
   159    158   functions will accept two arguments, the interpreter under which the
   160    159   library is unloaded and an integer, holding various flags.  The flags argument
   161         -can be either ''TCL_UNLOAD_DETACH_FROM_INTERPRETER'' or
   162         -''TCL_UNLOAD_DETACH_FROM_PROCESS''. In case the library will remain attached to
   163         -the process after the unload procedure returns (i.e. because the library is
   164         -used by other interpreters), TCL_UNLOAD_DETACH_FROM_INTERPRETER will be defined.
          160  +can be either _TCL\_UNLOAD\_DETACH\_FROM\_INTERPRETER_ or
          161  +_TCL\_UNLOAD\_DETACH\_FROM\_PROCESS_. In case the library will remain attached to
          162  +the process after the unload procedure returns \(i.e. because the library is
          163  +used by other interpreters\), TCL\_UNLOAD\_DETACH\_FROM\_INTERPRETER will be defined.
   165    164   However, if the library is used only by the target interpreter and the library
   166    165   will be detached from the application as soon as the unload procedure returns,
   167         -the flags argument will be set to TCL_UNLOAD_DETACH_FROM_PROCESS. 
          166  +the flags argument will be set to TCL\_UNLOAD\_DETACH\_FROM\_PROCESS. 
   168    167   
   169    168   The main responsibility of these functions is to remove from the
   170    169   interpreter they are unloaded under any reference to a function
   171    170   residing inside the library.  For example, such a function must:
   172    171   
   173    172      1.  Unregister any commands that have been registered by the
   174         -       ''Init()'' function to the ''interpreter'' given by the first
          173  +       _Init\(\)_ function to the _interpreter_ given by the first
   175    174          argument.  In order to do this, the library should keep
   176         -       internally the tokens returned by each ''Tcl_Create*Command'',
          175  +       internally the tokens returned by each _Tcl\_Create\*Command_,
   177    176          as command may have been renamed.
   178    177   
   179    178      2.  Unregister any other commands that may have been registered to
   180         -       the interpreter during the use of the library (usually used to
   181         -       represent special special data structures).
          179  +       the interpreter during the use of the library \(usually used to
          180  +       represent special special data structures\).
   182    181   
   183         -If the flag ''TCL_UNLOAD_DETACH_FROM_PROCESS'' is defined, the
          182  +If the flag _TCL\_UNLOAD\_DETACH\_FROM\_PROCESS_ is defined, the
   184    183   developer must do additional task, that are not normally required when
   185    184   the library gets unloaded from an interpreter:
   186    185   
   187    186      3.  Free any memory occupied by the internal structures of
   188    187          the library.
   189    188   
   190    189      4.  In general, try to remove any references Tcl may have
   191    190          to functions provided by the library.
   192    191   
   193    192   If the developer cannot remove all reference to functions to the
   194    193   library, its better to not provide at all these two functions, so as
   195    194   unload to never attempt to unload the library.
   196    195   
   197         -~ Dependencies Among Libraries
          196  +# Dependencies Among Libraries
   198    197   
   199    198   It is possible that a library A has been loaded that exports some
   200         -symbols.  Then a library B is loaded, that has dependencies (i.e. uses
   201         -some exported symbols) on A.  What if A gets unloaded?
          199  +symbols.  Then a library B is loaded, that has dependencies \(i.e. uses
          200  +some exported symbols\) on A.  What if A gets unloaded?
   202    201   
   203    202   Actually, most modern operating systems seem to provide a solution to
   204    203   this problem, as reference counts are hold internally by the operating
   205    204   system for each library.  Newer Windows, Solaris and Linux seem to
   206    205   provide similar solutions and in reality they don't unload the library
   207    206   if such symbols remain, even if the unload system call has been made
   208    207   for the library.  Both libraries A and B have to be unloaded in order
   209    208   for A to be really removed from the address space.
   210    209   
   211         -~ Reference Implementation
          210  +# Reference Implementation
   212    211   
   213    212   A reference implementation can be found at:
   214         -http://sf.net/tracker/?func=detail&aid=823486&group_id=10894&atid=310894
          213  +<http://sf.net/tracker/?func=detail&aid=823486&group\_id=10894&atid=310894>
   215    214   
   216         -~ Copyright
          215  +# Copyright
   217    216   
   218    217   This document has been placed in the public domain.
   219    218   
   220         -~ Appendix: The unload man page.
          219  +# Appendix: The unload man page.
   221    220   
   222    221        NAME
   223    222        unload - Unload machine code.
   224    223        SYNOPSIS
   225    224        unload ?switches? fileName
   226    225        unload ?switches? fileName packageName
   227    226        unload ?switches? fileName packageName interp
................................................................................
   253    252   This command tries to unload shared libraries previously
   254    253   loaded with load from the application's address space.
   255    254   fileName is the name of the file containing the library
   256    255   file to be unload; it must be the same as the filename
   257    256   provided to load for loading the library. packageName is
   258    257   the name of the package, and is used to compute the name
   259    258   of the unload procedure. interp is the path name of the
   260         -interpreter from which to unload the package (see the
   261         -interp manual entry for details); if interp is omitted,
          259  +interpreter from which to unload the package \(see the
          260  +interp manual entry for details\); if interp is omitted,
   262    261   it defaults to the interpreter in which the unload
   263    262   command was invoked.
   264    263   
   265    264   If the initial arguments to unload start with - then they
   266    265   are treated as switches. The following switches are
   267    266   currently supported:
   268    267   
................................................................................
   279    278        Marks the end of switches. The argument following
   280    279        this one will be treated as a fileName even if it
   281    280        starts with a -.
   282    281   
   283    282   When a file containing a shared library is loaded through
   284    283   the load command, Tcl associates two reference counts to
   285    284   the library file. The first counter shows how many times
   286         -the library has been loaded into normal (trusted)
          285  +the library has been loaded into normal \(trusted\)
   287    286   interpreters while the second describes how many times
   288    287   the library has been loaded into safe interpreters. As a
   289    288   file containing a shared library can be loaded only once
   290         -by Tcl (with the first load call on the file), these
          289  +by Tcl \(with the first load call on the file\), these
   291    290   counters track how many interpreters use the library.
   292    291   Each subsequent call to load after the first, simply
   293    292   increaments the proper reference count.
   294    293   
   295    294   unload works in the opposite direction. As a first step,
   296    295   unload will check whether the library is unloadable: an
   297    296   unloadable library exports a special unload procedure.
   298    297   The name of the unload procedure is determined by
   299    298   packageName and whether or not the target interpreter is
   300    299   a safe one. For normal interpreters the name of the
   301         -initialization procedure will have the form pkg_Unload,
          300  +initialization procedure will have the form pkg\_Unload,
   302    301   where pkg is the same as packageName except that the
   303    302   first letter is converted to upper case and all other
   304    303   letters are converted to lower case. For example, if
   305    304   packageName is foo or FOo, the initialization procedure's
   306         -name will be Foo_Unload. If the target interpreter is a
          305  +name will be Foo\_Unload. If the target interpreter is a
   307    306   safe interpreter, then the name of the initialization
   308         -procedure will be pkg_SafeUnload instead of pkg_Unload.
          307  +procedure will be pkg\_SafeUnload instead of pkg\_Unload.
   309    308   
   310         -If unload determines that a library is not unloadable (or
          309  +If unload determines that a library is not unloadable \(or
   311    310   unload functionality has been disabled during
   312         -compilation), an error will be returned. If the library
          311  +compilation\), an error will be returned. If the library
   313    312   is unloadable, then unload will call the unload
   314         -procedure. If the unload procedure returns TCL_OK, unload
          313  +procedure. If the unload procedure returns TCL\_OK, unload
   315    314   will proceed and decrease the proper reference count
   316         -(depending on the target interpreter type). When both
          315  +\(depending on the target interpreter type\). When both
   317    316   reference counts have reached 0, the library will be
   318    317   detached from the process.
   319    318   
   320    319   The unload procedure must match the following prototype:
   321         -typedef int Tcl_PackageUnloadProc(Tcl_Interp *interp, int
   322         -flags);
          320  +typedef int Tcl\_PackageUnloadProc\(Tcl\_Interp \*interp, int
          321  +flags\);
   323    322   
   324    323   The interp argument identifies the interpreter from which
   325    324   the library is to be unloaded. The unload procedure must
   326         -return TCL_OK or TCL_ERROR to indicate whether or not it
          325  +return TCL\_OK or TCL\_ERROR to indicate whether or not it
   327    326   completed successfully; in the event of an error it
   328    327   should set the interpreter's result to point to an error
   329    328   message. In this case, the result of the unload command
   330    329   will be the result returned by the unload procedure. The
   331    330   flags argument can be either
   332         -TCL_UNLOAD_DETACH_FROM_INTERPRETER or
   333         -TCL_UNLOAD_DETACH_FROM_PROCESS. In case the library will
          331  +TCL\_UNLOAD\_DETACH\_FROM\_INTERPRETER or
          332  +TCL\_UNLOAD\_DETACH\_FROM\_PROCESS. In case the library will
   334    333   remain attached to the process after the unload procedure
   335         -returns (i.e. because the library is used by other
   336         -interpreters), TCL_UNLOAD_DETACH_FROM_INTERPRETER will be
          334  +returns \(i.e. because the library is used by other
          335  +interpreters\), TCL\_UNLOAD\_DETACH\_FROM\_INTERPRETER will be
   337    336   defined. However, if the library is used only by the
   338    337   target interpreter and the library will be detached from
   339    338   the application as soon as the unload procedure returns,
   340    339   the flags argument will be set to
   341         -TCL_UNLOAD_DETACH_FROM_PROCESS.
          340  +TCL\_UNLOAD\_DETACH\_FROM\_PROCESS.
   342    341   
   343    342   The unload command cannot unload libraries that are
   344    343   statically linked with the application. If fileName is an
   345    344   empty string, then packageName must be specified.
   346    345   If packageName is omitted or specified as an empty
   347    346   string, Tcl tries to guess the name of the package. This
   348    347   may be done differently on different platforms. The
   349    348   default guess, which is used on most UNIX platforms, is
   350    349   to take the last element of fileName, strip off the first
   351    350   three characters if they are lib, and use any following
   352    351   alphabetic and underline characters as the module name.
   353    352   For example, the command unload libxyz4.2.so uses the
   354         -module name xyz and the command unload bin/last.so {}
          353  +module name xyz and the command unload bin/last.so \{\}
   355    354   uses the module name last.
   356    355   
   357    356   PORTABILITY ISSUES
   358    357   
   359    358   Unix
   360    359        Not all unix operating systems support library
   361    360        unloading. Under such an operating system unload
   362         -     returns an error (unless -nocomplain has been
   363         -     specified).
          361  +     returns an error \(unless -nocomplain has been
          362  +     specified\).
   364    363   
   365    364   Macintosh
   366    365        <Somebody to comment on this?>
   367    366   
   368    367   BUGS
   369    368   
   370    369   If the same file is loaded by different fileNames, it
   371    370   will be loaded into the process's address space multiple
   372    371   times. The behavior of this varies from system to system
   373         -(some systems may detect the redundant loads, others may
   374         -not). In case a library has been silently detached by the
   375         -operating system (and as a result Tcl thinks the library
   376         -is still loaded), it may be dangerous to use unload on
   377         -such a library (as the library will be completely
          372  +\(some systems may detect the redundant loads, others may
          373  +not\). In case a library has been silently detached by the
          374  +operating system \(and as a result Tcl thinks the library
          375  +is still loaded\), it may be dangerous to use unload on
          376  +such a library \(as the library will be completely
   378    377   detached from the application while some interpreters
   379         -will continue to use it).
          378  +will continue to use it\).
   380    379   
   381    380   SEE ALSO
   382    381   
   383    382   info sharedlibextension, load, safe
   384    383   
   385    384   KEYWORDS
   386    385   
   387    386   binary code, unloading, safe interpreter, shared library
          387  +

Name change from tip/101.tip to tip/101.md.

     1         -TIP:		101
     2         -Title:		Export Tcltest Configuration
     3         -Version:	$Revision: 1.4 $
     4         -Author:		Don Porter <dgp@users.sf.net>
     5         -State:		Final
     6         -Type:		Project
     7         -Vote:		Done
     8         -Created:	11-Jun-2002
     9         -Post-History:	
    10         -Tcl-Version:	8.4
            1  +# TIP 101: Export Tcltest Configuration
            2  +	Author:		Don Porter <dgp@users.sf.net>
            3  +	State:		Final
            4  +	Type:		Project
            5  +	Vote:		Done
            6  +	Created:	11-Jun-2002
            7  +	Post-History:	
            8  +	Tcl-Version:	8.4
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -Proposes public command ''tcltest::configure'' to give programmatic
           13  +Proposes public command _tcltest::configure_ to give programmatic
    15     14   control to processing configuration options of the tcltest package.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19         -During ''package require tcltest'', the internal command
    20         -''ProcessCmdLineArgs'' is evaluated.  This command uses the contents
    21         -of ''$::argv'' as option-value pairs to configure several aspects of
           18  +During _package require tcltest_, the internal command
           19  +_ProcessCmdLineArgs_ is evaluated.  This command uses the contents
           20  +of _$::argv_ as option-value pairs to configure several aspects of
    22     21   the tcltest package.
    23     22   
    24     23   This approach leaves two aspect of package configuration hardwired,
    25         -and outside of the control of users of ''tcltest''.  First, the timing
           24  +and outside of the control of users of _tcltest_.  First, the timing
    26     25   of configuration is fixed to package load time.  Second, the source of
    27         -configuration data is fixed to be the global variable ''argv''.
           26  +configuration data is fixed to be the global variable _argv_.
    28     27   
    29     28   It would improve flexible use of tcltest to export a public command,
    30         -''tcltest::configure'', that will allow configuration of ''tcltest''
           29  +_tcltest::configure_, that will allow configuration of _tcltest_
    31     30   by its users at any time and from any source.
    32     31   
    33         -~ Proposal
           32  +# Proposal
    34     33   
    35         -Add and export the command ''tcltest::configure'', with the syntax:
           34  +Add and export the command _tcltest::configure_, with the syntax:
    36     35   
    37         -|	tcltest::configure ?option? ?value option value ...?
           36  +		tcltest::configure ?option? ?value option value ...?
    38     37   
    39         -With no options, ''configure'' returns a list of the available
    40         -configurable options.  With a single ''option'' argument,
    41         -''configure'' returns the corresponding value of that option, or an
           38  +With no options, _configure_ returns a list of the available
           39  +configurable options.  With a single _option_ argument,
           40  +_configure_ returns the corresponding value of that option, or an
    42     41   error if no such option exists.  In the most general form,
    43         -''configure'' accepts an even number of arguments that are alternating
           42  +_configure_ accepts an even number of arguments that are alternating
    44     43   options and values, and sets each option to each value.
    45     44   
    46     45   The list of options and acceptable values are to be the same as those
    47         -currently recognized by ''tcltest'' as its command line options.  The
           46  +currently recognized by _tcltest_ as its command line options.  The
    48     47   difference is that this configuration can now be performed
    49     48   programmatically, not only on the command line.
    50     49   
    51         -With complete programmatic access to ''tcltest'' configuration made
    52         -available, the special customization hooks ''processCmdLineArgsHook''
    53         -and ''processCmdLineArgsAddFlagsHook'' will be deprecated and removed
           50  +With complete programmatic access to _tcltest_ configuration made
           51  +available, the special customization hooks _processCmdLineArgsHook_
           52  +and _processCmdLineArgsAddFlagsHook_ will be deprecated and removed
    54     53   from the documentation.  Compatibility support for their existing use
    55     54   will be provided as described below.
    56     55   
    57         -~ Compatibility
           56  +# Compatibility
    58     57   
    59     58   Many existing test suites have been written depending on the
    60         -auto-configuration from ''$::argv'' at package load time.  Some of
           59  +auto-configuration from _$::argv_ at package load time.  Some of
    61     60   them may also be using the special customization hooks that allow the
    62     61   addition of more command line options.  For compatibility, if the
    63         -presence of any of these hooks is detected, ''tcltest'' will fall back
           62  +presence of any of these hooks is detected, _tcltest_ will fall back
    64     63   to performing its load-time configuration.  Also, if any command that
    65     64   can be influenced by configured values is called prior to any call to
    66         -''configure'', then automatic configuration from ''::argv'' will be
           65  +_configure_, then automatic configuration from _::argv_ will be
    67     66   performed.
    68     67   
    69         -~ Copyright
           68  +# Copyright
    70     69   
    71     70   This document has been placed in the public domain.
           71  +

Name change from tip/102.tip to tip/102.md.

     1         -TIP:		102
     2         -Title:		Change [trace list] to [trace info]
     3         -Author:		Reinhard Max <max@suse.de>
     4         -Type:		Project
     5         -Tcl-Version:	8.4
     6         -State:		Final
     7         -Created:	12-Jun-2002
     8         -Keywords:	trace, info, introspection
     9         -Version:	$Revision: 1.4 $
    10         -Vote:		Done
    11         -Post-History:	
            1  +# TIP 102: Change [trace list] to [trace info]
            2  +	Author:		Reinhard Max <max@suse.de>
            3  +	Type:		Project
            4  +	Tcl-Version:	8.4
            5  +	State:		Final
            6  +	Created:	12-Jun-2002
            7  +	Keywords:	trace, info, introspection
            8  +	Vote:		Done
            9  +	Post-History:	
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15     14   This TIP proposes to change the name of the introspection subcommand
    16         -of the ''trace'' command from ''list'' to ''info''.
           15  +of the _trace_ command from _list_ to _info_.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20         -Although the functionality of the ''trace'' command (as extended by
    21         -[62]) is good, the name of the introspection subcommand, ''list'' is
           19  +Although the functionality of the _trace_ command \(as extended by
           20  +[[62]](62.md)\) is good, the name of the introspection subcommand, _list_ is
    22     21   not such a good choice:
    23     22   
    24         - * The name ''info'' is already well known for introspection purposes
    25         -   in Tcl (e.g. [[info]] and [[after info]].)
           23  + * The name _info_ is already well known for introspection purposes
           24  +   in Tcl \(e.g. [info] and [after info].\)
    26     25   
    27         - * The name [[trace list]] could be misunderstood as having to do with
           26  + * The name [trace list] could be misunderstood as having to do with
    28     27      tracing lists.
    29     28   
    30     29    * The introspection subcommand to trace could be extended to allow
    31         -   more specific queries along the lines of [[info commands]], [[info
    32         -   procs]], and [[info vars]].  ''(This is outside the scope of this
    33         -   TIP.)''
           30  +   more specific queries along the lines of [info commands], [info
           31  +   procs], and [info vars].  _\(This is outside the scope of this
           32  +   TIP.\)_
    34     33   
    35         -Hence, this TIP calls for the ''list'' subcommand to be renamed to
    36         -''info''.  (Note that this also makes the subcommand for introspecting
    37         -on variable traces more similar to its old form ''vinfo''.)
           34  +Hence, this TIP calls for the _list_ subcommand to be renamed to
           35  +_info_.  \(Note that this also makes the subcommand for introspecting
           36  +on variable traces more similar to its old form _vinfo_.\)
    38     37   
    39         -~ Copyright
           38  +# Copyright
    40     39   
    41     40   This document is placed in the public domain.
           41  +

Name change from tip/103.tip to tip/103.md.

     1         -TIP:            103
     2         -Title:          Argument Expansion Command
     3         -Version:        $Revision: 1.13 $
     4         -Author:         Peter Spjuth <peter.spjuth@space.se>
     5         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     6         -Author:         Andreas Leitgeb <avl@logic.at>
     7         -State:          Rejected
     8         -Type:           Project
     9         -Vote:           Done
    10         -Created:        15-Jun-2002
    11         -Post-History:   
    12         -Tcl-Version:    8.5
            1  +# TIP 103: Argument Expansion Command
            2  +	Author:         Peter Spjuth <peter.spjuth@space.se>
            3  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            4  +	Author:         Andreas Leitgeb <avl@logic.at>
            5  +	State:          Rejected
            6  +	Type:           Project
            7  +	Vote:           Done
            8  +	Created:        15-Jun-2002
            9  +	Post-History:   
           10  +	Tcl-Version:    8.5
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16     15   This TIP proposes to add a command that can perform argument expansion
    17     16   in a safe and efficient manner.
    18     17   
    19         -~ Introduction
           18  +# Introduction
    20     19   
    21     20   Many commands take a variable number of arguments and often you find
    22     21   yourself with those arguments in a list.  This list must then be
    23     22   expanded into individual arguments to the command.  This is currently
    24     23   done with eval:
    25     24   
    26         -|eval destroy [winfo children .]
           25  +	eval destroy [winfo children .]
    27     26   
    28     27   This is a bit obscure and also very error prone when the command
    29     28   becomes more complex.  It is also inefficient and not object safe, why
    30     29   a command specialised in doing this would be better.
    31     30   
    32         -~ Rationale
           31  +# Rationale
    33     32   
    34     33   There have been suggestions of introducing some new syntax to Tcl to
    35     34   handle argument expansion.  That is a big and controversial step, and
    36     35   not anything this TIP wants to meddle in.  A command can improve every
    37     36   point where eval has shortcomings and thus give a good result with
    38     37   less means.  It can also serve as a bridge to a future global syntax.
    39     38   
    40     39   Such a command can be done in several ways and below the choice in
    41     40   this TIP's specification is defended.
    42     41   
    43     42   As examples three statements are used which will be repeated for
    44     43   different alternatives.  This is the eval version:
    45     44   
    46         -|eval destroy [winfo children .]
    47         -|eval button .b $stdargs -text \$mytext -bd $border
    48         -|eval exec \$prog $opts1 [getMoreopts] \$file1 \$file2
           45  +	eval destroy [winfo children .]
           46  +	eval button .b $stdargs -text \$mytext -bd $border
           47  +	eval exec \$prog $opts1 [getMoreopts] \$file1 \$file2
    49     48   
    50     49   The eval version would be even more complex if the lists that are to
    51     50   be expanded are not known to be pure. To be really safe the last
    52     51   would be:
    53     52   
    54         -|eval exec \$prog [lrange $opts1 0 end] [lrange [getMoreopts] 0 end] \$file1 \$file2
           53  +	eval exec \$prog [lrange $opts1 0 end] [lrange [getMoreopts] 0 end] \$file1 \$file2
    55     54   
    56     55   With the proposed command they become:
    57     56   
    58         -|expand { destroy `[winfo children .] }
    59         -|expand { button .b `$stdargs -text $mytext -bd $border }
    60         -|expand { exec $prog `$opts1 `[getMoreopts] $file1 $file2 }
           57  +	expand { destroy `[winfo children .] }
           58  +	expand { button .b `$stdargs -text $mytext -bd $border }
           59  +	expand { exec $prog `$opts1 `[getMoreopts] $file1 $file2 }
    61     60   
    62     61   An alternative to having a local syntax is to point at the arguments
    63     62   that should be expanded, either by index:
    64     63   
    65         -|expand {end} destroy [winfo children .]
    66         -|expand {2} button .b $stdargs -text $mytext -bd $border
    67         -|expand {2 3} exec $prog $opts1 [getMoreopts] $file1 $file2
           64  +	expand {end} destroy [winfo children .]
           65  +	expand {2} button .b $stdargs -text $mytext -bd $border
           66  +	expand {2 3} exec $prog $opts1 [getMoreopts] $file1 $file2
    68     67   
    69     68   Or by some flag mechanism:
    70     69   
    71         -|expand destroy + [winfo children .]
    72         -|expand button .b + $stdargs -text - $mytext -bd $border
    73         -|expand exec - $prog + $opts1 + [getMoreopts] - $file1 - $file2
           70  +	expand destroy + [winfo children .]
           71  +	expand button .b + $stdargs -text - $mytext -bd $border
           72  +	expand exec - $prog + $opts1 + [getMoreopts] - $file1 - $file2
    74     73   
    75     74   Those lack in writability/readability/maintainability in a disturbing
    76     75   manner.
    77     76   
    78     77   For the choice of local syntax one goal is that it should not
    79     78   violate Tcl's rules, which simplifies implementation since Tcl's
    80     79   parser can do the job.
    81     80   
    82         -Any char that fulfils that could be used but the choice fell on ` for
           81  +Any char that fulfils that could be used but the choice fell on \` for
    83     82   forward compatibility reasons.  See below.
    84     83   
    85         -An alternative syntax could be using enclosing `` or some
           84  +An alternative syntax could be using enclosing \`\` or some
    86     85   other enclosing construct like:
    87     86   
    88         -|expand { destroy <[winfo children .]> }
    89         -|expand { button .b <$stdargs> -text $mytext -bd $border }
    90         -|expand { exec $prog <$opts1> <[getMoreopts]> $file1 $file2 }
           87  +	expand { destroy <[winfo children .]> }
           88  +	expand { button .b <$stdargs> -text $mytext -bd $border }
           89  +	expand { exec $prog <$opts1> <[getMoreopts]> $file1 $file2 }
    91     90   
    92     91   Paired characters are good for delimiting things.  Here is the
    93     92   beginning; here is the end.  But this is not about a new way to
    94     93   delimit things.  It is about indicating a boolean choice:  expand
    95     94   or do not expand a word into multiple words.  Whatever character
    96     95   is chosen to be that indicator, it should be a single, leading
    97     96   one.  No pairs.
    98     97   
    99     98   In the specification a restrictive rule was chosen that makes
   100         -it an error to use ` in a way that do not fit.  This is to make
           99  +it an error to use \` in a way that do not fit.  This is to make
   101    100   it easier to change things in the future should ideas come up
   102    101   for new features.  E.g., should this become a global syntax
   103    102   in Tcl 9.0 it can be chosen a bit differently and be backward
   104    103   compatible with the expand command.
   105    104   
   106         -~ Specification
          105  +# Specification
   107    106   
   108    107   A new command "expand" is added.  It takes one argument, which
   109    108   contains a Tcl script consisting of one command.  The script may
   110    109   contain comments but only one command is permitted.
   111    110   
   112    111   The command is processed in the following manner:
   113    112   
   114    113    1. Parse into words according to Tcl's standard rules.
   115    114   
   116         - 2. Any word starting with ` must be followed by a single variable
   117         -    or command substitution.  The word is remembered and the ` is
          115  + 2. Any word starting with \` must be followed by a single variable
          116  +    or command substitution.  The word is remembered and the \` is
   118    117       removed.
   119    118   
   120    119    3. Perform Tcl's normal execution steps on the new line up to the
   121    120       point where the command should have been called.
   122    121   
   123    122    4. Expand the arguments that should be expanded.
   124    123   
   125    124    5. Execute the command.
   126    125   
   127    126   The return value of expand is the return value of the command.
   128    127   
   129         -''Note 1:'' A word should really start with ` to trigger expansion
          128  +_Note 1:_ A word should really start with \` to trigger expansion
   130    129   which means that words like these are not expanded:
   131    130   
   132         -|cmd "`$temp" \`[something]
          131  +	cmd "`$temp" \`[something]
   133    132   
   134         -''Note 2:'' Expansion is only performed with words like:
          133  +_Note 2:_ Expansion is only performed with words like:
   135    134   
   136         -|cmd `$var `[somecmd $arg] `$arr([cmd $arg])
          135  +	cmd `$var `[somecmd $arg] `$arr([cmd $arg])
   137    136   
   138    137   Words like these are a syntax error:
   139    138   
   140         -|cmd `word` `$x,$y `[foo]xy[apa]
          139  +	cmd `word` `$x,$y `[foo]xy[apa]
   141    140   
   142         -~ Forward compatibility
          141  +# Forward compatibility
   143    142   
   144    143   One aspect of choosing a syntax here is to think about the
   145    144   future.  Should there later be a wish for a global syntax for argument
   146    145   expansion it would be nice if it were the same as the one chosen in
   147    146   the expand command.  If an agreement
   148    147   can be made for what may be acceptable in the future, this should
   149    148   affect the specification in this TIP.
   150    149   
   151         -If a single character like ` is chosen for a global expand syntax
          150  +If a single character like \` is chosen for a global expand syntax
   152    151   it means a backwards compatibility break.  So, what chars
   153    152   are likely to be used by people and thus causing problems or confusion
   154    153   when backwards compatibility is broken?
   155    154   
   156    155   Some food for thought about different chars:
   157    156   
   158         -|_     # Word char
   159         -|:     # Gets ugly with namespace qualifiers:  :$::var
   160         -
   161         -|!   if !$var {...}
   162         -|*   string match *$suffix $line
   163         -|^   regexp ^$prefix $line
   164         -|~   cd ~$user
   165         -||   open |$prog
   166         -|.   button .$w ; glob -nocomplain .$str
   167         -|=   wm geometry .e =$geo
   168         -|@   .x conf -bitmap @$bmp -cursor @$cur
   169         -|<   bind . <$left>  ; set html <$tag>
   170         -
   171         -|(   expr ($a + $b) * $c ;# Confuses paren-matching
   172         -|)     # Odd enough as opening, but would confuse any paren-matching
   173         -
   174         -|+   expr $a +$b  ;# Same for any operator
   175         -|-   
   176         -|%
   177         -|&   
   178         -|?
   179         -|/   open /$path   
   180         -
   181         -|'     # Makes more sense as enclosing?
   182         -|`     # Makes more sense as enclosing?
   183         -|>   exec foobar >/some/file
   184         -|,   append recipients ,[join $header($ccL) ,]
   185         -
   186         -|{}  completely forward-compatible, as {} currently cannot be
   187         -|    trailed by anything but whitespace. (This would limit the
   188         -|    originally proposed global syntax change to the argument
   189         -|    of the expand command)
          157  +	_     # Word char
          158  +	:     # Gets ugly with namespace qualifiers:  :$::var
          159  +
          160  +	!   if !$var {...}
          161  +	*   string match *$suffix $line
          162  +	^   regexp ^$prefix $line
          163  +	~   cd ~$user
          164  +	|   open |$prog
          165  +	.   button .$w ; glob -nocomplain .$str
          166  +	=   wm geometry .e =$geo
          167  +	@   .x conf -bitmap @$bmp -cursor @$cur
          168  +	<   bind . <$left>  ; set html <$tag>
          169  +
          170  +	(   expr ($a + $b) * $c ;# Confuses paren-matching
          171  +	)     # Odd enough as opening, but would confuse any paren-matching
          172  +
          173  +	+   expr $a +$b  ;# Same for any operator
          174  +	-   
          175  +	%
          176  +	&   
          177  +	?
          178  +	/   open /$path   
          179  +
          180  +	'     # Makes more sense as enclosing?
          181  +	`     # Makes more sense as enclosing?
          182  +	>   exec foobar >/some/file
          183  +	,   append recipients ,[join $header($ccL) ,]
          184  +
          185  +	{}  completely forward-compatible, as {} currently cannot be
          186  +	    trailed by anything but whitespace. (This would limit the
          187  +	    originally proposed global syntax change to the argument
          188  +	    of the expand command)
   190    189   
   191    190   Example usage of those that seem reasonable:
   192    191   
   193         -|expand { exec $prog '$opts1 '[getMoreopts] $file1 $file2 }
   194         -|expand { exec $prog `$opts1 `[getMoreopts] $file1 $file2 }
   195         -|expand { exec $prog ,$opts1 ,[getMoreopts] $file1 $file2 }
          192  +	expand { exec $prog '$opts1 '[getMoreopts] $file1 $file2 }
          193  +	expand { exec $prog `$opts1 `[getMoreopts] $file1 $file2 }
          194  +	expand { exec $prog ,$opts1 ,[getMoreopts] $file1 $file2 }
   196    195   
   197    196   For comparison, the syntax that has been proposed earlier that
   198    197   would not break backwards compatibility:
   199    198   
   200         -|expand { exec $prog {}$opts1 {}[getMoreopts] $file1 $file2 }
   201         -|expand { exec $prog {expand}$opts1 {expand}[getMoreopts] $file1 $file2 }
          199  +	expand { exec $prog {}$opts1 {}[getMoreopts] $file1 $file2 }
          200  +	expand { exec $prog {expand}$opts1 {expand}[getMoreopts] $file1 $file2 }
   202    201   
   203         -~ Discussion
          202  +# Discussion
   204    203   
   205    204   When first issued the TIP caused some discussion on c.l.t.  Until a
   206    205   summary is made, here is the thread:
   207    206   
   208         -http://groups.google.com/groups?th=9e77d5836b06ab1b
          207  +<http://groups.google.com/groups?th=9e77d5836b06ab1b>
   209    208   
   210    209   Another thread about it:
   211    210   
   212         -http://groups.google.com/groups?th=2ba287be87c2678c
          211  +<http://groups.google.com/groups?th=2ba287be87c2678c>
          212  +
          213  +# Reference Implementation
   213    214   
   214         -~ Reference Implementation
          215  +Patch \#570201
   215    216   
   216         -Patch #570201
          217  +<http://sourceforge.net/tracker/index.php?func=detail&aid=570201&group\_id=10894&atid=310894>
   217    218   
   218         -http://sourceforge.net/tracker/index.php?func=detail&aid=570201&group_id=10894&atid=310894
   219         -
   220         -~ Copyright
          219  +# Copyright
   221    220   
   222    221   This document has been placed in the public domain.
          222  +

Name change from tip/104.tip to tip/104.md.

     1         -TIP:            104
     2         -Title:          Generalization of the Tk Undo Subsystem
     3         -Version:        $Revision: 1.6 $
     4         -Author:         Ludwig Callewaert <ludwig.callewaert@belgacom.net>
     5         -Author:         Larry W. Virden. <lvirden@yahoo.com>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        19-Jun-2002
    10         -Post-History:   
    11         -Discussions-To: news:comp.lang.tcl
    12         -Tcl-Version:    8.4
            1  +# TIP 104: Generalization of the Tk Undo Subsystem
            2  +	Author:         Ludwig Callewaert <ludwig.callewaert@belgacom.net>
            3  +	Author:         Larry W. Virden. <lvirden@yahoo.com>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        19-Jun-2002
            8  +	Post-History:   
            9  +	Discussions-To: news:comp.lang.tcl
           10  +	Tcl-Version:    8.4
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16     15   This TIP proposes a reimplementation of the Tk Text widget undo
    17     16   feature.  The text widget interface is not affected.  No functional
    18     17   changes are made at the Tcl level.  The purpose of the
    19     18   reimplementation is to move the undo feature from a text only
    20     19   implementation to a general implementation also usable by other
    21     20   widgets.  This opens the door to undoing also tag, mark and other
    22     21   operations, and allows for an exposure of the undo stack at the Tcl
    23     22   level.  These new features are however not part of this TIP.
    24     23   
    25         -~ Rationale
           24  +# Rationale
    26     25   
    27     26   As stated in the abstract, the current implementation of the text
    28     27   widget undo feature only allows for text changes to be undone.  The
    29     28   usefulness of the undo feature would increase tremendously if
    30         -other operations could be undone (tags, marks, embedded windows, ...).
    31         -This was already part of the [26] discussions.  This TIP deals with
           29  +other operations could be undone \(tags, marks, embedded windows, ...\).
           30  +This was already part of the [[26]](26.md) discussions.  This TIP deals with
    32     31   the generalization of the undo stack to cope with these requirements.
    33     32   
    34         -~ Specification
           33  +# Specification
    35     34   
    36     35   As the undo functionality is no longer text widget specific, it has
    37         -been put in a separate file ''generic/tkUndo.c'' along with its header
    38         -file ''generic/tkUndo.h''.  The ''TkUndoRedoStack'' is a structure
           36  +been put in a separate file _generic/tkUndo.c_ along with its header
           37  +file _generic/tkUndo.h_.  The _TkUndoRedoStack_ is a structure
    39     38   containing the undo and redo stacks.  These undo and redo stacks are
    40         -linked lists of ''TkUndoAtom'' structures.  There are two types of
    41         -these atoms: the separator (similar to the previous implementation)
    42         -and the command.  When the type is command, both an ''apply'' and a
    43         -''revert'' action need to be provided.  The apply action is for the
           39  +linked lists of _TkUndoAtom_ structures.  There are two types of
           40  +these atoms: the separator \(similar to the previous implementation\)
           41  +and the command.  When the type is command, both an _apply_ and a
           42  +_revert_ action need to be provided.  The apply action is for the
    44     43   redo.  The revert action is for the undo.  Both are pointers to a
    45         -''Tcl_Obj'', so they can (and should) contain a Tcl script.
           44  +_Tcl\_Obj_, so they can \(and should\) contain a Tcl script.
    46     45   
    47         -The following functions all operating on a ''TkUndoRedoStack''
           46  +The following functions all operating on a _TkUndoRedoStack_
    48     47   stack are provided to implement the undo/redo functionality.
    49     48   
    50         -   1. ''TkUndoInitStack(interp)'': returns a pointer to an initialized
    51         -      TkUndoRedoStack and stores ''interp'' in that stack for script
           49  +   1. _TkUndoInitStack\(interp\)_: returns a pointer to an initialized
           50  +      TkUndoRedoStack and stores _interp_ in that stack for script
    52     51         evaluation.
    53     52   
    54         -   2. ''TkUndoClearStacks(stack)'': clears both the undo and the redo
           53  +   2. _TkUndoClearStacks\(stack\)_: clears both the undo and the redo
    55     54         stacks.
    56     55   
    57         -   3. ''TkUndoFreeStack(stack)'': clears both undo and redo stacks and
    58         -      frees any memory allocated to ''stack''.
           56  +   3. _TkUndoFreeStack\(stack\)_: clears both undo and redo stacks and
           57  +      frees any memory allocated to _stack_.
    59     58   
    60         -   4. ''TkUndoInsertUndoSeparator(stack)'': inserts a
           59  +   4. _TkUndoInsertUndoSeparator\(stack\)_: inserts a
    61     60         separator on the undo stack.  Note that there is currently no
    62         -      need for a ''TkUndoInsertRedoSeparator'' function, as the redo
    63         -      stack is managed by the internals of ''TkUndo''.
           61  +      need for a _TkUndoInsertRedoSeparator_ function, as the redo
           62  +      stack is managed by the internals of _TkUndo_.
    64     63   
    65         -   5. ''TkUndoPushAction(stack, actionScript, revertScript)'': pushes 
    66         -      an action of the undo stack (an atom of type command).
    67         -      ''actionScript'' and ''revertScript'' are ''Tcl_DString''
           64  +   5. _TkUndoPushAction\(stack, actionScript, revertScript\)_: pushes 
           65  +      an action of the undo stack \(an atom of type command\).
           66  +      _actionScript_ and _revertScript_ are _Tcl\_DString_
    68     67         pointers that provide the script to redo and undo the action
    69     68         respectively.  The redo stack is cleared.
    70     69   
    71         -   6. ''TkUndoRevert(stack)'': undo a compound action.
           70  +   6. _TkUndoRevert\(stack\)_: undo a compound action.
    72     71         Compound means all revert script of action between two
    73     72         separators on the undo stack are evaluated in the stack's 
    74     73         interpreter and the actions are moved to the redo stack.
    75         -      Returns TCL_ERROR when unsuccessful (stack empty for instance),
    76         -      and TCL_OK otherwise.
           74  +      Returns TCL\_ERROR when unsuccessful \(stack empty for instance\),
           75  +      and TCL\_OK otherwise.
    77     76   
    78         -   7. ''TkUndoApply(stack)'': redo a compound action.  The
           77  +   7. _TkUndoApply\(stack\)_: redo a compound action.  The
    79     78         apply script of all actions between two separators on the redo
    80     79         stack is evaluated in the stack's interpreter.  The actions are
    81         -      moved to the undo stack.  Returns TCL_ERROR when unsuccessful
    82         -      (stack empty for instance), and TCL_OK otherwise.
           80  +      moved to the undo stack.  Returns TCL\_ERROR when unsuccessful
           81  +      \(stack empty for instance\), and TCL\_OK otherwise.
    83     82   
    84         -   8. ''TkUndoSetDepth(stack, maxDepth)'': sets the maximum number
    85         -      of compound actions stored on the stack to ''maxDepth''.  By
    86         -      default, stacks are unlimited, and a value of ''maxDepth'' <= 0
           83  +   8. _TkUndoSetDepth\(stack, maxDepth\)_: sets the maximum number
           84  +      of compound actions stored on the stack to _maxDepth_.  By
           85  +      default, stacks are unlimited, and a value of _maxDepth_ <= 0
    87     86         resets the stack to be unlimited.
    88     87   
    89         -   9. The option ''-maxundo'' is added to the text widget to access the
           88  +   9. The option _-maxundo_ is added to the text widget to access the
    90     89         stack limit feature of the text widget's undo stack from the
    91     90         script level.
    92     91   
    93     92   These functions are sufficient to implement the current undo
    94     93   functionality of the text widget, and they have been used for this
    95     94   purpose.
    96     95   
    97         -~ Reference Implementation
           96  +# Reference Implementation
    98     97   
    99         -See patch #554763 on SourceForge: ''
   100         -https://sourceforge.net/tracker/?func=detail&atid=312997&aid=554763&group_id=12997
   101         -''
           98  +See patch \#554763 on SourceForge: _
           99  +<https://sourceforge.net/tracker/?func=detail&atid=312997&aid=554763&group\_id=12997>
          100  +_
   102    101   
   103         -~ Copyright
          102  +# Copyright
   104    103   
   105    104   This document has been placed in the public domain.
          105  +

Name change from tip/105.tip to tip/105.md.

     1         -TIP:		105
     2         -Title:		Add Prefix Matching for Switch
     3         -State:		Withdrawn
     4         -Type:		Project
     5         -Tcl-Version:	8.5
     6         -Vote:		Pending
     7         -Post-History:	
     8         -Version:	$Revision: 1.4 $
     9         -Author:		Donal K. Fellows <fellowsd@cs.man.ac.uk>
    10         -Created:	03-Jul-2002
    11         -Obsoleted-By:	195
            1  +# TIP 105: Add Prefix Matching for Switch
            2  +	State:		Withdrawn
            3  +	Type:		Project
            4  +	Tcl-Version:	8.5
            5  +	Vote:		Pending
            6  +	Post-History:	
            7  +	Author:		Donal K. Fellows <fellowsd@cs.man.ac.uk>
            8  +	Created:	03-Jul-2002
            9  +	Obsoleted-By:	195
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15         -This TIP adds a new option to the [[switch]] command to support
           14  +This TIP adds a new option to the [switch] command to support
    16     15   matching of strings to unique prefixes of patterns, similar to Tcl's
    17     16   existing subcommand-name matching or Tk's option-name matching.
    18     17   
    19         -~ Rationale
           18  +# Rationale
    20     19   
    21         -When code (particularly in script libraries) wants to support shortest
    22         -unique prefix matching in the manner of the Tcl core (as provided by
    23         -''Tcl_GetIndexFromObj'') currently either the prefixes have to be
    24         -precomputed (by hand or by script) or the matching has to be done
           20  +When code \(particularly in script libraries\) wants to support shortest
           21  +unique prefix matching in the manner of the Tcl core \(as provided by
           22  +_Tcl\_GetIndexFromObj_\) currently either the prefixes have to be
           23  +precomputed \(by hand or by script\) or the matching has to be done
    25     24   backwards.  In the first case, this is either error-prone or requires
    26     25   an extra piece of code that has to be developed by the programmer.  In
    27     26   the second case, the code has to be converted into a pattern which is
    28     27   matched against the list of supported options in some way, which is
    29     28   either inefficient or has hazards if the string being matched contains
    30     29   characters that are meaningful to the matching engine being used.
    31     30   Instead, it would be far nicer if we could make the core support this
    32     31   directly, so that script authors could just say what they mean.
    33     32   
    34         -~ Proposed Change
           33  +# Proposed Change
    35     34   
    36         -To support this, I propose modifying the ''switch'' command to take an
    37         -extra option ''-prefix'' (which should be mutually exclusive with
    38         -''-exact'', ''-glob'' and ''-regexp'' of course) to enable prefix
           35  +To support this, I propose modifying the _switch_ command to take an
           36  +extra option _-prefix_ \(which should be mutually exclusive with
           37  +_-exact_, _-glob_ and _-regexp_ of course\) to enable prefix
    39     38   matching.  When prefix matching is enabled, the arm chosen for
    40     39   execution will be the one such that the switch value is identical to
    41         -or an unambiguous prefix of its pattern (i.e. it will not be a prefix
           40  +or an unambiguous prefix of its pattern \(i.e. it will not be a prefix
    42     41   of any other pattern listed, unless the pattern of the arm chosen is
    43         -exactly equal to the switch value.)  If there is no arm whose pattern
           42  +exactly equal to the switch value.\)  If there is no arm whose pattern
    44     43   is an unambiguous prefix of the switch value, the default arm will be
    45     44   selected for execution, or if there is no default arm, the switch
    46         -command will terminate without an error and with an empty result (this
    47         -is in contrast to the behaviour of ''Tcl_GetIndexFromObj''.)
           45  +command will terminate without an error and with an empty result \(this
           46  +is in contrast to the behaviour of _Tcl\_GetIndexFromObj_.\)
    48     47   
    49         -~ Examples
           48  +# Examples
    50     49   
    51     50   The command:
    52     51   
    53         -|switch -prefix f {
    54         -|   foo {
    55         -|      puts "matched foo"
    56         -|   }
    57         -|   bar {
    58         -|      puts "matched bar"
    59         -|   }
    60         -|}
           52  +	switch -prefix f {
           53  +	   foo {
           54  +	      puts "matched foo"
           55  +	   }
           56  +	   bar {
           57  +	      puts "matched bar"
           58  +	   }
           59  +	}
    61     60   
    62     61   prints "matched foo".  The command:
    63     62   
    64         -|switch -prefix b {
    65         -|   bar {
    66         -|      puts "matched bar"
    67         -|   }
    68         -|   boo {
    69         -|      puts "matched boo"
    70         -|   }
    71         -|   default {
    72         -|      puts "the default action"
    73         -|   }
    74         -|}
           63  +	switch -prefix b {
           64  +	   bar {
           65  +	      puts "matched bar"
           66  +	   }
           67  +	   boo {
           68  +	      puts "matched boo"
           69  +	   }
           70  +	   default {
           71  +	      puts "the default action"
           72  +	   }
           73  +	}
    75     74   
    76         -prints "the default action" ("b" is a prefix of two patterns.)  The
           75  +prints "the default action" \("b" is a prefix of two patterns.\)  The
    77     76   command:
    78     77   
    79         -|switch -prefix tcl {
    80         -|   tcl {
    81         -|      puts "The Tool Command Language"
    82         -|   }
    83         -|   tk {
    84         -|      puts "The Tk Toolkit"
    85         -|   }
    86         -|   tcl/tk {
    87         -|      puts "A cool combination"
    88         -|   }
    89         -|}
           78  +	switch -prefix tcl {
           79  +	   tcl {
           80  +	      puts "The Tool Command Language"
           81  +	   }
           82  +	   tk {
           83  +	      puts "The Tk Toolkit"
           84  +	   }
           85  +	   tcl/tk {
           86  +	      puts "A cool combination"
           87  +	   }
           88  +	}
           89  +
           90  +prints "The Tool Command Language" \(although "tcl" is a prefix of two
           91  +patterns, it matches one of them exactly.\)
    90     92   
    91         -prints "The Tool Command Language" (although "tcl" is a prefix of two
    92         -patterns, it matches one of them exactly.)
    93         -
    94         -~ Copyright
           93  +# Copyright
    95     94   
    96     95   This document has been placed in the public domain.
           96  +

Name change from tip/106.tip to tip/106.md.

     1         -TIP:            106
     2         -Title:          Add Encoding Abilities to the [dde] Command
     3         -Version:        $Revision: 1.14 $
     4         -Author:         Harald Oehlmann <harald.oehlmann@elmicron.de>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        13-Aug-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.6
            1  +# TIP 106: Add Encoding Abilities to the [dde] Command
            2  +	Author:         Harald Oehlmann <harald.oehlmann@elmicron.de>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        13-Aug-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.6
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   When using Windows DDE communication with non-Tcl programs, the encoding of
    15     14   the exchanged strings is mostly needed to be the system encoding.  Selection
    16         -of this behaviour should be possible with in the '''dde''' command should be
           15  +of this behaviour should be possible with in the **dde** command should be
    17     16   done by a parameter.
    18     17   
    19         -~ Specification
           18  +# Specification
    20     19   
    21         -Extend the '''dde''' commands taking a data argument by the switch
    22         -'''-binary''':
           20  +Extend the **dde** commands taking a data argument by the switch
           21  +**-binary**:
    23     22   
    24         - > '''dde execute''' ?'''-async'''? ?'''-binary'''? ''service topic data''
           23  + > **dde execute** ?**-async**? ?**-binary**? _service topic data_
    25     24   
    26         - > '''dde poke''' ?'''-binary'''? ''service topic item data''
           25  + > **dde poke** ?**-binary**? _service topic item data_
    27     26   
    28         -The argument ''data'' is taken as a binary string if the '''-binary''' switch
           27  +The argument _data_ is taken as a binary string if the **-binary** switch
    29     28   is given.  Otherwise, it is interpreted as utf-8.
    30     29   
    31     30   Examples:
    32     31   
    33         -| dde execute -binary CS CS [encoding convertto [encoding system] Äpfel]\0
    34         -| dde poke -binary CS CS I [encoding convertto [encoding system] Äpfel]\0
           32  +	 dde execute -binary CS CS [encoding convertto [encoding system] Äpfel]\0
           33  +	 dde poke -binary CS CS I [encoding convertto [encoding system] Äpfel]\0
    35     34   
    36         -~ Rationale
           35  +# Rationale
    37     36   
    38     37   The communication with DDE with external programs uses the format clipboard
    39         -''CF_TEXT'' and the sent text should be coded in the system encoding
    40         -(''cp1252'' in my locale).
           38  +_CF\_TEXT_ and the sent text should be coded in the system encoding
           39  +\(_cp1252_ in my locale\).
    41     40   
    42     41   Most people who use DDE to communicate with, for example, Excel use the fact
    43         -that what Excel expects (''cp1252'') and what Tcl actually sends (''utf-8'')
           42  +that what Excel expects \(_cp1252_\) and what Tcl actually sends \(_utf-8_\)
    44     43   is identical for 7-bit values and they don't use 8-bit values.  Unfortunately,
    45     44   characters used in languages like German, French, etc., are located over this
    46     45   limit and thus are not transferable.
    47     46   
    48     47   Peter Hardie addressed this point on 2000-10-26 in the Tcl Feature Request at
    49         -SourceForge (#219185: "dde only handles UTF-8 data (-binary patch available)"
    50         -[http://sf.net/tracker/?func=detail&aid=219185&group_id=10894&atid=360894]).
    51         -His proposal was to add a '''-binary''' option.
           48  +SourceForge \(\#219185: "dde only handles UTF-8 data \(-binary patch available\)"
           49  +<http://sf.net/tracker/?func=detail&aid=219185&group_id=10894&atid=360894> \).
           50  +His proposal was to add a **-binary** option.
    52     51   
    53     52   This is a reasonable solution, because any encoding including the system
    54     53   encoding may be used as shown in the upper example.
    55     54   
    56         -~ Reference Implementation
           55  +# Reference Implementation
           56  +
           57  +See the _tip-106-impl_ branch in Tcl's fossil repository
           58  +<https://core.tcl.tk/tcl/timeline?r=tip-106-impl> .
    57     59   
    58         -See the ''tip-106-impl'' branch in Tcl's fossil repository
    59         -[https://core.tcl.tk/tcl/timeline?r=tip-106-impl].
           60  +# Rejected Alternatives
    60     61   
    61         -~ Rejected Alternatives
    62         -
    63         -I proposed to use a switch ?'''-encoding''' ''encoding''? which would
    64         -avoid the preparation of an encoded string by '''encoding convertto'''.
           62  +I proposed to use a switch ?**-encoding** _encoding_? which would
           63  +avoid the preparation of an encoded string by **encoding convertto**.
    65     64   DDE is so little used at those days so a minimal support is sufficient.
    66     65   
    67         -The '''dde request''' subcommand already has a parameter ''-binary''.
           66  +The **dde request** subcommand already has a parameter _-binary_.
    68     67   It is more logical to extend this to the other commands.
    69     68   
    70         -~ Copyright
           69  +# Copyright
    71     70   
    72     71   This document has been placed in the public domain
           72  +

Name change from tip/107.tip to tip/107.md.

     1         -TIP:		107
     2         -Title:		Fix the 2-second "raise delay" in Tk
     3         -Version:	$Revision: 1.4 $
     4         -Author:		Joe English <jenglish@flightlab.com>
     5         -State:		Final
     6         -Type:		Project
     7         -Created:	28-Aug-2002
     8         -Tcl-Version:	8.4
     9         -Vote:		Done
    10         -Post-History:	
            1  +# TIP 107: Fix the 2-second "raise delay" in Tk
            2  +	Author:		Joe English <jenglish@flightlab.com>
            3  +	State:		Final
            4  +	Type:		Project
            5  +	Created:	28-Aug-2002
            6  +	Tcl-Version:	8.4
            7  +	Vote:		Done
            8  +	Post-History:	
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP explains the genesis of the long delays often associated with
    15         -the [[raise]] and [[lower]] commands under Unix/X with some window
           14  +the [raise] and [lower] commands under Unix/X with some window
    16     15   managers, as well as describing the solution.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20         -Currently, Tk's [[raise]] and [[lower]] commands do not return to the
           19  +Currently, Tk's [raise] and [lower] commands do not return to the
    21     20   caller until the operation has completed.  Under Unix, the window
    22     21   manager is responsible for changing the stacking order of toplevel
    23         -windows, so [[raise]] and [[lower]] must wait for a notification from
           22  +windows, so [raise] and [lower] must wait for a notification from
    24     23   the WM before returning.  Not all window managers are ICCCM-compliant
    25     24   in this regard, however, so the operation may time out instead.
    26     25   
    27     26   This two-second "raise delay" has been a longstanding, persistent
    28     27   problem in Tk.  It has supposedly been fixed several times, but the
    29     28   problem keeps reoccurring under new window managers and new
    30     29   environments.  At present, the problem is most noticeable under KDE 2
    31     30   and KDE 3.
    32     31   
    33         -~ Proposal
           32  +# Proposal
    34     33   
    35         -Change Tk so that [[raise]] and [[lower]] return immediately, without
           34  +Change Tk so that [raise] and [lower] return immediately, without
    36     35   waiting for a notification that may not be forthcoming.
    37     36   
    38     37   This should not be be a controversial change.  This behaviour is not
    39     38   documented anywhere, and is not observable by Tk programs except via
    40         -[[wm stackorder]] (see [74]).
           39  +[wm stackorder] \(see [[74]](74.md)\).
    41     40   
    42         -Moreover, the guarantee is largely meaningless.  After [[raise]]
    43         -returns, the window ''contents'' may still not be visible (there may
    44         -be pending <Expose> events, for example), and the actual position in
           41  +Moreover, the guarantee is largely meaningless.  After [raise]
           42  +returns, the window _contents_ may still not be visible \(there may
           43  +be pending <Expose> events, for example\), and the actual position in
    45     44   the stacking order is still subject to window manager intervention.
    46     45   
    47         -~ Compatibility Issues
           46  +# Compatibility Issues
    48     47   
    49     48   The only Tk programs that would break with this change are ones which
    50         -expect the return value of [[wm stackorder]] to reflect the results of
    51         -any immediately-preceding [[raise]] and [[lower]] commands.  (The Tk
    52         -test suite is one such program, and would need to be modified).
           49  +expect the return value of [wm stackorder] to reflect the results of
           50  +any immediately-preceding [raise] and [lower] commands.  \(The Tk
           51  +test suite is one such program, and would need to be modified\).
    53     52   
    54     53   Unfortunately there is no reliable way to fix such programs -
    55         -[[update]] will not work, and the ICCCM does not, to the author's
           54  +[update] will not work, and the ICCCM does not, to the author's
    56     55   knowledge, provide a way to synchronize with the window manager to
    57     56   make sure it has processed all outstanding client requests.  Even if
    58     57   it did, this wouldn't help - the raise delay problem only occurs under
    59     58   non-compliant window managers to begin with!
    60     59   
    61         -Since the stacking order is not observable except through [[wm
    62         -stackorder]] - that was the whole point of [74] - no other programs
    63         -will be affected.  (Note that [[wm stackorder]] will still work: the
           60  +Since the stacking order is not observable except through [wm
           61  +stackorder] - that was the whole point of [[74]](74.md) - no other programs
           62  +will be affected.  \(Note that [wm stackorder] will still work: the
    64     63   only difference is that it may return soon-to-be out-of-date
    65     64   information.  Since this is the case already - the user may restack or
    66         -iconify windows at any time - this change should be low-impact.)
           65  +iconify windows at any time - this change should be low-impact.\)
    67     66   
    68         -~ Reference Implementation
           67  +# Reference Implementation
    69     68   
    70         -See Sourceforge Tk Patch #601518.
    71         -http://sourceforge.net/tracker/index.php?func=detail&aid=601518&group_id=12997&atid=312997
           69  +See Sourceforge Tk Patch \#601518.
           70  +<http://sourceforge.net/tracker/index.php?func=detail&aid=601518&group\_id=12997&atid=312997>
    72     71   
    73         -~ Author's Note
           72  +# Author's Note
    74     73   
    75     74   Could we fast-track this?  It's a longstanding problem with a simple
    76     75   fix and ought to make it in before 8.4 goes final.
    77     76   
    78         -~ Detailed Analysis
           77  +# Detailed Analysis
    79     78   
    80     79   First, some terminology:
    81     80   
    82         -    *	''toplevel'': a Tk [[toplevel]] window.
           81  +    *	_toplevel_: a Tk [toplevel] window.
    83     82   
    84         -    *	''wrapper'': an auxiliary window created by Tk to hold the
    85         -	toplevel and its (optional) menubar.  Initially created as a
           83  +    *	_wrapper_: an auxiliary window created by Tk to hold the
           84  +	toplevel and its \(optional\) menubar.  Initially created as a
    86     85   	child of the root window.
    87     86   
    88         -    *	''client window'': From the window manager's perspective, any
           87  +    *	_client window_: From the window manager's perspective, any
    89     88   	window created as a child of the root window by an X client.
    90     89   	Tk wrapper windows are client windows.  Most window managers
    91     90   	reparent client windows under a new frame window which holds
    92     91   	window manager decorations.
    93     92   
    94         -    *	''reparent'': Used as a noun, the immediate parent of a
           93  +    *	_reparent_: Used as a noun, the immediate parent of a
    95     94   	wrapper which has been reparented by a window manager.
    96     95   
    97         -    *	''frame'': The immediate child of the root window (or virtual
    98         -	root window) created by the window manager to hold a client
           96  +    *	_frame_: The immediate child of the root window \(or virtual
           97  +	root window\) created by the window manager to hold a client
    99     98   	window and its decorations.  May or may not be the same as the
   100     99   	reparent window.
   101    100   
   102    101   Next, some methodology:
   103    102   
   104    103   The correct way to change the stacking order of a client window is to
   105         -make a ''ConfigureRequest'' on the client window with ''stack_mode''
          104  +make a _ConfigureRequest_ on the client window with _stack\_mode_
   106    105   set appropriately.  If the client has not been reparented, then the X
   107    106   server performs the operation directly, and will send a
   108         -''ConfigureNotify'' back to the client if, and only if, the actual
   109         -stacking order has changed.  (Raising a window which is already at the
   110         -top of the stacking order will not result in a ''ConfigureNotify'',
   111         -for example).
          107  +_ConfigureNotify_ back to the client if, and only if, the actual
          108  +stacking order has changed.  \(Raising a window which is already at the
          109  +top of the stacking order will not result in a _ConfigureNotify_,
          110  +for example\).
   112    111   
   113         -If the client window ''has'' been reparented (which is usually the
   114         -case), then the window manager intercepts the request and, at its
          112  +If the client window _has_ been reparented \(which is usually the
          113  +case\), then the window manager intercepts the request and, at its
   115    114   discretion, restacks the frame window instead.  It then sends a
   116         -synthetic ''ConfigureNotify'' back to the client, regardless of
          115  +synthetic _ConfigureNotify_ back to the client, regardless of
   117    116   whether or not it honored the request.
   118    117   
   119    118   If the stacking order is to be changed relative to some other window -
   120         -that is, if the ''sibling'' field is also set - and the client has
   121         -been reparented, then the ''ConfigureRequest'' will fail with a
   122         -''BadMatch'' error before it gets to the WM.  Clients must be prepared
          119  +that is, if the _sibling_ field is also set - and the client has
          120  +been reparented, then the _ConfigureRequest_ will fail with a
          121  +_BadMatch_ error before it gets to the WM.  Clients must be prepared
   123    122   to handle this case by catching the error and re-sending a synthetic
   124         -''ConfigureRequest'' to the root window, which the WM receives and
          123  +_ConfigureRequest_ to the root window, which the WM receives and
   125    124   handles as above.
   126    125   
   127    126   See ICCCM section 4.1.5 "Configuring the Window" for the full
   128         -specification.  The Xlib function ''XReconfigureWMWindow()'' takes
          127  +specification.  The Xlib function _XReconfigureWMWindow\(\)_ takes
   129    128   care of all these details.
   130    129   
   131    130   Now, some archaeology:
   132    131   
   133         -Tk 4.0 did not do this: instead, it called ''XConfigureWindow()'' on
   134         -the ''reparent'' window, then waited for a ''ConfigureNotify'' on that
          132  +Tk 4.0 did not do this: instead, it called _XConfigureWindow\(\)_ on
          133  +the _reparent_ window, then waited for a _ConfigureNotify_ on that
   135    134   window.
   136    135   
   137    136   This was wrong on at least two counts.  First, the reparent window
   138    137   might not be the same as the frame window, in which case this would
   139         -have no effect at all.  (In 4DWm and Sawfish, for example, the
   140         -reparent window is a child of an outer frame window).  Second, it's
   141         -not ICCCM-compliant (Tk doesn't own the reparent window and shouldn't
   142         -be mucking with it).
          138  +have no effect at all.  \(In 4DWm and Sawfish, for example, the
          139  +reparent window is a child of an outer frame window\).  Second, it's
          140  +not ICCCM-compliant \(Tk doesn't own the reparent window and shouldn't
          141  +be mucking with it\).
   143    142   
   144    143   Tk 4.0 also included several heuristics that attempted to determine
   145    144   when the operation was unnecessary, to avoid waiting for a
   146         -''ConfigureNotify'' on the reparent that was not forthcoming.
          145  +_ConfigureNotify_ on the reparent that was not forthcoming.
   147    146   
   148         -In Tk 4.1, the (incorrect) call to ''XConfigureWindow()'' on the
   149         -reparent was changed to a (correct) call to ''XReconfigureWMWindow()''
          147  +In Tk 4.1, the \(incorrect\) call to _XConfigureWindow\(\)_ on the
          148  +reparent was changed to a \(correct\) call to _XReconfigureWMWindow\(\)_
   150    149   on the wrapper, but the old heuristic code was left mostly intact.
   151    150   
   152    151   Browsing the CVS logs and the older Tk Changelog, we see that this
   153    152   code has been updated several times to account for new conditions, but
   154    153   ultimately without success: the problem persists.
   155    154   
   156    155   These heuristics are not needed at all under WMs which send a
   157         -synthetic ''ConfigureNotify'' in response to client window stacking
          156  +synthetic _ConfigureNotify_ in response to client window stacking
   158    157   order changes.  On some non-compliant WMs, however, they may help
   159    158   lessen the problem - more by accident than by design - if the reparent
   160    159   is the same as the frame window then the Tk 4.0 heuristics sometimes
   161    160   still work.  But even then the heuristics are not reliable.  For
   162         -instance under KDE 2.2 and KDE 3, calling [[raise]] twice in
          161  +instance under KDE 2.2 and KDE 3, calling [raise] twice in
   163    162   succession always results in a 2-second delay.
   164    163   
   165    164   It is the author's opinion that the only way forward is to let
   166         -[[raise]] and [[lower]] run asynchronously, and fix the two-second
          165  +[raise] and [lower] run asynchronously, and fix the two-second
   167    166   raise delay once and for all.
   168    167   
   169         -~ Copyright
          168  +# Copyright
   170    169   
   171    170   This document is hereby placed in the public domain.
          171  +

Name change from tip/108.tip to tip/108.md.

     1         -TIP:            108
     2         -Title:          Summary of Changes to Generic Tcl/Tk Code to Enable Mac OS X Port
     3         -Version:        $Revision: 1.2 $
     4         -Author:         Jim Ingham <jingham@apple.com>
     5         -State:          Final
     6         -Type:           Informative
     7         -Vote:           No voting
     8         -Created:        29-Aug-2002
     9         -Post-History:   
            1  +# TIP 108: Summary of Changes to Generic Tcl/Tk Code to Enable Mac OS X Port
            2  +	Author:         Jim Ingham <jingham@apple.com>
            3  +	State:          Final
            4  +	Type:           Informative
            5  +	Vote:           No voting
            6  +	Created:        29-Aug-2002
            7  +	Post-History:   
            8  +-----
    10      9   
    11         -~ Abstract
           10  +# Abstract
    12     11   
    13     12   The submission of the changes to generic Tcl/Tk necessary for the Mac
    14     13   OS X port was discussed on the Tcl Core mailing list.  In light of the
    15     14   very minor changes to shared code involved, and to facilitate
    16     15   including the port in the 8.4 release, it was decided that we would
    17     16   not hold a formal vote.  This informational TIP is offered to
    18     17   summarize the work done, however, and to maintain a more complete
    19     18   record.
    20     19   
    21         -~ What Changes are Required for the Mac OS X Port?
           20  +# What Changes are Required for the Mac OS X Port?
    22     21   
    23     22   These fall into two parts: macosx only changes, and changes that
    24     23   effect generic code.
    25     24   
    26     25   The Mac OS X-only changes again fall into two parts.  On the one hand,
    27     26   we introduced new macosx directories to the Tcl and Tk trees, at the
    28     27   same level as the win, unix and mac directories.  At present, the
    29         -''tcl/macosx'' directory only contains one ''.c'' file and a project
    30         -file.  The ''tk/macosx'' directory is much more substantial.  This set
           28  +_tcl/macosx_ directory only contains one _.c_ file and a project
           29  +file.  The _tk/macosx_ directory is much more substantial.  This set
    31     30   of changes manifestly only effects this port, and since something is
    32     31   better than nothing, should be uncontroversial.
    33     32   
    34     33   The other Mac OS X-only part is the addition of Mac OS X specific
    35         -elements to the ''.decls'' files.  This should also be
           34  +elements to the _.decls_ files.  This should also be
    36     35   uncontroversial, though I had to add some slightly non-trivial code to
    37         -the ''genStubs.tcl'' file to handle the fact that Tk loosely uses
           36  +the _genStubs.tcl_ file to handle the fact that Tk loosely uses
    38     37   "unix" to mean "X11", which for Mac OS X is not the case.
    39     38   
    40     39   The Tcl side of Mac OS X is clearly unix, but the same Tcl can in fact
    41         -be used with X11 (there is a native X Server in quite common use on
    42         -Mac OS X) and with the Aqua based Tk port.
           40  +be used with X11 \(there is a native X Server in quite common use on
           41  +Mac OS X\) and with the Aqua based Tk port.
    43     42   
    44     43   In the end, however, the stubs generated for the generic, mac, win &
    45     44   X11 parts of Tcl/Tk are the same, and there is just some extra logic
    46     45   for the aqua part, so the result effects only Mac OS X code.
    47     46   
    48     47   The generic code changes are quite small - a testament to the design
    49     48   of the Tcl/Tk porting layers.
    50     49   
    51         - 1. We changed the ''configure.in'', ''Makefile.in'' and ''tcl.m4'' to
           50  + 1. We changed the _configure.in_, _Makefile.in_ and _tcl.m4_ to
    52     51       handle building Tcl in a the Framework form that is common on Mac
    53     52       OS X.
    54     53   
    55         - 2. I added a bit of code (conditionalized to Mac OS X) to
    56         -    ''tclUnixInit.c'' (in the ''TclpSetVariables'' function) to
           54  + 2. I added a bit of code \(conditionalized to Mac OS X\) to
           55  +    _tclUnixInit.c_ \(in the _TclpSetVariables_ function\) to
    57     56       support looking for script files embedded in the Mac OS X
    58     57       Framework bundle.  This fits the Mac OS X model better than
    59         -    putting files in ''/usr/local'' or such-like.
           58  +    putting files in _/usr/local_ or such-like.
    60     59   
    61         - 3. I added a few more elements to the ''notifierProcPtr''.  For the
           60  + 3. I added a few more elements to the _notifierProcPtr_.  For the
    62     61       aqua Tk, we need to swap the Unix notifier with our own, and so we
    63     62       needed more control over the notifier than was allowed.  This
    64     63       change has no effect if you don't use it, however.
    65     64   
    66         - 4. I added a function, ''TkGetFirstTextLayout'', which gets the run
           65  + 4. I added a function, _TkGetFirstTextLayout_, which gets the run
    67     66       of text up the the first wrap.  I have to get this because the Mac
    68     67       OS X button control doesn't like a newline in the button text.  It
    69     68       is a private function, however, so it doesn't cause any
    70     69       incompatibilities.
    71     70   
    72     71    5. We had to change various places in the Tk script code and the
    73         -    demos where the implicit assumption was made that [[string equal
    74         -    $tcl_platform(platform) "unix"]] meant you were using X11.  To
    75         -    this end, we will add a ''windowingsystem'' subcommand to the
    76         -    ''tk'' command, and then using it to replace the cases where
    77         -    ''tcl_platform'' was being erroneously checked.  This command will
           72  +    demos where the implicit assumption was made that [string equal
           73  +    $tcl\_platform\(platform\) "unix"] meant you were using X11.  To
           74  +    this end, we will add a _windowingsystem_ subcommand to the
           75  +    _tk_ command, and then using it to replace the cases where
           76  +    _tcl\_platform_ was being erroneously checked.  This command will
    78     77       return "x11" for an X11 server, "aqua" for the native Mac OS X
    79     78       window manager, "win32" for Windows, and "classic" for Classic
    80     79       MacOS.
    81     80   
    82         -~ Reference Implementation
           81  +# Reference Implementation
    83     82   
    84         -The reference implementation is on the ''macosx-8-4-branch'' in the
           83  +The reference implementation is on the _macosx-8-4-branch_ in the
    85     84   SourceForge CVS repository.
    86     85   
    87         -~ Copyright
           86  +# Copyright
    88     87   
    89     88   This document has been placed in the public domain.
           89  +

Name change from tip/109.tip to tip/109.md.

     1         -TIP:		109
     2         -Title:		New Look for Checkbutton and Radiobutton on Unix
     3         -State:		Final
     4         -Type:		Project
     5         -Tcl-Version:	8.5
     6         -Vote:		Done
     7         -Post-History:	
     8         -Version:	$Revision: 1.4 $
     9         -Author:		Brian Griffin <bgriffin@model.com>
    10         -Created:	01-Oct-2002
            1  +# TIP 109: New Look for Checkbutton and Radiobutton on Unix
            2  +	State:		Final
            3  +	Type:		Project
            4  +	Tcl-Version:	8.5
            5  +	Vote:		Done
            6  +	Post-History:	
            7  +	Author:		Brian Griffin <bgriffin@model.com>
            8  +	Created:	01-Oct-2002
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP proposes changing the look of the Tk checkbutton and
    15     14   radiobutton widgets on Unix to more closely match the Windows
    16     15   counterparts.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20     19   The current visual aspect of the Unix version checkbutton and
    21     20   radiobutton has proved to be confusing to users.  The distinction
    22         -between selected (On) and unselected (Off) states are not visually
           21  +between selected \(On\) and unselected \(Off\) states are not visually
    23     22   different enough to clearly identify one from another.  Indeed, in the
    24     23   rare case where only one checkbutton is present, one cannot tell for
    25     24   certain if the state is On or Off.  With a check or dot mark icon
    26         -(dependent on the type of widget) displayed in the Windows version,
           25  +\(dependent on the type of widget\) displayed in the Windows version,
    27     26   there is no question about the state of the widget.
    28     27   
    29         -~ Proposed Changes
           28  +# Proposed Changes
    30     29   
    31         -The checkbutton shall (when the indicator is turned on) display an
           30  +The checkbutton shall \(when the indicator is turned on\) display an
    32     31   check-mark or other distinguishing icon/symbol that clearly indicates
    33     32   an On state.  The Off state will be displayed with an empty box.  The
    34         -state values will ''not'' be indicated by changing relief or
           33  +state values will _not_ be indicated by changing relief or
    35     34   background color.
    36     35   
    37         -The radiobutton shall (when the indicator is turned on) display an dot
           36  +The radiobutton shall \(when the indicator is turned on\) display an dot
    38     37   mark or other distinguishing icon/symbol that clearly indicates a
    39     38   selected or On state.  The unselected or Off state shall be displayed
    40         -with an empty diamond.  The state values will ''not'' be indicated by
           39  +with an empty diamond.  The state values will _not_ be indicated by
    41     40   changing relief or background color.
    42     41   
    43         -~ Copyright
           42  +# Copyright
    44     43   
    45     44   This document has been placed in the public domain.
           45  +

Name change from tip/11.tip to tip/11.md.

     1         -TIP:            11
     2         -Title:          Tk Menubutton Enhancement: -compound option for menubutton
     3         -Version:        $Revision: 1.5 $
     4         -Author:         Todd Helfter <tmh@purdue.edu>
     5         -State:          Final
     6         -Type:           Project
     7         -Tcl-Version:    8.4
     8         -Vote:           Done
     9         -Created:        16-Nov-2000
    10         -Post-History:
            1  +# TIP 11: Tk Menubutton Enhancement: -compound option for menubutton
            2  +	Author:         Todd Helfter <tmh@purdue.edu>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Tcl-Version:    8.4
            6  +	Vote:           Done
            7  +	Created:        16-Nov-2000
            8  +	Post-History:
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP describes how to change the menubutton in the Tk core to add
    15     14   a -compound option to display both text and images.  This behavior
    16     15   already exists in the button widget.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20     19   In order to have a menubutton with both text and images, this change
    21     20   is needed.  This change facilitates the use of an image for the
    22     21   menubutton face with text on top.  Like the button widget, the
    23     22   -compound option will accept these values: none, center, left, right,
    24     23   top, bottom.
    25     24   
    26         -~ Reference Implementation
           25  +# Reference Implementation
    27     26   
    28     27   This TIP proposes to change the internals of the menubutton.
    29     28   
    30     29   The changes necessary to accomplish this are:
    31     30   
    32         -   1. Extend the structure ''TkMenuButton'' in
    33         -      ''generic/tkMenubutton.h'' with a new field of type ''int'' to
           31  +   1. Extend the structure _TkMenuButton_ in
           32  +      _generic/tkMenubutton.h_ with a new field of type _int_ to
    34     33         hold the value of the compound setting.
    35     34   
    36     35      2. Add an enumeration of valid -compound options in
    37         -      ''generic/tkMenubutton.h''.
           36  +      _generic/tkMenubutton.h_.
    38     37   
    39         -   3. Modify ''generic/tkMenuButton.c'' and ''unix/tkUnixMenubu.c'' in
           38  +   3. Modify _generic/tkMenuButton.c_ and _unix/tkUnixMenubu.c_ in
    40     39         such a way to process this new option.  Note: The windows port
    41         -      of Tk uses the ''unix/tkUnixMenubu.c'' file.  So this change is
           40  +      of Tk uses the _unix/tkUnixMenubu.c_ file.  So this change is
    42     41         portable to both Unix and windows.
    43     42   
    44         -   4. Change ''tests/menubut.test'' so that the test for configure
           43  +   4. Change _tests/menubut.test_ so that the test for configure
    45     44         options checks for 33 instead of the current 32.
    46     45   
    47         -   5. Change ''doc/menubutton.n'' to show the new option under widget
           46  +   5. Change _doc/menubutton.n_ to show the new option under widget
    48     47         specific options.
    49     48   
    50         -~ Copyright
           49  +# Copyright
    51     50   
    52     51   This document has been placed in the public domain.
    53     52   
    54         -~ Patch
           53  +# Patch
    55     54   
    56         -|Index: doc/menubutton.n
    57         -|===================================================================
    58         -|RCS file: /cvsroot/tk/doc/menubutton.n,v
    59         -|retrieving revision 1.3
    60         -|diff -c -r1.3 menubutton.n
    61         -|*** menubutton.n	2000/08/25 06:58:32	1.3
    62         -|--- menubutton.n	2000/11/16 14:37:15
    63         -|***************
    64         -|*** 26,31 ****
    65         -|--- 26,39 ----
    66         -|  \-disabledforeground	\-padx
    67         -|  .SE
    68         -|  .SH "WIDGET-SPECIFIC OPTIONS"
    69         -|+ .OP \-compound compound Compound
    70         -|+ Specifies whether the menubutton should display both an image and text,
    71         -|+ and if so, where the image should be placed relative to the text.
    72         -|+ Valid values for this option are \fBbottom\fR, \fBcenter\fR,
    73         -|+ \fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR.  The default value
    74         -|+ is \fBnone\fR, meaning that the menubutton will display either an image or
    75         -|+ text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR
    76         -|+ options.
    77         -|  .VS
    78         -|  .OP \-direction direction Height
    79         -|  Specifies where the menu is going to be popup up. \fBabove\fR tries to
    80         -|Index: generic/tkMenubutton.c
    81         -|===================================================================
    82         -|RCS file: /cvsroot/tk/generic/tkMenubutton.c,v
    83         -|retrieving revision 1.4
    84         -|diff -c -r1.4 tkMenubutton.c
    85         -|*** tkMenubutton.c	1999/04/24 01:50:49	1.4
    86         -|--- tkMenubutton.c	2000/11/16 14:37:16
    87         -|***************
    88         -|*** 37,42 ****
    89         -|--- 37,51 ----
    90         -|  };
    91         -|  
    92         -|  /*
    93         -|+  * The following table defines the legal values for the -compound option.
    94         -|+  * It is used with the "enum compound" declaration in tkButton.h
    95         -|+  */
    96         -|+ 
    97         -|+ static char *compoundStrings[] = {
    98         -|+     "bottom", "center", "left", "none", "right", "top", (char *) NULL
    99         -|+ };
   100         -|+ 
   101         -|+ /*
   102         -|   * Information used for parsing configuration specs:
   103         -|   */
   104         -|  
   105         -|***************
   106         -|*** 113,118 ****
   107         -|--- 122,130 ----
   108         -|      {TK_OPTION_RELIEF, "-relief", "relief", "Relief",
   109         -|	 DEF_MENUBUTTON_RELIEF, -1, Tk_Offset(TkMenuButton, relief), 
   110         -|	   0, 0, 0},
   111         -|+     {TK_OPTION_STRING_TABLE, "-compound", "compound", "Compound",
   112         -|+          DEF_BUTTON_COMPOUND, -1, Tk_Offset(TkMenuButton, compound), 0,
   113         -|+          (ClientData) compoundStrings, 0},
   114         -|      {TK_OPTION_STRING_TABLE, "-state", "state", "State",
   115         -|	 DEF_MENUBUTTON_STATE, -1, Tk_Offset(TkMenuButton, state),
   116         -|	 0, (ClientData) stateStrings, 0},
   117         -|Index: generic/tkMenubutton.h
   118         -|===================================================================
   119         -|RCS file: /cvsroot/tk/generic/tkMenubutton.h,v
   120         -|retrieving revision 1.5
   121         -|diff -c -r1.5 tkMenubutton.h
   122         -|*** tkMenubutton.h	1999/04/16 01:51:19	1.5
   123         -|--- tkMenubutton.h	2000/11/16 14:37:16
   124         -|***************
   125         -|*** 25,30 ****
   126         -|--- 25,39 ----
   127         -|  #endif
   128         -|  
   129         -|  /*
   130         -|+  * Legal values for the "compound" field of TkButton records.
   131         -|+  */
   132         -|+ 
   133         -|+ enum compound {
   134         -|+     COMPOUND_BOTTOM, COMPOUND_CENTER, COMPOUND_LEFT, COMPOUND_NONE,
   135         -|+         COMPOUND_RIGHT, COMPOUND_TOP
   136         -|+ };
   137         -|+ 
   138         -|+ /*
   139         -|   * Legal values for the "orient" field of TkMenubutton records.
   140         -|   */
   141         -|  
   142         -|***************
   143         -|*** 161,166 ****
   144         -|--- 170,179 ----
   145         -|      /*
   146         -|	* Miscellaneous information:
   147         -|	*/
   148         -|+ 
   149         -|+     int compound;               /* Value of -compound option; specifies whether
   150         -|+                                  * the button should show both an image and
   151         -|+                                  * text, and, if so, how. */
   152         -|  
   153         -|      enum direction direction;	/* Direction for where to pop the menu.
   154         -|				  * Valid directions are "above", "below",
   155         -|Index: tests/menubut.test
   156         -|===================================================================
   157         -|RCS file: /cvsroot/tk/tests/menubut.test,v
   158         -|retrieving revision 1.5
   159         -|diff -c -r1.5 menubut.test
   160         -|*** menubut.test	1999/04/21 21:53:29	1.5
   161         -|--- menubut.test	2000/11/16 14:37:18
   162         -|***************
   163         -|*** 138,144 ****
   164         -|  } {3}
   165         -|  test menubutton-3.7 {ButtonWidgetCmd procedure, "configure" option} {
   166         -|      llength [.mb configure]
   167         -|! } {32}
   168         -|  test menubutton-3.8 {ButtonWidgetCmd procedure, "configure" option} {
   169         -|      list [catch {.mb configure -gorp} msg] $msg
   170         -|  } {1 {unknown option "-gorp"}}
   171         -|--- 138,144 ----
   172         -|  } {3}
   173         -|  test menubutton-3.7 {ButtonWidgetCmd procedure, "configure" option} {
   174         -|      llength [.mb configure]
   175         -|! } {33}
   176         -|  test menubutton-3.8 {ButtonWidgetCmd procedure, "configure" option} {
   177         -|      list [catch {.mb configure -gorp} msg] $msg
   178         -|  } {1 {unknown option "-gorp"}}
   179         -|Index: unix/tkUnixMenubu.c
   180         -|===================================================================
   181         -|RCS file: /cvsroot/tk/unix/tkUnixMenubu.c,v
   182         -|retrieving revision 1.4
   183         -|diff -c -r1.4 tkUnixMenubu.c
   184         -|*** tkUnixMenubu.c	1999/09/21 06:43:01	1.4
   185         -|--- tkUnixMenubu.c	2000/11/16 14:37:18
   186         -|***************
   187         -|*** 75,83 ****
   188         -|      Pixmap pixmap;
   189         -|      int x = 0;			/* Initialization needed only to stop
   190         -|				  * compiler warning. */
   191         -|!     int y;
   192         -|      register Tk_Window tkwin = mbPtr->tkwin;
   193         -|!     int width, height;
   194         -|  
   195         -|      mbPtr->flags &= ~REDRAW_PENDING;
   196         -|      if ((mbPtr->tkwin == NULL) || !Tk_IsMapped(tkwin)) {
   197         -|--- 75,85 ----
   198         -|      Pixmap pixmap;
   199         -|      int x = 0;			/* Initialization needed only to stop
   200         -|				  * compiler warning. */
   201         -|!     int y = 0;
   202         -|      register Tk_Window tkwin = mbPtr->tkwin;
   203         -|!     int width, height, fullWidth, fullHeight;
   204         -|!     int imageXOffset, imageYOffset, textXOffset, textYOffset;
   205         -|!     int haveImage = 0, haveText = 0;
   206         -|  
   207         -|      mbPtr->flags &= ~REDRAW_PENDING;
   208         -|      if ((mbPtr->tkwin == NULL) || !Tk_IsMapped(tkwin)) {
   209         -|***************
   210         -|*** 96,101 ****
   211         -|--- 98,112 ----
   212         -|	 border = mbPtr->normalBorder;
   213         -|      }
   214         -|  
   215         -|+     if (mbPtr->image != None) {
   216         -|+ 	Tk_SizeOfImage(mbPtr->image, &width, &height);
   217         -|+ 	haveImage = 1;
   218         -|+     } else if (mbPtr->bitmap != None) {
   219         -|+ 	Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
   220         -|+ 	haveImage = 1;
   221         -|+     }
   222         -|+     haveText = (mbPtr->textWidth != 0 && mbPtr->textHeight != 0);
   223         -|+ 
   224         -|      /*
   225         -|	* In order to avoid screen flashes, this procedure redraws
   226         -|	* the menu button in a pixmap, then copies the pixmap to the
   227         -|***************
   228         -|*** 107,141 ****
   229         -|	     Tk_Width(tkwin), Tk_Height(tkwin), Tk_Depth(tkwin));
   230         -|      Tk_Fill3DRectangle(tkwin, pixmap, border, 0, 0, Tk_Width(tkwin),
   231         -|	     Tk_Height(tkwin), 0, TK_RELIEF_FLAT);
   232         -|- 
   233         -|-     /*
   234         -|-      * Display image or bitmap or text for button.
   235         -|-      */
   236         -|  
   237         -|!     if (mbPtr->image != None) {
   238         -|! 	Tk_SizeOfImage(mbPtr->image, &width, &height);
   239         -|! 
   240         -|! 	imageOrBitmap:
   241         -|! 	TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0, 
   242         -|! 		width + mbPtr->indicatorWidth, height, &x, &y);
   243         -|! 	if (mbPtr->image != NULL) {
   244         -|! 	    Tk_RedrawImage(mbPtr->image, 0, 0, width, height, pixmap,
   245         -|! 		    x, y);
   246         -|! 	} else {
   247         -|! 	    XCopyPlane(mbPtr->display, mbPtr->bitmap, pixmap,
   248         -|! 		    gc, 0, 0, (unsigned) width, (unsigned) height, x, y, 1);
   249         -|! 	}
   250         -|!     } else if (mbPtr->bitmap != None) {
   251         -|! 	Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
   252         -|! 	goto imageOrBitmap;
   253         -|      } else {
   254         -|! 	TkComputeAnchor(mbPtr->anchor, tkwin, mbPtr->padX, mbPtr->padY,
   255         -|! 		mbPtr->textWidth + mbPtr->indicatorWidth,
   256         -|! 		mbPtr->textHeight, &x, &y);
   257         -|! 	Tk_DrawTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout, x, y,
   258         -|! 		0, -1);
   259         -|! 	Tk_UnderlineTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout,
   260         -|! 		x, y, mbPtr->underline);
   261         -|      }
   262         -|  
   263         -|      /*
   264         -|--- 118,223 ----
   265         -|	     Tk_Width(tkwin), Tk_Height(tkwin), Tk_Depth(tkwin));
   266         -|      Tk_Fill3DRectangle(tkwin, pixmap, border, 0, 0, Tk_Width(tkwin),
   267         -|	     Tk_Height(tkwin), 0, TK_RELIEF_FLAT);
   268         -|  
   269         -|!     imageXOffset = 0;
   270         -|!     imageYOffset = 0;
   271         -|!     textXOffset = 0;
   272         -|!     textYOffset = 0;
   273         -|!     fullWidth = 0;
   274         -|!     fullHeight = 0;
   275         -|! 
   276         -|!     if (mbPtr->compound != COMPOUND_NONE && haveImage && haveText) {
   277         -|! 
   278         -|!         switch ((enum compound) mbPtr->compound) {
   279         -|!             case COMPOUND_TOP:
   280         -|!             case COMPOUND_BOTTOM: {
   281         -|!                 /* Image is above or below text */
   282         -|!                 if (mbPtr->compound == COMPOUND_TOP) {
   283         -|!                     textYOffset = height + mbPtr->padY;
   284         -|!                 } else {
   285         -|!                     imageYOffset = mbPtr->textHeight + mbPtr->padY;
   286         -|!                 }
   287         -|!                 fullHeight = height + mbPtr->textHeight + mbPtr->padY;
   288         -|!                 fullWidth = (width > mbPtr->textWidth ? width :
   289         -|!                         mbPtr->textWidth);
   290         -|!                 textXOffset = (fullWidth - mbPtr->textWidth)/2;
   291         -|!                 imageXOffset = (fullWidth - width)/2;
   292         -|!                 break;
   293         -|!             }
   294         -|!             case COMPOUND_LEFT:
   295         -|!             case COMPOUND_RIGHT: {
   296         -|!                 /* Image is left or right of text */
   297         -|!                 if (mbPtr->compound == COMPOUND_LEFT) {
   298         -|!                     textXOffset = width + mbPtr->padX;
   299         -|!                 } else {
   300         -|!                     imageXOffset = mbPtr->textWidth + mbPtr->padX;
   301         -|!                 }
   302         -|!                 fullWidth = mbPtr->textWidth + mbPtr->padX + width;
   303         -|!                 fullHeight = (height > mbPtr->textHeight ? height :
   304         -|!                         mbPtr->textHeight);
   305         -|!                 textYOffset = (fullHeight - mbPtr->textHeight)/2;
   306         -|!                 imageYOffset = (fullHeight - height)/2;
   307         -|!                 break;
   308         -|!             }
   309         -|!             case COMPOUND_CENTER: {
   310         -|!                 /* Image and text are superimposed */
   311         -|!                 fullWidth = (width > mbPtr->textWidth ? width :
   312         -|!                         mbPtr->textWidth);
   313         -|!                 fullHeight = (height > mbPtr->textHeight ? height :
   314         -|!                         mbPtr->textHeight);
   315         -|!                 textXOffset = (fullWidth - mbPtr->textWidth)/2;
   316         -|!                 imageXOffset = (fullWidth - width)/2;
   317         -|!                 textYOffset = (fullHeight - mbPtr->textHeight)/2;
   318         -|!                 imageYOffset = (fullHeight - height)/2;
   319         -|!                 break;
   320         -|!             }
   321         -|!             case COMPOUND_NONE: {break;}
   322         -|!         }
   323         -|! 
   324         -|!         TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0,
   325         -|!                 mbPtr->indicatorWidth + fullWidth, fullHeight,
   326         -|! 		&x, &y);
   327         -|! 
   328         -|!         if (mbPtr->image != NULL) {
   329         -|!             Tk_RedrawImage(mbPtr->image, 0, 0, width, height, pixmap,
   330         -|!                     x + imageXOffset, y + imageYOffset);
   331         -|!         }
   332         -|!         if (mbPtr->bitmap != None) {
   333         -|!             XCopyPlane(mbPtr->display, mbPtr->bitmap, pixmap,
   334         -|!                     gc, 0, 0, (unsigned) width, (unsigned) height, 
   335         -|! 		    x + imageXOffset, y + imageYOffset, 1);
   336         -|!         }
   337         -|!         if (haveText) {
   338         -|!             Tk_DrawTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout, 
   339         -|! 		    x  + textXOffset, y + textYOffset ,
   340         -|!                     0, -1);
   341         -|!             Tk_UnderlineTextLayout(mbPtr->display, pixmap, gc, 
   342         -|! 		    mbPtr->textLayout, x + textXOffset, y + textYOffset ,
   343         -|! 		    mbPtr->underline);
   344         -|!         }
   345         -|      } else {
   346         -|!        if (mbPtr->image != NULL) {
   347         -|!            TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0,
   348         -|!                    width + mbPtr->indicatorWidth, height, &x, &y);
   349         -|!            Tk_RedrawImage(mbPtr->image, 0, 0, width, height, pixmap,
   350         -|!                    x + imageXOffset, y + imageYOffset);
   351         -|!        } else if (mbPtr->bitmap != None) {
   352         -|!            TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0,
   353         -|!                    width + mbPtr->indicatorWidth, height, &x, &y);
   354         -|!            XCopyPlane(mbPtr->display, mbPtr->bitmap, pixmap,
   355         -|!                    gc, 0, 0, (unsigned) width, (unsigned) height, 
   356         -|! 		   x + imageXOffset, y + imageYOffset, 1);
   357         -|!        } else {
   358         -|!            TkComputeAnchor(mbPtr->anchor, tkwin, mbPtr->padX, mbPtr->padY,
   359         -|!                    mbPtr->textWidth + mbPtr->indicatorWidth,
   360         -|!                    mbPtr->textHeight, &x, &y);
   361         -|!            Tk_DrawTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout, 
   362         -|! 		   x  + textXOffset, y + textYOffset ,
   363         -|!                    0, -1);
   364         -|!            Tk_UnderlineTextLayout(mbPtr->display, pixmap, gc, 
   365         -|! 		   mbPtr->textLayout, x + textXOffset, y + textYOffset ,
   366         -|! 		   mbPtr->underline);
   367         -|!         }
   368         -|      }
   369         -|  
   370         -|      /*
   371         -|***************
   372         -|*** 252,305 ****
   373         -|      TkMenuButton *mbPtr;	/* Widget record for menu button. */
   374         -|  {
   375         -|      int width, height, mm, pixels;
   376         -|  
   377         -|      mbPtr->inset = mbPtr->highlightWidth + mbPtr->borderWidth;
   378         -|      if (mbPtr->image != None) {
   379         -|	 Tk_SizeOfImage(mbPtr->image, &width, &height);
   380         -|! 	if (mbPtr->width > 0) {
   381         -|! 	    width = mbPtr->width;
   382         -|! 	}
   383         -|! 	if (mbPtr->height > 0) {
   384         -|! 	    height = mbPtr->height;
   385         -|! 	}
   386         -|      } else if (mbPtr->bitmap != None) {
   387         -|	 Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
   388         -|! 	if (mbPtr->width > 0) {
   389         -|! 	    width = mbPtr->width;
   390         -|! 	}
   391         -|! 	if (mbPtr->height > 0) {
   392         -|! 	    height = mbPtr->height;
   393         -|! 	}
   394         -|!     } else {
   395         -|	 Tk_FreeTextLayout(mbPtr->textLayout);
   396         -|	 mbPtr->textLayout = Tk_ComputeTextLayout(mbPtr->tkfont, mbPtr->text,
   397         -|		 -1, mbPtr->wrapLength, mbPtr->justify, 0, &mbPtr->textWidth,
   398         -|		 &mbPtr->textHeight);
   399         -|! 	width = mbPtr->textWidth;
   400         -|! 	height = mbPtr->textHeight;
   401         -|! 	if (mbPtr->width > 0) {
   402         -|! 	    width = mbPtr->width * Tk_TextWidth(mbPtr->tkfont, "0", 1);
   403         -|! 	}
   404         -|! 	if (mbPtr->height > 0) {
   405         -|! 	    Tk_FontMetrics fm;
   406         -|  
   407         -|! 	    Tk_GetFontMetrics(mbPtr->tkfont, &fm);
   408         -|! 	    height = mbPtr->height * fm.linespace;
   409         -|	 }
   410         -|! 	width += 2*mbPtr->padX;
   411         -|! 	height += 2*mbPtr->padY;
   412         -|      }
   413         -|  
   414         -|      if (mbPtr->indicatorOn) {
   415         -|! 	mm = WidthMMOfScreen(Tk_Screen(mbPtr->tkwin));
   416         -|! 	pixels = WidthOfScreen(Tk_Screen(mbPtr->tkwin));
   417         -|! 	mbPtr->indicatorHeight= (INDICATOR_HEIGHT * pixels)/(10*mm);
   418         -|! 	mbPtr->indicatorWidth = (INDICATOR_WIDTH * pixels)/(10*mm)
   419         -|! 		+ 2*mbPtr->indicatorHeight;
   420         -|! 	width += mbPtr->indicatorWidth;
   421         -|      } else {
   422         -|! 	mbPtr->indicatorHeight = 0;
   423         -|! 	mbPtr->indicatorWidth = 0;
   424         -|      }
   425         -|  
   426         -|      Tk_GeometryRequest(mbPtr->tkwin, (int) (width + 2*mbPtr->inset),
   427         -|--- 334,446 ----
   428         -|      TkMenuButton *mbPtr;	/* Widget record for menu button. */
   429         -|  {
   430         -|      int width, height, mm, pixels;
   431         -|+     int  avgWidth, txtWidth, txtHeight;
   432         -|+     int haveImage = 0, haveText = 0;
   433         -|+     Tk_FontMetrics fm;
   434         -|  
   435         -|      mbPtr->inset = mbPtr->highlightWidth + mbPtr->borderWidth;
   436         -|+ 
   437         -|+     width = 0;
   438         -|+     height = 0;
   439         -|+     txtWidth = 0;
   440         -|+     txtHeight = 0;
   441         -|+     avgWidth = 0;
   442         -|+ 
   443         -|      if (mbPtr->image != None) {
   444         -|	 Tk_SizeOfImage(mbPtr->image, &width, &height);
   445         -|! 	haveImage = 1;
   446         -|      } else if (mbPtr->bitmap != None) {
   447         -|	 Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
   448         -|! 	haveImage = 1;
   449         -|!     }
   450         -|! 
   451         -|!     if (haveImage == 0 || mbPtr->compound != COMPOUND_NONE) {
   452         -|	 Tk_FreeTextLayout(mbPtr->textLayout);
   453         -|+ 
   454         -|	 mbPtr->textLayout = Tk_ComputeTextLayout(mbPtr->tkfont, mbPtr->text,
   455         -|		 -1, mbPtr->wrapLength, mbPtr->justify, 0, &mbPtr->textWidth,
   456         -|		 &mbPtr->textHeight);
   457         -|! 	txtWidth = mbPtr->textWidth;
   458         -|! 	txtHeight = mbPtr->textHeight;
   459         -|!         avgWidth = Tk_TextWidth(mbPtr->tkfont, "0", 1);
   460         -|!         Tk_GetFontMetrics(mbPtr->tkfont, &fm);
   461         -|!         haveText = (txtWidth != 0 && txtHeight != 0);
   462         -|!     }
   463         -|! 
   464         -|!     /*
   465         -|!      * If the menubutton is compound (ie, it shows both an image and text),
   466         -|!      * the new geometry is a combination of the image and text geometry.
   467         -|!      * We only honor the compound bit if the menubutton has both text and
   468         -|!      * an image, because otherwise it is not really a compound menubutton.
   469         -|!      */
   470         -|  
   471         -|!     if (mbPtr->compound != COMPOUND_NONE && haveImage && haveText) {
   472         -|!         switch ((enum compound) mbPtr->compound) {
   473         -|!             case COMPOUND_TOP:
   474         -|!             case COMPOUND_BOTTOM: {
   475         -|!                 /* Image is above or below text */
   476         -|!                 height += txtHeight + mbPtr->padY;
   477         -|!                 width = (width > txtWidth ? width : txtWidth);
   478         -|!                 break;
   479         -|!             }
   480         -|!             case COMPOUND_LEFT:
   481         -|!             case COMPOUND_RIGHT: {
   482         -|!                 /* Image is left or right of text */
   483         -|!                 width += txtWidth + mbPtr->padX;
   484         -|!                 height = (height > txtHeight ? height : txtHeight);
   485         -|!                 break;
   486         -|!             }
   487         -|!             case COMPOUND_CENTER: {
   488         -|!                 /* Image and text are superimposed */
   489         -|!                 width = (width > txtWidth ? width : txtWidth);
   490         -|!                 height = (height > txtHeight ? height : txtHeight);
   491         -|!                 break;
   492         -|!             }
   493         -|!             case COMPOUND_NONE: {break;}
   494         -|!         }
   495         -|!         if (mbPtr->width > 0) {
   496         -|!             width = mbPtr->width;
   497         -|!         }
   498         -|!         if (mbPtr->height > 0) {
   499         -|!             height = mbPtr->height;
   500         -|!         }
   501         -|!         width += 2*mbPtr->padX;
   502         -|!         height += 2*mbPtr->padY;
   503         -|!     } else {
   504         -|! 	if (haveImage) {
   505         -|!             if (mbPtr->width > 0) {
   506         -|!                 width = mbPtr->width;
   507         -|!             }
   508         -|!             if (mbPtr->height > 0) {
   509         -|!                 height = mbPtr->height;
   510         -|!             }
   511         -|! 	} else {
   512         -|! 	    width = txtWidth;
   513         -|! 	    height = txtHeight;
   514         -|!             if (mbPtr->width > 0) {
   515         -|!                 width = mbPtr->width * avgWidth;
   516         -|!             }
   517         -|!             if (mbPtr->height > 0) {
   518         -|!                 height = mbPtr->height * fm.linespace;
   519         -|!             }
   520         -|	 }
   521         -|!     }
   522         -|! 
   523         -|!     if (! haveImage) {
   524         -|!         width += 2*mbPtr->padX;
   525         -|!         height += 2*mbPtr->padY;
   526         -|      }
   527         -|  
   528         -|      if (mbPtr->indicatorOn) {
   529         -|!         mm = WidthMMOfScreen(Tk_Screen(mbPtr->tkwin));
   530         -|!         pixels = WidthOfScreen(Tk_Screen(mbPtr->tkwin));
   531         -|!         mbPtr->indicatorHeight= (INDICATOR_HEIGHT * pixels)/(10*mm);
   532         -|!         mbPtr->indicatorWidth = (INDICATOR_WIDTH * pixels)/(10*mm)
   533         -|!     	    + 2*mbPtr->indicatorHeight;
   534         -|!         width += mbPtr->indicatorWidth;
   535         -|      } else {
   536         -|!         mbPtr->indicatorHeight = 0;
   537         -|!         mbPtr->indicatorWidth = 0;
   538         -|      }
   539         -|  
   540         -|      Tk_GeometryRequest(mbPtr->tkwin, (int) (width + 2*mbPtr->inset),
           55  +	Index: doc/menubutton.n
           56  +	===================================================================
           57  +	RCS file: /cvsroot/tk/doc/menubutton.n,v
           58  +	retrieving revision 1.3
           59  +	diff -c -r1.3 menubutton.n
           60  +	*** menubutton.n	2000/08/25 06:58:32	1.3
           61  +	--- menubutton.n	2000/11/16 14:37:15
           62  +	***************
           63  +	*** 26,31 ****
           64  +	--- 26,39 ----
           65  +	  \-disabledforeground	\-padx
           66  +	  .SE
           67  +	  .SH "WIDGET-SPECIFIC OPTIONS"
           68  +	+ .OP \-compound compound Compound
           69  +	+ Specifies whether the menubutton should display both an image and text,
           70  +	+ and if so, where the image should be placed relative to the text.
           71  +	+ Valid values for this option are \fBbottom\fR, \fBcenter\fR,
           72  +	+ \fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR.  The default value
           73  +	+ is \fBnone\fR, meaning that the menubutton will display either an image or
           74  +	+ text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR
           75  +	+ options.
           76  +	  .VS
           77  +	  .OP \-direction direction Height
           78  +	  Specifies where the menu is going to be popup up. \fBabove\fR tries to
           79  +	Index: generic/tkMenubutton.c
           80  +	===================================================================
           81  +	RCS file: /cvsroot/tk/generic/tkMenubutton.c,v
           82  +	retrieving revision 1.4
           83  +	diff -c -r1.4 tkMenubutton.c
           84  +	*** tkMenubutton.c	1999/04/24 01:50:49	1.4
           85  +	--- tkMenubutton.c	2000/11/16 14:37:16
           86  +	***************
           87  +	*** 37,42 ****
           88  +	--- 37,51 ----
           89  +	  };
           90  +	  
           91  +	  /*
           92  +	+  * The following table defines the legal values for the -compound option.
           93  +	+  * It is used with the "enum compound" declaration in tkButton.h
           94  +	+  */
           95  +	+ 
           96  +	+ static char *compoundStrings[] = {
           97  +	+     "bottom", "center", "left", "none", "right", "top", (char *) NULL
           98  +	+ };
           99  +	+ 
          100  +	+ /*
          101  +	   * Information used for parsing configuration specs:
          102  +	   */
          103  +	  
          104  +	***************
          105  +	*** 113,118 ****
          106  +	--- 122,130 ----
          107  +	      {TK_OPTION_RELIEF, "-relief", "relief", "Relief",
          108  +		 DEF_MENUBUTTON_RELIEF, -1, Tk_Offset(TkMenuButton, relief), 
          109  +		   0, 0, 0},
          110  +	+     {TK_OPTION_STRING_TABLE, "-compound", "compound", "Compound",
          111  +	+          DEF_BUTTON_COMPOUND, -1, Tk_Offset(TkMenuButton, compound), 0,
          112  +	+          (ClientData) compoundStrings, 0},
          113  +	      {TK_OPTION_STRING_TABLE, "-state", "state", "State",
          114  +		 DEF_MENUBUTTON_STATE, -1, Tk_Offset(TkMenuButton, state),
          115  +		 0, (ClientData) stateStrings, 0},
          116  +	Index: generic/tkMenubutton.h
          117  +	===================================================================
          118  +	RCS file: /cvsroot/tk/generic/tkMenubutton.h,v
          119  +	retrieving revision 1.5
          120  +	diff -c -r1.5 tkMenubutton.h
          121  +	*** tkMenubutton.h	1999/04/16 01:51:19	1.5
          122  +	--- tkMenubutton.h	2000/11/16 14:37:16
          123  +	***************
          124  +	*** 25,30 ****
          125  +	--- 25,39 ----
          126  +	  #endif
          127  +	  
          128  +	  /*
          129  +	+  * Legal values for the "compound" field of TkButton records.
          130  +	+  */
          131  +	+ 
          132  +	+ enum compound {
          133  +	+     COMPOUND_BOTTOM, COMPOUND_CENTER, COMPOUND_LEFT, COMPOUND_NONE,
          134  +	+         COMPOUND_RIGHT, COMPOUND_TOP
          135  +	+ };
          136  +	+ 
          137  +	+ /*
          138  +	   * Legal values for the "orient" field of TkMenubutton records.
          139  +	   */
          140  +	  
          141  +	***************
          142  +	*** 161,166 ****
          143  +	--- 170,179 ----
          144  +	      /*
          145  +		* Miscellaneous information:
          146  +		*/
          147  +	+ 
          148  +	+     int compound;               /* Value of -compound option; specifies whether
          149  +	+                                  * the button should show both an image and
          150  +	+                                  * text, and, if so, how. */
          151  +	  
          152  +	      enum direction direction;	/* Direction for where to pop the menu.
          153  +					  * Valid directions are "above", "below",
          154  +	Index: tests/menubut.test
          155  +	===================================================================
          156  +	RCS file: /cvsroot/tk/tests/menubut.test,v
          157  +	retrieving revision 1.5
          158  +	diff -c -r1.5 menubut.test
          159  +	*** menubut.test	1999/04/21 21:53:29	1.5
          160  +	--- menubut.test	2000/11/16 14:37:18
          161  +	***************
          162  +	*** 138,144 ****
          163  +	  } {3}
          164  +	  test menubutton-3.7 {ButtonWidgetCmd procedure, "configure" option} {
          165  +	      llength [.mb configure]
          166  +	! } {32}
          167  +	  test menubutton-3.8 {ButtonWidgetCmd procedure, "configure" option} {
          168  +	      list [catch {.mb configure -gorp} msg] $msg
          169  +	  } {1 {unknown option "-gorp"}}
          170  +	--- 138,144 ----
          171  +	  } {3}
          172  +	  test menubutton-3.7 {ButtonWidgetCmd procedure, "configure" option} {
          173  +	      llength [.mb configure]
          174  +	! } {33}
          175  +	  test menubutton-3.8 {ButtonWidgetCmd procedure, "configure" option} {
          176  +	      list [catch {.mb configure -gorp} msg] $msg
          177  +	  } {1 {unknown option "-gorp"}}
          178  +	Index: unix/tkUnixMenubu.c
          179  +	===================================================================
          180  +	RCS file: /cvsroot/tk/unix/tkUnixMenubu.c,v
          181  +	retrieving revision 1.4
          182  +	diff -c -r1.4 tkUnixMenubu.c
          183  +	*** tkUnixMenubu.c	1999/09/21 06:43:01	1.4
          184  +	--- tkUnixMenubu.c	2000/11/16 14:37:18
          185  +	***************
          186  +	*** 75,83 ****
          187  +	      Pixmap pixmap;
          188  +	      int x = 0;			/* Initialization needed only to stop
          189  +					  * compiler warning. */
          190  +	!     int y;
          191  +	      register Tk_Window tkwin = mbPtr->tkwin;
          192  +	!     int width, height;
          193  +	  
          194  +	      mbPtr->flags &= ~REDRAW_PENDING;
          195  +	      if ((mbPtr->tkwin == NULL) || !Tk_IsMapped(tkwin)) {
          196  +	--- 75,85 ----
          197  +	      Pixmap pixmap;
          198  +	      int x = 0;			/* Initialization needed only to stop
          199  +					  * compiler warning. */
          200  +	!     int y = 0;
          201  +	      register Tk_Window tkwin = mbPtr->tkwin;
          202  +	!     int width, height, fullWidth, fullHeight;
          203  +	!     int imageXOffset, imageYOffset, textXOffset, textYOffset;
          204  +	!     int haveImage = 0, haveText = 0;
          205  +	  
          206  +	      mbPtr->flags &= ~REDRAW_PENDING;
          207  +	      if ((mbPtr->tkwin == NULL) || !Tk_IsMapped(tkwin)) {
          208  +	***************
          209  +	*** 96,101 ****
          210  +	--- 98,112 ----
          211  +		 border = mbPtr->normalBorder;
          212  +	      }
          213  +	  
          214  +	+     if (mbPtr->image != None) {
          215  +	+ 	Tk_SizeOfImage(mbPtr->image, &width, &height);
          216  +	+ 	haveImage = 1;
          217  +	+     } else if (mbPtr->bitmap != None) {
          218  +	+ 	Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
          219  +	+ 	haveImage = 1;
          220  +	+     }
          221  +	+     haveText = (mbPtr->textWidth != 0 && mbPtr->textHeight != 0);
          222  +	+ 
          223  +	      /*
          224  +		* In order to avoid screen flashes, this procedure redraws
          225  +		* the menu button in a pixmap, then copies the pixmap to the
          226  +	***************
          227  +	*** 107,141 ****
          228  +		     Tk_Width(tkwin), Tk_Height(tkwin), Tk_Depth(tkwin));
          229  +	      Tk_Fill3DRectangle(tkwin, pixmap, border, 0, 0, Tk_Width(tkwin),
          230  +		     Tk_Height(tkwin), 0, TK_RELIEF_FLAT);
          231  +	- 
          232  +	-     /*
          233  +	-      * Display image or bitmap or text for button.
          234  +	-      */
          235  +	  
          236  +	!     if (mbPtr->image != None) {
          237  +	! 	Tk_SizeOfImage(mbPtr->image, &width, &height);
          238  +	! 
          239  +	! 	imageOrBitmap:
          240  +	! 	TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0, 
          241  +	! 		width + mbPtr->indicatorWidth, height, &x, &y);
          242  +	! 	if (mbPtr->image != NULL) {
          243  +	! 	    Tk_RedrawImage(mbPtr->image, 0, 0, width, height, pixmap,
          244  +	! 		    x, y);
          245  +	! 	} else {
          246  +	! 	    XCopyPlane(mbPtr->display, mbPtr->bitmap, pixmap,
          247  +	! 		    gc, 0, 0, (unsigned) width, (unsigned) height, x, y, 1);
          248  +	! 	}
          249  +	!     } else if (mbPtr->bitmap != None) {
          250  +	! 	Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
          251  +	! 	goto imageOrBitmap;
          252  +	      } else {
          253  +	! 	TkComputeAnchor(mbPtr->anchor, tkwin, mbPtr->padX, mbPtr->padY,
          254  +	! 		mbPtr->textWidth + mbPtr->indicatorWidth,
          255  +	! 		mbPtr->textHeight, &x, &y);
          256  +	! 	Tk_DrawTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout, x, y,
          257  +	! 		0, -1);
          258  +	! 	Tk_UnderlineTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout,
          259  +	! 		x, y, mbPtr->underline);
          260  +	      }
          261  +	  
          262  +	      /*
          263  +	--- 118,223 ----
          264  +		     Tk_Width(tkwin), Tk_Height(tkwin), Tk_Depth(tkwin));
          265  +	      Tk_Fill3DRectangle(tkwin, pixmap, border, 0, 0, Tk_Width(tkwin),
          266  +		     Tk_Height(tkwin), 0, TK_RELIEF_FLAT);
          267  +	  
          268  +	!     imageXOffset = 0;
          269  +	!     imageYOffset = 0;
          270  +	!     textXOffset = 0;
          271  +	!     textYOffset = 0;
          272  +	!     fullWidth = 0;
          273  +	!     fullHeight = 0;
          274  +	! 
          275  +	!     if (mbPtr->compound != COMPOUND_NONE && haveImage && haveText) {
          276  +	! 
          277  +	!         switch ((enum compound) mbPtr->compound) {
          278  +	!             case COMPOUND_TOP:
          279  +	!             case COMPOUND_BOTTOM: {
          280  +	!                 /* Image is above or below text */
          281  +	!                 if (mbPtr->compound == COMPOUND_TOP) {
          282  +	!                     textYOffset = height + mbPtr->padY;
          283  +	!                 } else {
          284  +	!                     imageYOffset = mbPtr->textHeight + mbPtr->padY;
          285  +	!                 }
          286  +	!                 fullHeight = height + mbPtr->textHeight + mbPtr->padY;
          287  +	!                 fullWidth = (width > mbPtr->textWidth ? width :
          288  +	!                         mbPtr->textWidth);
          289  +	!                 textXOffset = (fullWidth - mbPtr->textWidth)/2;
          290  +	!                 imageXOffset = (fullWidth - width)/2;
          291  +	!                 break;
          292  +	!             }
          293  +	!             case COMPOUND_LEFT:
          294  +	!             case COMPOUND_RIGHT: {
          295  +	!                 /* Image is left or right of text */
          296  +	!                 if (mbPtr->compound == COMPOUND_LEFT) {
          297  +	!                     textXOffset = width + mbPtr->padX;
          298  +	!                 } else {
          299  +	!                     imageXOffset = mbPtr->textWidth + mbPtr->padX;
          300  +	!                 }
          301  +	!                 fullWidth = mbPtr->textWidth + mbPtr->padX + width;
          302  +	!                 fullHeight = (height > mbPtr->textHeight ? height :
          303  +	!                         mbPtr->textHeight);
          304  +	!                 textYOffset = (fullHeight - mbPtr->textHeight)/2;
          305  +	!                 imageYOffset = (fullHeight - height)/2;
          306  +	!                 break;
          307  +	!             }
          308  +	!             case COMPOUND_CENTER: {
          309  +	!                 /* Image and text are superimposed */
          310  +	!                 fullWidth = (width > mbPtr->textWidth ? width :
          311  +	!                         mbPtr->textWidth);
          312  +	!                 fullHeight = (height > mbPtr->textHeight ? height :
          313  +	!                         mbPtr->textHeight);
          314  +	!                 textXOffset = (fullWidth - mbPtr->textWidth)/2;
          315  +	!                 imageXOffset = (fullWidth - width)/2;
          316  +	!                 textYOffset = (fullHeight - mbPtr->textHeight)/2;
          317  +	!                 imageYOffset = (fullHeight - height)/2;
          318  +	!                 break;
          319  +	!             }
          320  +	!             case COMPOUND_NONE: {break;}
          321  +	!         }
          322  +	! 
          323  +	!         TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0,
          324  +	!                 mbPtr->indicatorWidth + fullWidth, fullHeight,
          325  +	! 		&x, &y);
          326  +	! 
          327  +	!         if (mbPtr->image != NULL) {
          328  +	!             Tk_RedrawImage(mbPtr->image, 0, 0, width, height, pixmap,
          329  +	!                     x + imageXOffset, y + imageYOffset);
          330  +	!         }
          331  +	!         if (mbPtr->bitmap != None) {
          332  +	!             XCopyPlane(mbPtr->display, mbPtr->bitmap, pixmap,
          333  +	!                     gc, 0, 0, (unsigned) width, (unsigned) height, 
          334  +	! 		    x + imageXOffset, y + imageYOffset, 1);
          335  +	!         }
          336  +	!         if (haveText) {
          337  +	!             Tk_DrawTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout, 
          338  +	! 		    x  + textXOffset, y + textYOffset ,
          339  +	!                     0, -1);
          340  +	!             Tk_UnderlineTextLayout(mbPtr->display, pixmap, gc, 
          341  +	! 		    mbPtr->textLayout, x + textXOffset, y + textYOffset ,
          342  +	! 		    mbPtr->underline);
          343  +	!         }
          344  +	      } else {
          345  +	!        if (mbPtr->image != NULL) {
          346  +	!            TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0,
          347  +	!                    width + mbPtr->indicatorWidth, height, &x, &y);
          348  +	!            Tk_RedrawImage(mbPtr->image, 0, 0, width, height, pixmap,
          349  +	!                    x + imageXOffset, y + imageYOffset);
          350  +	!        } else if (mbPtr->bitmap != None) {
          351  +	!            TkComputeAnchor(mbPtr->anchor, tkwin, 0, 0,
          352  +	!                    width + mbPtr->indicatorWidth, height, &x, &y);
          353  +	!            XCopyPlane(mbPtr->display, mbPtr->bitmap, pixmap,
          354  +	!                    gc, 0, 0, (unsigned) width, (unsigned) height, 
          355  +	! 		   x + imageXOffset, y + imageYOffset, 1);
          356  +	!        } else {
          357  +	!            TkComputeAnchor(mbPtr->anchor, tkwin, mbPtr->padX, mbPtr->padY,
          358  +	!                    mbPtr->textWidth + mbPtr->indicatorWidth,
          359  +	!                    mbPtr->textHeight, &x, &y);
          360  +	!            Tk_DrawTextLayout(mbPtr->display, pixmap, gc, mbPtr->textLayout, 
          361  +	! 		   x  + textXOffset, y + textYOffset ,
          362  +	!                    0, -1);
          363  +	!            Tk_UnderlineTextLayout(mbPtr->display, pixmap, gc, 
          364  +	! 		   mbPtr->textLayout, x + textXOffset, y + textYOffset ,
          365  +	! 		   mbPtr->underline);
          366  +	!         }
          367  +	      }
          368  +	  
          369  +	      /*
          370  +	***************
          371  +	*** 252,305 ****
          372  +	      TkMenuButton *mbPtr;	/* Widget record for menu button. */
          373  +	  {
          374  +	      int width, height, mm, pixels;
          375  +	  
          376  +	      mbPtr->inset = mbPtr->highlightWidth + mbPtr->borderWidth;
          377  +	      if (mbPtr->image != None) {
          378  +		 Tk_SizeOfImage(mbPtr->image, &width, &height);
          379  +	! 	if (mbPtr->width > 0) {
          380  +	! 	    width = mbPtr->width;
          381  +	! 	}
          382  +	! 	if (mbPtr->height > 0) {
          383  +	! 	    height = mbPtr->height;
          384  +	! 	}
          385  +	      } else if (mbPtr->bitmap != None) {
          386  +		 Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
          387  +	! 	if (mbPtr->width > 0) {
          388  +	! 	    width = mbPtr->width;
          389  +	! 	}
          390  +	! 	if (mbPtr->height > 0) {
          391  +	! 	    height = mbPtr->height;
          392  +	! 	}
          393  +	!     } else {
          394  +		 Tk_FreeTextLayout(mbPtr->textLayout);
          395  +		 mbPtr->textLayout = Tk_ComputeTextLayout(mbPtr->tkfont, mbPtr->text,
          396  +			 -1, mbPtr->wrapLength, mbPtr->justify, 0, &mbPtr->textWidth,
          397  +			 &mbPtr->textHeight);
          398  +	! 	width = mbPtr->textWidth;
          399  +	! 	height = mbPtr->textHeight;
          400  +	! 	if (mbPtr->width > 0) {
          401  +	! 	    width = mbPtr->width * Tk_TextWidth(mbPtr->tkfont, "0", 1);
          402  +	! 	}
          403  +	! 	if (mbPtr->height > 0) {
          404  +	! 	    Tk_FontMetrics fm;
          405  +	  
          406  +	! 	    Tk_GetFontMetrics(mbPtr->tkfont, &fm);
          407  +	! 	    height = mbPtr->height * fm.linespace;
          408  +		 }
          409  +	! 	width += 2*mbPtr->padX;
          410  +	! 	height += 2*mbPtr->padY;
          411  +	      }
          412  +	  
          413  +	      if (mbPtr->indicatorOn) {
          414  +	! 	mm = WidthMMOfScreen(Tk_Screen(mbPtr->tkwin));
          415  +	! 	pixels = WidthOfScreen(Tk_Screen(mbPtr->tkwin));
          416  +	! 	mbPtr->indicatorHeight= (INDICATOR_HEIGHT * pixels)/(10*mm);
          417  +	! 	mbPtr->indicatorWidth = (INDICATOR_WIDTH * pixels)/(10*mm)
          418  +	! 		+ 2*mbPtr->indicatorHeight;
          419  +	! 	width += mbPtr->indicatorWidth;
          420  +	      } else {
          421  +	! 	mbPtr->indicatorHeight = 0;
          422  +	! 	mbPtr->indicatorWidth = 0;
          423  +	      }
          424  +	  
          425  +	      Tk_GeometryRequest(mbPtr->tkwin, (int) (width + 2*mbPtr->inset),
          426  +	--- 334,446 ----
          427  +	      TkMenuButton *mbPtr;	/* Widget record for menu button. */
          428  +	  {
          429  +	      int width, height, mm, pixels;
          430  +	+     int  avgWidth, txtWidth, txtHeight;
          431  +	+     int haveImage = 0, haveText = 0;
          432  +	+     Tk_FontMetrics fm;
          433  +	  
          434  +	      mbPtr->inset = mbPtr->highlightWidth + mbPtr->borderWidth;
          435  +	+ 
          436  +	+     width = 0;
          437  +	+     height = 0;
          438  +	+     txtWidth = 0;
          439  +	+     txtHeight = 0;
          440  +	+     avgWidth = 0;
          441  +	+ 
          442  +	      if (mbPtr->image != None) {
          443  +		 Tk_SizeOfImage(mbPtr->image, &width, &height);
          444  +	! 	haveImage = 1;
          445  +	      } else if (mbPtr->bitmap != None) {
          446  +		 Tk_SizeOfBitmap(mbPtr->display, mbPtr->bitmap, &width, &height);
          447  +	! 	haveImage = 1;
          448  +	!     }
          449  +	! 
          450  +	!     if (haveImage == 0 || mbPtr->compound != COMPOUND_NONE) {
          451  +		 Tk_FreeTextLayout(mbPtr->textLayout);
          452  +	+ 
          453  +		 mbPtr->textLayout = Tk_ComputeTextLayout(mbPtr->tkfont, mbPtr->text,
          454  +			 -1, mbPtr->wrapLength, mbPtr->justify, 0, &mbPtr->textWidth,
          455  +			 &mbPtr->textHeight);
          456  +	! 	txtWidth = mbPtr->textWidth;
          457  +	! 	txtHeight = mbPtr->textHeight;
          458  +	!         avgWidth = Tk_TextWidth(mbPtr->tkfont, "0", 1);
          459  +	!         Tk_GetFontMetrics(mbPtr->tkfont, &fm);
          460  +	!         haveText = (txtWidth != 0 && txtHeight != 0);
          461  +	!     }
          462  +	! 
          463  +	!     /*
          464  +	!      * If the menubutton is compound (ie, it shows both an image and text),
          465  +	!      * the new geometry is a combination of the image and text geometry.
          466  +	!      * We only honor the compound bit if the menubutton has both text and
          467  +	!      * an image, because otherwise it is not really a compound menubutton.
          468  +	!      */
          469  +	  
          470  +	!     if (mbPtr->compound != COMPOUND_NONE && haveImage && haveText) {
          471  +	!         switch ((enum compound) mbPtr->compound) {
          472  +	!             case COMPOUND_TOP:
          473  +	!             case COMPOUND_BOTTOM: {
          474  +	!                 /* Image is above or below text */
          475  +	!                 height += txtHeight + mbPtr->padY;
          476  +	!                 width = (width > txtWidth ? width : txtWidth);
          477  +	!                 break;
          478  +	!             }
          479  +	!             case COMPOUND_LEFT:
          480  +	!             case COMPOUND_RIGHT: {
          481  +	!                 /* Image is left or right of text */
          482  +	!                 width += txtWidth + mbPtr->padX;
          483  +	!                 height = (height > txtHeight ? height : txtHeight);
          484  +	!                 break;
          485  +	!             }
          486  +	!             case COMPOUND_CENTER: {
          487  +	!                 /* Image and text are superimposed */
          488  +	!                 width = (width > txtWidth ? width : txtWidth);
          489  +	!                 height = (height > txtHeight ? height : txtHeight);
          490  +	!                 break;
          491  +	!             }
          492  +	!             case COMPOUND_NONE: {break;}
          493  +	!         }
          494  +	!         if (mbPtr->width > 0) {
          495  +	!             width = mbPtr->width;
          496  +	!         }
          497  +	!         if (mbPtr->height > 0) {
          498  +	!             height = mbPtr->height;
          499  +	!         }
          500  +	!         width += 2*mbPtr->padX;
          501  +	!         height += 2*mbPtr->padY;
          502  +	!     } else {
          503  +	! 	if (haveImage) {
          504  +	!             if (mbPtr->width > 0) {
          505  +	!                 width = mbPtr->width;
          506  +	!             }
          507  +	!             if (mbPtr->height > 0) {
          508  +	!                 height = mbPtr->height;
          509  +	!             }
          510  +	! 	} else {
          511  +	! 	    width = txtWidth;
          512  +	! 	    height = txtHeight;
          513  +	!             if (mbPtr->width > 0) {
          514  +	!                 width = mbPtr->width * avgWidth;
          515  +	!             }
          516  +	!             if (mbPtr->height > 0) {
          517  +	!                 height = mbPtr->height * fm.linespace;
          518  +	!             }
          519  +		 }
          520  +	!     }
          521  +	! 
          522  +	!     if (! haveImage) {
          523  +	!         width += 2*mbPtr->padX;
          524  +	!         height += 2*mbPtr->padY;
          525  +	      }
          526  +	  
          527  +	      if (mbPtr->indicatorOn) {
          528  +	!         mm = WidthMMOfScreen(Tk_Screen(mbPtr->tkwin));
          529  +	!         pixels = WidthOfScreen(Tk_Screen(mbPtr->tkwin));
          530  +	!         mbPtr->indicatorHeight= (INDICATOR_HEIGHT * pixels)/(10*mm);
          531  +	!         mbPtr->indicatorWidth = (INDICATOR_WIDTH * pixels)/(10*mm)
          532  +	!     	    + 2*mbPtr->indicatorHeight;
          533  +	!         width += mbPtr->indicatorWidth;
          534  +	      } else {
          535  +	!         mbPtr->indicatorHeight = 0;
          536  +	!         mbPtr->indicatorWidth = 0;
          537  +	      }
          538  +	  
          539  +	      Tk_GeometryRequest(mbPtr->tkwin, (int) (width + 2*mbPtr->inset),
          540  +

Name change from tip/110.tip to tip/110.md.

     1         -TIP:            110
     2         -Title:          Add a Tristate Mode to the Checkbutton and Radiobutton
     3         -Version:        $Revision: 1.12 $
     4         -Author:         Brian Griffin <bgriffin@model.com>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        01-Oct-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 110: Add a Tristate Mode to the Checkbutton and Radiobutton
            2  +	Author:         Brian Griffin <bgriffin@model.com>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        01-Oct-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -This TIP proposes adding a third value (tristate) to the checkbutton
           13  +This TIP proposes adding a third value \(tristate\) to the checkbutton
    15     14   and radiobutton widgets and corresponding display.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19     18   In order to meet more demanding requirements of todays complex
    20     19   graphical user interfaces, it would help add to the functionality of
    21     20   the basic checkbutton and radiobutton widgets. To support using
    22     21   checkbuttons and radiobuttons along with multiple selection, it is
    23     22   necessary for these buttons to be able to display a third state,
    24     23   i.e., both On and Off.  This indicates the situation where a property
    25     24   has a particular value for some members of a selection set, but
    26     25   not others.
    27     26   
    28         -~ Proposed Change
           27  +# Proposed Change
    29     28   
    30     29   The change would add a third "tristate" value to current On Off values
    31     30   of the checkbutton and radiobutton widgets.  The widget would then
    32         -display the check/dot mark (as appropriate) along with a "grayed"
           31  +display the check/dot mark \(as appropriate\) along with a "grayed"
    33     32   background, for example.  When the checkbutton or radiobutton is 
    34         -invoked (i.e. clicked on) it would behave exactly as it does currently, 
           33  +invoked \(i.e. clicked on\) it would behave exactly as it does currently, 
    35     34   setting the variable to the On value.
    36     35   
    37     36   There is a concern that the Unix version of these widgets do not have
    38     37   a sufficiently different appearance when in the tristate state
    39     38   compared with the On and Off states.  This issue is addressed in
    40         -[109].
           39  +[[109]](109.md).
    41     40   
    42         -~ Propsal Specifics
           41  +# Propsal Specifics
    43     42   
    44         -   1. Identify a third, platform specific, presentation (e.g. check
    45         -      with grayed background) to represent the tristate value,
           43  +   1. Identify a third, platform specific, presentation \(e.g. check
           44  +      with grayed background\) to represent the tristate value,
    46     45   
    47     46      1. Add the option "-tristatevalue" to specify the match value
    48         -      only. The default value of this option will be "{}",
           47  +      only. The default value of this option will be "\{\}",
    49     48   
    50     49      1. Change the behavior to display the indeterminate or tristate
    51     50         presentation when the associated variable's value matches the
    52     51         -tristatevalue, and
    53     52   
    54     53      1. Add the option "-tristateimage" to specify an image to display
    55         -      (in place of the image option) when the checkbutton or
    56         -      radiobutton has the tristate value (as defined above.)
           54  +      \(in place of the image option\) when the checkbutton or
           55  +      radiobutton has the tristate value \(as defined above.\)
    57     56   
    58         -~ Copyright
           57  +# Copyright
    59     58   
    60     59   This document has been placed in the public domain.
           60  +

Name change from tip/111.tip to tip/111.md.

     1         -TIP:            111
     2         -Title:          Dictionary Values and Manipulators
     3         -Version:        $Revision: 1.12 $
     4         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     5         -Author:         David S. Cargo <dcargo@marix.com>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        05-Oct-2002
    10         -Post-History:   
    11         -Tcl-Version:    8.5
            1  +# TIP 111: Dictionary Values and Manipulators
            2  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            3  +	Author:         David S. Cargo <dcargo@marix.com>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        05-Oct-2002
            8  +	Post-History:   
            9  +	Tcl-Version:    8.5
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15         -This TIP proposes adding a standard value format (and supporting
    16         -commands) to Tcl that implements a value-to-value mapping, just as
           14  +This TIP proposes adding a standard value format \(and supporting
           15  +commands\) to Tcl that implements a value-to-value mapping, just as
    17     16   Tcl's list values can be regarded as implementing a number-to-value
    18     17   mapping.
    19     18   
    20         -~ Rationale
           19  +# Rationale
    21     20   
    22     21   What is a dictionary?  It is a translation from arbitrary values to
    23     22   arbitrary values, often also known as an associative map.  Many
    24     23   computer languages, especially higher-level ones, have them as part of
    25     24   the language or the standard library.  It would be nice to have them
    26     25   in Tcl too.
    27     26   
................................................................................
    28     27   Now, I realise that Tcl already contains arrays which provide
    29     28   dictionary functionality, but they are not quite the same thing.
    30     29   Tcl's arrays are collections of variables indexable by name, and not
    31     30   collections of values.  This has some far-reaching implications; it is
    32     31   possible to set traces on individual elements of the array, but it is
    33     32   not possible to pass the array by value.  However, one of the main
    34     33   concerns is the sheer cost of arrays in terms of memory space; aside
    35         -from the hash table used as the core of the implementation (and the
    36         -representations of the keys and values, of course) there is a
           34  +from the hash table used as the core of the implementation \(and the
           35  +representations of the keys and values, of course\) there is a
    37     36   substantial overhead for each array to support traces on the array as
    38         -a whole, plus a similar overhead ''per element'' that stems from the
           37  +a whole, plus a similar overhead _per element_ that stems from the
    39     38   fact that elements are variables in their own right.  By contrast, a
    40     39   dictionary value should be a lot more frugal.
    41     40   
    42         -~ Value Syntax and Semantics
           41  +# Value Syntax and Semantics
    43     42   
    44     43   Naturally, it is desirable for dictionary values to have
    45     44   human-readable forms that are similar to those that currently exist.
    46         -I propose using ''key value key value ...'' form with list-style
           45  +I propose using _key value key value ..._ form with list-style
    47     46   quoting for keys and values that contain characters that are
    48     47   significant to Tcl, which should be immediately familiar to users of
    49         -the '''array get''' and '''array set''' commands.  No special
           48  +the **array get** and **array set** commands.  No special
    50     49   interpretation will be placed on the amount of whitespace separating
    51         -keys and values, just as with lists (indeed, any list with an even
    52         -number of elements can be regarded as a dictionary.)  For example, the
           50  +keys and values, just as with lists \(indeed, any list with an even
           51  +number of elements can be regarded as a dictionary.\)  For example, the
    53     52   following value represents a mapping from selected languages to a
    54     53   possible program to invoke to compile them:
    55     54   
    56         -|	C gcc C++ g++ FORTRAN f77 Java javac
           55  +		C gcc C++ g++ FORTRAN f77 Java javac
    57     56   
    58     57   Empty dictionaries are those that contain no mappings from keys to
    59     58   values.  Any representation of an empty list will also be a
    60     59   representation of an empty dictionary.  There is no upper bound on the
    61     60   number of items that a dictionary may hold.
    62     61   
    63     62   It should be specially noted that dictionary values have copy-on-write
    64     63   semantics just like lists.  This means that if I hand a dictionary
    65     64   value into a procedure as an argument, and that procedure updates the
    66     65   variable containing that value, the value as seen by the caller will
    67     66   not have changed.  This is in complete contrast with arrays which
    68         -cannot (currently) be passed by value other than through using '''array
    69         -get''' to convert the array to a list form and '''array set''' to convert
           67  +cannot \(currently\) be passed by value other than through using **array
           68  +get** to convert the array to a list form and **array set** to convert
    70     69   back again.
    71     70   
    72     71   This specification does not state what order the keys and values are
    73     72   listed in.  That depends on the implementation.
    74     73   
    75         -~ Command Syntax and Semantics
           74  +# Command Syntax and Semantics
    76     75   
    77         -I propose that all operations that work with dictionary values (where
    78         -not done through adaptations of existing commands) will go through the
    79         -'''dict''' command.  The alternatives are "array" which is already in
           76  +I propose that all operations that work with dictionary values \(where
           77  +not done through adaptations of existing commands\) will go through the
           78  +**dict** command.  The alternatives are "array" which is already in
    80     79   use, "dictionary" which is rather long for what I believe will be a
    81         -fairly commonly used command, "alist" (association list) which is
           80  +fairly commonly used command, "alist" \(association list\) which is
    82     81   probably too easy to confuse with existing commands, and "map" which
    83     82   is probably better reserved for future use as something for applying
    84         -an operation to a list (or other collection of values), "hash" (which
    85         -is perhaps too common), and "table" (which is used for this type of
    86         -data structure in the Icon programming language).
           83  +an operation to a list \(or other collection of values\), "hash" \(which
           84  +is perhaps too common\), and "table" \(which is used for this type of
           85  +data structure in the Icon programming language\).
    87     86   
    88         -Most subcommands operate on either a dictionary value (''exists'',
    89         -''for'', ''get'', ''info'', ''keys'', ''remove'', ''replace'',
    90         -''size'', and ''values''), or on a variable containing a dictionary
    91         -value (''append'', ''incr'', ''lappend'', ''set'', and ''unset'').
           87  +Most subcommands operate on either a dictionary value \(_exists_,
           88  +_for_, _get_, _info_, _keys_, _remove_, _replace_,
           89  +_size_, and _values_\), or on a variable containing a dictionary
           90  +value \(_append_, _incr_, _lappend_, _set_, and _unset_\).
    92     91   
    93     92   Proposed subcommands:
    94     93   
    95     94    dict create:	Make a dictionary.
    96     95   
    97         - > '''dict create''' ?''key1 value1 key2 value2 ...''?
           96  + > **dict create** ?_key1 value1 key2 value2 ..._?
    98     97   
    99     98    > This will create a new dictionary from the given keys and values
   100     99      and return it as the result.  The command will take an even number
   101         -   of arbitrary strings (or other objects, naturally) and will use the
          100  +   of arbitrary strings \(or other objects, naturally\) and will use the
   102    101      first, third, fifth, etc. as keys and the second, fourth, sixth,
   103    102      etc. as values.  From the point of view of string representations,
   104         -   this command will behave the same as the '''list''' command with an
          103  +   this command will behave the same as the **list** command with an
   105    104      even number of arguments.  There is no restriction on the possible
   106    105      representations of keys or values.  It is legal to call this
   107    106      command with no arguments at all, which creates an empty
   108    107      dictionary.
   109    108   
   110    109    dict get:	Get value for given key.
   111    110   
   112         - > '''dict get''' ''dictionaryValue'' ?''key ...''?
          111  + > **dict get** _dictionaryValue_ ?_key ..._?
   113    112   
   114         - > Given a dictionary value (first argument) and a key (second
   115         -   argument), this will retrieve the value for that key.  Where
          113  + > Given a dictionary value \(first argument\) and a key \(second
          114  +   argument\), this will retrieve the value for that key.  Where
   116    115      several keys are supplied, the behaviour of the command shall be as
   117         -   if the result of '''dict get''' ''dictVal key'' was passed as the first
   118         -   argument to '''dict get'' with the remaining arguments as second
   119         -   (and possibly subsequent) arguments.  This facilitates lookups in
          116  +   if the result of **dict get** _dictVal key_ was passed as the first
          117  +   argument to **dict get_ with the remaining arguments as second
          118  +   \(and possibly subsequent\) arguments.  This facilitates lookups in
   120    119      nested dictionaries.  For example, the following two commands are
   121    120      equivalent:
   122    121   
   123         -|	dict get $dict foo bar spong
   124         -|	dict get [dict get [dict get $dict foo] bar] spong
          122  +		dict get $dict foo bar spong
          123  +		dict get [dict get [dict get $dict foo] bar] spong
   125    124   
   126    125    > If no keys are provided, dict would return a list containing pairs
   127         -   of elements in a manner similar to '''array get'''.  That is, the
          126  +   of elements in a manner similar to **array get**.  That is, the
   128    127      first element of each pair would be the key and the second element
   129    128      would be the value for that key.
   130    129   
   131    130    > It is an error to attempt to retrieve a value for a key that is not
   132    131      present in the dictionary.
   133    132   
   134    133    dict replace:	Create a new dictionary that is a copy of an old one
   135    134   		except with some values different or some extra
   136    135   		key/value pairs added.
   137    136   
   138         - > '''dict replace''' ''dictionaryValue'' ?''key value ...''?
          137  + > **dict replace** _dictionaryValue_ ?_key value ..._?
   139    138   
   140         - > This is very much the analogue of '''lreplace''', taking a dictionary
          139  + > This is very much the analogue of **lreplace**, taking a dictionary
   141    140      value as its first argument and then a list of key/value pairs.
   142    141      The result of the command is a new dictionary value that is a copy
   143    142      of the supplied dictionary other than that whenever a key is one of
   144    143      those supplied to this command, the returned dictionary will map
   145    144      that key to the associated value.  It is legal for this command to
   146    145      be called with no key/value pairs, but illegal for this command to
   147    146      be called with a key but no value.
   148    147   
   149    148    dict remove:	Create a new dictionary that is a copy of an old one
   150    149   		except without the key/value mappings whose keys are
   151    150   		listed.
   152    151   
   153         - > '''dict remove''' ''dictionaryValue'' ?''key key ...''?
          152  + > **dict remove** _dictionaryValue_ ?_key key ..._?
   154    153   
   155         - > This operation does what '''dict replace''' can't do; removes keys
          154  + > This operation does what **dict replace** can't do; removes keys
   156    155      and values.  The result of the command is a new dictionary value
   157    156      that does not contain mappings for any of the keys listed; it is
   158    157      not an error if either there are no keys listed, or if any of the
   159    158      listed keys does not exist in the supplied dictionary.
   160    159   
   161    160    dict set:	Set value for given key in a dictionary in a variable.
   162    161   
   163         - > '''dict set''' ''dictionaryVar key'' ?''key ...''? ''value''
          162  + > **dict set** _dictionaryVar key_ ?_key ..._? _value_
   164    163   
   165    164    > This operation takes the name of a variable containing a dictionary
   166    165      value and places an updated dictionary value in that variable
   167    166      containing a mapping from the given key to the given value.  In a
   168         -   manner analogous to '''lset''', where multiple keys are present, they
          167  +   manner analogous to **lset**, where multiple keys are present, they
   169    168      do indexing into nested dictionaries.
   170    169   
   171    170    dict unset:	Remove association for given key in a dictionary in a
   172    171   		variable.
   173    172   
   174         - > '''dict unset''' ''dictionaryVar key'' ?''key ...''?
          173  + > **dict unset** _dictionaryVar key_ ?_key ..._?
   175    174   
   176    175    > This operation takes the name of a variable containing a dictionary
   177    176      value and places an updated dictionary value in that variable that
   178    177      does not contain a mapping for the given key.  Where multiple keys
   179    178      are present, this describes a path through nested dictionaries to
   180    179      the mapping to remove.  At least one key must be specified.
   181    180   
   182         - dict keys:	List all keys (with optional criteria matching) in
          181  + dict keys:	List all keys \(with optional criteria matching\) in
   183    182   		dictionary.
   184    183   
   185         - > '''dict keys''' ''dictionaryValue'' ?''globPattern''?
          184  + > **dict keys** _dictionaryValue_ ?_globPattern_?
   186    185   
   187    186    > Return a list of all keys in the given dictionary value.  If a
   188         -   pattern is supplied, only those keys that match it (according to
   189         -   the rules of '''string match''') will be returned.  The returned keys
          187  +   pattern is supplied, only those keys that match it \(according to
          188  +   the rules of **string match**\) will be returned.  The returned keys
   190    189      will be in an arbitrary implementation-specific order.
   191    190   
   192         - dict values:	List all values (with optional criteria matching) in
          191  + dict values:	List all values \(with optional criteria matching\) in
   193    192   		the dictionary.
   194    193   
   195         - > '''dict values''' ''dictionaryValue'' ?''globPattern''?
          194  + > **dict values** _dictionaryValue_ ?_globPattern_?
   196    195   
   197    196    > Return a list of all values in the given dictionary value.  If a
   198         -   pattern is supplied, only those values that match it (according to
   199         -   the rules of '''string match''') will be returned.  The returned keys
          197  +   pattern is supplied, only those values that match it \(according to
          198  +   the rules of **string match**\) will be returned.  The returned keys
   200    199      will be in an arbitrary implementation-specific order, though where
   201         -   no pattern is supplied the ''i''th key returned by '''dict keys'''
   202         -   will be the key for the ''i''th value returned by '''dict values'''
          200  +   no pattern is supplied the _i_th key returned by **dict keys**
          201  +   will be the key for the _i_th value returned by **dict values**
   203    202      applied to the same dictionary value.
   204    203   
   205    204    dict for:	Iterate across all key/value mappings in the
   206    205   		dictionary.
   207    206   
   208         - > '''dict for''' {''keyVar valueVar''} ''dictionaryValue body''
          207  + > **dict for** \{_keyVar valueVar_\} _dictionaryValue body_
   209    208   
   210         - > This takes three arguments, the first a pair of variable names (for
   211         -   the key and value respectively of each mapping in the dictionary),
          209  + > This takes three arguments, the first a pair of variable names \(for
          210  +   the key and value respectively of each mapping in the dictionary\),
   212    211      the second the dictionary value to iterate across, and the third a
   213    212      script to be evaluated for each mapping with the key and value
   214         -   variables set appropriately (in the manner of '''foreach'''.)  The
          213  +   variables set appropriately \(in the manner of **foreach**.\)  The
   215    214      result of the command is an empty string.  If any evaluation of the
   216         -   body generates a ''TCL_BREAK'' result, no further pairs from the
   217         -   dictionary will be iterated over and the '''dict for''' command will
          215  +   body generates a _TCL\_BREAK_ result, no further pairs from the
          216  +   dictionary will be iterated over and the **dict for** command will
   218    217      terminate successfully immediately.  If any evaluation of the body
   219         -   generates a ''TCL_CONTINUE'' result, this shall be treated exactly
   220         -   like a normal ''TCL_OK'' result.
          218  +   generates a _TCL\_CONTINUE_ result, this shall be treated exactly
          219  +   like a normal _TCL\_OK_ result.
   221    220   
   222    221    dict filter:	Create a new dictionary from an old one containing just
   223    222   		a selection of key/value pairs.
   224    223   
   225         - > '''dict filter''' ''dictionaryValue'' '''key''' ''globPattern''
          224  + > **dict filter** _dictionaryValue_ **key** _globPattern_
   226    225   
   227         - > '''dict filter''' ''dictionaryValue'' '''value''' ''globPattern''
          226  + > **dict filter** _dictionaryValue_ **value** _globPattern_
   228    227   
   229         - > '''dict filter''' ''dictionaryValue'' '''script''' {''keyVar valueVar''} ''script''
          228  + > **dict filter** _dictionaryValue_ **script** \{_keyVar valueVar_\} _script_
   230    229   
   231    230    > This takes a dictionary value and returns a new dictionary that
   232    231      contains just those key/value pairs that match the specified rule.
   233         -   Three rules are outlined above.  The '''key''' rule only matches those
          232  +   Three rules are outlined above.  The **key** rule only matches those
   234    233      key/value pairs whose keys match the given glob-style pattern.  The
   235         -   '''value''' rule only matches those key/value pairs whose values match
   236         -   the given glob-style pattern.  The '''script''' rule tests for matching
   237         -   by assigning the key to the ''keyVar'' and the value to the
   238         -   ''valueVar'', and then evaluating the given script which should
   239         -   return a boolean value (with the key/value pair only being included
   240         -   in the result of the '''dict filter''' when a true value is returned.)
          234  +   **value** rule only matches those key/value pairs whose values match
          235  +   the given glob-style pattern.  The **script** rule tests for matching
          236  +   by assigning the key to the _keyVar_ and the value to the
          237  +   _valueVar_, and then evaluating the given script which should
          238  +   return a boolean value \(with the key/value pair only being included
          239  +   in the result of the **dict filter** when a true value is returned.\)
   241    240   
   242    241    dict append:	Append a string to the value for a particular key in
   243    242   		the dictionary.
   244    243   
   245         - > '''dict append''' ''dictionaryVar key'' ?''string ...''?
          244  + > **dict append** _dictionaryVar key_ ?_string ..._?
   246    245   
   247         - > This appends the given string (or strings) to the value that the
          246  + > This appends the given string \(or strings\) to the value that the
   248    247      given key maps to in the dictionary value contained in the given
   249    248      variable, writing the resulting dictionary value back to that
   250    249      variable.  Non-existent keys are treated as if they map to an empty
   251    250      string.
   252    251   
   253    252    dict incr:	Increment the value for a particular key in the
   254    253   		dictionary.
   255    254   
   256         - > '''dict incr''' ''dictionaryVar key'' ?''increment''?
          255  + > **dict incr** _dictionaryVar key_ ?_increment_?
   257    256   
   258         - > This adds the given increment value (an integer that defaults to 1
   259         -   if not specified) to the value that the given key maps to in the
          257  + > This adds the given increment value \(an integer that defaults to 1
          258  +   if not specified\) to the value that the given key maps to in the
   260    259      dictionary value contained in the given variable, writing the
   261    260      resulting dictionary value back to that variable.  Non-existent
   262    261      keys are treated as if they map to 0.  It is an error to increment
   263    262      a value for an existing key if that value is not an integer.
   264    263   
   265    264    dict lappend:	Append an item to the list-value for a particular key
   266    265   		in the dictionary.
   267    266   
   268         - > '''dict lappend''' ''dictionaryVar key'' ?''item ...''?
          267  + > **dict lappend** _dictionaryVar key_ ?_item ..._?
   269    268   
   270    269    > This appends the given items to the list value that the given key
   271    270      maps to in the dictionary value contained in the given variable,
   272    271      writing the resulting dictionary value back to that variable.
   273    272      Non-existent keys are treated as if they map to an empty list, and
   274    273      it is legal for there to be no items to append to the list.  It is
   275    274      an error for the value that the key maps to to not be representable
   276    275      as a list.
   277    276   
   278    277    dict exists:	Test whether a mapping exists for a key.
   279    278   
   280         - > '''dict exists''' ''dictionaryValue key'' ?''key ...''?
          279  + > **dict exists** _dictionaryValue key_ ?_key ..._?
   281    280   
   282         - > This returns a boolean value indicating whether the given key (or
   283         -   path of keys through a set of nested dictionaries) exists in the
          281  + > This returns a boolean value indicating whether the given key \(or
          282  +   path of keys through a set of nested dictionaries\) exists in the
   284    283      given dictionary value.  This returns a true value exactly when
   285         -   '''dict get''' on that path will succeed.
          284  +   **dict get** on that path will succeed.
   286    285   
   287    286    dict size:	Get the number of key/value mappings in a dictionary.
   288    287   
   289         - > '''dict size''' ''dictionaryValue''
          288  + > **dict size** _dictionaryValue_
   290    289   
   291    290    > This returns the size of the dictionary, which will be exactly half
   292         -   the value that '''llength''' ''dictionaryValue'' would return.  It is an
          291  +   the value that **llength** _dictionaryValue_ would return.  It is an
   293    292      error to apply this command to a non-dictionary value.
   294    293   
   295    294    dict info:	Get implementation-specific information about the
   296    295   		dictionary value.
   297    296   
   298         - > '''dict info''' ''dictionaryValue''
          297  + > **dict info** _dictionaryValue_
   299    298   
   300         - > This returns information (intended for display to people) about the
          299  + > This returns information \(intended for display to people\) about the
   301    300      given dictionary though the format of this data is dependent on the
   302    301      implementation of the dictionary.  For dictionaries that are
   303    302      implemented by hash tables, it is expected that this will return
   304         -   the string produced by ''Tcl_HashStats()''.
          303  +   the string produced by _Tcl\_HashStats\(\)_.
   305    304   
   306         -~ Other Related Changes
          305  +# Other Related Changes
   307    306   
   308    307   There are a few other commands that change:
   309    308   
   310         - * '''array set''' will take a dictionary instead of (or as well as) a
          309  + * **array set** will take a dictionary instead of \(or as well as\) a
   311    310      list as its final argument.
   312    311   
   313         - * '''array get''' will return a dictionary.
          312  + * **array get** will return a dictionary.
   314    313   
   315         - * '''string map''' will take a dictionary instead of (or as well as) a
          314  + * **string map** will take a dictionary instead of \(or as well as\) a
   316    315      list as its map argument.
   317    316   
   318         -Naturally, dictionary handling will form its own maintenance area.  [16] and [24] will be updated as necessary.
          317  +Naturally, dictionary handling will form its own maintenance area.  [[16]](16.md) and [[24]](24.md) will be updated as necessary.
   319    318   
   320         -~ C API
          319  +# C API
   321    320   
   322    321   There will be a new public structure and a few new public functions to
   323    322   allow C-level access to dictionary values:
   324    323   
   325         -The new structure (called ''Tcl_DictSearch'') will be there to allow
   326         -for searches (i.e. traversals) of a dictionary.  This TIP does not
          324  +The new structure \(called _Tcl\_DictSearch_\) will be there to allow
          325  +for searches \(i.e. traversals\) of a dictionary.  This TIP does not
   327    326   specify the fields of the structure; the declaration is just to allow
   328    327   for allocation of these structures on the C stack.
   329    328   
   330    329   Many public API functions are capable of generating error messages;
   331    330   these generally indicate some type-conversion failure.  Sharing
   332         -constraint violations (where applicable) cause panics as they indicate
          331  +constraint violations \(where applicable\) cause panics as they indicate
   333    332   basic programming errors which should not be causable by scripts.  The
   334    333   public API functions are:
   335    334   
   336         - > Tcl_Obj *'''Tcl_NewDictObj'''(void);
          335  + > Tcl\_Obj \***Tcl\_NewDictObj**\(void\);
   337    336   
   338         - > Tcl_Obj *'''Tcl_DbNewDictObj'''(CONST char *''file'', int ''line'');
          337  + > Tcl\_Obj \***Tcl\_DbNewDictObj**\(CONST char \*_file_, int _line_\);
   339    338   
   340         -These functions (in non-debug and debug versions) create a new
          339  +These functions \(in non-debug and debug versions\) create a new
   341    340   dictionary object and return it.
   342    341   
   343         - > int '''Tcl_DictObjPut'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   344         -	Tcl_Obj *''keyPtr'', Tcl_Obj *''valuePtr'');
          342  + > int **Tcl\_DictObjPut**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          343  +	Tcl\_Obj \*_keyPtr_, Tcl\_Obj \*_valuePtr_\);
   345    344   
   346    345   This function inserts a new key/value pair into a dictionary, or
   347    346   updates a key/value pair already in the dictionary.  The dictionary
   348    347   object must be unshared.  Note that both the key and value objects
   349    348   will have their reference count increased.  The return value is a
   350         -normal TCL_OK/TCL_ERROR result, with the ''interp'' for error
          349  +normal TCL\_OK/TCL\_ERROR result, with the _interp_ for error
   351    350   reporting.
   352    351   
   353         - > int '''Tcl_DictObjGet'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   354         -	Tcl_Obj *''keyPtr'', Tcl_Obj **''valuePtrPtr'');
          352  + > int **Tcl\_DictObjGet**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          353  +	Tcl\_Obj \*_keyPtr_, Tcl\_Obj \*\*_valuePtrPtr_\);
   355    354   
   356    355   This function looks up the value for a key in a dictionary.  The
   357         -variable pointed to by the ''valuePtrPtr'' argument is updated to
          356  +variable pointed to by the _valuePtrPtr_ argument is updated to
   358    357   contain a reference to the value, or a NULL if there is no mapping for
   359    358   the key in the dictionary.  No reference counts are manipulated by
   360         -this function.  The return value is a normal TCL_OK/TCL_ERROR result,
   361         -with the ''interp'' for error reporting.
          359  +this function.  The return value is a normal TCL\_OK/TCL\_ERROR result,
          360  +with the _interp_ for error reporting.
   362    361   
   363         - > int '''Tcl_DictObjRemove'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   364         -	Tcl_Obj *''keyPtr'');
          362  + > int **Tcl\_DictObjRemove**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          363  +	Tcl\_Obj \*_keyPtr_\);
   365    364   
   366    365   This function removes the key/value pair with the given key from the
   367    366   dictionary.  It is not an error if the key is not present in the
   368    367   dictionary.  The dictionary must be unshared.  The return value is a
   369         -normal TCL_OK/TCL_ERROR result, with the ''interp'' for error
          368  +normal TCL\_OK/TCL\_ERROR result, with the _interp_ for error
   370    369   reporting.
   371    370   
   372         - > int '''Tcl_DictObjSize'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   373         -	int *''sizePtr'');
          371  + > int **Tcl\_DictObjSize**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          372  +	int \*_sizePtr_\);
   374    373   
   375         -This function updates the integer variable pointed to by ''sizePtr''
          374  +This function updates the integer variable pointed to by _sizePtr_
   376    375   with the number of key/value pairs in the dictionary.  The return
   377         -value is a normal TCL_OK/TCL_ERROR result, with the ''interp'' for
          376  +value is a normal TCL\_OK/TCL\_ERROR result, with the _interp_ for
   378    377   error reporting.
   379    378   
   380         - > int '''Tcl_DictObjFirst'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   381         -	Tcl_DictSearch *''searchPtr'',
   382         -	Tcl_Obj **''keyPtrPtr'', Tcl_Obj **''valuePtrPtr'', int *''donePtr'');
          379  + > int **Tcl\_DictObjFirst**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          380  +	Tcl\_DictSearch \*_searchPtr_,
          381  +	Tcl\_Obj \*\*_keyPtrPtr_, Tcl\_Obj \*\*_valuePtrPtr_, int \*_donePtr_\);
   383    382   
   384         -This function starts a search of (i.e. iteration over) the given
   385         -dictionary, using the structure pointed to by ''searchPtr'' as
   386         -context.  The return value is a normal TCL_OK/TCL_ERROR result, with
   387         -the ''interp'' for error reporting.  Three variables are updated to
   388         -indicate what was found; ''keyPtrPtr'' is used for reporting the key
   389         -of a key/value pair and ''valuePtrPtr'' is used for reporting the
   390         -corresponding value.  Finally, ''donePtr'' is used for indicating
          383  +This function starts a search of \(i.e. iteration over\) the given
          384  +dictionary, using the structure pointed to by _searchPtr_ as
          385  +context.  The return value is a normal TCL\_OK/TCL\_ERROR result, with
          386  +the _interp_ for error reporting.  Three variables are updated to
          387  +indicate what was found; _keyPtrPtr_ is used for reporting the key
          388  +of a key/value pair and _valuePtrPtr_ is used for reporting the
          389  +corresponding value.  Finally, _donePtr_ is used for indicating
   391    390   whether the search has found all the values; if the variable it points
   392    391   to is set to 1 there are no key/value pairs in the dictionary
   393         -(i.e. the variables pointed to by ''keyPtrPtr'' and ''valuePtrPtr''
   394         -were not updated), but if the variable is set to 0, a key/value pair
   395         -was found and ''Tcl_DictObjNext()'' should be called to discover
          392  +\(i.e. the variables pointed to by _keyPtrPtr_ and _valuePtrPtr_
          393  +were not updated\), but if the variable is set to 0, a key/value pair
          394  +was found and _Tcl\_DictObjNext\(\)_ should be called to discover
   396    395   whether that was the last value or if there are further ones in the
   397    396   dictionary.  Note that if this function indicates that the search is
   398    397   not done but the calling code wishes to extract no further values from
   399         -the dictionary, ''Tcl_DictObjDone()'' ''must'' be called to release
          398  +the dictionary, _Tcl\_DictObjDone\(\)_ _must_ be called to release
   400    399   the internal locks on the representation of the value.
   401    400   
   402         - > void '''Tcl_DictObjNext'''(Tcl_DictSearch *''searchPtr'',
   403         -	Tcl_Obj **''keyPtrPtr'', Tcl_Obj **''valuePtrPtr'', int *''donePtr'');
          401  + > void **Tcl\_DictObjNext**\(Tcl\_DictSearch \*_searchPtr_,
          402  +	Tcl\_Obj \*\*_keyPtrPtr_, Tcl\_Obj \*\*_valuePtrPtr_, int \*_donePtr_\);
   404    403   
   405    404   This function gets the next key/value pair from the search of a
   406         -dictionary, using the search referenced by ''searchPtr''.  The meaning
   407         -of the ''keyPtrPtr'', ''valuePtrPtr'' and ''donePtr'' variables is
   408         -much the same as in ''Tcl_DictObjFirst()'', along with the restriction
          405  +dictionary, using the search referenced by _searchPtr_.  The meaning
          406  +of the _keyPtrPtr_, _valuePtrPtr_ and _donePtr_ variables is
          407  +much the same as in _Tcl\_DictObjFirst\(\)_, along with the restriction
   409    408   that if the function indicates that the search is not done but the
   410    409   calling code wishes to extract no further values from the dictionary,
   411         -''Tcl_DictObjDone()'' ''must'' be called to release the internal locks
          410  +_Tcl\_DictObjDone\(\)_ _must_ be called to release the internal locks
   412    411   on the representation of the value.
   413    412   
   414         - > void '''Tcl_DictObjDone'''(Tcl_DictSearch *''searchPtr'');
          413  + > void **Tcl\_DictObjDone**\(Tcl\_DictSearch \*_searchPtr_\);
   415    414   
   416    415   This function terminates a search of a dictionary before all the
   417    416   values in the dictionary have been iterated over, releasing the
   418    417   internal locks on the dictionary representation.
   419    418   
   420         - > int '''Tcl_DictObjPutKeyList'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   421         -	int ''keyc'', Tcl_Obj *CONST *''keyv'', Tcl_Obj *''valuePtr'');
          419  + > int **Tcl\_DictObjPutKeyList**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          420  +	int _keyc_, Tcl\_Obj \*CONST \*_keyv_, Tcl\_Obj \*_valuePtr_\);
   422    421   
   423         -This function is a variant on ''Tcl_DictObjPut()'' that takes a list
          422  +This function is a variant on _Tcl\_DictObjPut\(\)_ that takes a list
   424    423   of keys so as to work with nested dictionaries.
   425    424   
   426         - > int '''Tcl_DictObjRemoveKeyList'''(Tcl_Interp *''interp'', Tcl_Obj *''dictPtr'',
   427         -	int ''keyc'', Tcl_Obj *CONST *''keyv'');
          425  + > int **Tcl\_DictObjRemoveKeyList**\(Tcl\_Interp \*_interp_, Tcl\_Obj \*_dictPtr_,
          426  +	int _keyc_, Tcl\_Obj \*CONST \*_keyv_\);
   428    427   
   429         -This function is a variant on ''Tcl_DictObjRemove()'' that takes a
          428  +This function is a variant on _Tcl\_DictObjRemove\(\)_ that takes a
   430    429   list of keys so as to work with nested dictionaries.
   431    430   
   432         -~ Examples
          431  +# Examples
   433    432   
   434    433   Counting the number of unique words in a file and the number of times
   435    434   each word occurs:
   436    435   
   437         -|set f [open someFile.txt]
   438         -|set contents [read $f]
   439         -|close $f
   440         -|foreach word [regexp -all -inline {\w+} $contents] {
   441         -|   dict incr count $word
   442         -|}
   443         -|puts "There are [dict size $count] unique words."
   444         -|foreach word [lsort -dictionary [dict keys $count]] {
   445         -|   puts "${word}: [dict get $count $word] occurrences"
   446         -|}
          436  +	set f [open someFile.txt]
          437  +	set contents [read $f]
          438  +	close $f
          439  +	foreach word [regexp -all -inline {\w+} $contents] {
          440  +	   dict incr count $word
          441  +	}
          442  +	puts "There are [dict size $count] unique words."
          443  +	foreach word [lsort -dictionary [dict keys $count]] {
          444  +	   puts "${word}: [dict get $count $word] occurrences"
          445  +	}
          446  +
          447  +A localisable **string toupper** implementation:
   447    448   
   448         -A localisable '''string toupper''' implementation:
          449  +	set capital [dict create C [dict create]]
          450  +	foreach c {abcdefghijklmnopqrstuvwxyz} {
          451  +	   dict set capital C $c [string toupper $c]
          452  +	}
          453  +	dict set capital en [dict get $capital C]
          454  +	# ... and so on for other supported languages ...
          455  +	set upperCase [string map [dict get $capital $env(LANG)] $string
   449    456   
   450         -|set capital [dict create C [dict create]]
   451         -|foreach c {abcdefghijklmnopqrstuvwxyz} {
   452         -|   dict set capital C $c [string toupper $c]
   453         -|}
   454         -|dict set capital en [dict get $capital C]
   455         -|# ... and so on for other supported languages ...
   456         -|set upperCase [string map [dict get $capital $env(LANG)] $string
   457         -
   458         -~ Copyright
          457  +# Copyright
   459    458   
   460    459   This document has been placed in the public domain.
   461    460   
   462    461   ----
   463    462   
   464         -~ Appendices
          463  +# Appendices
          464  +
          465  +_These appendices are not formally part of the proposal and exist
          466  +merely to help understanding._
   465    467   
   466         -''These appendices are not formally part of the proposal and exist
   467         -merely to help understanding.''
          468  +# ~ Implementation Notes
   468    469   
   469         -~ ~ Implementation Notes
   470         -
   471         -Implement using hash tables (of course.)  Need efficient ways to
          470  +Implement using hash tables \(of course.\)  Need efficient ways to
   472    471   convert to/from lists, perhaps making lists know what's going on
   473    472   underneath the covers?
   474    473   
   475         -~ ~ Future Directions
          474  +# ~ Future Directions
   476    475   
   477    476   Alternate implementations of mappings, like trees or disk-backed
   478    477   databases?
          478  +

Name change from tip/112.tip to tip/112.md.

     1         -TIP:            112
     2         -Title:          Ensembles are Namespaces are Commands
     3         -Version:        $Revision: 2.28 $
     4         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        10-Oct-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 112: Ensembles are Namespaces are Commands
            2  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        10-Oct-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -This TIP proposes unifying the concept of ensembles (from [[Incr
    15         -Tcl]]) with namespaces and commands.  It also adds control of command
           13  +This TIP proposes unifying the concept of ensembles \(from [Incr
           14  +Tcl]\) with namespaces and commands.  It also adds control of command
    16     15   rewriting to allow for more efficient support for object systems like
    17     16   Snit.
    18     17   
    19         -~ Rationale
           18  +# Rationale
    20     19   
    21         -Tcl's subcommand-style command collections (e.g. ''array'', ''info'',
    22         -''string'', ''interp'', etc.) are a very intuitive and popular way of
           20  +Tcl's subcommand-style command collections \(e.g. _array_, _info_,
           21  +_string_, _interp_, etc.\) are a very intuitive and popular way of
    23     22   structuring collections of related commands.  However, it is quite
    24         -awkward to write Tcl code that behaves that way.  Users of [[Incr
    25         -Tcl]] have access to ensembles which provide that, but it would be a
           23  +awkward to write Tcl code that behaves that way.  Users of [Incr
           24  +Tcl] have access to ensembles which provide that, but it would be a
    26     25   very useful feature for many other uses too.
    27     26   
    28     27   At the same time, it is becoming clear that many applications want to
    29         -commonly refer to commands inside other namespaces directly (instead
    30         -of through the [[namespace import]] mechanism) but the syntax for
           28  +commonly refer to commands inside other namespaces directly \(instead
           29  +of through the [namespace import] mechanism\) but the syntax for
    31     30   doing this is verbose and not as elegant as it might be.
    32     31   
    33     32   I believe that the same solution can address these two problems in one
    34     33   go, and make the language stronger and more usable for it.
    35     34   
    36     35   Furthermore, by giving the programmer control over the mapping from
    37     36   the ensemble subcommands to their implementing commands, we can build
    38     37   a simple class system on the cheap since we can, in effect, import
    39     38   commands from elsewhere into the ensemble.  By extending the mapping
    40     39   so that it allows the specification of not just the implementing
    41         -command, but also some leading arguments to that command (similar to
    42         -what you can do with the [[interp alias]] mechanism) this becomes a
           40  +command, but also some leading arguments to that command \(similar to
           41  +what you can do with the [interp alias] mechanism\) this becomes a
    43     42   very powerful mechanism indeed.
    44     43   
    45     44   Finally, a sophisticated extra capability is the addition of an unknown
    46     45   subcommand callback to allow the creator of the ensemble to specify a
    47     46   customized strategy for handling subcommands that are not recognized by
    48     47   the ensemble machinery.  This allows an ensemble to be dynamically
    49     48   updated to include those subcommands that the user asks for, which is
    50     49   a potential route for doing things like using an ensemble as a wrapper
    51     50   round a Tk widget.
    52     51   
    53         -~ Proposed Change
           52  +# Proposed Change
    54     53   
    55         -I propose to add a new subcommand to the [[namespace]] command,
    56         -''ensemble'', that creates and manipulates the ensemble command for a
           54  +I propose to add a new subcommand to the [namespace] command,
           55  +_ensemble_, that creates and manipulates the ensemble command for a
    57     56   namespace.  Each namespace may have any number of ensemble commands
    58     57   associated with it, with the default name of an ensemble command
    59     58   being the fully-qualified name of the namespace itself, though it will
    60         -be legal to rename ensemble commands (anyone wanting to track such
    61         -events should use the [[trace]] command.)  Tcl will not create an
           59  +be legal to rename ensemble commands \(anyone wanting to track such
           60  +events should use the [trace] command.\)  Tcl will not create an
    62     61   ensemble command for any namespace by default.
    63     62   
    64         -The [[namespace ensemble]] command will have the following subcommands:
           63  +The [namespace ensemble] command will have the following subcommands:
    65     64   
    66         - create: For creating a new ensemble for the ''current'' namespace. The
    67         -   command takes a list of option value pairs (as defined below) to
           65  + create: For creating a new ensemble for the _current_ namespace. The
           66  +   command takes a list of option value pairs \(as defined below\) to
    68     67      set the ensemble up with.  As stated above, the default command name
    69     68      is exactly the name of the namespace, but any other name may be
    70         -   supplied (via the -command option); if it does not start with a
           69  +   supplied \(via the -command option\); if it does not start with a
    71     70      namespace separator, the name will be taken as being relative to
    72     71      the current namespace.  If another command with the same name exists,
    73     72      it is deleted as part of the creation of the ensemble.
    74     73   
    75     74    configure: For reading and writing the configuration of a particular
    76     75      ensemble.  The command takes an argument specifying the name of the
    77     76      ensemble to configure, and then works with either no extra arguments
    78         -   (when it retrieves the entire ensemble configuration), one extra
    79         -   argument (the name of the option to retrieve), or a list of option
           77  +   \(when it retrieves the entire ensemble configuration\), one extra
           78  +   argument \(the name of the option to retrieve\), or a list of option
    80     79      value pairs to configure the ensemble with.  This command returns an error if applied to anything that is not an ensemble.
    81     80   
    82         - exists: This subcommand (which takes a single argument) tests whether
    83         -   a command (with the given name) exists and is an ensemble.  This command only returns an error if the wrong number of arguments are supplied.
           81  + exists: This subcommand \(which takes a single argument\) tests whether
           82  +   a command \(with the given name\) exists and is an ensemble.  This command only returns an error if the wrong number of arguments are supplied.
    84     83   
    85     84   The options available for creation and configuring are:
    86     85   
    87         - -subcommands: This option (if non-empty) specifies a list of ensemble
           86  + -subcommands: This option \(if non-empty\) specifies a list of ensemble
    88     87      subcommands that the ensemble supports.  It does not need to be
    89     88      sorted.  Each command is mapped according to the dictionary in the
    90         -   ''-map'' option (if a non-empty map is present and the command has
    91         -   a mapping) or to the correspondingly named command (which is not
    92         -   required to exist at the time this is specified) in the context
           89  +   _-map_ option \(if a non-empty map is present and the command has
           90  +   a mapping\) or to the correspondingly named command \(which is not
           91  +   required to exist at the time this is specified\) in the context
    93     92      namespace.
    94     93   
    95         - -map: This option (if non-empty) specifies a dictionary that maps
           94  + -map: This option \(if non-empty\) specifies a dictionary that maps
    96     95      from ensemble subcommand names to lists of arguments to substitute
    97     96      into the ensemble invokation in place of the ensemble command name
    98         -   and the subcommand name.  See the ''-subcommands'' option for the meaning
           97  +   and the subcommand name.  See the _-subcommands_ option for the meaning
    99     98      of this option when that option is also non-empty.  If this option is
   100         -   empty and the ''-subcommands'' option is empty too, the namespace will use
           99  +   empty and the _-subcommands_ option is empty too, the namespace will use
   101    100      the exported commands of the namespace as its command set, dynamically
   102         -   determining them (subject to cacheing) every time the ensemble is
   103         -   ''invoked''.  Note that the words in the dictionary values that give
   104         -   the commands to map to (as opposed to any arguments to them) are
   105         -   always resolved (if not absolute) relative to the namespace which is
   106         -   running [[namespace ensemble create]] or [[namespace ensemble
   107         -   configure]].
          101  +   determining them \(subject to cacheing\) every time the ensemble is
          102  +   _invoked_.  Note that the words in the dictionary values that give
          103  +   the commands to map to \(as opposed to any arguments to them\) are
          104  +   always resolved \(if not absolute\) relative to the namespace which is
          105  +   running [namespace ensemble create] or [namespace ensemble
          106  +   configure].
   108    107   
   109         - -prefixes: This boolean option (which is on by default) controls whether
          108  + -prefixes: This boolean option \(which is on by default\) controls whether
   110    109      unambiguous prefixes of ensemble commands are recognized as if they
   111    110      were the fully specified ensemble command names.
   112    111   
   113         - -unknown: This provides (when non-empty) a partial command to handle
          112  + -unknown: This provides \(when non-empty\) a partial command to handle
   114    113      the case where an ensemble subcommand is not recognized and would
   115         -   otherwise generate an error.  When empty (the default) an error (in
   116         -   the style of ''Tcl_GetIndexFromObj'') is generated whenever the
          114  +   otherwise generate an error.  When empty \(the default\) an error \(in
          115  +   the style of _Tcl\_GetIndexFromObj_\) is generated whenever the
   117    116      ensemble is unable to determine how to implement a particular
   118    117      subcommand.
   119    118   
   120         - > See ''Unknown Handler Behaviour'' below for details of how the
          119  + > See _Unknown Handler Behaviour_ below for details of how the
   121    120      ensemble interacts with its unknown handler.
   122    121   
   123    122   Ensemble creation takes an extra option value pair:
   124    123   
   125    124    -command: This option allows you to override what the name of the
   126    125      ensemble to create is.
   127    126   
   128    127   Ensemble configuring allows the querying of an extra read-only option:
   129    128   
   130         - -namespace: This ''read-only'' option allows the retrieval of the name
          129  + -namespace: This _read-only_ option allows the retrieval of the name
   131    130      of the namespace that the ensemble was created in.
   132    131   
   133    132   Given an ensemble command created by the above mechanism, calling the
   134    133   command will first of all match the subcommand to its implementing
   135         -command (or command/argument list, as derived from the dictionary) in
          134  +command \(or command/argument list, as derived from the dictionary\) in
   136    135   a manner that will be recognizably similar to that enforced by
   137         -''Tcl_GetIndexFromObj()'' (unless the ''-unknown'' option override this
   138         -behaviour.)  For details of how the ensemble determines what its subcommands are, please see the ''-subcommands'' and ''-map'' options above.
          136  +_Tcl\_GetIndexFromObj\(\)_ \(unless the _-unknown_ option override this
          137  +behaviour.\)  For details of how the ensemble determines what its subcommands are, please see the _-subcommands_ and _-map_ options above.
   139    138   Then the ensemble command will rewrite the command and arguments so
   140    139   that the ensemble command and subcommand are replaced by the
   141    140   implementing command and any specified arguments, with the resulting
   142         -word list being fed to ''Tcl_EvalObjv()'' for execution.  Note that
   143         -this does not increase the stack depth in terms of [[uplevel]], and
          141  +word list being fed to _Tcl\_EvalObjv\(\)_ for execution.  Note that
          142  +this does not increase the stack depth in terms of [uplevel], and
   144    143   that the implementing command may itself be an ensemble command.
   145    144   
   146    145   Note that if the namespace for an ensemble is deleted, the ensemble will
   147    146   also be deleted though there is no lifetime constraint in the other
   148         -direction (i.e. using [[rename $theEnsemble {}]] will not cause the
   149         -namespace to vanish.)  Obviously, any ensemble which has the global
          147  +direction \(i.e. using [rename $theEnsemble {}] will not cause the
          148  +namespace to vanish.\)  Obviously, any ensemble which has the global
   150    149   namespace backing it up will have the same natural lifespan as the
   151    150   hosting Tcl interpreter.
   152    151   
   153         -~ Unknown Handler Behaviour
          152  +# Unknown Handler Behaviour
   154    153   
   155         -If an unknown handler is specified for an ensemble, that handler is called when the ensemble command would otherwise return an error due to it being unable to decide which subcommand to invoke.  The exact conditions under which that occurs are controlled by the ''-subcommands'', ''-map'' and ''-prefixes'' options as described above.
          154  +If an unknown handler is specified for an ensemble, that handler is called when the ensemble command would otherwise return an error due to it being unable to decide which subcommand to invoke.  The exact conditions under which that occurs are controlled by the _-subcommands_, _-map_ and _-prefixes_ options as described above.
   156    155   
   157         -To execute the unknown handler, the ensemble mechanism takes the specified -unknown option and appends each argument of the attempted ensemble command invocation (including the ensemble command itself, expressed as a fully qualified name). It invokes the resulting command in the scope of the attempted call. If the execution of the unknown handler terminates normally, the ensemble engine reparses the subcommand (as described below) and tries to dispatch it again, which is ideal for when the ensemble's configuration has been updated by the unknown subcommand handler.  Any other kind of termination of the unknown handler is treated as an error.
          156  +To execute the unknown handler, the ensemble mechanism takes the specified -unknown option and appends each argument of the attempted ensemble command invocation \(including the ensemble command itself, expressed as a fully qualified name\). It invokes the resulting command in the scope of the attempted call. If the execution of the unknown handler terminates normally, the ensemble engine reparses the subcommand \(as described below\) and tries to dispatch it again, which is ideal for when the ensemble's configuration has been updated by the unknown subcommand handler.  Any other kind of termination of the unknown handler is treated as an error.
   158    157   
   159         -The result of the unknown handler is expected to be a list (it is an error if it is not).  If the list is an empty list, the ensemble command attempts to look up the original subcommand again and, if it is not found this time, an error will be generated just as if the -unknown handler was not there (i.e. for any particular invokation of an ensemble, its unknown handler will be called at most once.)  This makes it easy for the unknown handler to update the ensemble or its backing namespace so as to provide an implementation of the desired subcommand and reparse.
          158  +The result of the unknown handler is expected to be a list \(it is an error if it is not\).  If the list is an empty list, the ensemble command attempts to look up the original subcommand again and, if it is not found this time, an error will be generated just as if the -unknown handler was not there \(i.e. for any particular invokation of an ensemble, its unknown handler will be called at most once.\)  This makes it easy for the unknown handler to update the ensemble or its backing namespace so as to provide an implementation of the desired subcommand and reparse.
          159  +
          160  +When the result is a non-empty list, the words of that list are used to replace the ensemble command and subcommand, just as if they had been looked up in the -map.  It is up to the unknown handler to supply all namespace qualifiers if the implementing subcommand is not in the namespace of the caller of the ensemble command.  Also note that when ensemble commands are chained \(e.g. if you make one of the commands that implement an ensemble subcommand into an ensemble, in a manner similar to the text widget's _tag_ and _mark_ subcommands\) then the rewrite happens in the context of the caller of the outermost ensemble.  That is to say that ensembles do not in themselves place any namespace contexts on the Tcl call stack.
          161  +
          162  +Where an empty -unknown handler is given \(the default\), the ensemble command will generate an error message based on the list of commands that the ensemble has defined \(formatted similarly to the error message from _Tcl\_GetIndexFromObj\(\)_\).  This is the error that will be thrown when the subcommand is still not recognized during reparsing. It is also an error for an -unknown handler to delete its namespace.
   160    163   
   161         -When the result is a non-empty list, the words of that list are used to replace the ensemble command and subcommand, just as if they had been looked up in the -map.  It is up to the unknown handler to supply all namespace qualifiers if the implementing subcommand is not in the namespace of the caller of the ensemble command.  Also note that when ensemble commands are chained (e.g. if you make one of the commands that implement an ensemble subcommand into an ensemble, in a manner similar to the text widget's ''tag'' and ''mark'' subcommands) then the rewrite happens in the context of the caller of the outermost ensemble.  That is to say that ensembles do not in themselves place any namespace contexts on the Tcl call stack.
   162         -
   163         -Where an empty -unknown handler is given (the default), the ensemble command will generate an error message based on the list of commands that the ensemble has defined (formatted similarly to the error message from ''Tcl_GetIndexFromObj()'').  This is the error that will be thrown when the subcommand is still not recognized during reparsing. It is also an error for an -unknown handler to delete its namespace.
   164         -
   165         -~ Examples
          164  +# Examples
   166    165   
   167         -|namespace eval carrot {
   168         -|   namespace export foo bar potato
   169         -|   namespace ensemble create     ;# Creates command ::carrot
   170         -|
   171         -|   proc foo {} {puts 1}          ;# Exported
   172         -|   proc bar {} {puts 2}          ;# Exported
   173         -|   proc boo {} {puts 3}          ;# Not exported
   174         -|
   175         -|   namespace eval turnip {       ;# Not exported
   176         -|      namespace export alpha
   177         -|      proc alpha {} {puts 4}     ;# Exported
   178         -|      proc beta {} {puts 5}      ;# Not exported
   179         -|      namespace ensemble create
   180         -|   }
   181         -|
   182         -|   namespace eval potato {       ;# Exported
   183         -|      proc north {x} {puts 6,$x} ;# Not exported
   184         -|      proc south {x} {puts 7,$x} ;# Not exported
   185         -|      # Notice we resolve names locally, and Tcl metachars are not special
   186         -|      namespace ensemble create -map {
   187         -|         north {north [$meta[$chars}
   188         -|      }
   189         -|   }
   190         -|}
   191         -|
   192         -|
   193         -|carrot foo                       ;# Prints 1
   194         -|carrot bar                       ;# Prints 2
   195         -|carrot b                         ;# Also prints 2 ("boo" not exported)
   196         -|carrot ?                         ;# ERROR: Alternatives "bar", "foo" and "potato"
   197         -|carrot potato                    ;# ERROR: Missing argument
   198         -|carrot potato ?                  ;# ERROR: Try "north" instead
   199         -|carrot potato north              ;# Prints 6,[$meta[$chars
   200         -|carrot turnip alpha              ;# ERROR: "turnip" not known
   201         -|carrot::turnip alpha             ;# Prints 4
   202         -|carrot::turnip::beta             ;# Prints 5
   203         -|
   204         -|rename ::carrot::potato ::spud
   205         -|spud north                       ;# Prints 6,[$meta[$chars
   206         -|spud south                       ;# ERROR: "south" not known
   207         -|carrot potato north              ;# ERROR: No ::carrot::potato command
   208         -|# Reconfigure spud; notice we get different name resolution now!
   209         -|namespace ensemble configure spud -map {
   210         -|   north {puts NORTH} south {puts SOUTH}
   211         -|}
   212         -|spud north                       ;# Prints NORTH
   213         -|spud south                       ;# Prints SOUTH
   214         -|namespace delete carrot
   215         -|spud north                       ;# ERROR: spud command already deleted
   216         -|
   217         -|
   218         -|namespace eval A {
   219         -|   proc a args {puts A::a=>$args}
   220         -|}
   221         -|namespace eval B {
   222         -|   proc b args {puts B::b=>$args}
   223         -|}
   224         -|# Create an ensemble in the global namespace
   225         -|namespace ensemble create -command C -map {
   226         -|   eg1 {::A::a foo bar}
   227         -|   eg2 {::B::b 1 2 3}
   228         -|   eg3 ::string
   229         -|}
   230         -|C eg1 spong                      ;# Prints A::a=>foo bar spong
   231         -|C eg2 evil code {[exit]}         ;# Prints B::b=>1 2 3 evil code [exit]
   232         -|C eg3 length qwertyuiop          ;# Returns 10
   233         -|
   234         -|
   235         -|# An example demonstrating the use of -unknown to do delegation
   236         -|# This uses an ensemble to add a subcommand to a frame
   237         -|package require Tk
   238         -|rename [frame .f] _impl.f
   239         -|namespace ensemble create -command .f -unknown {delegate _impl.f} -map {
   240         -|   flash {flashFrame _impl.f}
   241         -|}
   242         -|# General delegation framework handler
   243         -|proc delegate {target ensemble subcmd args} {
   244         -|   # Read the current map
   245         -|   set map [namespace ensemble configure $ensemble -map]
   246         -|   # Update it to include the new subcommand
   247         -|   dict set map $subcmd [list $target $subcmd]
   248         -|   # Install back into the ensemble
   249         -|   namespace ensemble configure $ensemble -map $map
   250         -|   # Result is empty string, so we reparse
   251         -|   return {}
   252         -|}
   253         -|# Our new subcommand implementation
   254         -|proc flashFrame w {
   255         -|   set bg [$w cget -background]
   256         -|   foreach colour {black white black white black white} {
   257         -|      $w configure -background $colour
   258         -|      update idletasks
   259         -|      after 150
   260         -|   }
   261         -|   $w configure -background $bg
   262         -|}
          166  +	namespace eval carrot {
          167  +	   namespace export foo bar potato
          168  +	   namespace ensemble create     ;# Creates command ::carrot
          169  +	
          170  +	   proc foo {} {puts 1}          ;# Exported
          171  +	   proc bar {} {puts 2}          ;# Exported
          172  +	   proc boo {} {puts 3}          ;# Not exported
          173  +	
          174  +	   namespace eval turnip {       ;# Not exported
          175  +	      namespace export alpha
          176  +	      proc alpha {} {puts 4}     ;# Exported
          177  +	      proc beta {} {puts 5}      ;# Not exported
          178  +	      namespace ensemble create
          179  +	   }
          180  +	
          181  +	   namespace eval potato {       ;# Exported
          182  +	      proc north {x} {puts 6,$x} ;# Not exported
          183  +	      proc south {x} {puts 7,$x} ;# Not exported
          184  +	      # Notice we resolve names locally, and Tcl metachars are not special
          185  +	      namespace ensemble create -map {
          186  +	         north {north [$meta[$chars}
          187  +	      }
          188  +	   }
          189  +	}
          190  +	
          191  +	
          192  +	carrot foo                       ;# Prints 1
          193  +	carrot bar                       ;# Prints 2
          194  +	carrot b                         ;# Also prints 2 ("boo" not exported)
          195  +	carrot ?                         ;# ERROR: Alternatives "bar", "foo" and "potato"
          196  +	carrot potato                    ;# ERROR: Missing argument
          197  +	carrot potato ?                  ;# ERROR: Try "north" instead
          198  +	carrot potato north              ;# Prints 6,[$meta[$chars
          199  +	carrot turnip alpha              ;# ERROR: "turnip" not known
          200  +	carrot::turnip alpha             ;# Prints 4
          201  +	carrot::turnip::beta             ;# Prints 5
          202  +	
          203  +	rename ::carrot::potato ::spud
          204  +	spud north                       ;# Prints 6,[$meta[$chars
          205  +	spud south                       ;# ERROR: "south" not known
          206  +	carrot potato north              ;# ERROR: No ::carrot::potato command
          207  +	# Reconfigure spud; notice we get different name resolution now!
          208  +	namespace ensemble configure spud -map {
          209  +	   north {puts NORTH} south {puts SOUTH}
          210  +	}
          211  +	spud north                       ;# Prints NORTH
          212  +	spud south                       ;# Prints SOUTH
          213  +	namespace delete carrot
          214  +	spud north                       ;# ERROR: spud command already deleted
          215  +	
          216  +	
          217  +	namespace eval A {
          218  +	   proc a args {puts A::a=>$args}
          219  +	}
          220  +	namespace eval B {
          221  +	   proc b args {puts B::b=>$args}
          222  +	}
          223  +	# Create an ensemble in the global namespace
          224  +	namespace ensemble create -command C -map {
          225  +	   eg1 {::A::a foo bar}
          226  +	   eg2 {::B::b 1 2 3}
          227  +	   eg3 ::string
          228  +	}
          229  +	C eg1 spong                      ;# Prints A::a=>foo bar spong
          230  +	C eg2 evil code {[exit]}         ;# Prints B::b=>1 2 3 evil code [exit]
          231  +	C eg3 length qwertyuiop          ;# Returns 10
          232  +	
          233  +	
          234  +	# An example demonstrating the use of -unknown to do delegation
          235  +	# This uses an ensemble to add a subcommand to a frame
          236  +	package require Tk
          237  +	rename [frame .f] _impl.f
          238  +	namespace ensemble create -command .f -unknown {delegate _impl.f} -map {
          239  +	   flash {flashFrame _impl.f}
          240  +	}
          241  +	# General delegation framework handler
          242  +	proc delegate {target ensemble subcmd args} {
          243  +	   # Read the current map
          244  +	   set map [namespace ensemble configure $ensemble -map]
          245  +	   # Update it to include the new subcommand
          246  +	   dict set map $subcmd [list $target $subcmd]
          247  +	   # Install back into the ensemble
          248  +	   namespace ensemble configure $ensemble -map $map
          249  +	   # Result is empty string, so we reparse
          250  +	   return {}
          251  +	}
          252  +	# Our new subcommand implementation
          253  +	proc flashFrame w {
          254  +	   set bg [$w cget -background]
          255  +	   foreach colour {black white black white black white} {
          256  +	      $w configure -background $colour
          257  +	      update idletasks
          258  +	      after 150
          259  +	   }
          260  +	   $w configure -background $bg
          261  +	}
   263    262   
   264         -~ Consequences
          263  +# Consequences
   265    264   
   266    265   Many commands in both Tcl and Tk would benefit from leveraging this,
   267    266   and it would enable straight-forward implementations of things like
   268         -[65] in pure Tcl code.  It would also make doing things like partial
          267  +[[65]](65.md) in pure Tcl code.  It would also make doing things like partial
   269    268   exposure of ensemble-like commands in safe interpreters much easier.
   270    269   
   271         -~ Sample Implementation
          270  +# Sample Implementation
   272    271   
   273         -http://sf.net/tracker/?func=detail&aid=786509&group_id=10894&atid=310894
          272  +<http://sf.net/tracker/?func=detail&aid=786509&group\_id=10894&atid=310894>
   274    273   
   275         -~ Copyright
          274  +# Copyright
   276    275   
   277    276   This document has been placed in the public domain.
   278    277   
   279         -~ Acknowledgements
          278  +# Acknowledgements
   280    279   
   281    280   Thanks very much to Joe English, Don Porter and Kevin Kenny for their
   282    281   suggestions in the development of this TIP.  Without them, it would have
   283    282   been a far worse suggestion.  And thanks to Will Duquette for writing a
   284         -piece of software (Snit) that would benefit immensely from pushing the
   285         -ensemble stuff as hard as possible and then a bit.  :^)
          283  +piece of software \(Snit\) that would benefit immensely from pushing the
          284  +ensemble stuff as hard as possible and then a bit.  :^\)
          285  +

Name change from tip/113.tip to tip/113.md.

     1         -TIP:            113
     2         -Title:          Multi-Line Searches in the Text Widget
     3         -Version:        $Revision: 1.13 $
     4         -Author:         Vince Darley <vincentdarley@users.sourceforge.net>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        11-Oct-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 113: Multi-Line Searches in the Text Widget
            2  +	Author:         Vince Darley <vincentdarley@users.sourceforge.net>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        11-Oct-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -This TIP proposes enhancing the implementation of the ''$textwidget
    15         -search'' subcommand to allow matching of both exact strings and regexp
           13  +This TIP proposes enhancing the implementation of the _$textwidget
           14  +search_ subcommand to allow matching of both exact strings and regexp
    16     15   patterns which span multiple lines, and to allow reporting on all matches.
    17     16   
    18         -~ Proposal
           17  +# Proposal
    19     18   
    20         -If the string/pattern given to the ''search'' subcommand contains
           19  +If the string/pattern given to the _search_ subcommand contains
    21     20   sub-strings/patterns which match newlines, then it will be possible
    22     21   for that command to return a match which spans multiple lines.  Where
    23     22   a match could occur both within a single line and across multiple
    24     23   lines, the first such match will be found, and the length of the match
    25     24   will follow the usual regexp rules, as documented in the regexp man
    26         -page.  Since the text widget is inherently a line-based container of text, regexp searches will implicitly use the regexp ''-line'' functionality so that ''^'', ''$'' matching beginning and end of any line, and ''.'', ''[^'' will not match a newline (but see the ''-nolinestop'' flag to turn off the latter behaviour).
           25  +page.  Since the text widget is inherently a line-based container of text, regexp searches will implicitly use the regexp _-line_ functionality so that _^_, _$_ matching beginning and end of any line, and _._, _[^_ will not match a newline \(but see the _-nolinestop_ flag to turn off the latter behaviour\).
    27     26   
    28     27   This can be implemented very efficiently, given
    29         -the ''TCL_REG_CANMATCH'' flag supported by the regexp library, with no
           28  +the _TCL\_REG\_CANMATCH_ flag supported by the regexp library, with no
    30     29   impact at all on the speed of matching single lines.
    31     30   
    32         -In addition, two new options to the ''search'' subcommand are available:
           31  +In addition, two new options to the _search_ subcommand are available:
    33     32   
    34         -If the new ''-all'' option is given to the ''search'' subcommand, then all matches within the given range will be reported. This means the return result of the command will be a list of indices, and, if a ''-count var'' option was given, ''var'' will be set to a list of match-index-lengths.
           33  +If the new _-all_ option is given to the _search_ subcommand, then all matches within the given range will be reported. This means the return result of the command will be a list of indices, and, if a _-count var_ option was given, _var_ will be set to a list of match-index-lengths.
    35     34   
    36         -If the new ''-nolinestop'' option is given then regexp searches will allow ''.'' and ''[^'' sequences to match newline characters (which is normally not the case).  This is equivalent to ''not'' providing the ''-linestop'' flag to Tcl's ''regexp'' command.
           35  +If the new _-nolinestop_ option is given then regexp searches will allow _._ and _[^_ sequences to match newline characters \(which is normally not the case\).  This is equivalent to _not_ providing the _-linestop_ flag to Tcl's _regexp_ command.
           36  +
           37  +The text widget man page will be updated to reflect the new _-all_ and _-nolinestop_ options, and to remove the "single line" caveat.
    37     38   
    38         -The text widget man page will be updated to reflect the new ''-all'' and ''-nolinestop'' options, and to remove the "single line" caveat.
    39         -
    40         -~ Reference implementation
           39  +# Reference implementation
    41     40   
    42     41   This is available from:
    43     42   
    44         -http://sourceforge.net/tracker/?func=detail&aid=621901&group_id=12997&atid=312997
           43  +<http://sourceforge.net/tracker/?func=detail&aid=621901&group\_id=12997&atid=312997>
    45     44   
    46         -The patch includes objectification of the entire Text widget, so the multi-line search changes are not obvious to isolate.  In fact the changes required are < 100 lines of code (given that the rest has been objectified, that is).  Of course one nice side-effect of objectification is that regexp objects used in searches are actually cached, which they previously couldn't be.
           45  +The patch includes objectification of the entire Text widget, so the multi-line search changes are not obvious to isolate.  In fact the changes required are < 100 lines of code \(given that the rest has been objectified, that is\).  Of course one nice side-effect of objectification is that regexp objects used in searches are actually cached, which they previously couldn't be.
    47     46   
    48     47   Note: this patch has to workaround a crashing bug in Tcl's unicode string manipulation.  It would be best if that bug was fixed before applying this patch.
    49     48   
    50         -~ Issues
           49  +# Issues
    51     50   
    52     51   On the implementation side, it might be interesting to abstract the search interface away from the text widget, so that it could in principle be applied to any line-based textual source.
    53     52   
    54         -As in the single-line matching implementation in Tcl 8.x, the lack of support for backwards matching in Tcl's regexp library means that backwards matching can only be implemented as repeated forward matches, with a commensurate performance penalty (the solution to which is outside the scope of this tip).
           53  +As in the single-line matching implementation in Tcl 8.x, the lack of support for backwards matching in Tcl's regexp library means that backwards matching can only be implemented as repeated forward matches, with a commensurate performance penalty \(the solution to which is outside the scope of this tip\).
    55     54   
    56         -Tk has a curious misfeature that ''$text search -regexp "\n" $pos'' will always fail to match anything. This behaviour will change as a result of this TIP (it will match the first newline after ''$pos''), and any code which somehow depended on that peculiarity will therefore break.
           55  +Tk has a curious misfeature that _$text search -regexp "\\n" $pos_ will always fail to match anything. This behaviour will change as a result of this TIP \(it will match the first newline after _$pos_\), and any code which somehow depended on that peculiarity will therefore break.
    57     56   
    58         -~ Copyright
           57  +# Copyright
    59     58   
    60     59   This document has been placed in the public domain.
           60  +

Name change from tip/114.tip to tip/114.md.

     1         -TIP:            114
     2         -Title:          Eliminate Octal Parsing of Leading Zero Integer Strings
     3         -Author:         Don Porter <dgp@users.sf.net>
     4         -Created:        16-Oct-2007
     5         -Type:           Project
     6         -State:          Draft
     7         -Vote:           Done
     8         -Version:        $Revision: 2.3 $
     9         -Tcl-Version:    9.0
    10         -Post-History:   
    11         -Keywords:       octal
            1  +# TIP 114: Eliminate Octal Parsing of Leading Zero Integer Strings
            2  +	Author:         Don Porter <dgp@users.sf.net>
            3  +	Created:        16-Oct-2007
            4  +	Type:           Project
            5  +	State:          Draft
            6  +	Vote:           Done
            7  +	Tcl-Version:    9.0
            8  +	Post-History:   
            9  +	Keywords:       octal
           10  +-----
    12     11   
    13         -~Abstract
           12  +# Abstract
    14     13   
    15     14   This TIP proposes elimination of Tcl's practice of using octal
    16     15   notation to interpret a string with a leading zero when an
    17     16   integer value is expected.
    18     17   
    19         -~History and Rationale
           18  +# History and Rationale
    20     19   
    21     20   There are several places in the syntax of several Tcl commands
    22     21   where an integer value may be accepted.  Routines such as
    23         -'''Tcl_GetInt()''' perform the task of parsing an integer value
           22  +**Tcl\_GetInt\(\)** perform the task of parsing an integer value
    24     23   from the string value in these places.  Ultimately, these routines
    25     24   have been built on C standard library functions such as
    26         -'''strtol()'''.  Due to this implementation choice, Tcl integer
    27         -parsing has inherited features from '''strtol()''' including
           25  +**strtol\(\)**.  Due to this implementation choice, Tcl integer
           26  +parsing has inherited features from **strtol\(\)** including
    28     27   the feature that a leading zero in a string has been taken
    29     28   as a signal that the string is an integer value in octal format.
    30     29   
    31     30   Several programmers and programs have hit this feature by
    32     31   surprise, resulting in nasty bugs such as:
    33     32   
    34         -| % proc m date {
    35         -|      lassign [split $date -] y m d
    36         -|      return [string index _JFMAMJJASOND $m]
    37         -|   }
    38         -| % m 2007-02-14
    39         -| F
    40         -| % m 2007-12-25
    41         -| D
    42         -| % m 2007-09-26
    43         -| bad index "09": must be integer?[+-]integer? or end?[+-]integer? (looks like invalid octal number)
           33  +	 % proc m date {
           34  +	      lassign [split $date -] y m d
           35  +	      return [string index _JFMAMJJASOND $m]
           36  +	   }
           37  +	 % m 2007-02-14
           38  +	 F
           39  +	 % m 2007-12-25
           40  +	 D
           41  +	 % m 2007-09-26
           42  +	 bad index "09": must be integer?[+-]integer? or end?[+-]integer? (looks like invalid octal number)
    44     43   
    45     44   There are very few places in Tcl scripts where this feature
    46     45   is actually useful.  Octal format for integers simply isn't
    47     46   encountered all that often in most programming tasks tackled by
    48     47   Tcl scripts.  The main counterexample is the use of octal format
    49     48   integers to describe filesystem permissions on unix systems.
    50     49   The Tcl commands that operate on filesystem permission values
    51         -are '''open''' and '''file attributes''', and it is a simple matter
           50  +are **open** and **file attributes**, and it is a simple matter
    52     51   to directly code them to recognize octal format, rather that have
    53     52   then rely on octal parsing as a general integer value recognition
    54     53   feature.  On the HEAD, these commands have already been so revised.
    55     54   With those few cases accounted for, it's been observed that
    56     55   removing this feature of Tcl integer parsing "will likely fix
    57     56   more scripts than it breaks."
    58     57   
    59     58   The opportunity to make this change in Tcl 8.5 arises because
    60     59   we've already replaced our old parsing routines based on
    61         -'''strtol()'''  with our own number parser [249].
           60  +**strtol\(\)**  with our own number parser [[249]](249.md).
    62     61   
    63         -~ Proposal
           62  +# Proposal
    64     63   
    65     64   Revise all integer parsing in Tcl by making modifications to
    66         -the '''TclParseNumber()''' routine.  With reference to the
    67         -state machine graph in [249], we change the exit edges of
    68         -state ''integer[[1]]''.  Characters '''0''' - '''7''' and
    69         -characters '''8''' - '''9''' should now lead to state ''integer[[4]]'',
           65  +the **TclParseNumber\(\)** routine.  With reference to the
           66  +state machine graph in [[249]](249.md), we change the exit edges of
           67  +state _integer[[1]](1.md)_.  Characters **0** - **7** and
           68  +characters **8** - **9** should now lead to state _integer[[4]](4.md)_,
    70     69   so that they continue decimal parsing, and not octal parsing.
    71         -The states ''integer[[2]]'' and ''error[[5]]'' will now be
    72         -accessible only if the character '''o''' or '''O''' is seen
    73         -while in state ''integer[[1]]'' and there will no longer be
    74         -any exit from those states when the characters '''.''' or '''e'''
    75         -or '''E''' are observed.
           70  +The states _integer[[2]](2.md)_ and _error[[5]](5.md)_ will now be
           71  +accessible only if the character **o** or **O** is seen
           72  +while in state _integer[[1]](1.md)_ and there will no longer be
           73  +any exit from those states when the characters **.** or **e**
           74  +or **E** are observed.
    76     75   
    77         -This change to '''TclParseNumber()''' is achieved with a
    78         -'''#define KILL_OCTAL''' in the file ''tclStrToD.c''.
           76  +This change to **TclParseNumber\(\)** is achieved with a
           77  +**\#define KILL\_OCTAL** in the file _tclStrToD.c_.
    79     78   
    80         -~ Compatibility
           79  +# Compatibility
    81     80   
    82     81   This change is an incompatibility.  It's long
    83     82   been believed that such a change should not happen until Tcl 9
    84     83   because of this, but over time the consensus belief has developed
    85     84   that far fewer programs and programmers will be harmed by the
    86     85   incompatibility than will be helped by removing the misfeature.
    87     86   
    88     87   That said, the incompatibility is serious.  The same string in
    89     88   the same place in a script can now have a completely different
    90     89   meaning.  Before the change:
    91     90   
    92         -| % lindex {a b c d e f g h i j k} 010
    93         -| i
           91  +	 % lindex {a b c d e f g h i j k} 010
           92  +	 i
    94     93   
    95     94   After the change:
    96     95   
    97         -| % lindex {a b c d e f g h i j k} 010
    98         -| k
           96  +	 % lindex {a b c d e f g h i j k} 010
           97  +	 k
    99     98   
   100     99   This is not the usual situation where new feature causes scripts
   101    100   that were an error to become non-errors -- a compatible change.
   102    101   
   103    102   This is also not a situation where a change causes legal scripts
   104    103   to become errors.  Such a change would break scripts, but would
   105    104   at least leave behind scripts that raise noisy errors alerting
   106    105   about the breakage.
   107    106   
   108    107   This is the most serious kind of incompatibility, where we replace
   109    108   a working script with another working script that does something
   110    109   completely different.  An illustration of the problem from Tcl's
   111    110   own test suite highlights the danger.  Some of Tcl's tests in
   112         -'''io.test''' depend on the umask value, so that value is captured:
          111  +**io.test** depend on the umask value, so that value is captured:
   113    112   
   114         -| set umaskValue [exec /bin/sh -c umask]
          113  +	 set umaskValue [exec /bin/sh -c umask]
   115    114   
   116         -Note that the shell command '''umask''' returns a mask value as
          115  +Note that the shell command **umask** returns a mask value as
   117    116   an integer in octal format.  The test suite has relied on Tcl's
   118    117   built-in ability to recognize this format, and the expected
   119         -result of test '''io-40.3''' has been computed:
          118  +result of test **io-40.3** has been computed:
   120    119   
   121         -| format %04o [expr {0666 & ~$umaskValue}]
          120  +	 format %04o [expr {0666 & ~$umaskValue}]
   122    121   
   123         -After the proposed change, ''$umaskValue'' is treated as a decimal
   124         -number, and the wrong expected result is computed.  (This test
   125         -has already been updated on the HEAD to avoid such problems.)
          122  +After the proposed change, _$umaskValue_ is treated as a decimal
          123  +number, and the wrong expected result is computed.  \(This test
          124  +has already been updated on the HEAD to avoid such problems.\)
   126    125   
   127    126   It is not difficult to imagine more serious problems in scripts
   128         -that make use of the result returned by the shell command '''umask'''
          127  +that make use of the result returned by the shell command **umask**
   129    128   where a file might be created or modified with completely unintended
   130    129   permissions as a result of the proposed change.  Such scripts
   131    130   might easily raise security concerns.
   132    131   
   133         -Even in the light of the judgment that such (hopefully rare) compatibility
          132  +Even in the light of the judgment that such \(hopefully rare\) compatibility
   134    133   issues are acceptable in exchange for the benefits of purging the
   135    134   misfeature, we really ought to consider seriously how we can alert
   136    135   those migrating to Tcl 8.5 to this possibility and to the need to
   137    136   examine their scripts for this issue.
   138    137   
   139    138   Besides the impact on Tcl commands, this change may also cause
   140    139   incompatibilities in extensions, to the extent their commands
   141    140   rely on Tcl's integer parsing to support octal notation.
   142    141   
   143         -~ Rejected Alternatives
          142  +# Rejected Alternatives
   144    143   
   145    144   Motivated largely by the serious incompatibilities lurking here,
   146    145   a few people have suggested that some means be provided to toggle
   147    146   Tcl's integer parsing behavior between two modes, one which
   148    147   recognizes octal and one which does not.  This idea appears inspired
   149         -in part by the '''::tcl_precision''' variable, which has long
          148  +in part by the **::tcl\_precision** variable, which has long
   150    149   exercised control over Tcl's floating point number formatting.
   151    150   
   152    151   While the motivation may be well-intended, this proposal is basically
   153    152   unworkable, and can't really help anybody.  The point of the proposed
   154    153   change is to make simple code work as simple coders expect it to.
   155    154   Our original example proc can already be corrected like so:
   156    155   
   157         -| proc m date {
   158         -|    scan $date %d-%d-%d y m d
   159         -|    return [string index _JFMAMJJASOND $m]
   160         -| }
          156  +	 proc m date {
          157  +	    scan $date %d-%d-%d y m d
          158  +	    return [string index _JFMAMJJASOND $m]
          159  +	 }
   161    160   
   162    161   The point of this proposal is to make the original code just work.
   163    162   It doesn't help to offer this complexity as a solution:
   164    163   
   165         -| % proc m date {
   166         -|      set mode [tcl::unsupported::octal]
   167         -|      tcl::unsupported::octal off
   168         -|      lassign [split $date -] y m d
   169         -|      set result [string index _JFMAMJJASOND $m]
   170         -|      tcl::unsupported::octal $mode
   171         -|      return $result
   172         -|   }
          164  +	 % proc m date {
          165  +	      set mode [tcl::unsupported::octal]
          166  +	      tcl::unsupported::octal off
          167  +	      lassign [split $date -] y m d
          168  +	      set result [string index _JFMAMJJASOND $m]
          169  +	      tcl::unsupported::octal $mode
          170  +	      return $result
          171  +	   }
   173    172   
   174    173   No one would choose that over just fixing the code
   175         -to use '''scan''', in which case this proposal won't be needed.
          174  +to use **scan**, in which case this proposal won't be needed.
   176    175   Also, this kind of management of a shared mode setting cannot
   177         -(easily and cheaply) be avoided, because at the point we need
          176  +\(easily and cheaply\) be avoided, because at the point we need
   178    177   to control the Tcl number parser, the most specific context
   179    178   we have is the thread, so the mode has to be set thread-wide.
   180    179   
   181         -Likewise, the (hopefully rare) set of scripts that would actually
          180  +Likewise, the \(hopefully rare\) set of scripts that would actually
   182    181   want to turn octal parsing back on are not going to announce themselves.
   183    182   In order to know that 
   184    183   
   185         -| tcl::unsupported::octal on
          184  +	 tcl::unsupported::octal on
   186    185   
   187    186   needs to be added to a script to make it function correctly,
   188    187   some kind of audit has to reach that conclusion, and once that
   189    188   conclusion is reached and the issues are understood, it's just
   190         -as easy to insert '''scan %o''' in the proper places as it would
   191         -be to insert the '''tcl::unsupported::octal''' stopgap.
          189  +as easy to insert **scan %o** in the proper places as it would
          190  +be to insert the **tcl::unsupported::octal** stopgap.
   192    191   
   193    192   In short, any coder finding themselves in a position to consider
   194         -using a '''tcl::unsupported::octal''' tool, would quickly decide
          193  +using a **tcl::unsupported::octal** tool, would quickly decide
   195    194   not to use it in favor of just fixing their code.  Thus users
   196    195   of this feature are mythical, and it will not be implemented.
   197    196   
   198         -~ Note
          197  +# Note
   199    198   
   200         -This TIP has been ''explicitly'' rejected as a feature for Tcl 8.5.
          199  +This TIP has been _explicitly_ rejected as a feature for Tcl 8.5.
   201    200   Consensus was that the type of breakage it inherently induces is not
   202    201   acceptable in a minor version change.
   203    202   
   204         -~Copyright
          203  +# Copyright
   205    204   
   206    205   This document is placed in the public domain.
          206  +

Name change from tip/115.tip to tip/115.md.

     1         -TIP:            115
     2         -Title:          Making Tcl Truly 64-Bit Ready
     3         -Version:        $Revision: 1.3 $
     4         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     5         -State:          Draft
     6         -Type:           Project
     7         -Vote:           Pending
     8         -Created:        23-Oct-2002
     9         -Post-History:   
    10         -Tcl-Version:    9.0
            1  +# TIP 115: Making Tcl Truly 64-Bit Ready
            2  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            3  +	State:          Draft
            4  +	Type:           Project
            5  +	Vote:           Pending
            6  +	Created:        23-Oct-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    9.0
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP proposes changes to Tcl to make it operate more effectively
    15     14   on 64-bit systems.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19     18   It is a fact of life that 64-bit platforms are becoming more common.
    20     19   While once the assumption that virtually everything was a 32-bit
    21         -machine (where not smaller) was valid, this is no longer the case.
    22         -Particularly on modern supercomputers (though increasingly in
    23         -workstations and high-end desktop systems too), the amount of memory
           20  +machine \(where not smaller\) was valid, this is no longer the case.
           21  +Particularly on modern supercomputers \(though increasingly in
           22  +workstations and high-end desktop systems too\), the amount of memory
    24     23   that the machine contains is exceeding 2GB, and the need to address
    25     24   very large amounts of memory is certainly there in scientific and
    26     25   engineering applications.  And where they lead, consumer systems will
    27     26   probably follow too.
    28     27   
    29     28   At the moment, Tcl is ill-prepared for this.  In particular, the type
    30         -used for expressing sizes of entities in Tcl (whether strings, lists
    31         -or undifferentiated blocks of memory) is ''int'' (and cannot be made
    32         -into an ''unsigned int'' in most of those places where it is not
    33         -already an unsigned value) but on the majority of 64-bit platforms
           29  +used for expressing sizes of entities in Tcl \(whether strings, lists
           30  +or undifferentiated blocks of memory\) is _int_ \(and cannot be made
           31  +into an _unsigned int_ in most of those places where it is not
           32  +already an unsigned value\) but on the majority of 64-bit platforms
    34     33   this is still a 32-bit type, which is a major restriction.  However,
    35         -on the vast majority of those platforms ''long'' is a 64-bit type, and
    36         -so a suitable replacement.  (The exceptions to this are the Alpha - but
    37         -that is unusual in that both ''int'' and ''long'' are 64-bit types
           34  +on the vast majority of those platforms _long_ is a 64-bit type, and
           35  +so a suitable replacement.  \(The exceptions to this are the Alpha - but
           36  +that is unusual in that both _int_ and _long_ are 64-bit types
    38     37   there, meaning that the platform will be unaffected by such an
    39         -alteration - and Win64, which has a 32-bit ''long'' but 64-bit
    40         -pointers.)
           38  +alteration - and Win64, which has a 32-bit _long_ but 64-bit
           39  +pointers.\)
    41     40   
    42     41   Luckily, standards like POSIX have already been dealing with this
    43         -problem before us, and the types ''size_t'' (which is unsigned) and
    44         -''ssize_t'' (which is signed) exist for the sorts of uses we're
    45         -interested in (i.e. they are both the same size as each other, and
    46         -''size_t'' is large enough to describe the size of any allocatable
    47         -memory chunk.)
           42  +problem before us, and the types _size\_t_ \(which is unsigned\) and
           43  +_ssize\_t_ \(which is signed\) exist for the sorts of uses we're
           44  +interested in \(i.e. they are both the same size as each other, and
           45  +_size\_t_ is large enough to describe the size of any allocatable
           46  +memory chunk.\)
    48     47   
    49         -~ Details of Changes
           48  +# Details of Changes
    50     49   
    51     50   The key changes will be to change the lengths of the following types
    52         -from ''int'' to ''ssize_t'' in all appropriate places, and ''unsigned
    53         -int'' to ''size_t'' likewise (mainly in memory allocation routines.)
           51  +from _int_ to _ssize\_t_ in all appropriate places, and _unsigned
           52  +int_ to _size\_t_ likewise \(mainly in memory allocation routines.\)
    54     53   
    55         - * ''Tcl_Obj'' - the ''length'' member.  (Potentially the ''refCount''
    56         -   member needs updating as well, but that's less critical.)
           54  + * _Tcl\_Obj_ - the _length_ member.  \(Potentially the _refCount_
           55  +   member needs updating as well, but that's less critical.\)
    57     56   
    58         - * ''Tcl_SavedResult'' - the ''appendAvl'' and ''appendUsed'' members.
           57  + * _Tcl\_SavedResult_ - the _appendAvl_ and _appendUsed_ members.
    59     58   
    60         - * ''Tcl_DString'' - the ''length'' and ''spaceAvl'' members.
           59  + * _Tcl\_DString_ - the _length_ and _spaceAvl_ members.
    61     60   
    62         - * ''Tcl_Token'' - the ''size'' and ''numComponents'' members.
           61  + * _Tcl\_Token_ - the _size_ and _numComponents_ members.
    63     62   
    64         - * ''Tcl_Parse'' - the ''commentSize'', ''commandSize'', numWords'',
    65         -   ''numTokens'' and ''tokensAvailable'' members.
           63  + * _Tcl\_Parse_ - the _commentSize_, _commandSize_, numWords_,
           64  +   _numTokens_ and _tokensAvailable_ members.
    66     65   
    67         - * ''CompiledLocal'' - the ''nameLength'' member.
           66  + * _CompiledLocal_ - the _nameLength_ member.
    68     67   
    69         - * ''Interp'' - the ''appendAvl'', ''appendUsed'' and ''termOffset''
           68  + * _Interp_ - the _appendAvl_, _appendUsed_ and _termOffset_
    70     69      members.
    71     70   
    72         - * ''List'' - the ''maxElemCount'' and ''elemCount'' members.
           71  + * _List_ - the _maxElemCount_ and _elemCount_ members.
    73     72   
    74         - * ''ByteArray'' - the ''used'' and ''allocated'' members.
           73  + * _ByteArray_ - the _used_ and _allocated_ members.
    75     74   
    76         - * ''SortElement'' - the ''count'' member.
           75  + * _SortElement_ - the _count_ member.
    77     76   
    78         - * ''SortInfo'' - the ''index'' member.
           77  + * _SortInfo_ - the _index_ member.
    79     78   
    80         - * ''CopyState'' - the ''toRead'' and ''total'' members.
           79  + * _CopyState_ - the _toRead_ and _total_ members.
    81     80   
    82         - * ''GetsState'' - the ''rawRead'', ''bytesWrote'', ''charsWrote'' and
    83         -   ''totalChars'' members.
           81  + * _GetsState_ - the _rawRead_, _bytesWrote_, _charsWrote_ and
           82  +   _totalChars_ members.
    84     83   
    85         - * ''ParseInfo'' - the ''size'' member.
           84  + * _ParseInfo_ - the _size_ member.
    86     85   
    87         - * ''String'' - the ''numChars'' member (see also the ''TestString''
    88         -   structure.)
           86  + * _String_ - the _numChars_ member \(see also the _TestString_
           87  +   structure.\)
    89     88   
    90     89   Changes to the bytecode-related structures might be worthwhile doing
    91     90   too, though there are more backward-compatibility issues there.
    92     91   
    93     92   These changes will force many of the types used in the public API to
    94     93   change as well.  Notable highlights:
    95     94   
    96         - * ''Tcl_Alloc'' will now take an ''size_t''.
           95  + * _Tcl\_Alloc_ will now take an _size\_t_.
           96  +
           97  + * _Tcl\_GetByteArrayFromObj_ will now take a pointer to a _ssize\_t_.
    97     98   
    98         - * ''Tcl_GetByteArrayFromObj'' will now take a pointer to a ''ssize_t''.
           99  + * _Tcl\_GetStringFromObj_ will now take a pointer to a _ssize\_t_.
    99    100   
   100         - * ''Tcl_GetStringFromObj'' will now take a pointer to a ''ssize_t''.
          101  + * _Tcl\_ListObjLength_ will now take a pointer to a _ssize\_t_.
   101    102   
   102         - * ''Tcl_ListObjLength'' will now take a pointer to a ''ssize_t''.
   103         -
   104         - * ''Tcl_GetUnicodeFromObj'' will now take a pointer to a ''ssize_t''.
          103  + * _Tcl\_GetUnicodeFromObj_ will now take a pointer to a _ssize\_t_.
   105    104   
   106    105   In the internal API, the following notable change will happen:
   107    106   
   108         - * ''TclGetIntForIndex'' will now take a pointer to a ''ssize_t''.
          107  + * _TclGetIntForIndex_ will now take a pointer to a _ssize\_t_.
   109    108   
   110    109   There are probably other similar API changes required.
   111    110   
   112         -~ What This TIP Does Not Do
          111  +# What This TIP Does Not Do
   113    112   
   114    113   This TIP does not rearrange structure orderings.  Although this would
   115         -be very useful for some common structures (notably ''Tcl_Obj'') if the
          114  +be very useful for some common structures \(notably _Tcl\_Obj_\) if the
   116    115   common arithmetic types were smaller than the word size, it turns out
   117    116   that the changes in types required to deal with larger entities will
   118    117   make these rearrangements largely unnecessary and/or pointless.
   119         -(Inefficiency in statically-allocated structures won't matter as the
          118  +\(Inefficiency in statically-allocated structures won't matter as the
   120    119   number of instances will remain comparatively small, even in very
   121         -large programs.)  Once the changes are applied, there is typically at
   122         -most a single ''int'' field per structure, usually holding either a
          120  +large programs.\)  Once the changes are applied, there is typically at
          121  +most a single _int_ field per structure, usually holding either a
   123    122   reference count, a set of flags, or a Tcl result code.
   124    123   
   125    124   It should also be noted that all structures are always going to be
   126    125   correctly aligned internally as we never use C's bitfield support, so
   127    126   structure alignment is purely an issue of efficiency, and not of correct
   128    127   access to the fields.
   129    128   
   130         -~ Copyright
          129  +# Copyright
   131    130   
   132    131   This document has been placed in the public domain.
          132  +

Name change from tip/116.tip to tip/116.md.

     1         -TIP:            116
     2         -Title:          More Safety for Large Images
     3         -Version:        $Revision: 1.6 $
     4         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        28-Oct-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 116: More Safety for Large Images
            2  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        28-Oct-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP alters the C API for Tk's images so that failures to allocate
    15     14   sufficient memory for a large image can be handled more gracefully
    16         -than a straight ''panic()''.
           15  +than a straight _panic\(\)_.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20     19   Tk's image mechanism is nice and flexible, but it can run into
    21     20   problems with a large image.  If we consider a square image that is
    22         -2000 pixels on each side (such sizes of images are becoming more
           21  +2000 pixels on each side \(such sizes of images are becoming more
    23     22   common with the increasing popularity and sophistication of digital
    24         -photography), we find it requires about 16MB of memory to load (4
    25         -million pixels, four bytes per pixel) but obviously just because an
    26         -application fails to load that image (or something even larger), it
    27         -doesn't mean that the best course of action is a ''panic()''-induced
           23  +photography\), we find it requires about 16MB of memory to load \(4
           24  +million pixels, four bytes per pixel\) but obviously just because an
           25  +application fails to load that image \(or something even larger\), it
           26  +doesn't mean that the best course of action is a _panic\(\)_-induced
    28     27   crash.  Instead, a graceful failure back to the Tcl interpreter would
    29     28   allow for scripts to find a way to report this low-memory situation in
    30     29   a way that users can understand.
    31     30   
    32     31   The problem with this is that for many of the routes through the Tk
    33     32   image API, there is no way to report a memory allocation failure;
    34     33   currently, the only failure mode is total.  This TIP changes this.
    35     34   
    36         -~ Proposed Changes
           35  +# Proposed Changes
    37     36   
    38     37   I propose making the following functions that currently return
    39         -''void'' return ''int'' instead and that they should additionally take
    40         -a standard ''Tcl_Interp *interp'' argument to allow an error message
    41         -describing the failure (currently only due to insufficient memory) to
           38  +_void_ return _int_ instead and that they should additionally take
           39  +a standard _Tcl\_Interp \*interp_ argument to allow an error message
           40  +describing the failure \(currently only due to insufficient memory\) to
    42     41   be added to the current interpreter.  It will not be an error for the
    43         -''interp'' argument to be ''NULL'', though it will be up to the caller
           42  +_interp_ argument to be _NULL_, though it will be up to the caller
    44     43   to guess why the failure happened.
    45     44   
    46         - * ''Tk_PhotoExpand'' will become:
           45  + * _Tk\_PhotoExpand_ will become:
    47     46   
    48         -|int
    49         -|Tk_PhotoExpand(Tcl_Interp *interp, Tk_PhotoHandle handle,
    50         -|               int width, int height)
           47  +		int
           48  +		Tk_PhotoExpand(Tcl_Interp *interp, Tk_PhotoHandle handle,
           49  +		               int width, int height)
           50  +
           51  + * _Tk\_PhotoPutBlock_ will become:
           52  +
           53  +		int
           54  +		Tk_PhotoPutBlock(Tcl_Interp *interp, Tk_PhotoHandle handle,
           55  +		                 Tk_PhotoImageBlock *blockPtr,
           56  +		                 int x, int y, int width, int height, int compRule)
           57  +
           58  + * _Tk\_PhotoPutZoomedBlock_ will become:
    51     59   
    52         - * ''Tk_PhotoPutBlock'' will become:
           60  +		int
           61  +		Tk_PhotoPutZoomedBlock(Tcl_Interp *interp, Tk_PhotoHandle handle,
           62  +		                       Tk_PhotoImageBlock *blockPtr,
           63  +		                       int x, int y, int width, int height,
           64  +		                       int zoomX, int zoomY, int subsampleX, int subsampleY,
           65  +		                       int compRule)
    53     66   
    54         -|int
    55         -|Tk_PhotoPutBlock(Tcl_Interp *interp, Tk_PhotoHandle handle,
    56         -|                 Tk_PhotoImageBlock *blockPtr,
    57         -|                 int x, int y, int width, int height, int compRule)
    58         -
    59         - * ''Tk_PhotoPutZoomedBlock'' will become:
           67  + * _Tk\_PhotoSetSize_ will become:
    60     68   
    61         -|int
    62         -|Tk_PhotoPutZoomedBlock(Tcl_Interp *interp, Tk_PhotoHandle handle,
    63         -|                       Tk_PhotoImageBlock *blockPtr,
    64         -|                       int x, int y, int width, int height,
    65         -|                       int zoomX, int zoomY, int subsampleX, int subsampleY,
    66         -|                       int compRule)
    67         -
    68         - * ''Tk_PhotoSetSize'' will become:
    69         -
    70         -|int
    71         -|Tk_PhotoSetSize(Tcl_Interp *interp, Tk_PhotoHandle handle,
    72         -|                int width, int height)
           69  +		int
           70  +		Tk_PhotoSetSize(Tcl_Interp *interp, Tk_PhotoHandle handle,
           71  +		                int width, int height)
    73     72   
    74     73   Also note that as a consequence of this, some image-related Tk
    75     74   commands will also gain additional error return situations.  Since
    76         -these all trigger abnormal process termination (and potentially a
    77         -core-dump too) at the moment, this change in behaviour is believed to
           75  +these all trigger abnormal process termination \(and potentially a
           76  +core-dump too\) at the moment, this change in behaviour is believed to
    78     77   be wholly beneficial.
    79     78   
    80         -~ Backward Compatibility
           79  +# Backward Compatibility
    81     80   
    82     81   This TIP also proposes a backward compatibility interface, so that
    83     82   extensions need not be heavily modified to work with new versions of
    84     83   Tk.  This is done by leaving backwardly-compatible functions in the
    85         -old locations in Tk's stub table and adding a ''#define'' to allow
           84  +old locations in Tk's stub table and adding a _\#define_ to allow
    86     85   selection of the old API with the standard names.  I propose doing this
    87         -when the symbol ''USE_PANIC_ON_PHOTO_ALLOC_FAILURE'' is defined; like
           86  +when the symbol _USE\_PANIC\_ON\_PHOTO\_ALLOC\_FAILURE_ is defined; like
    88     87   this, extension authors can switch from compiling with Tk 8.4 to using
    89         -later versions by adding just one flag to their makefile (or other build
    90         -script/environment.)
           88  +later versions by adding just one flag to their makefile \(or other build
           89  +script/environment.\)
    91     90   
    92     91   Note that this interacts with the backward-compatability interface
    93         -defined in [98]; if that is enabled, the back-compat interface defined
           92  +defined in [[98]](98.md); if that is enabled, the back-compat interface defined
    94     93   here is enabled as well.
    95     94   
    96         -~ Sample Implementation
           95  +# Sample Implementation
    97     96   
    98         -http://sf.net/tracker/?func=detail&aid=646382&group_id=12997&atid=312997
           97  +<http://sf.net/tracker/?func=detail&aid=646382&group\_id=12997&atid=312997>
    99     98   
   100         -~ Copyright
           99  +# Copyright
   101    100   
   102    101   This document has been placed in the public domain.
          102  +

Name change from tip/117.tip to tip/117.md.

     1         -TIP:            117
     2         -Title:          Object Type Introspection
     3         -Version:        $Revision: 1.9 $
     4         -Author:         Peter Spjuth <peter.spjuth@space.se>
     5         -State:          Withdrawn
     6         -Type:           Project
     7         -Vote:           Pending
     8         -Created:        01-Nov-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
    11         -Obsoleted-By:	214
            1  +# TIP 117: Object Type Introspection
            2  +	Author:         Peter Spjuth <peter.spjuth@space.se>
            3  +	State:          Withdrawn
            4  +	Type:           Project
            5  +	Vote:           Pending
            6  +	Created:        01-Nov-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +	Obsoleted-By:	214
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15     14   This TIP proposes to add a command to give information
    16     15   on the current internal representation of an object.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20     19   When trying to understand the internals of objects and when trying to
    21     20   track down shimmering problems it is very helpful to be able to see
    22     21   what type an object currently has.
    23     22   
    24         -~ Specification
           23  +# Specification
    25     24   
    26     25   A new package called "Debug" is created as part of the core.
    27     26   
    28         -A new command, ''objtype'', is added to the Debug package.
           27  +A new command, _objtype_, is added to the Debug package.
    29     28   The command has the syntax:
    30     29   
    31         - > '''Debug::objtype''' ?''value''?
           30  + > **Debug::objtype** ?_value_?
    32     31   
    33     32   If no value is submitted, a list of all currently registered object
    34     33   types are returned.
    35     34   
    36     35   If a value is submitted, it returns a list where the first element
    37     36   is the name of value's object type, or "none" if there is no
    38     37   internal representation.  The second element is a boolean stating
    39     38   if the object has a valid string representation.
    40     39   
    41     40   Examples:
    42     41   
    43         -|% Debug::objtype
    44         -|boolean index double end-offset wideInt list cmdName bytecode
    45         -|nsName procbody bytearray int {array search} string
    46         -|% set apa hejsan
    47         -|hejsan
    48         -|% Debug::objtype $apa
    49         -|none 1
    50         -|% string length $apa
    51         -|6
    52         -|% Debug::objtype $apa
    53         -|string 1
    54         -|% regexp $apa hoppsan
    55         -|0
    56         -|% Debug::objtype $apa
    57         -|regexp 1
    58         -|% Debug::objtype [expr 1+1]
    59         -|int 0
           42  +	% Debug::objtype
           43  +	boolean index double end-offset wideInt list cmdName bytecode
           44  +	nsName procbody bytearray int {array search} string
           45  +	% set apa hejsan
           46  +	hejsan
           47  +	% Debug::objtype $apa
           48  +	none 1
           49  +	% string length $apa
           50  +	6
           51  +	% Debug::objtype $apa
           52  +	string 1
           53  +	% regexp $apa hoppsan
           54  +	0
           55  +	% Debug::objtype $apa
           56  +	regexp 1
           57  +	% Debug::objtype [expr 1+1]
           58  +	int 0
    60     59   
    61         -~ Discussion
           60  +# Discussion
    62     61   
    63     62   The first proposal was to add this as a subcommand to info.  This
    64     63   was considered bad since this should be a pure debug command
    65     64   and should never be used in live code.  Thus the proposition
    66     65   came up to create a Debug package and put it in there to emphasise
    67     66   its debug nature.  The Debug package can also be extended in the
    68     67   future with other utilities.
    69     68   
    70         -~ Reference Implementation
           69  +# Reference Implementation
    71     70   
    72         -|static int
    73         -|ObjTypeCmd(dummy, interp, objc, objv)
    74         -|    ClientData dummy;		/* Not used. */
    75         -|    Tcl_Interp *interp;	/* Current interpreter. */
    76         -|    int objc;			/* Number of arguments. */
    77         -|    Tcl_Obj *CONST objv[];	/* Argument objects. */
    78         -|{
    79         -|    Tcl_Obj *listPtr;
    80         -|
    81         -|    if ((objc != 2) && (objc != 3)) {
    82         -|        Tcl_WrongNumArgs(interp, 2, objv, "?value?");
    83         -|        return TCL_ERROR;
    84         -|    }
    85         -|
    86         -|    listPtr = Tcl_NewListObj(0, (Tcl_Obj **) NULL);
    87         -|
    88         -|    if (objc == 2) {
    89         -|        Tcl_AppendAllObjTypes(interp, listPtr);
    90         -|    } else {
    91         -|        Tcl_ListObjAppendElement(interp, listPtr, Tcl_NewStringObj(
    92         -|                (objv[2]->typePtr != NULL) ? objv[2]->typePtr->name : "none", -1));
    93         -|        Tcl_ListObjAppendElement(interp, listPtr,
    94         -|                Tcl_NewBooleanObj(objv[2]->bytes != NULL));
    95         -|    }
    96         -|    Tcl_SetObjResult(interp, listPtr);
    97         -|    return TCL_OK;
    98         -|}
           71  +	static int
           72  +	ObjTypeCmd(dummy, interp, objc, objv)
           73  +	    ClientData dummy;		/* Not used. */
           74  +	    Tcl_Interp *interp;	/* Current interpreter. */
           75  +	    int objc;			/* Number of arguments. */
           76  +	    Tcl_Obj *CONST objv[];	/* Argument objects. */
           77  +	{
           78  +	    Tcl_Obj *listPtr;
           79  +	
           80  +	    if ((objc != 2) && (objc != 3)) {
           81  +	        Tcl_WrongNumArgs(interp, 2, objv, "?value?");
           82  +	        return TCL_ERROR;
           83  +	    }
           84  +	
           85  +	    listPtr = Tcl_NewListObj(0, (Tcl_Obj **) NULL);
           86  +	
           87  +	    if (objc == 2) {
           88  +	        Tcl_AppendAllObjTypes(interp, listPtr);
           89  +	    } else {
           90  +	        Tcl_ListObjAppendElement(interp, listPtr, Tcl_NewStringObj(
           91  +	                (objv[2]->typePtr != NULL) ? objv[2]->typePtr->name : "none", -1));
           92  +	        Tcl_ListObjAppendElement(interp, listPtr,
           93  +	                Tcl_NewBooleanObj(objv[2]->bytes != NULL));
           94  +	    }
           95  +	    Tcl_SetObjResult(interp, listPtr);
           96  +	    return TCL_OK;
           97  +	}
    99     98   
   100         -~ Future possibilities
           99  +# Future possibilities
   101    100   
   102    101   For further object introspection the command can easily be 
   103    102   extended by options.
   104    103   
   105         -~ Copyright
          104  +# Copyright
   106    105   
   107    106   This document has been placed in the public domain.
          107  +

Name change from tip/118.tip to tip/118.md.

     1         -TIP:            118
     2         -Title:          Enhance [file attributes] and [file copy] on Mac OS X & BSD
     3         -Version:        $Revision: 1.7 $
     4         -Author:         Daniel A. Steffen <das@users.sourceforge.net>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        01-Nov-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 118: Enhance [file attributes] and [file copy] on Mac OS X & BSD
            2  +	Author:         Daniel A. Steffen <das@users.sourceforge.net>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        01-Nov-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -This TIP proposes a set of changes to ''[file attributes]'' and
    15         -''[file copy]'' to make them function better on MacOS X and other
           13  +This TIP proposes a set of changes to _[file attributes]_ and
           14  +_[file copy]_ to make them function better on MacOS X and other
    16     15   BSD-Unix systems.
    17     16   
    18         -~ Summary of Proposed Changes
           17  +# Summary of Proposed Changes
    19     18   
    20         -This TIP proposes five sets of changes to ''[file attributes]'' and
    21         -''[file copy]'':
           19  +This TIP proposes five sets of changes to _[file attributes]_ and
           20  +_[file copy]_:
    22     21   
    23         - 1. Add support for the Macintosh and Windows specific flag ''[file
    24         -    attributes -readonly]'' to Unixes that support the ''chflags()''
    25         -    API, to allow the ''user immutable'' flag to be accessed &
           22  + 1. Add support for the Macintosh and Windows specific flag _[file
           23  +    attributes -readonly]_ to Unixes that support the _chflags\(\)_
           24  +    API, to allow the _user immutable_ flag to be accessed &
    26     25       modified from Tcl.
    27     26   
    28         - 2. Add support for the Macintosh specific flags ''[file attributes
    29         -    -readonly -creator -type -hidden]'' to Mac OS X via the POSIX
    30         -    level API ''getattrlist()''.
           27  + 2. Add support for the Macintosh specific flags _[file attributes
           28  +    -readonly -creator -type -hidden]_ to Mac OS X via the POSIX
           29  +    level API _getattrlist\(\)_.
    31     30   
    32         - 3. Add a new flag ''[file attributes -rsrclength]'' to Mac OS X and
           31  + 3. Add a new flag _[file attributes -rsrclength]_ to Mac OS X and
    33     32       Mac OS 9 that gives the length of the resource fork of a file; 0
    34     33       is the only value that this attribute can be set to, which strips
    35     34       the resource fork off a file.
    36     35   
    37         - 4. Change ''[file attributes]'' to return the list of attributes that
           36  + 4. Change _[file attributes]_ to return the list of attributes that
    38     37       can be retrieved without error for a given file, instead of
    39     38       aborting the whole command when any error occurs.
    40     39   
    41         - 5. Enhance ''[file copy]'' on Mac OS X (more precisely, the native
    42         -    file-system ''Tcl_FSCopyFile'') to copy finder attributes (i.e.
    43         -    ''-readonly -creator -type -hidden'') and resource forks
           40  + 5. Enhance _[file copy]_ on Mac OS X \(more precisely, the native
           41  +    file-system _Tcl\_FSCopyFile_\) to copy finder attributes \(i.e.
           42  +    _-readonly -creator -type -hidden_\) and resource forks
    44     43       transparently.
    45     44   
    46         -~ Rationale
           45  +# Rationale
    47     46   
    48     47   There is currently no way to access and modify HFS file-system metadata
    49         -from Tcl on Mac OS X whereas Tcl on Mac OS 9 (or Classic) on the same
    50         -Macintosh has that capability.  Worse, ''[file copy]'' (and
    51         -potentially even ''[file rename]'' if it results in a copy) on Mac OS
           48  +from Tcl on Mac OS X whereas Tcl on Mac OS 9 \(or Classic\) on the same
           49  +Macintosh has that capability.  Worse, _[file copy]_ \(and
           50  +potentially even _[file rename]_ if it results in a copy\) on Mac OS
    52     51   X can be a destructive operation at present if it operates on a file
    53     52   that has essential data in its resource fork or its HFS metadata.
    54     53   This again in contrast to the same operations in Tcl on Mac OS 9 where
    55     54   this information is preserved.  This TIP seeks to rectify these
    56     55   asymmetries in order to better hide such file-system related platform
    57     56   specificities from the scripter.
    58     57   
    59         -~ Details
           58  +# Details
    60     59   
    61     60   Additional information & examples:
    62     61   
    63         - 1. Unix versions that support ''chflags()'' include BSD >= 4.4 and
    64         -    Darwin/Mac OS X (where ''user immutable'' is the flag
           62  + 1. Unix versions that support _chflags\(\)_ include BSD >= 4.4 and
           63  +    Darwin/Mac OS X \(where _user immutable_ is the flag
    65     64       corresponding to the file locked state on the HFS file-system,
    66         -    which is what ''[file attributes -readonly]'' controls on Mac OS
    67         -    9).
           65  +    which is what _[file attributes -readonly]_ controls on Mac OS
           66  +    9\).
    68     67   
    69         - 2. The use of ''getattrlist()'' does not require linking with Carbon
           68  + 2. The use of _getattrlist\(\)_ does not require linking with Carbon
    70     69       and thus allows access to HFS file-system metadata from Tcl on pure
    71         -    open-source Darwin systems (which is something no other scripting
    72         -    language can claim at present).
           70  +    open-source Darwin systems \(which is something no other scripting
           71  +    language can claim at present\).
    73     72   
    74         - 3. The new attribute ''-rsrclength'' is useful to check whether a
           73  + 3. The new attribute _-rsrclength_ is useful to check whether a
    75     74       file has a resource fork and to calculate total file size on Mac
    76         -    OS 9 and X (note that ''[file size]'' returns the size of the data
    77         -    fork only).  Stripping a file's resource fork (by setting
    78         -    ''-rsrclength'' to 0) is a common operation on Mac OS when dealing
           75  +    OS 9 and X \(note that _[file size]_ returns the size of the data
           76  +    fork only\).  Stripping a file's resource fork \(by setting
           77  +    _-rsrclength_ to 0\) is a common operation on Mac OS when dealing
    79     78       with files that are destined for other platforms.  This is a
    80     79       feature that has been requested several times and given that it
    81     80       ties in well with the implementation of the other new attributes
    82     81       it comes at essentially no additional cost.
    83     82   
    84         -|% file attributes test
    85         -|-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 314
    86         -|% file attributes test -rsrclength 5
    87         -|setting nonzero rsrclength not supported
    88         -|% file attributes test -rsrclength 0
    89         -|% file attributes test
    90         -|-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 0
           83  +		% file attributes test
           84  +		-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 314
           85  +		% file attributes test -rsrclength 5
           86  +		setting nonzero rsrclength not supported
           87  +		% file attributes test -rsrclength 0
           88  +		% file attributes test
           89  +		-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 0
    91     90   
    92         - 4. On Mac OS X, trying to retrieve the new attributes ''-creator
    93         -    -type -rsrclength'' fails on non-regular files & directories (and
           91  + 4. On Mac OS X, trying to retrieve the new attributes _-creator
           92  +    -type -rsrclength_ fails on non-regular files & directories \(and
    94     93       on any file located on a non-HFS file-system that doesn't support
    95         -    ''getattrlist()'').  Returning only the list of attributes that
           94  +    _getattrlist\(\)_\).  Returning only the list of attributes that
    96     95       are valid seems like much more sensible behaviour in this case
    97     96       than failing with an error and not returning anything.  In the
    98     97       case where no valid attributes can be retrieved at all, the error
    99     98       returned by the last attempt is passed upstream, to preserve
   100     99       existing error handling.  This proposed change in behaviour of
   101         -    ''[file attributes]'' seems necessary to allow the command to
          100  +    _[file attributes]_ seems necessary to allow the command to
   102    101       continue to work in a consistent way on all inputs and on all
   103    102       platforms; it should not impact existing code since for current
   104    103       attributes, failure to retrieve any one attribute is equivalent to
   105    104       failure to retrieve all attributes.
   106    105   
   107         -|% close [open test w]
   108         -|% file attributes test
   109         -|-group admin -owner steffen -permissions 00644 -readonly 0 -creator {} -type {} -hidden 0 -rsrclength 0
   110         -|% file delete test
   111         -|% file mkdir test
   112         -|% file attributes test
   113         -|-group admin -owner steffen -permissions 040755 -readonly 0 -hidden 0
   114         -|% file delete test
          106  +		% close [open test w]
          107  +		% file attributes test
          108  +		-group admin -owner steffen -permissions 00644 -readonly 0 -creator {} -type {} -hidden 0 -rsrclength 0
          109  +		% file delete test
          110  +		% file mkdir test
          111  +		% file attributes test
          112  +		-group admin -owner steffen -permissions 040755 -readonly 0 -hidden 0
          113  +		% file delete test
   115    114   
   116    115    5. Unlike the Finder and other HFS aware tools on Mac OS X, Tcl
   117    116       currently ignores HFS metadata and the resource fork, which will
   118         -    undoubtedly surprise scripters unpleasantly.  ''[file copy]''
          117  +    undoubtedly surprise scripters unpleasantly.  _[file copy]_
   119    118       should hide such platform specificities and copy a file in the
   120    119       same way as the Finder:
   121    120   
   122         -|% file attributes test
   123         -|-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 314
   124         -|% file copy test test1
   125         -|% file attributes test1
   126         -|-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 314
   127         -|% file delete test1
          121  +		% file attributes test
          122  +		-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 314
          123  +		% file copy test test1
          124  +		% file attributes test1
          125  +		-group admin -owner steffen -permissions 00644 -readonly 0 -creator Doug -type RSRC -hidden 0 -rsrclength 314
          126  +		% file delete test1
   128    127   
   129         -~ Comments
          128  +# Comments
   130    129   
   131    130   Additional implementation details:
   132    131   
   133         - * To support the new attributes ''-creator -type'', routines to
   134         -   convert from numerical OSTypes (''u_int32_t'') to the usual four
          132  + * To support the new attributes _-creator -type_, routines to
          133  +   convert from numerical OSTypes \(_u\_int32\_t_\) to the usual four
   135    134      character human readable format have been adapted from
   136         -   ''mac/tclMacResource.c''; the new versions accept/return strings of
          135  +   _mac/tclMacResource.c_; the new versions accept/return strings of
   137    136      length 0-4 unlike the originals that only dealt with length 4.
   138         -   This is important because creator/type 0 (i.e. ''-creator {} -type
   139         -   {}'') is common on Mac OS X. The Mac OS 9 implementation of the
          137  +   This is important because creator/type 0 \(i.e. _-creator \{\} -type
          138  +   \{\}_\) is common on Mac OS X. The Mac OS 9 implementation of the
   140    139      OSType string representation code has been modified accordingly by
   141    140      adding support for strings of length 0-4 and missing
   142         -   ''UtfToExternal/ExternalToUtf'' conversions.
          141  +   _UtfToExternal/ExternalToUtf_ conversions.
   143    142   
   144         - * ''macRoman'' is the encoding used for the string representation of
          143  + * _macRoman_ is the encoding used for the string representation of
   145    144      OSTypes, for consistency with Tcl on Mac OS 9 as well as with
   146    145      common Mac OS X tools such as Resorcerer & SuperGetInfo that all
   147         -   use ''macRoman'' to display creator/type codes; this encoding is
          146  +   use _macRoman_ to display creator/type codes; this encoding is
   148    147      probably what most people would expect.  It's unfortunate that this
   149         -   means that use of ''[file attributes]'' on Darwin/Mac OS X will
   150         -   cause the non-builtin ''macRoman'' encoding to load.  ASCII-only
   151         -   OSTypes will still work properly if ''macRoman'' is not available,
   152         -   fallback to ''latin1'' in that case could also be added if deemed
          148  +   means that use of _[file attributes]_ on Darwin/Mac OS X will
          149  +   cause the non-builtin _macRoman_ encoding to load.  ASCII-only
          150  +   OSTypes will still work properly if _macRoman_ is not available,
          151  +   fallback to _latin1_ in that case could also be added if deemed
   153    152      necessary.  However, the Tk Aqua port already relies on
   154         -   ''macRoman'' being present so in the most common usage pattern
   155         -   ''macRoman'' should be present and loaded anyway.
          153  +   _macRoman_ being present so in the most common usage pattern
          154  +   _macRoman_ should be present and loaded anyway.
   156    155   
   157         - * The Mac OS 9 implementation of ''[file attributes -creator -type]''
          156  + * The Mac OS 9 implementation of _[file attributes -creator -type]_
   158    157      currently returns the bogus 'Fldr' type & creator for directories,
   159    158      this has been changed to return an error for consistency with the
   160    159      Mac OS X implementation.
   161    160   
   162    161    * Most of the implementation of the new Mac OS X specific features
   163         -   has been added added at the end of ''unix/tclUnixFCmd.c'', it might
          162  +   has been added added at the end of _unix/tclUnixFCmd.c_, it might
   164    163      be cleaner to move this code to a separate file
   165         -   ''macosx/tclMacOSXFCmd.c'', but that would require several routines
   166         -   in both ''unix/tclUnixFCmd.c'' and ''mac/tclMacOSXFCmd.c'' to be
          164  +   _macosx/tclMacOSXFCmd.c_, but that would require several routines
          165  +   in both _unix/tclUnixFCmd.c_ and _mac/tclMacOSXFCmd.c_ to be
   167    166      made non-static.  It's unclear whether this is an acceptable change
   168    167      just for the sake of code separation/cleanliness.
   169    168   
   170         -~ Reference Implementation
          169  +# Reference Implementation
   171    170   
   172         -SourceForge patch #626360
   173         -[[http://sourceforge.net/tracker/index.php?func=detail&aid=626360&group_id=10894&atid=310894]]
          171  +SourceForge patch \#626360
          172  +<http://sourceforge.net/tracker/index.php?func=detail&aid=626360&group_id=10894&atid=310894> 
   174    173   implements this TIP as a patch to the current HEAD.
   175    174   
   176    175   The patch has been tested on the SF compile-farm on hosts:
   177    176   
   178         - [Alpha] Linux 2.4 (Debian 3.0): where ''chflags()'' and
   179         -   ''getattrlist()'' are not available and no ill effects ensue
   180         -   (i.e. no new tests fail).
          177  + [Alpha] Linux 2.4 \(Debian 3.0\): where _chflags\(\)_ and
          178  +   _getattrlist\(\)_ are not available and no ill effects ensue
          179  +   \(i.e. no new tests fail\).
   181    180   
   182         - [x86] FreeBSD (4.7-RC): where ''chflags()'' is available and ''[file
   183         -   attributes -readonly]'' can successfully be interrogated (but not
   184         -   set due to permission issues at SourceForge).  No new tests fail.
          181  + [x86] FreeBSD \(4.7-RC\): where _chflags\(\)_ is available and _[file
          182  +   attributes -readonly]_ can successfully be interrogated \(but not
          183  +   set due to permission issues at SourceForge\).  No new tests fail.
   185    184   
   186    185   as well as on Mac OS 9, X 10.1.5 and X 10.2.1, where all the new
   187    186   functionality is available and no new tests fail.
   188    187   
   189         -~ Copyright
          188  +# Copyright
   190    189   
   191    190   This document has been placed in the public domain.
          191  +

Name change from tip/119.tip to tip/119.md.

     1         -TIP:            119
     2         -Title:          Angled Text on a Canvas
     3         -Version:        $Revision: 1.8 $
     4         -Author:         Simon Geard <simon.geard@ntlworld.com>
     5         -Author:		Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        18-Nov-2002
    10         -Post-History:   
    11         -Tcl-Version:    8.6
            1  +# TIP 119: Angled Text on a Canvas
            2  +	Author:         Simon Geard <simon.geard@ntlworld.com>
            3  +	Author:		Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        18-Nov-2002
            8  +	Post-History:   
            9  +	Tcl-Version:    8.6
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15     14   The current text object on a canvas does not support the creation of
    16     15   text strings at an arbitrary angle.  For some applications this is
    17     16   limitation is sufficiently serious to disqualify Tk from use.  This
    18     17   TIP removes this restriction.
    19     18   
    20         -~ Rationale
           19  +# Rationale
    21     20   
    22     21   Using a Tk canvas to display e.g. an engineering drawing from a CAD
    23     22   application is limited - such applications will output angled text and
    24     23   there is simply no way of displaying such text on a canvas.
    25     24   
    26     25   Another consideration is the competition.  Both Qt and Java canvas
    27     26   objects support angled text on their canvas object - most new users
    28     27   would I believe be surprised to discover that this functionality is not
    29     28   supported.
    30     29   
    31     30   Due to the internal architecture of Tk a side effect of this work
    32         -would be to enable buttons (and possibly other widgets) to have their
           31  +would be to enable buttons \(and possibly other widgets\) to have their
    33     32   text written at an angle as well.  This TIP does not expose that
    34     33   functionality.
    35     34   
    36         -~ Implementation
           35  +# Implementation
    37     36   
    38         -At the command level there would be an extra attribute, ''-angle'',
           37  +At the command level there would be an extra attribute, _-angle_,
    39     38   added to the canvas's text object:
    40     39   
    41         -|<canvas> create text <x> <y> -text <str> ?-angle <angle>? ...
           40  +	<canvas> create text <x> <y> -text <str> ?-angle <angle>? ...
    42     41   
    43     42   where the angle is specified in degrees.  Manipulation of the angle
    44         -would be done in the usual way through the ''itemconfigure'' and
    45         -''itemcget'' subcommands:
           43  +would be done in the usual way through the _itemconfigure_ and
           44  +_itemcget_ subcommands:
    46     45   
    47         -|<canvas> itemconfigure <tag> -angle <angle>
           46  +	<canvas> itemconfigure <tag> -angle <angle>
    48     47   
    49     48   Note that PostScript naturally supports rotation of text.
    50     49   
    51         -~ Reference Implementation
           50  +# Reference Implementation
    52     51   
    53     52   I have done an initial assessment of the amount of work required and
    54     53   have and have created a patch to implement it in Tk 8.4.5 .  This
    55     54   initial work was fairly straightforward but the internal housekeeping
    56     55   work maintaining and interacting with an angled box will be more
    57         -substantial.  The patch (uploaded to SourceForge
    58         -[http://sf.net/tracker/?func=detail&aid=1611359&group_id=12997&atid=312997]) is
           56  +substantial.  The patch \(uploaded to SourceForge
           57  +<http://sf.net/tracker/?func=detail&aid=1611359&group_id=12997&atid=312997> \) is
    59     58   for X only.  It doesn't use any X extensions and should work for X11R3
    60     59   and above.  I don't know how it would be done on non-X systems but
    61         -hopefully they'll (Win & MacOS at least) provide native tools to make
           60  +hopefully they'll \(Win & MacOS at least\) provide native tools to make
    62     61   their implementation straightforward as well.
    63     62   
    64         -~~ Implementation Notes
           63  +## Implementation Notes
    65     64   
    66     65   The implementation was tricky to develop, because it was wholly different on
    67         -each rendering platform (X11 is two, depending on which font rendering engine
    68         -is used). This delayed implementation of this TIP for a whole release.
           66  +each rendering platform \(X11 is two, depending on which font rendering engine
           67  +is used\). This delayed implementation of this TIP for a whole release.
    69     68   
    70     69    Classic X11: Uses a general monochrome pixmap rotation engine.
    71     70   
    72         - X11 + Xft: Generates rotated versions of the fonts by installing a rotation
           71  + X11 \+ Xft: Generates rotated versions of the fonts by installing a rotation
    73     72      matrix, caching them in the subfont management engine.
    74     73   
    75     74    Win32: Generates rotated versions of the fonts using the built-in font
    76     75      rotation suport, caching them in the subfont management engine.
    77     76   
    78     77    MacOS X: Applies the rotation to the Current Transformation Matrix
    79     78      immediately before rendering.
    80     79   
    81         -~ Copyright
           80  +# Copyright
    82     81   
    83     82   This document has been placed in the public domain.
           83  +

Name change from tip/12.tip to tip/12.md.

     1         -TIP:            12
     2         -Title:          The "Batteries Included" Distribution
     3         -Version:        $Revision: 1.3 $
     4         -Author:         George A. Howlett <gah@siliconmetrics.com>
     5         -Author:         Larry W. Virden <lvirden@yahoo.com>
     6         -State:          Draft
     7         -Type:           Informative
     8         -Vote:           Pending
     9         -Created:        15-Sep-2000
    10         -Post-History:   
    11         -Discussions-To: news:comp.lang.tcl
            1  +# TIP 12: The "Batteries Included" Distribution
            2  +	Author:         George A. Howlett <gah@siliconmetrics.com>
            3  +	Author:         Larry W. Virden <lvirden@yahoo.com>
            4  +	State:          Draft
            5  +	Type:           Informative
            6  +	Vote:           Pending
            7  +	Created:        15-Sep-2000
            8  +	Post-History:   
            9  +	Discussions-To: news:comp.lang.tcl
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15     14   This document describes a comprehensive Tcl/Tk distribution.  Its
    16     15   primary purpose is to create a standard source tree that includes Tcl,
    17     16   Tk, and extensions so that they can be built and installed in an
    18     17   simple and easy manner.
    19     18   
    20         -~ Introduction
           19  +# Introduction
    21     20   
    22     21   One of the most enduring complaints about Tcl/Tk is that it lacks
    23     22   features, especially when compared to Perl, Python, or Java.  We
    24     23   patiently explain that some particular feature is available in
    25     24   extension "XYZ" only to hear how hard it is to build and install
    26     25   extensions.
    27     26   
    28         -Frank Stajano ("The SMS server, or why I switched from Tcl to Python")
           27  +Frank Stajano \("The SMS server, or why I switched from Tcl to Python"\)
    29     28   describes the problem succinctly.
    30     29   
    31     30    > "But if I had to put the finger on the single most important reason
    32         -   that has me now working in Python rather than in Tcl/[[incr Tcl]]
           31  +   that has me now working in Python rather than in Tcl/[incr Tcl]
    33     32      it would not be a language issue but a library issue. I prefer
    34     33      Python because its standard library is a gold mine. Sure, for
    35     34      anything I want to do there's bound to be an extension available in
    36     35      the Tcl code repository on the FTP site. Now I just have to find
    37         -   it, fetch it, recompile the interpreter with it (Oh wait - this may
           36  +   it, fetch it, recompile the interpreter with it \(Oh wait - this may
    38     37      mean getting and installing a C compiler for this system. Will the
    39     38      GNU one compile the windowing stuff properly or do I need to get
    40         -   VC++, or Borland?  Who wants to have some fun discovering where
    41         -   another IDE has hidden the useful compiler flags this week?), hope
           39  +   VC\+\+, or Borland?  Who wants to have some fun discovering where
           40  +   another IDE has hidden the useful compiler flags this week?\), hope
    42     41      that it won't clash with other extensions I've had to install, hope
    43     42      that it will not require a different version of the interpreter
    44     43      from the one I am running, and so on. Python supports the same C
    45     44      extension mechanism as Tcl - but the practical difference is that
    46     45      the stuff I want is, most of the time, already included and shipped
    47     46      in the standard distribution of the language!"
    48     47   
................................................................................
    64     63   that words "core" and "extension" disappear from our Tcl vocabularies.
    65     64   We've lived their artifical distinctions that are useful only to core
    66     65   developers and extension writers.  It's skewed our thinking about
    67     66   relationship between Tcl and its parts.  After all, application
    68     67   writers first care about whether a feature or capability is available,
    69     68   not how it's structured under the hood.
    70     69   
    71         -~ The "Batteries Included" Distribution.
           70  +# The "Batteries Included" Distribution.
    72     71   
    73     72   Let's start with a very modest example.  Let's imagine that the
    74     73   "Batteries Included" distribution is nothing more than an archive file of
    75     74   the source code for Tcl/Tk and several extensions.
    76     75   
    77         -|            Unix    Windows  Mac
    78         -|             ----    -------  ---
    79         -|  Tcl 8.3       x       x      x
    80         -|  Tk 8.3        x       x      x
    81         -|  [incr Tcl]    x       x      x
    82         -|  expect        x       ?
    83         -|  TclX          x
    84         -|  BLT           x       x
    85         -|  Trf           
    86         -|  Html widget
    87         -|  XML
    88         -|  ...lots more...
           76  +	            Unix    Windows  Mac
           77  +	             ----    -------  ---
           78  +	  Tcl 8.3       x       x      x
           79  +	  Tk 8.3        x       x      x
           80  +	  [incr Tcl]    x       x      x
           81  +	  expect        x       ?
           82  +	  TclX          x
           83  +	  BLT           x       x
           84  +	  Trf           
           85  +	  Html widget
           86  +	  XML
           87  +	  ...lots more...
    89     88   
    90     89   Tcl, Tk, and the packages are configured such that they can be built
    91         -and installed just from a top level directory (not individually).
           90  +and installed just from a top level directory \(not individually\).
    92     91   Someone can download and try out all sorts of new features without
    93     92   repeating the same "configure", "make", "make install" sequences.
    94     93   
    95     94   With this simple tar file, the following benefits are automatically
    96     95   generated:
    97     96   
    98     97     * It provides a simple way for users to try out extensions.  Users
................................................................................
   108    107       features being universally available.  Your program can again be
   109    108       just a Tcl script, not an array of packages that everyone needs to
   110    109       download and install.
   111    110   
   112    111     * It's better for extension writers.  Configuration is simpler,
   113    112       since you know where all the sources and the compiler-specific
   114    113       information will reside.  You don't need to search for
   115         -    ''tclConfig.sh'' or ''tkConfig.sh'' files.
          114  +    _tclConfig.sh_ or _tkConfig.sh_ files.
   116    115   
   117    116     * It's better for Tcl/Tk distribution builders.  This includes both
   118    117       the Linux distributors and company sysadmins that build Tcl/Tk.
   119    118       They don't have to fear installing extensions because of version
   120    119       dependencies.
   121    120   
   122         -  > Let's give Redhat and SuSE a good reason to move off of version
   123         -    8.0. One the big advantages of Linux over (let's say) Solaris is
          121  +	  > Let's give Redhat and SuSE a good reason to move off of version
          122  +    8.0. One the big advantages of Linux over \(let's say\) Solaris is
   124    123       that each new Redhat or SuSE distribution comes with updated
   125    124       versions of utilities already built.
   126    125   
   127    126     * It's better for the core developers. Extension writers will
   128    127       willing the adopt changes in exchange for the wider distribution.
   129    128       The core team will in turn gain better understanding of the
   130    129       burdens of extension writers.
   131    130   
   132    131     * It's better for Tcl library writers.  With [incr Tcl], we now have
   133    132       a basis for a real, extensible Tcl-code library.  Library code
   134    133       rely on a full set of extensions being available.
   135    134   
   136         -~ Rationale
          135  +# Rationale
   137    136   
   138    137   We want to create an open door procedure that makes it easy for
   139    138   contributors to add new features and commands to Tcl and Tk.  By
   140    139   creating a framework for extensions to be built and distributed, the
   141    140   "Batteries Included" distribution will provide a path for great new
   142    141   features to quickly become available to the Tcl community.
   143    142   
................................................................................
   157    156   
   158    157   If the "Batteries Included" distribution is to become successful, it
   159    158   must be a cooperative effort between Tcl core developers, extension
   160    159   writers, and the Tcl user community.  For example, we need the help of
   161    160   extension writers to adopt the new configuration scheme and directory
   162    161   structure.
   163    162   
   164         -~ Particulars
          163  +# Particulars
   165    164   
   166    165   We can stage the project with small milestones while still focusing on
   167    166   longer range goals.  For example, the first phase can be as simple as
   168    167   creating a tar file.  It will start to address questions that were
   169    168   raised by TEA.  For example, how do we manage documentation?
   170    169   
   171    170   The biggest reason why this proposal will succeed is the incredible
   172    171   talent in the Tcl community.  We can leverage the skills and
   173    172   experiences of the foremost experts on the core, extensions, and
   174    173   applications.
   175    174   
   176         -~ Tcl/Tk Version.
          175  +# Tcl/Tk Version.
   177    176   
   178         -The distribution will be based on 8.3.2 (or 8.3.3 when it is
   179         -released).  While there's no assurance when 8.4 will be released and
          177  +The distribution will be based on 8.3.2 \(or 8.3.3 when it is
          178  +released\).  While there's no assurance when 8.4 will be released and
   180    179   in what state, we also want to place a premium on stable, robust
   181    180   extensions, that have been thoroughly tested.  Most extensions will be
   182    181   unlikely to have been tested against the 8.4 alphas.
   183    182   
   184         -~ Phase 1.
          183  +# Phase 1.
   185    184   
   186    185    * Identify extensions.  
   187    186   
   188         - > What extensions should be included in the near term?  We need
          187  +	 > What extensions should be included in the near term?  We need
   189    188      extension authors that are willing to work with us to build a
   190    189      directory framework, change configuration files, etc.  Extensions
   191    190      do not need to work on all platforms.  For example, there is a
   192    191      wealth of Windows-based extensions that should be included in 
   193    192      a Windows specific build.
   194    193   
   195         - > What are the minimum requirements for extensions in the short term?
          194  +	 > What are the minimum requirements for extensions in the short term?
   196    195      Manual pages, html, tests, demos all would be nice.  We need to
   197    196      temper this with what's practical.  This is a learning process. We
   198    197      can adjust requirements in future phases.
   199    198   
   200    199    * Determine build and install directory structures.  
   201    200   
   202         - > We need to make this work with more that one release installed.
          201  +	 > We need to make this work with more that one release installed.
   203    202      Don't suppose that there only one version will ever be used.
   204    203   
   205    204    * Setup CVS archives.
   206    205   
   207    206    * Create configuration files.  
   208    207   
   209         - > This will require negotiation with extension writers.  We want
          208  +	 > This will require negotiation with extension writers.  We want
   210    209      their buy-in so they will maintain the changes.
   211    210   
   212         - > There may be more than one form of configuration required.  One
          211  +	 > There may be more than one form of configuration required.  One
   213    212      subtle but important issue is that extensions must be able to be
   214    213      configured without Tcl or Tk libraries already existing.  This is a
   215    214      "trusted" configure.  The extension must trust that the library
   216    215      will exist.  Right now, most extensions work from "untrusted"
   217    216      configurations.
   218    217   
   219    218    * Test builds on multiple platforms.  
   220    219   
   221         - > For now, the Windows and Mac build files can be hand-generated.  It
          220  +	 > For now, the Windows and Mac build files can be hand-generated.  It
   222    221      may be too hard to create a seamless build environment. We're not
   223    222      trying to satisfy every Windows/Mac developer here.  We can focus
   224    223      on creating pre-built binary distributions for these platforms.
   225    224   
   226    225    * Create self-installing executables for Windows and the Mac.  
   227    226   
   228         - > If we want, we can provide Linux, Solaris, etc. binaries by
          227  +	 > If we want, we can provide Linux, Solaris, etc. binaries by
   229    228      reviving Michael McLennan's Tclish installer.
   230    229   
   231         -~ Phase 2.
          230  +# Phase 2.
   232    231   
   233    232    * Handle documentation issues.  
   234    233   
   235         - > Generate platform specific doc with Richard Hipp's XML code.
          234  +	 > Generate platform specific doc with Richard Hipp's XML code.
   236    235   
   237    236    * Establish Tcl code library.
   238    237   
   239    238    * Identify more extensions.
   240    239   
   241    240    * Determine the release schedule for "batteries included" distribution.  
   242    241   
   243         - > How often do you release a new version?  It must be more frequent
          242  +	 > How often do you release a new version?  It must be more frequent
   244    243      than Tcl/Tk.  We can start by planning for quarterly releases and
   245    244      then adding more frequent releases if necessary.
   246    245   
   247         - * Determine what core changes (if any) are needed for the distribution.
          246  + * Determine what core changes \(if any\) are needed for the distribution.
   248    247   
   249    248    * Start looking at network-based updates.
   250    249   
   251    250    * Start looking at selective builds.  Allow builders to compile/install 
   252    251      subsets of the distribution.
   253    252   
   254    253    * Push on Redhat, SuSE, etc. to pick up distribution.
   255    254   
   256         -~ Phase 3.
          255  +# Phase 3.
   257    256   
   258    257    * Network-based installs.
   259    258   
   260    259    * Selective installations/builds.
   261    260   
   262    261    * Include applications tree.
   263    262   
   264    263    * Identify more extensions.
   265    264   
   266    265   The last phases are sketchy.  Feel free to add to this list, further
   267    266   breaking down goals into subtasks.
   268    267   
   269         -~ Open Issues
          268  +# Open Issues
   270    269   
   271    270    * Windows and MacIntosh sources.
   272    271   
   273         - > Given the dearth of configuration tools for these platforms, it's
          272  +	 > Given the dearth of configuration tools for these platforms, it's
   274    273      likely that only binary installations will be available for the
   275    274      near term.
   276    275   
   277    276    * Documentation
   278    277   
   279         - > Overlap in command and widget names can be neatly handled by
          278  +	 > Overlap in command and widget names can be neatly handled by
   280    279      namespaces.  Need to consider how to handle manual pages.
   281    280   
   282         -~ More Information
          281  +# More Information
   283    282   
   284    283   If anyone has interest to participate or would like to add comments to
   285    284   the "Batteries Included" proposal, please send mail to George Howlett
   286    285   <gah@siliconmetrics.com>.
   287    286   
   288         -~ Copyright
          287  +# Copyright
   289    288   
   290    289   This document has been placed in the public domain.
   291    290   
   292         -~ See Also
          291  +# See Also
   293    292   
   294         -[4] by Brent Welch <welch@acm.org>.
          293  +[[4]](4.md) by Brent Welch <welch@acm.org>.
          294  +

Name change from tip/120.tip to tip/120.md.

     1         -TIP:            120
     2         -Title:          Restricted DDE Services
     3         -Version:        $Revision: 1.5 $
     4         -Author:         Pat Thoyts <patthoyts@users.sourceforge.net>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        04-Dec-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 120: Restricted DDE Services
            2  +	Author:         Pat Thoyts <patthoyts@users.sourceforge.net>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        04-Dec-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP will enhance the DDE package for use with safe interpreters
    15     14   and allow programmer control of the commands exposed by the DDE
    16     15   service.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20     19   By default the Tcl DDE service exposes all of the commands and
    21     20   variables available in the interpreter to all DDE clients.  This is
    22     21   not always desirable.  One solution might be to load the package into
    23         -a safe slave interpreter and use [[interp alias]] to expose the
           22  +a safe slave interpreter and use [interp alias] to expose the
    24     23   required commands.  Unfortunately the package doesn't support loading
    25     24   into safe interpreters.
    26     25   
    27         -~ Proposed Changes
           26  +# Proposed Changes
    28     27   
    29         -Firstly, this TIP proposes a ''-handler'' option to the [[dde
    30         -servername]] sub-command.  The argument for this option should be the
           28  +Firstly, this TIP proposes a _-handler_ option to the [dde
           29  +servername] sub-command.  The argument for this option should be the
    31     30   name of a procedure that will authenticate and evaluate DDE requests.
    32     31   
    33     32   Secondly, the DDE package should be enhanced to be capable of
    34     33   providing a service within a safe interpreter.
    35     34   
    36         -~ New Option
           35  +# New Option
    37     36   
    38         -The new syntax will be ''dde servername ?-handler command?
    39         -servername''.  To permit introspection we will accept ''dde servername
    40         --handler'' which will return the handler name (if any).  If a
           37  +The new syntax will be _dde servername ?-handler command?
           38  +servername_.  To permit introspection we will accept _dde servername
           39  +-handler_ which will return the handler name \(if any\).  If a
    41     40   servername must be defined using an initial hyphen then the standard
    42     41   '--' separator can be used.
    43     42   
    44         -The dde request is appended to the handler command (which may be a list)
           43  +The dde request is appended to the handler command \(which may be a list\)
    45     44   and then evaluated in the global context. This ensures that all unsafe
    46     45   elements will not be evaluated before the handler code has a chance to
    47     46   examine them. So
    48     47   
    49         -| proc handler {request} {
    50         -|    if {[string match "info *" $request} {
    51         -|       uplevel #0 [lindex $request 0] [lrange $request 1 end]
    52         -|    } else
    53         -|       return -code error "permission denied"
    54         -|    }
    55         -| }
           48  +	 proc handler {request} {
           49  +	    if {[string match "info *" $request} {
           50  +	       uplevel #0 [lindex $request 0] [lrange $request 1 end]
           51  +	    } else
           52  +	       return -code error "permission denied"
           53  +	    }
           54  +	 }
    56     55   
    57         -The above handler will permit [[info vars]] but will fail when trying
    58         -[[info vars ; bad_proc]] with info complaining about the wrong number
           56  +The above handler will permit [info vars] but will fail when trying
           57  +[info vars ; bad_proc] with info complaining about the wrong number
    59     58   of parameters. Passing a single string means that we can handle
    60     59   standard dde styles of requests, for instance 
    61         -'Open("c:\Program Files\prog.exe")' which would not usefully convert
           60  +'Open\("c:\\Program Files\\prog.exe"\)' which would not usefully convert
    62     61   into a list.
    63     62   
    64         -~ Safe DDE
           63  +# Safe DDE
    65     64   
    66     65   The dde package should support loading within a safe interpreter but
    67     66   with the following constraints.
    68     67   
    69     68    * The dde command should be hidden.  This means that the safe
    70     69      interpreter may not call the command but a master interpreter call
    71     70      this command within the context of the safe interpreter.
    72     71   
    73         - * Remote execution requests should be handled ''only'' by a defined
           72  + * Remote execution requests should be handled _only_ by a defined
    74     73      handler procedure.  The normal default is to evaluate a remote
    75     74      execution request in the global namespace.  I propose that when
    76     75      operating in a safe interpreter that the request be denied unless a
    77     76      handler is defined.  The programmer then has the ability to
    78     77      authenticate the request before it is evaluated.
    79     78   
    80     79    * Remote variable reads should be denied.  Rather that add in another
    81         -   handler - the XTYP_REQUEST service command should be denied for
    82         -   safe interpreters.  It is trivial to use [[dde eval Remote set
    83         -   $varname]] to read the value of a variable.
           80  +   handler - the XTYP\_REQUEST service command should be denied for
           81  +   safe interpreters.  It is trivial to use [dde eval Remote set
           82  +   $varname] to read the value of a variable.
    84     83   
    85         -~ Reference Implementation
           84  +# Reference Implementation
    86     85   
    87     86   See the SourceForge Feature Request at
    88         -https://sourceforge.net/tracker/index.php?func=detail&aid=649859&group_id=10894&atid=310894
           87  +<https://sourceforge.net/tracker/index.php?func=detail&aid=649859&group\_id=10894&atid=310894>
    89     88   
    90         -~ Example
           89  +# Example
    91     90   
    92         -| # Provide a handler that only allows the [info] command
    93         -| # Note: This runs in the master interp.
    94         -| proc restricted_handler {request} {
    95         -|    if {[string match "info *" $request} {
    96         -|       uplevel #0 [lindex $request 0] [lrange $request 1 end]
    97         -|    } else
    98         -|       return -code error "permission denied"
    99         -|    }
   100         -| }
   101         -|
   102         -| # Create a safe slave interpreter and expose as a DDE service.
   103         -| safe::interpCreate slave
   104         -| slave invokehidden load tcldde12d.dll Dde
   105         -| slave invokehidden dde servername -handler dde_cmd SafeSlave
   106         -| interp alias slave dde_cmd {} restricted_handler
   107         -|
   108         -| # If testing in tclsh...
   109         -| set ::_waiting 0 ; after 20000 {set ::_waiting 1} ; vwait ::_waiting
           91  +	 # Provide a handler that only allows the [info] command
           92  +	 # Note: This runs in the master interp.
           93  +	 proc restricted_handler {request} {
           94  +	    if {[string match "info *" $request} {
           95  +	       uplevel #0 [lindex $request 0] [lrange $request 1 end]
           96  +	    } else
           97  +	       return -code error "permission denied"
           98  +	    }
           99  +	 }
          100  +	
          101  +	 # Create a safe slave interpreter and expose as a DDE service.
          102  +	 safe::interpCreate slave
          103  +	 slave invokehidden load tcldde12d.dll Dde
          104  +	 slave invokehidden dde servername -handler dde_cmd SafeSlave
          105  +	 interp alias slave dde_cmd {} restricted_handler
          106  +	
          107  +	 # If testing in tclsh...
          108  +	 set ::_waiting 0 ; after 20000 {set ::_waiting 1} ; vwait ::_waiting
   110    109   
   111         -~ Consequences
          110  +# Consequences
   112    111   
   113    112   There should be no change to current users of this package unless they
   114    113   are using a server name beginning with a hyphen.  In this case they
   115    114   will need to insert '--' before the server name.
   116    115   
   117         -~ Copyright
          116  +# Copyright
   118    117   
   119    118   This document is hereby placed in the public domain.
          119  +

Name change from tip/121.tip to tip/121.md.

     1         -TIP:            121
     2         -Title:          Controlled Application Shutdown via Tcl_Exit
     3         -Version:        $Revision: 1.8 $
     4         -Author:         Joe Mistachkin <joe@mistachkin.com>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        05-Dec-2002
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 121: Controlled Application Shutdown via Tcl_Exit
            2  +	Author:         Joe Mistachkin <joe@mistachkin.com>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        05-Dec-2002
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP will allow all applications to perform a controlled shutdown
    15         -(or do nothing) in the event that ''Tcl_Exit()'' is called.
           14  +\(or do nothing\) in the event that _Tcl\_Exit\(\)_ is called.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19     18   For most applications written in C that use Tcl, calling the runtime
    20         -''exit()'' function is normally a reasonable way to shutdown the
           19  +_exit\(\)_ function is normally a reasonable way to shutdown the
    21     20   application.  Unfortunately, this is not always the case.
    22         -Applications written in other languages (and very complex C
    23         -applications) may have very specific application shutdown
           21  +Applications written in other languages \(and very complex C
           22  +applications\) may have very specific application shutdown
    24     23   requirements.  This is especially true in multi-threaded
    25     24   environments.  The problem is further compounded by extensions that
    26         -use ''Tcl_Exit''.
           25  +use _Tcl\_Exit_.
    27     26   
    28         -~ Versus Exit Handlers
           27  +# Versus Exit Handlers
    29     28   
    30     29   There are distinct advantages to using this method instead of using
    31     30   normal exit handlers in some cases.  The normal exit handler cannot
    32         -defer (or in an emergency, prevent) the application shutdown because
    33         -''Tcl_Finalize()'' has already been called.  From the perspective of
           31  +defer \(or in an emergency, prevent\) the application shutdown because
           32  +_Tcl\_Finalize\(\)_ has already been called.  From the perspective of
    34     33   the exit handler, we have no way of knowing what other exit handlers
    35     34   have been called and/or their subsystems destroyed. In addition, even
    36         -if it could somehow cause ''Tcl_Finalize()'' to defer the application
           35  +if it could somehow cause _Tcl\_Finalize\(\)_ to defer the application
    37     36   shutdown, some or all of the other exit handlers may have already
    38     37   been executed, which would leave the application in an inconsistent
    39     38   state.  This relatively simple change allows the programmer to get
    40     39   control very early during the application shutdown process.
    41     40   
    42         -~ Proposed Changes
           41  +# Proposed Changes
    43     42   
    44     43   First, this TIP proposes a new Tcl API function called
    45         -''Tcl_SetExitProc()'' or something similar.  This function
    46         -accepts a ''Tcl_ExitProc'' pointer and returns a ''Tcl_ExitProc''
           44  +_Tcl\_SetExitProc\(\)_ or something similar.  This function
           45  +accepts a _Tcl\_ExitProc_ pointer and returns a _Tcl\_ExitProc_
    47     46   pointer.  The return value is the old exit proc pointer.
    48     47   
    49         -Second, the ''Tcl_Exit()'' Tcl API function would be modified to
           48  +Second, the _Tcl\_Exit\(\)_ Tcl API function would be modified to
    50     49   allow for the handler to be called.
    51     50   
    52         -Third, the documentation for ''Tcl_Exit()'' would be updated to
    53         -include ''Tcl_SetExitProc()'' and a warning that any custom exit proc
           51  +Third, the documentation for _Tcl\_Exit\(\)_ would be updated to
           52  +include _Tcl\_SetExitProc\(\)_ and a warning that any custom exit proc
    54     53   should NOT return.
    55     54   
    56         -~ Tcl_SetExitProc
           55  +# Tcl\_SetExitProc
           56  +
           57  +	Tcl_ExitProc *
           58  +	Tcl_SetExitProc(proc)
           59  +	    Tcl_ExitProc *proc; /* new exit handler for app or NULL */
           60  +	{
           61  +	    Tcl_ExitProc *prevExitProc; /* return prev exit handler to caller */
           62  +	
           63  +	    Tcl_MutexLock(&exitMutex);
           64  +	    prevExitProc = appExitPtr; /* get old app exit ptr */
           65  +	    appExitPtr = proc; /* set new app exit ptr */
           66  +	    Tcl_MutexUnlock(&exitMutex);
           67  +	
           68  +	    return prevExitProc;
           69  +	}
           70  +
           71  +# Tcl\_Exit
    57     72   
    58         -|Tcl_ExitProc *
    59         -|Tcl_SetExitProc(proc)
    60         -|    Tcl_ExitProc *proc; /* new exit handler for app or NULL */
    61         -|{
    62         -|    Tcl_ExitProc *prevExitProc; /* return prev exit handler to caller */
    63         -|
    64         -|    Tcl_MutexLock(&exitMutex);
    65         -|    prevExitProc = appExitPtr; /* get old app exit ptr */
    66         -|    appExitPtr = proc; /* set new app exit ptr */
    67         -|    Tcl_MutexUnlock(&exitMutex);
    68         -|
    69         -|    return prevExitProc;
    70         -|}
           73  +	void
           74  +	Tcl_Exit(status)
           75  +	    int status;			/* Exit status for application;  typically
           76  +					 * 0 for normal return, 1 for error return. */
           77  +	{
           78  +	    Tcl_ExitProc *currentAppExitPtr;
           79  +	
           80  +	    Tcl_MutexLock(&exitMutex);
           81  +	    currentAppExitPtr = appExitPtr;
           82  +	    Tcl_MutexUnlock(&exitMutex);
           83  +	
           84  +	    if (currentAppExitPtr) {
           85  +	      /***********************************************************/
           86  +	      /* WARNING: This code SHOULD NOT return, as there is code  */
           87  +	      /*          that depends on Tcl_Exit never returning.      */
           88  +	      /***********************************************************/
           89  +	      currentAppExitPtr((ClientData) status);
           90  +	    } else {
           91  +	      Tcl_Finalize();
           92  +	      TclpExit(status);
           93  +	    }
           94  +	
           95  +	    Tcl_Panic ("exitProc returned!");
           96  +	}
    71     97   
    72         -~ Tcl_Exit
           98  +# Example
    73     99   
    74         -|void
    75         -|Tcl_Exit(status)
    76         -|    int status;			/* Exit status for application;  typically
    77         -|				 * 0 for normal return, 1 for error return. */
    78         -|{
    79         -|    Tcl_ExitProc *currentAppExitPtr;
    80         -|
    81         -|    Tcl_MutexLock(&exitMutex);
    82         -|    currentAppExitPtr = appExitPtr;
    83         -|    Tcl_MutexUnlock(&exitMutex);
    84         -|
    85         -|    if (currentAppExitPtr) {
    86         -|      /***********************************************************/
    87         -|      /* WARNING: This code SHOULD NOT return, as there is code  */
    88         -|      /*          that depends on Tcl_Exit never returning.      */
    89         -|      /***********************************************************/
    90         -|      currentAppExitPtr((ClientData) status);
    91         -|    } else {
    92         -|      Tcl_Finalize();
    93         -|      TclpExit(status);
    94         -|    }
    95         -|
    96         -|    Tcl_Panic ("exitProc returned!");
    97         -|}
          100  +	void MyAppExitProc(ClientData clientData)
          101  +	{
          102  +	  /* #1. Perform application specific shutdown code...    */
          103  +	  /* #2. Wait for other threads to gracefully shutdown... */
          104  +	
          105  +	  exit(0);
          106  +	
          107  +	  return; /* We should never get here. */
          108  +	}
          109  +	
          110  +	
          111  +	 ... sometime during application initialization ...
          112  +	
          113  +	 /* from this point on MyAppExitProc will handle Tcl_Exit requests */
          114  +	 Tcl_SetExitProc(MyAppExitProc);
          115  +	
          116  +	 ... optionally, sometime later ...
          117  +	
          118  +	 /* from this point on the old (default) handling will be used */
          119  +	 Tcl_SetExitProc(NULL);
    98    120   
    99         -~ Example
   100         -
   101         -|void MyAppExitProc(ClientData clientData)
   102         -|{
   103         -|  /* #1. Perform application specific shutdown code...    */
   104         -|  /* #2. Wait for other threads to gracefully shutdown... */
   105         -|
   106         -|  exit(0);
   107         -|
   108         -|  return; /* We should never get here. */
   109         -|}
   110         -|
   111         -|
   112         -| ... sometime during application initialization ...
   113         -|
   114         -| /* from this point on MyAppExitProc will handle Tcl_Exit requests */
   115         -| Tcl_SetExitProc(MyAppExitProc);
   116         -|
   117         -| ... optionally, sometime later ...
   118         -|
   119         -| /* from this point on the old (default) handling will be used */
   120         -| Tcl_SetExitProc(NULL);
   121         -
   122         -~ Reference Implementation
          121  +# Reference Implementation
   123    122   
   124    123   A patch that implements everything suggested in this TIP is available
   125    124   at the URL:
   126    125   
   127         -http://sourceforge.net/tracker/index.php?func=detail&aid=649313&group_id=10894&atid=310894
          126  +<http://sourceforge.net/tracker/index.php?func=detail&aid=649313&group\_id=10894&atid=310894>
   128    127   
   129         -~ Consequences
          128  +# Consequences
   130    129   
   131         -There is no change for current users of the ''Tcl_Exit()'' function,
   132         -including the [[exit]] command, if ''Tcl_SetExitProc()'' is never
          130  +There is no change for current users of the _Tcl\_Exit\(\)_ function,
          131  +including the [exit] command, if _Tcl\_SetExitProc\(\)_ is never
   133    132   called explicitly by the application.
   134    133   
   135         -~ Copyright
          134  +# Copyright
   136    135   
   137    136   This document is hereby placed in the public domain.
          137  +

Name change from tip/122.tip to tip/122.md.

     1         -TIP:            122
     2         -Title:          Use tcl_{non,}wordchars Throughout Tcl/Tk
     3         -Version:        $Revision: 1.9 $
     4         -Author:         Martin Weber <ephaeton@gmx.net>
     5         -Author:         Vince Darley <vincentdarley@users.sourceforge.net>
     6         -State:          Rejected
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        12-Dec-2002
    10         -Post-History:   
    11         -Tcl-Version:    8.6
    12         -
    13         -~ Abstract
    14         -
    15         -This TIP shall bring flexible management of word and non-word chars to
    16         -Tcl, to be used throughout the Tcl realm in e.g. [[regexp]]'s \w \W,
    17         -Tk's [[textwidget]], [[string]] wordstart/wordend etc.
    18         -
    19         -~Specification
    20         -
    21         -Assignment to ''tcl_{non,}wordchars'' shall influence any place in Tcl
            1  +# TIP 122: Use tcl_{non,}wordchars Throughout Tcl/Tk
            2  +	Author:         Martin Weber <ephaeton@gmx.net>
            3  +	Author:         Vince Darley <vincentdarley@users.sourceforge.net>
            4  +	State:          Rejected
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        12-Dec-2002
            8  +	Post-History:   
            9  +	Tcl-Version:    8.6
           10  +-----
           11  +
           12  +# Abstract
           13  +
           14  +This TIP shall bring flexible management of word and non-word chars to
           15  +Tcl, to be used throughout the Tcl realm in e.g. [regexp]'s \\w \\W,
           16  +Tk's [textwidget], [string] wordstart/wordend etc.
           17  +
           18  +# Specification
           19  +
           20  +Assignment to _tcl\_\{non,\}wordchars_ shall influence any place in Tcl
    22     21   which decides whether something is a word character or not, including
    23     22   detection of word boundaries in e.g. regular expressions, Tk's text
    24     23   widget and so on.
    25     24   
    26     25   For this there shall be no hard-coding of lists of values which are
    27     26   word and non-word characters, and neither shall the language rely on
    28         -the language of implementation (i.e. C's ''is*()'' functions), as this
    29         -disallows dynamic changing of ''tcl_{non,}wordchars''.
           27  +the language of implementation \(i.e. C's _is\*\(\)_ functions\), as this
           28  +disallows dynamic changing of _tcl\_\{non,\}wordchars_.
    30     29   
    31         -Rather shall the value(s) of ''tcl_{non,}wordchars'' be used to
           30  +Rather shall the value\(s\) of _tcl\_\{non,\}wordchars_ be used to
    32     31   determine whether a given character is part of a word or not.
    33     32   
    34         -~Rationale
           33  +# Rationale
    35     34   
    36     35   Currently in Tcl there are different hard-coded ways to decide whether
    37     36   a certain character is a word character or a non word character.
    38     37   Different hard-coded ways also imply that changes on one side might
    39     38   not get over to the other side, so there soon are different hard-coded
    40     39   ways which yield different hard-coded results.  As a inference of it
    41     40   being hard-coded, this also means that there is no way to change or
    42     41   fix that potentially broken behavior.  Having Tcl lookup the values of
    43     42   those variables at runtime allows for the needed flexibility, both
    44     43   when dealing with nonstandard demands and nonstandard character sets.
    45     44   
    46     45   As an example of the breakage, you can assign a regular expression
    47         -to tcl_{,non}wordchars, and the double click binding in the textwidget
           46  +to tcl\_\{,non\}wordchars, and the double click binding in the textwidget
    48     47   will regard that pattern when marking a "whole word". When you try
    49     48   to ask the text widget to deliver the data under a certain coordinate
    50     49   with the indices 'wortstart' and 'wordend', the value of
    51         -tcl_{non,}wordchars is not used though.
           50  +tcl\_\{non,\}wordchars is not used though.
    52     51   
    53     52   There may be a problem with the performance of the lookup, but on the
    54         -other hand are C's ''is*()'' functions also implemented via a table
           53  +other hand are C's _is\*\(\)_ functions also implemented via a table
    55     54   lookup.  An installation of a caching static character table could
    56     55   guarantee the needed performance.
    57     56   
    58         -~Example of current word confusion
           57  +# Example of current word confusion
    59     58   
    60     59   Tk's text widget uses "word" in several ways:
    61     60   
    62         -1. selection by word (double-click + drag),
           61  +1. selection by word \(double-click \+ drag\),
    63     62   
    64         -2. movement by word ('insert wordstart'),
           63  +2. movement by word \('insert wordstart'\),
           64  +
           65  +3. regexp searching with \\m\\M wordmatching.
    65     66   
    66         -3. regexp searching with \m\M wordmatching.
    67         -
    68         -4. line breaks when wrapping (-wrap word)
           67  +4. line breaks when wrapping \(-wrap word\)
    69     68   
    70     69   It is not at all clear from reading Tcl or Tk's documentation what the
    71     70   behaviour of the above options will be.  It turns out that:
    72     71   
    73     72   1. after a convoluted call-chain, ends up calling
    74         -tcl_wordBreakAfter/Before which use tcl_wordchars and tcl_nonwordchars (which actually are defined differently on Windows vs Unix/MacOS!!).
           73  +tcl\_wordBreakAfter/Before which use tcl\_wordchars and tcl\_nonwordchars \(which actually are defined differently on Windows vs Unix/MacOS!!\).
           74  +
           75  +2. uses 'isalnum\(char\)' or '\_' to define a word \(hard-coded in Tk's
           76  +tkTextIndex.c\) \(in Tk8.5a0 this has been fixed to use _Tcl\_UniCharIsWordChar_\)
    75     77   
    76         -2. uses 'isalnum(char)' or '_' to define a word (hard-coded in Tk's
    77         -tkTextIndex.c) (in Tk8.5a0 this has been fixed to use ''Tcl_UniCharIsWordChar'')
           78  +3. uses Tcl's regexp engine's definition of a word \(this ought to be the same as that used in \(2\)\).
    78     79   
    79         -3. uses Tcl's regexp engine's definition of a word (this ought to be the same as that used in (2)).
    80         -
    81         -4. Anything separated by white-space from something else, used with '-wrap word' to define line-wrapping in text widgets (and canvases).
           80  +4. Anything separated by white-space from something else, used with '-wrap word' to define line-wrapping in text widgets \(and canvases\).
    82     81   
    83     82   It is quite likely that most of the above are different under some
    84     83   circumstances or some platforms/locales, and certainly if the
    85     84   user/developer wants to create a text widget with a different word
    86     85   definition, they basically can't in any consistent way.
    87     86   
    88         -~Implementation
           87  +# Implementation
    89     88   
    90     89   None yet.
    91     90   
    92         -~Copyright
           91  +# Copyright
    93     92   
    94     93   This document is placed in the public domain.
           94  +

Name change from tip/123.tip to tip/123.md.

     1         -TIP:            123
     2         -Title:          Adding an Exponentiation Operator to the [expr] Command
     3         -Version:        $Revision: 1.6 $
     4         -Author:         Arjen Markus <arjen.markus@wldelft.nl>
     5         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        16-Dec-2002
    10         -Post-History:   
    11         -Keywords:       mathematics,evaluation
    12         -Tcl-Version:    8.5
            1  +# TIP 123: Adding an Exponentiation Operator to the [expr] Command
            2  +	Author:         Arjen Markus <arjen.markus@wldelft.nl>
            3  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        16-Dec-2002
            8  +	Post-History:   
            9  +	Keywords:       mathematics,evaluation
           10  +	Tcl-Version:    8.5
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16     15   This TIP proposes to add a new operator to the operators recognised by
    17         -the [[expr]] command: the exponentiation operator.  This operator will
    18         -enhance the functionality of the current ''pow()'' function by
           16  +the [expr] command: the exponentiation operator.  This operator will
           17  +enhance the functionality of the current _pow\(\)_ function by
    19     18   returning a result that depends on the type of its operands.  It will
    20     19   also make complicated formulae more readable.
    21     20   
    22         -~ Introduction
           21  +# Introduction
    23     22   
    24         -Currently Tcl's [[expr]] command uses the exponentiation function
    25         -''pow()'' to calculate such expressions as "2 to the power 10".  The
           23  +Currently Tcl's [expr] command uses the exponentiation function
           24  +_pow\(\)_ to calculate such expressions as "2 to the power 10".  The
    26     25   drawback of this is twofold:
    27     26   
    28     27    * Expressions using several exponentiations become difficult to read.
    29     28      For instance, a third-degree polynomial looks like:
    30     29   
    31         -| 2.0*pow($x,3) - 1.2*pow($x,2) + 3.0*$x + 4.0
           30  +		 2.0*pow($x,3) - 1.2*pow($x,2) + 3.0*$x + 4.0
    32     31   
    33         - > or:
           32  +	 > or:
    34     33   
    35         -| 2.0*$x*$x*$x - 1.2*$x*$x + 3.0*$x + 4.0
           34  +		 2.0*$x*$x*$x - 1.2*$x*$x + 3.0*$x + 4.0
    36     35   
    37     36    * The result of raising an integer to an integer power is a
    38     37      double: 2 to the power 10 is 1024.0, not 1024.
    39     38   
    40     39   Other languages, like for instance FORTRAN, use an operator instead of
    41         -a function.  Two operators are commonly found: ** and ^.  As the
    42         -latter already has a meaning within the [[expr]] command, we propose
    43         -to add the "**" operator instead.  The above example would become:
           40  +a function.  Two operators are commonly found: \*\* and ^.  As the
           41  +latter already has a meaning within the [expr] command, we propose
           42  +to add the "\*\*" operator instead.  The above example would become:
    44     43   
    45         -| 2.0*$x**3 - 1.2*$x**2 + 3.0*$x + 4.0
           44  +	 2.0*$x**3 - 1.2*$x**2 + 3.0*$x + 4.0
    46     45   
    47         -~ Mathematical Details
           46  +# Mathematical Details
    48     47   
    49     48   The implementation of the exponentiation operator will have the
    50         -following properties (below we refer to the expression ''$x**$y''):
           49  +following properties \(below we refer to the expression _$x\*\*$y_\):
    51     50   
    52         -If ''x'' and ''y'' are both integers (ordinary or wide):
           51  +If _x_ and _y_ are both integers \(ordinary or wide\):
    53     52   
    54     53    * The result is of the same type as the widest operand
    55     54   
    56     55    * An error is raised if the operation makes no mathematical sense,
    57         -   ''0**(-1)'' for instance.
           56  +   _0\*\*\(-1\)_ for instance.
    58     57   
    59         - * If ''x'' has the value 0, then:
           58  + * If _x_ has the value 0, then:
    60     59   
    61         - > * if ''y > 0'', the result is 0
           60  +	 > \* if _y > 0_, the result is 0
    62     61   
    63         - > * if ''y < 0'', the result is an error
           62  +	 > \* if _y < 0_, the result is an error
    64     63   
    65         - > * if ''y == 0'', the result is 1
           64  +	 > \* if _y == 0_, the result is 1
    66     65   
    67         - * If ''x'' has the value 1, then the result is always 1
           66  + * If _x_ has the value 1, then the result is always 1
    68     67   
    69         - * If ''y'' has the value 0, the result is always 1
           68  + * If _y_ has the value 0, the result is always 1
    70     69   
    71         - * If ''x'' has a negative value lower than -1 and ''y < 0'', the
           70  + * If _x_ has a negative value lower than -1 and _y < 0_, the
    72     71      result is 0
    73     72   
    74         - * If ''x'' has the value -1, then depending on whether ''y'' is even
    75         -   or odd, the result is 1 or -1 (respectively.)
           73  + * If _x_ has the value -1, then depending on whether _y_ is even
           74  +   or odd, the result is 1 or -1 \(respectively.\)
    76     75   
    77         - * For all other combinations, the value is "''x'' raised to the power
    78         -   ''y''"
           76  + * For all other combinations, the value is "_x_ raised to the power
           77  +   _y_"
    79     78   
    80     79    * When evaluating this, no attention is paid to overflow, even though
    81         -   the result might fit into a wide integer (though of course the
    82         -   result will be a wide integer if either operand was wide.)  This is
    83         -   in accordance with the type model used in other [[expr]] operators.
           80  +   the result might fit into a wide integer \(though of course the
           81  +   result will be a wide integer if either operand was wide.\)  This is
           82  +   in accordance with the type model used in other [expr] operators.
    84     83   
    85         -If either ''x'' or ''y'' is a double, the C function ''pow()'' is used
           84  +If either _x_ or _y_ is a double, the C function _pow\(\)_ is used
    86     85   to compute the result.
    87     86   
    88     87   The following expressions are parsed and evaluated in accordance with
    89     88   all other operators:
    90     89   
    91         -| $x ** $y ** $z ==> ($x ** $y ) ** $z
    92         -| $x ** -1       ==> ($x ** (-1))
           90  +	 $x ** $y ** $z ==> ($x ** $y ) ** $z
           91  +	 $x ** -1       ==> ($x ** (-1))
    93     92   
    94         -The precedence of the exponentiation operator is thus ''higher'' than
           93  +The precedence of the exponentiation operator is thus _higher_ than
    95     94   the multiplication, division and remainder operations and lower than
    96     95   the unary operations, in accordance with common definitions.
    97     96   
    98         -~ Sample Implementation
           97  +# Sample Implementation
    99     98   
   100         -http://sf.net/tracker/?func=detail&aid=655176&group_id=10894&atid=310894
           99  +<http://sf.net/tracker/?func=detail&aid=655176&group\_id=10894&atid=310894>
   101    100   
   102         -~ Copyright
          101  +# Copyright
   103    102   
   104    103   This document is placed in the public domain.
          104  +

Name change from tip/124.tip to tip/124.md.

     1         -TIP:            124
     2         -Title:          High-Resolution Absolute Time Values From [clock]
     3         -Version:        $Revision: 1.13 $
     4         -Author:         Mark Harrison <mh@pixar.com>
     5         -Author:         Kevin Kenny <kennykb@users.sourceforge.net>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        20-Dec-2002
    10         -Post-History:   
    11         -Tcl-Version:    8.5
            1  +# TIP 124: High-Resolution Absolute Time Values From [clock]
            2  +	Author:         Mark Harrison <mh@pixar.com>
            3  +	Author:         Kevin Kenny <kennykb@users.sourceforge.net>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        20-Dec-2002
            8  +	Post-History:   
            9  +	Tcl-Version:    8.5
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15         -This TIP proposes altering the '''clock clicks''' command to add
    16         -a '''-microseconds''' option, and to tie it to an absolute reference.
           14  +This TIP proposes altering the **clock clicks** command to add
           15  +a **-microseconds** option, and to tie it to an absolute reference.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20         -The '''clock clicks''' command is a useful feature for analyzing and
           19  +The **clock clicks** command is a useful feature for analyzing and
    21     20   tuning performance in Tcl programs.  Since the timer is relative,
    22     21   however, it is difficult to correlate times between two programs or
    23     22   with timestamps stored in a log file.
    24     23   
    25         -~ Proposed change
           24  +# Proposed change
    26     25   
    27         -This TIP proposes two changes to '''clock clicks''' to make it more
           26  +This TIP proposes two changes to **clock clicks** to make it more
    28     27   useful in situations where absolute times are needed:
    29     28   
    30         -   1. Change '''clock clicks -milliseconds''' to return a wide integer,
           29  +   1. Change **clock clicks -milliseconds** to return a wide integer,
    31     30         representing the number of milliseconds since the Posix epoch.
    32     31   
    33         -   1. Add a '''clock clicks -microseconds''' that likewise returns
           32  +   1. Add a **clock clicks -microseconds** that likewise returns
    34     33         a wide integer, representing the number of microseconds since
    35     34         the Posix epoch.
    36     35   
    37         -~ Compatibility with existing code
           36  +# Compatibility with existing code
    38     37   
    39     38   Now that Tcl supports 64-bit integers transparently, compatibility
    40     39   with existing code is unlikely to cause trouble.  In practice, the
    41         -only uses of '''clock clicks''' that the authors have seen all simply
           40  +only uses of **clock clicks** that the authors have seen all simply
    42     41   compute the difference between two successive values.  Since the
    43     42   difference will continue to fit in 32 bits if it did so before,
    44     43   such code will simply continue to work.
    45     44   
    46     45   The change from a relative standard to an absolute one is
    47     46   likewise transparent.  One fact that supports this claim is that
    48         -such a change was made in '''clock clicks -milliseconds''' on Windows
    49         -in support of [7], and no Windows users reported trouble as
           47  +such a change was made in **clock clicks -milliseconds** on Windows
           48  +in support of [[7]](7.md), and no Windows users reported trouble as
    50     49   a result.
    51     50   
    52         -Code that attempts to use '''clock clicks'' as an absolute standard
    53         -by correlating its values with those returned from '''clock seconds'''
    54         -(as in http://wiki.tcl.tk/1035) will also continue to work without
    55         -without change, although the improvements to '''clock clicks''' will
           51  +Code that attempts to use **clock clicks_ as an absolute standard
           52  +by correlating its values with those returned from **clock seconds**
           53  +\(as in <http://wiki.tcl.tk/1035\)> will also continue to work without
           54  +without change, although the improvements to **clock clicks** will
    56     55   certainly provide a better way to do it.
    57     56   
    58         -~ Reference Implementation
           57  +# Reference Implementation
    59     58   
    60     59   The original reference implementation at
    61     60   
    62         -http://sf.net/tracker/?func=detail&atid=310894&aid=656997&group_id=10894
           61  +<http://sf.net/tracker/?func=detail&atid=310894&aid=656997&group\_id=10894>
    63     62   
    64     63   presents an interface that has since been superseded. The
    65     64   reference implementation will be updated at such time as this
    66     65   TIP is approved.
    67     66   
    68         -~ Copyright
           67  +# Copyright
    69     68   
    70     69   This document has been placed in the public domain.
    71     70   
    72         -~ Comments
           71  +# Comments
    73     72   
    74         -Gerald Lester also points out (in the Tcl'ers Chat) that we ought
           73  +Gerald Lester also points out \(in the Tcl'ers Chat\) that we ought
    75     74   to make [clock seconds] return a wide value at the same time as
    76     75   we implement the rest of these changes, in order to address the
    77         -Y2038 problem.  Alas, the problem goes deeper; the ''gettimeofday()''
    78         -call (and Tcl's mirroring of it in the ''Tcl_GetTime'' interface) is
           76  +Y2038 problem.  Alas, the problem goes deeper; the _gettimeofday\(\)_
           77  +call \(and Tcl's mirroring of it in the _Tcl\_GetTime_ interface\) is
    79     78   not Y2038-ready. The necessary upgrades to return a 64-bit value
    80     79   for [clock seconds] are outside the scope of this TIP.
    81     80   
    82     81   Several people have informally asked whether 64 bits are enough
    83         -to hold the microsecond counter.  Since 2**64 microseconds is
           82  +to hold the microsecond counter.  Since 2\*\*64 microseconds is
    84     83   roughly half a million years, the authors are confident that
    85     84   the answer is, "yes."
           85  +

Name change from tip/125.tip to tip/125.md.

     1         -TIP:            125
     2         -Title:          Converting between Frame and Toplevel Windows
     3         -Version:        $Revision: 1.10 $
     4         -Author:         Brian Griffin <bgriffin@model.com>
     5         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     6         -Author:         Sacha Schär <sacha.schaer@unibas.ch>
     7         -State:          Final
     8         -Type:           Project
     9         -Vote:           Done
    10         -Created:        20-Jan-2003
    11         -Post-History:   
    12         -Keywords:       reparent,Tk
    13         -Tcl-Version:    8.5
            1  +# TIP 125: Converting between Frame and Toplevel Windows
            2  +	Author:         Brian Griffin <bgriffin@model.com>
            3  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            4  +	Author:         Sacha Schär <sacha.schaer@unibas.ch>
            5  +	State:          Final
            6  +	Type:           Project
            7  +	Vote:           Done
            8  +	Created:        20-Jan-2003
            9  +	Post-History:   
           10  +	Keywords:       reparent,Tk
           11  +	Tcl-Version:    8.5
           12  +-----
    14     13   
    15         -~ Abstract
           14  +# Abstract
    16     15   
    17         -This TIP modifies the '''wm''' command to act as a geometry manager for
           16  +This TIP modifies the **wm** command to act as a geometry manager for
    18     17   Frames, allowing them to become Toplevel windows.
    19     18   
    20         -~ Rationale
           19  +# Rationale
    21     20   
    22     21   One of the usability features introduced recently in many windowing systems,
    23     22   is the ability to "tear out" or "insert" sub-frames and panes within an
    24     23   application. The most common form of this is the ability to tear off a
    25     24   toolbar, making it an independent window. This feature gives the end user the
    26     25   ability to configure the application in ways that best suit them and improve
    27     26   their overall productivity.
................................................................................
    28     27   
    29     28   Currently there is no mechanism with Tk to move a widget subtree to a new
    30     29   toplevel parent without reconstructing the hierarchy from scratch. The basic
    31     30   command will give the Tk programmer the ability to implement megawidgets that
    32     31   support tear-off toolbars, notebooks, etc., since the children widgets of the
    33     32   frame will follow along, unchanged.
    34     33   
    35         -An alternative approach has been taken from the orignal '''wm toplevel'''
           34  +An alternative approach has been taken from the orignal **wm toplevel**
    36     35   proposal as described here:
    37     36   
    38     37   In Tk, Toplevel windows are basically a special form of a Frame which are
    39         -managed by the window manager. The proposal is to add the commands '''wm
    40         -manage''' and '''wm forget''' which will take an arbitrary Frame and allow it
           38  +managed by the window manager. The proposal is to add the commands **wm
           39  +manage** and **wm forget** which will take an arbitrary Frame and allow it
    41     40   to be managed by the window manager, making it a Toplevel window.
    42     41   
    43     42   There are three configure options of Toplevel that are not present on a frame,
    44         -'''-menu''', '''-screen''', and '''-use'''. The options '''-screen''' and
    45         -'''-use''' can only be specified when a Toplevel is created and cannot be
    46         -modified later. The '''-menu''' option can be modified after widget creation
           43  +**-menu**, **-screen**, and **-use**. The options **-screen** and
           44  +**-use** can only be specified when a Toplevel is created and cannot be
           45  +modified later. The **-menu** option can be modified after widget creation
    47     46   and should be available on a frame so that when the frame is managed as a
    48     47   Toplevel, the menu can be present, therefore, this option has been added to
    49         -the Frame widget. When a frame is not managed as a toplevel, the '''-menu'''
           48  +the Frame widget. When a frame is not managed as a toplevel, the **-menu**
    50     49   option is ignored.
    51     50   
    52     51   Note: because of special conditions of Toplevel, it is necessary to restrict
    53     52   them to only be managed by the window manager; they cannot be converted to
    54         -frames and therefore, '''wm forget''' is not allowed on a Toplevel widget.
           53  +frames and therefore, **wm forget** is not allowed on a Toplevel widget.
    55     54   
    56         -~ Reference Implementation
           55  +# Reference Implementation
    57     56   
    58         -TkToolkit patch #998125 implements the '''wm manage''' and '''wm forget'''
           57  +TkToolkit patch \#998125 implements the **wm manage** and **wm forget**
    59     58   commands on Unix and Windows. A partial MacOSX implementation is also
    60     59   provided. This implementation only works for buttons and menubuttons. For the
    61         -remaining Tk widgets to be present in a '''wm manage''''d frame, the widgets
    62         -need to recognize and implement the TK_URBAN_RENEWAL flag.
           60  +remaining Tk widgets to be present in a **wm manage**'d frame, the widgets
           61  +need to recognize and implement the TK\_URBAN\_RENEWAL flag.
    63     62   
    64         -The original '''wm toplevel''' implementation can be obtained
           63  +The original **wm toplevel** implementation can be obtained
    65     64   [ftp://ftp.model.com/pub/tcl/reframe], with patch files as well as Linux and
    66     65   Win32 builds of 8.3.4 and 8.4.1 available.
    67     66   
    68         -The ''demo.tcl'' file illustrates the basic function.
           67  +The _demo.tcl_ file illustrates the basic function.
    69     68   
    70         -~ Known Issues
           69  +# Known Issues
    71     70   
    72     71   The reference implementation works on Windows and Linux. A Mac implementation
    73     72   has been partially implemented. Because of the Mac architecture, it is
    74     73   necessary to reconstruct widgets in order to remap their window hierarchy.
    75         -The reference implementation includes a widget flag, TK_URBAN_RENEWAL which is
           74  +The reference implementation includes a widget flag, TK\_URBAN\_RENEWAL which is
    76     75   used to trigger this reconstruction.
    77     76   
    78     77   Because of assumptions and restrictions, Toplevels can only be managed by the
    79     78   window manager and cannot become frames and be managed by any other geometry
    80         -manager. This restriction is enforced which means the '''-use''' and
    81         -'''-screen''' options do not present any problem or complication with this
           79  +manager. This restriction is enforced which means the **-use** and
           80  +**-screen** options do not present any problem or complication with this
    82     81   proposal.
    83     82   
    84         -The toplevel '''-menu''' option has been added to frames. This allows the
           83  +The toplevel **-menu** option has been added to frames. This allows the
    85     84   setting of menus on a frame so that when the frame is managed as a toplevel,
    86     85   the menus will appear, otherwise the option is ignored.
    87     86   
    88         -~ Alternatives
           87  +# Alternatives
    89     88   
    90         -An alternative to extending the '''wm''' command is to make this feature
           89  +An alternative to extending the **wm** command is to make this feature
    91     90   either a method or a configure option of the Toplevel and Frame widget.
    92     91   
    93         -''A.'' [[''w'' '''detach''']] to convert a Frame into a Toplevel, and [[''w''
    94         -attach''']] to convert a Toplevel into a Frame.
           92  +_A._ [_w_ **detach**] to convert a Frame into a Toplevel, and [_w_
           93  +attach**] to convert a Toplevel into a Frame.
    95     94   
    96         -''B.'' [[''w'' '''configure -toplevel 1''']] to convert a Frame into a
    97         -Toplevel, and [[''w'' '''configure -toplevel 0''']] to convert a Toplevel into
           95  +_B._ [_w_ **configure -toplevel 1**] to convert a Frame into a
           96  +Toplevel, and [_w_ **configure -toplevel 0**] to convert a Toplevel into
    98     97   a Frame.
    99     98   
   100         -These different approaches (wm, method, config) depend on how the feature is
   101         -viewed. One view is that the of changing the nature or class (Toplevel, Frame)
           99  +These different approaches \(wm, method, config\) depend on how the feature is
          100  +viewed. One view is that the of changing the nature or class \(Toplevel, Frame\)
   102    101   of the widget. An alternative view is that of changing "who" manages the
   103         -widget (wm, place, grid, pack).
          102  +widget \(wm, place, grid, pack\).
   104    103   
   105    104   I suppose another alternative is to follow the precedent of the geometry
   106    105   managers:
   107    106   
   108         - * '''wm''' ''w'' ?'''-transient''' ''parent''? ?'''-overrideredirect'''
   109         -   ''boolean''? ...
          107  + * **wm** _w_ ?**-transient** _parent_? ?**-overrideredirect**
          108  +   _boolean_? ...
          109  +
          110  + * **wm forget** _w_
   110    111   
   111         - * '''wm forget''' ''w''
          112  +# Comments
   112    113   
   113         -~ Comments
   114         -
   115         -''From Sacha Schär <sacha.schaer@unibas.ch>:''
          114  +_From Sacha Schär <sacha.schaer@unibas.ch>:_
   116    115   
   117    116   The way the TIP and its alternatives are proposed, a frame can be made into a
   118    117   toplevel and vice versa. However, it is not possible, to move a frame from one
   119    118   toplevel to another. This is of importance even for the most common motivation
   120    119   for this TIP, the possibility to implement a tear-off behaviour. If a frame is
   121    120   going to be teared out of a toplevel window, it might be desirable that it
   122    121   becomes part of another toplevel window, together with some extra decoration.
   123    122   
   124    123   I see, that with this more general behaviour, the path name becomes a problem.
   125         -Therefore I propose the alternative approach, of making the '''-container'''
   126         -and '''-use''' options dynamically configurable as already discussed in the
          124  +Therefore I propose the alternative approach, of making the **-container**
          125  +and **-use** options dynamically configurable as already discussed in the
   127    126   past
   128    127   
   129         -''From Brian:''
          128  +_From Brian:_
   130    129   
   131    130   The problem is that we can't reparent widgets without changing their Tk widget
   132    131   pathname. Doing this introduces all kinds of sticky problems.
   133    132   
   134    133   In practice, the decoration is in the form of Menus, Toolbars, and Footers.
   135         -All of these things can (must) be created and managed as part of the
          134  +All of these things can \(must\) be created and managed as part of the
   136    135   dock/undock process. The way to do this is to create these things the first
   137    136   time a window is undocked, then just "hide" them when redocking the window;
   138    137   they still exist, but are just not mapped anywhere, until the next time the
   139    138   window is undocked.
   140    139   
   141         -The bottom line is that the '''wm manage''' command does not do ''everything''
          140  +The bottom line is that the **wm manage** command does not do _everything_
   142    141   you need when performing an undock operation; it is only a small piece of the
   143    142   pie, but a very critical one.
   144    143   
   145         -~ Copyright
          144  +# Copyright
   146    145   
   147    146   This document has been placed in the public domain.
          147  +

Name change from tip/126.tip to tip/126.md.

     1         -TIP:		126
     2         -Title:		Rich Strings for Representation Persistence
     3         -Created:	30-Jan-2003
     4         -Author:		Donal K. Fellows <donal.k.fellows@man.ac.uk>
     5         -Type:		Project
     6         -Tcl-Version:	9.0
     7         -Vote:		Pending
     8         -State:		Draft
     9         -Version:	$Revision: 1.1 $
    10         -Post-History:	
            1  +# TIP 126: Rich Strings for Representation Persistence
            2  +	Created:	30-Jan-2003
            3  +	Author:		Donal K. Fellows <donal.k.fellows@man.ac.uk>
            4  +	Type:		Project
            5  +	Tcl-Version:	9.0
            6  +	Vote:		Pending
            7  +	State:		Draft
            8  +	Post-History:	
            9  +-----
    11     10   
    12         -~Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP enriches the standard UTF-8 string representation of every
    15         -''Tcl_Obj'' to allow for improved persistence of non-string
           14  +_Tcl\_Obj_ to allow for improved persistence of non-string
    16     15   representations.  This, combined with rules for substring and
    17     16   substitution handling, allows the lifetime of an object to correspond
    18     17   far more closely with the more-broadly understood concept of "object
    19     18   lifetime".
    20     19   
    21         -~Rationale
           20  +# Rationale
    22     21   
    23     22   At the moment in Tcl, whenever someone wants to create a stateful
    24         -entity of limited lifespan (i.e. an object) and pass it through a Tcl
           23  +entity of limited lifespan \(i.e. an object\) and pass it through a Tcl
    25     24   script, they have to do one of two things:
    26     25   
    27         - 1. Tie the lifespan of the object to the lifespan of the ''Tcl_Obj''
           26  + 1. Tie the lifespan of the object to the lifespan of the _Tcl\_Obj_
    28     27       value that represents it, so that when the internal representation
    29     28       of the value is deleted, so to is the object.
    30     29   
    31         - 2. Create a table (typically a hash table) of objects and have the
           30  + 2. Create a table \(typically a hash table\) of objects and have the
    32     31       value passed through the Tcl script be a handle that is really an
    33     32       index into this table.  Deletion happens precisely when some kind
    34     33       of delete "method" is called on the object.
    35     34   
    36     35   Each of these techniques has problems.  With the first, difficulties
    37     36   arise because it is a fundamental assumption of Tcl that it is always
    38     37   possible to recreate the internal-representation part of a value from
    39     38   the string-representation part of the value.  While this is a good
    40     39   assumption for lists, numbers, etc. it is not true for anything where
    41     40   the deletion of the internal-rep results in the deletion of the
    42     41   underlying data structure.  Thus, there is a tendency for the object
    43         -to get deleted far too early.  (In practise, the problem occurs in
    44         -locations like scripts passed to Tk's [[bind]] command and in some
    45         -invocations of the [[eval]] command.)  Nevertheless, this technique
           42  +to get deleted far too early.  \(In practise, the problem occurs in
           43  +locations like scripts passed to Tk's [bind] command and in some
           44  +invocations of the [eval] command.\)  Nevertheless, this technique
    46     45   can be used subject to some caveats, and this is done in a number of
    47         -extensions (e.g. TclBlend/Jacl, where Java objects are passed through
    48         -Tcl this way.)
           46  +extensions \(e.g. TclBlend/Jacl, where Java objects are passed through
           47  +Tcl this way.\)
    49     48   
    50     49   However, the second technique has a different set of troubles.
    51     50   Although the process of explicit deletion works around all the faults
    52     51   with over-early deletion as described above, it instead has a strong
    53     52   tendency to not delete objects at all; it is far too easy to have a
    54     53   resource leak that is fairly difficult to track down.  Most Tcl
    55         -extensions that deal with objects (and all the ones that predate
    56         -Tcl8.0, like [[incr Tcl]]) use this technique.
           54  +extensions that deal with objects \(and all the ones that predate
           55  +Tcl8.0, like [incr Tcl]\) use this technique.
    57     56   
    58     57   What we really need is a way to allow non-string object
    59     58   representations to persist substantially longer, so making the first
    60     59   of the two techniques outlined above much more robust.  In particular,
    61     60   I have identified the string concatenation, string substitution and
    62     61   substring operations as being in need of attention, though obviously
    63         -the required work will extend further as well (the script parser is an
    64         -obvious target.)  This is the focus of this TIP.
           62  +the required work will extend further as well \(the script parser is an
           63  +obvious target.\)  This is the focus of this TIP.
    65     64   
    66         -~Alterations to the Tcl_Obj
           65  +# Alterations to the Tcl\_Obj
    67     66   
    68     67   So, what is the best way of maintaining these valuable representations
    69         -within a supposedly pure-string Tcl_Obj value?  Well, since we do not
    70         -want to alter the internal representation (after all, it is that which
    71         -we would really like to preserve) we will have to add an extra field
    72         -(or potentially more) to the Tcl_Obj structure itself.  This is
           68  +within a supposedly pure-string Tcl\_Obj value?  Well, since we do not
           69  +want to alter the internal representation \(after all, it is that which
           70  +we would really like to preserve\) we will have to add an extra field
           71  +\(or potentially more\) to the Tcl\_Obj structure itself.  This is
    73     72   technically feasible in a backward-compatible way, as allocation of
    74     73   instances of this structure have always been performed by the Tcl
    75     74   library, but there is a significant downside to this in that the
    76     75   structure is far and away the most common structure allocated in the
    77     76   entire Tcl core.  Any field added will have a significant impact on
    78     77   the overall memory consumption of any Tcl-enabled binary.
    79     78   
    80     79   What information do we actually need to store for these
    81     80   representations to be preserved in a string while allowing extraction
    82     81   of the underlying values?  The simplest possible option is for a list
    83     82   of string-subrange/object-reference pairs to be associated with the
    84     83   object, probably as an array of simple structures pointed to by a new
    85         -field of the Tcl_Obj (with a NULL indicating that no range of the
    86         -string has an object associated with it.)  The easiest way of
           84  +field of the Tcl\_Obj \(with a NULL indicating that no range of the
           85  +string has an object associated with it.\)  The easiest way of
    87     86   representing those string ranges is as pairs of byte-indexes relative
    88     87   to the start of the string, though character-indexes have much to
    89         -commend them (especially when working with strings with a UCS-16
    90         -internal representation) as do direct pointers into the string (easy
           88  +commend them \(especially when working with strings with a UCS-16
           89  +internal representation\) as do direct pointers into the string \(easy
    91     90   to compute, but much more problematic when another string is
    92         -appended.)  The end of the list would be marked in some obvious way,
           91  +appended.\)  The end of the list would be marked in some obvious way,
    93     92   probably by using a NULL in the object-reference part.
    94     93   
    95     94   This mechanism has the advantage that it keeps the increase in size of
    96         -the Tcl_Obj itself fairly small (i.e. an extra 4 bytes for another
    97         -pointer on 32-bit platforms) which is an advantage when you consider
           95  +the Tcl\_Obj itself fairly small \(i.e. an extra 4 bytes for another
           96  +pointer on 32-bit platforms\) which is an advantage when you consider
    98     97   the fact that it is likely that most strings in an average Tcl program
    99     98   will not have objects contained within them.  This will act to
   100     99   minimise the overall memory overhead.
   101    100   
   102         -~Concatenation, Substitution and Substring Semantics
          101  +# Concatenation, Substitution and Substring Semantics
   103    102   
   104    103   When two strings with these object annotations are concatenated, it is
   105         -clear that the resulting string should also have the annotations (and
          104  +clear that the resulting string should also have the annotations \(and
   106    105   the actual human-readable part will use the string-representation of
   107         -the objects), and this is trivially extended to arbitrary
          106  +the objects\), and this is trivially extended to arbitrary
   108    107   concatenations of strings.  Similarly for the taking of substrings
   109    108   with the following restrictions:
   110    109   
   111    110    1. Where the portion of substring taken corresponds exactly to the
   112    111       part of a string associated with an object, the operation shall
   113         -    instead return the object in question (which shall be assumed to
   114         -    have a compatible string representation.)
          112  +    instead return the object in question \(which shall be assumed to
          113  +    have a compatible string representation.\)
   115    114   
   116    115    2. Where a substring wholly contains a range associated with some
   117    116       object, then the resulting substring object will also contain the
   118    117       object associated with the "same" characters.
   119    118   
   120    119    3. Where a substring only partially overlaps a range associated with
   121    120       an object, that object will not be associated with the
   122         -    corresponding characters in the resultant substring (unless the
          121  +    corresponding characters in the resultant substring \(unless the
   123    122       object is separately part of the substring due to the other rules,
   124         -    of course.)  The object is associated with the string segment as a
          123  +    of course.\)  The object is associated with the string segment as a
   125    124       whole, and not any one part of it.
   126    125   
   127    126   Substitution, whether of variable contents, script execution results
   128    127   or anything else, is semantically a concatenation operation where some
   129         -strings are (as it were) immediate operands and others are derived
          128  +strings are \(as it were\) immediate operands and others are derived
   130    129   from reading variables, executing scripts, etc.
   131    130   
   132         -Thus, if we start variable ''a'' containing an object ''Ob1'' and
   133         -variable ''b'' containing an object ''Ob2'', the following shall be
          131  +Thus, if we start variable _a_ containing an object _Ob1_ and
          132  +variable _b_ containing an object _Ob2_, the following shall be
   134    133   true:
   135    134   
   136         -|set var x${a}y${b}z        => xOb1yOb2z
   137         -|#  where characters 1-3 are assocaited with Ob1
   138         -|#    and characters 5-7 are associated with Ob2
   139         -|set c [string range $var 1 3]
   140         -|#  precisely equivalent to [set c $a]
   141         -|set d [string range $var 5 7]
   142         -|#  precisely equivalent to [set d $b]
          135  +	set var x${a}y${b}z        => xOb1yOb2z
          136  +	#  where characters 1-3 are assocaited with Ob1
          137  +	#    and characters 5-7 are associated with Ob2
          138  +	set c [string range $var 1 3]
          139  +	#  precisely equivalent to [set c $a]
          140  +	set d [string range $var 5 7]
          141  +	#  precisely equivalent to [set d $b]
   143    142   
   144         -~Consequences
          143  +# Consequences
   145    144   
   146    145   It is an obvious consequence of this that script evaluation should
   147    146   take into account of these object annotations when attached to the
   148    147   scripts themselves, particularly as the process of parsing can really
   149         -be regarded as being mostly the taking of (suitable) substrings.  Only
          148  +be regarded as being mostly the taking of \(suitable\) substrings.  Only
   150    149   slightly less obviously, it is also the responsibility of all code
   151         -that stores strings (and especially scripts) for future use to store
   152         -them as ''Tcl_Obj'' instances and not as just plain character strings,
          150  +that stores strings \(and especially scripts\) for future use to store
          151  +them as _Tcl\_Obj_ instances and not as just plain character strings,
   153    152   and to perform any substitutions it needs to perform in a way that
   154    153   preserves these object annotations on the parts that it is not
   155    154   interested in.  This in turn will probably require changes on the part
   156    155   of many extensions to actually turn into reality.
   157    156   
   158         -On the other hand, there are quite a few objects (numbers and boolean
   159         -values are probably very good examples here) for which this
          157  +On the other hand, there are quite a few objects \(numbers and boolean
          158  +values are probably very good examples here\) for which this
   160    159   representation preservation is probably not a very good option as the
   161    160   objects in question are perfectly preservable.  It makes sense to add
   162         -some kind of signalling mechanism (e.g. a bit in a newly added
   163         -''flags'' field) to allow the type of a ''Tcl_Obj'' instance to
          161  +some kind of signalling mechanism \(e.g. a bit in a newly added
          162  +_flags_ field\) to allow the type of a _Tcl\_Obj_ instance to
   164    163   declare that it need not be preserved.  As a general note, such a flag
   165         -would only be useful in "leaf" objects; structural objects (i.e. those
   166         -that are intended to contain others, like lists) would be expected to
          164  +would only be useful in "leaf" objects; structural objects \(i.e. those
          165  +that are intended to contain others, like lists\) would be expected to
   167    166   do without this.
   168    167   
   169         -Strings (now a structural as opposed to a leaf type) probably need
          168  +Strings \(now a structural as opposed to a leaf type\) probably need
   170    169   even more special handling, but that can really be regarded as a
   171    170   type-specific special case.
   172    171   
   173    172   The flags field mentioned a few paragraphs above would probably have
   174         -other potential uses (e.g. for marking an object as being impossible
   175         -to change into any other type) though these lie outside the scope of
          173  +other potential uses \(e.g. for marking an object as being impossible
          174  +to change into any other type\) though these lie outside the scope of
   176    175   this TIP.
   177    176   
   178    177   Because these changes at the C API level are far reaching and fairly
   179    178   subtle in some cases, this TIP explicitly seeks to introduce this
   180    179   behaviour with a major version number change.  Although the alteration
   181    180   at the script level should be small - existing code should continue
   182    181   working without alteration - it is a huge philosophical leap as it
   183    182   will no longer be the case that everything in Tcl will be a string, or
   184         -at least not a string that you (or anyone else) can type.  Again, that
          183  +at least not a string that you \(or anyone else\) can type.  Again, that
   185    184   implies introduction at a new major version number.
   186    185   
   187         -~Notes
          186  +# Notes
   188    187   
   189         - * The existing API function ''Tcl_InvalidateStringRep'' will gain
          188  + * The existing API function _Tcl\_InvalidateStringRep_ will gain
   190    189      additional significance with the introduction of this TIP: its
   191    190      invocation may well trigger the deletion of many objects.
   192    191   
   193    192    * It is probably a very good idea indeed for code that creates
   194    193      objects whose lifespan is meant to persist, to create those objects
   195    194      with string representations composed entirely of alphanumeric
   196    195      characters.  An ideal choice might be to use a prefix derived from
   197    196      the type/class of the object, and a suffix that is the address of
   198    197      the object or the next value from some counter variable.
   199    198   
   200         -~Copyright
          199  +# Copyright
   201    200   
   202    201   This document is placed in the public domain.
          202  +

Name change from tip/127.tip to tip/127.md.

     1         -TIP:            127
     2         -Title:          Add an -index Option to [lsearch]
     3         -Version:        $Revision: 1.13 $
     4         -Author:         Michael Schlenker <schlenk@uni-oldenburg.de>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        26-Feb-2003
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 127: Add an -index Option to [lsearch]
            2  +	Author:         Michael Schlenker <schlenk@uni-oldenburg.de>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        26-Feb-2003
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -Matching the ''lsort'' functionality a ''-index'' option should be
    15         -added to the ''lsearch'' command to make searching lists in list
    16         -easier. The ''lsort -index'' and the ''lsearch -index'' options should
    17         -accept list style indices like ''lindex'' and ''lset'' do.  This TIP
           13  +Matching the _lsort_ functionality a _-index_ option should be
           14  +added to the _lsearch_ command to make searching lists in list
           15  +easier. The _lsort -index_ and the _lsearch -index_ options should
           16  +accept list style indices like _lindex_ and _lset_ do.  This TIP
    18     17   proposes such added options.
    19     18   
    20         -~ Specification
           19  +# Specification
    21     20   
    22         -Under this proposal the syntax of the ''lsearch'' is to be modified to
           21  +Under this proposal the syntax of the _lsearch_ is to be modified to
    23     22   accept two extra options. 
    24     23   
    25         -The ''-index'' option:
           24  +The _-index_ option:
    26     25   
    27         -The ''lsort'' -index option would get enhanced with multiple index
           26  +The _lsort_ -index option would get enhanced with multiple index
    28     27   support.
    29     28   
    30         -|    lsearch ?-index index? 
           29  +	    lsearch ?-index index? 
    31     30   
    32         -The ''-index'' option should work similar to the ''-index'' option
    33         -in the ''lsort'' command.
           31  +The _-index_ option should work similar to the _-index_ option
           32  +in the _lsort_ command.
    34     33   
    35     34   If this option is specified, each of the elements of list must itself
    36     35   be a proper Tcl sublist.  Instead of searching based on whole
    37         -sublists, ''lsearch'' will extract the index'th element from each
           36  +sublists, _lsearch_ will extract the index'th element from each
    38     37   sublist and search based on the given element.  The keyword end is
    39     38   allowed for the index to search on the last sublist element, and
    40     39   end-index searches on a sublist element offset from the end. For
    41     40   example,
    42     41   
    43         -|    lsearch -integer -index 1 {{First 24} {Second 18} {Third 30}} 18
           42  +	    lsearch -integer -index 1 {{First 24} {Second 18} {Third 30}} 18
    44     43   
    45         -returns ''1'', and
           44  +returns _1_, and
    46     45   
    47         -|    lsearch -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} d
           46  +	    lsearch -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} d
    48     47   
    49         -returns ''2''.
           48  +returns _2_.
    50     49   
    51         -The index given to ''lsearch -index'' and ''lsort -index'' may be
    52         -either a single scalar index as in the current ''lsort''
    53         -implementation or the argument to ''-index'' may be a list of scalar
    54         -indices (similar, but not exactly like the lset/lindex multiple
    55         -indices).  The -index option causes lsearch and lsort to extract the
           50  +The index given to _lsearch -index_ and _lsort -index_ may be
           51  +either a single scalar index as in the current _lsort_
           52  +implementation or the argument to _-index_ may be a list of scalar
           53  +indices \(similar, but not exactly like the lset/lindex multiple
           54  +indices\).  The -index option causes lsearch and lsort to extract the
    56     55   item for searching or sorting comparision from the list element by
    57         -using in effect ''lindex $element $index''.
           56  +using in effect _lindex $element $index_.
    58     57   
    59     58   For example:
    60     59   
    61         -|    set record {
    62         -|        {
    63         -|          {James Dean} {Musician} {some other data}
    64         -|        }
    65         -|        {
    66         -|          {Elvis Presley} {Musician} {some more data}
    67         -|        }
    68         -|     }
    69         -|
    70         -|   lsearch -index {0 0} $record "Elvis"
           60  +	    set record {
           61  +	        {
           62  +	          {James Dean} {Musician} {some other data}
           63  +	        }
           64  +	        {
           65  +	          {Elvis Presley} {Musician} {some more data}
           66  +	        }
           67  +	     }
           68  +	
           69  +	   lsearch -index {0 0} $record "Elvis"
    71     70   
    72         -returns ''1''.
           71  +returns _1_.
    73     72   
    74         -|   lsort -dictionary -decreasing -index {0 1} $record
           73  +	   lsort -dictionary -decreasing -index {0 1} $record
    75     74   
    76         -returns ''{{{Elvis Presley} {Musician} {some more data}} {{James Dean}
    77         -{Musician} {some other data}}}''.
           75  +returns _\{\{\{Elvis Presley\} \{Musician\} \{some more data\}\} \{\{James Dean\}
           76  +\{Musician\} \{some other data\}\}\}_.
    78     77   
    79     78   Note: The following example is invalid, -index only takes a list as
    80     79   argument, unlike lset and lindex, that take either a list or multiple
    81     80   arguments, that get concatenated by the command.
    82     81   
    83         -| lsearch -index 1 1 $record Presley
           82  +	 lsearch -index 1 1 $record Presley
    84     83   
    85         -The ''-subindices'' option:
           84  +The _-subindices_ option:
    86     85   
    87         -The ''-subindices'' option should be added only to the ''lsearch''
           86  +The _-subindices_ option should be added only to the _lsearch_
    88     87   command as a convenience shortcut. It is only a valid option if the
    89         -''-index'' option is also used.
           88  +_-index_ option is also used.
    90     89   
    91         -If ''-subindices'' is given, ''lsearch'' should return a list of
    92         -indices that can be used directly by ''lindex'' or ''lset'' to
           90  +If _-subindices_ is given, _lsearch_ should return a list of
           91  +indices that can be used directly by _lindex_ or _lset_ to
    93     92   manipulate the element used for searching, instead of the top level
    94     93   element of the list.
    95     94   
    96         -If ''-subindices'' and ''-inline'' are specified at the same time, the
           95  +If _-subindices_ and _-inline_ are specified at the same time, the
    97     96   command returns the value instead of the index.
    98     97   
    99     98   example:
   100     99   
   101         -| lsearch -subindices -index {0 0} $record Elvis
          100  +	 lsearch -subindices -index {0 0} $record Elvis
   102    101   
   103         -returns ''{1 0 0}''.
          102  +returns _\{1 0 0\}_.
   104    103   
   105    104   If no -all option is specified, this is the same as doing:
   106    105   
   107         -| concat [lsearch -index {0 0} $record Elvis] [list 0 0]
          106  +	 concat [lsearch -index {0 0} $record Elvis] [list 0 0]
   108    107   
   109         -~ Rationale
          108  +# Rationale
   110    109   
   111    110   Lists containing one or more level of sublists are a common technique to
   112    111   simulated complex data structures like matrices or records, or for
   113         -results from database queries.  The ''lsort'' command was enhanced
   114         -with the ''-index'' option for this case, to handle sorting on sublist
          112  +results from database queries.  The _lsort_ command was enhanced
          113  +with the _-index_ option for this case, to handle sorting on sublist
   115    114   keys.
   116    115   
   117         -The ''lsearch'' command does not have this functionality yet, one has
   118         -to use ''foreach'' and ''lindex'' to loop over the list one by one.
          116  +The _lsearch_ command does not have this functionality yet, one has
          117  +to use _foreach_ and _lindex_ to loop over the list one by one.
   119    118   
   120         -Multiple indices for the ''-index'' option to both ''lsearch'' and
   121         -''lsort'' should be added, to make the option more similar to ''lset''
   122         -and ''lindex'' style indices.
          119  +Multiple indices for the _-index_ option to both _lsearch_ and
          120  +_lsort_ should be added, to make the option more similar to _lset_
          121  +and _lindex_ style indices.
   123    122   
   124         -The ''-subindices'' option is a convenience option to make constructs
          123  +The _-subindices_ option is a convenience option to make constructs
   125    124   like this example work well:
   126    125   
   127         -| foreach item [lsearch -all -subindices -index {0 0} $record bla] {
   128         -|         lset record $item bar
   129         -| }
          126  +	 foreach item [lsearch -all -subindices -index {0 0} $record bla] {
          127  +	         lset record $item bar
          128  +	 }
   130    129   
   131    130   Without the subindices option it could be written as:
   132    131   
   133         -| foreach item [lsearch -all -index $idx $record bla] {
   134         -|         lset record [concat $idx $item] bar
   135         -| }
          132  +	 foreach item [lsearch -all -index $idx $record bla] {
          133  +	         lset record [concat $idx $item] bar
          134  +	 }
   136    135   
   137         -~ Reference Implementation
          136  +# Reference Implementation
   138    137   
   139    138   A reference implementation exists, see the files attached to the Tcl
   140    139   Patch 693836 on SourceForge.
   141         -http://sf.net/tracker/?func=detail&atid=310894&aid=693836&group_id=10894
          140  +<http://sf.net/tracker/?func=detail&atid=310894&aid=693836&group\_id=10894>
   142    141   
   143    142   The reference implementation isn't honouring the -inline option if
   144    143   given in conjuction with -subindices, at the moment.
   145    144   
   146         -~ Copyright
          145  +# Copyright
   147    146   
   148    147   This document has been placed in the public domain.
          148  +

Name change from tip/128.tip to tip/128.md.

     1         -TIP:            128
     2         -Title:          Ability to Install a Custom Memory Allocator
     3         -Version:        $Revision: 1.5 $
     4         -Author:         Christophe Cap <udragon@users.sourceforge.net>
     5         -Author:         Mike Jackson <hhyJackson1275@who-got-mail.com>
     6         -State:          Rejected
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        13-Mar-2003
    10         -Post-History:   
    11         -Tcl-Version:    8.6
            1  +# TIP 128: Ability to Install a Custom Memory Allocator
            2  +	Author:         Christophe Cap <udragon@users.sourceforge.net>
            3  +	Author:         Mike Jackson <hhyJackson1275@who-got-mail.com>
            4  +	State:          Rejected
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        13-Mar-2003
            8  +	Post-History:   
            9  +	Tcl-Version:    8.6
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15         -This TIP alters Tcl to allow embedded uses of the Tcl library (and any
    16         -extensions) to either use the Tcl memory allocators as their main
    17         -allocator (especially in C++) or to set the memory allocator that Tcl
    18         -uses for itself through ''ckalloc()''.
           14  +This TIP alters Tcl to allow embedded uses of the Tcl library \(and any
           15  +extensions\) to either use the Tcl memory allocators as their main
           16  +allocator \(especially in C\+\+\) or to set the memory allocator that Tcl
           17  +uses for itself through _ckalloc\(\)_.
    19     18   
    20         -~ Background
           19  +# Background
    21     20   
    22     21   A while ago I was experiencing troubles when allocating images
    23         -([[image create photo]]) while memory was already exhausted, my app
    24         -crashed (due to known bug item #698571, which is in the HEAD by now!)
           22  +\([image create photo]\) while memory was already exhausted, my app
           23  +crashed \(due to known bug item \#698571, which is in the HEAD by now!\)
    25     24   This shouldn't happen anyway since my application had it's new handler
    26     25   set.
    27     26   
    28     27   Tracing down the source of the allocators I noticed that Tcl uses
    29         -''HeapAlloc()'' (on Win32) to allocate its memory.  Why not use
    30         -''malloc()''?
           28  +_HeapAlloc\(\)_ \(on Win32\) to allocate its memory.  Why not use
           29  +_malloc\(\)_?
    31     30   
    32         -~ New/Malloc Handler 
           31  +# New/Malloc Handler 
    33     32   
    34     33   It would be nice to be able to catch memory allocation errors with a
    35     34   custom new handler.
    36     35   
    37         -A solution could be to replace ''HeapAlloc()'' (on Win32) and other
    38         -platform specific memory handlers should be replaced by ''malloc()''.
           36  +A solution could be to replace _HeapAlloc\(\)_ \(on Win32\) and other
           37  +platform specific memory handlers should be replaced by _malloc\(\)_.
    39     38   
    40         -This way a new handler can by set through ''set_new_handler()''.
           39  +This way a new handler can by set through _set\_new\_handler\(\)_.
    41     40   
    42         -Note that the Microsoft VC++ compiler has some ANSI incompatibility in
    43         -that it uses ''_set_new_handler()'' rather than ''set_new_handler()''.
           41  +Note that the Microsoft VC\+\+ compiler has some ANSI incompatibility in
           42  +that it uses _\_set\_new\_handler\(\)_ rather than _set\_new\_handler\(\)_.
    44     43   We would naturally conceal this platform difference.
    45     44   
    46     45   For example:
    47     46   
    48         -|#include <new> 
    49         -|
    50         -|//
    51         -|// New handler for Microsoft Visual C++ compiler
    52         -|//
    53         -|
    54         -|#ifdef _MSC_VER
    55         -|#include <new.h>
    56         -|
    57         -|int __cdecl _newHandler(size_t size )
    58         -|{
    59         -|   // Do whatever
    60         -|
    61         -|   return 0;
    62         -|}
    63         -|
    64         -|#else
    65         -|
    66         -|//
    67         -|// Ansi C/C++ new handler
    68         -|//
    69         -|
    70         -|void __cdecl _newHandler( void )
    71         -|{
    72         -|   // Do whatever
    73         -|}
    74         -|#endif
    75         -|
    76         -|void sethandlers(void)
    77         -|{
    78         -|// Microsoft compiler 
    79         -|#ifdef _MSC_VER  
    80         -|
    81         -|   _set_new_handler (_newHandler); // Setup new handler
    82         -|   _set_new_mode( 1 ); // Re-route malloc failures to new handler !
    83         -|
    84         -|// Ansi compiler 
    85         -|
    86         -|#else 
    87         -|
    88         -|   set_new_handler (_newHandler); // ANSI new handler
    89         -|
    90         -|#endif
    91         -|}
           47  +	#include <new> 
           48  +	
           49  +	//
           50  +	// New handler for Microsoft Visual C++ compiler
           51  +	//
           52  +	
           53  +	#ifdef _MSC_VER
           54  +	#include <new.h>
           55  +	
           56  +	int __cdecl _newHandler(size_t size )
           57  +	{
           58  +	   // Do whatever
           59  +	
           60  +	   return 0;
           61  +	}
           62  +	
           63  +	#else
           64  +	
           65  +	//
           66  +	// Ansi C/C++ new handler
           67  +	//
           68  +	
           69  +	void __cdecl _newHandler( void )
           70  +	{
           71  +	   // Do whatever
           72  +	}
           73  +	#endif
           74  +	
           75  +	void sethandlers(void)
           76  +	{
           77  +	// Microsoft compiler 
           78  +	#ifdef _MSC_VER  
           79  +	
           80  +	   _set_new_handler (_newHandler); // Setup new handler
           81  +	   _set_new_mode( 1 ); // Re-route malloc failures to new handler !
           82  +	
           83  +	// Ansi compiler 
           84  +	
           85  +	#else 
           86  +	
           87  +	   set_new_handler (_newHandler); // ANSI new handler
           88  +	
           89  +	#endif
           90  +	}
    92     91   
    93         -~ Tcl Implementation 
           92  +# Tcl Implementation 
    94     93   
    95     94   The above suggested solution could work for some compilers, but may
    96         -not for all (some compilers might not support setting a malloc failure
    97         -callback.)  Therefore a Tcl custom new handler functionality could be
           95  +not for all \(some compilers might not support setting a malloc failure
           96  +callback.\)  Therefore a Tcl custom new handler functionality could be
    98     97   implemented that handles Tcl specific memory allocation failures.
    99     98   
   100         -Something like: ''Tcl_SetMemHandler()''?
           99  +Something like: _Tcl\_SetMemHandler\(\)_?
   101    100   
   102         -~ Copyright
          101  +# Copyright
   103    102   
   104    103   This document has been placed in the public domain.
          104  +

Name change from tip/129.tip to tip/129.md.

     1         -TIP:            129
     2         -Title:          New Format Codes for the [binary] Command
     3         -Version:        $Revision: 1.5 $
     4         -Author:         Arjen Markus <arjen.markus@wldelft.nl>
     5         -Author:         Torsten Reincke <reincke@typoscriptics.de>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        14-Mar-2003
    10         -Post-History:   
    11         -Keywords:       IEEE,binary data,Tcl
    12         -Tcl-Version:    8.5
            1  +# TIP 129: New Format Codes for the [binary] Command
            2  +	Author:         Arjen Markus <arjen.markus@wldelft.nl>
            3  +	Author:         Torsten Reincke <reincke@typoscriptics.de>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        14-Mar-2003
            8  +	Post-History:   
            9  +	Keywords:       IEEE,binary data,Tcl
           10  +	Tcl-Version:    8.5
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16         -This TIP proposes to add a set of new format codes to the '''binary'''
           15  +This TIP proposes to add a set of new format codes to the **binary**
    17     16   command to enhance its ability to deal with especially non-native
    18     17   floating-point data.  The assumption is that current limitations are
    19     18   due to the distinction between little-endian and big-endian storage of
    20     19   such data.
    21     20   
    22         -~ Introduction
           21  +# Introduction
    23     22   
    24         -The current '''binary''' command can manipulate little-endian and
    25         -big-endian ''integer'' data, but only ''native'' floating-point data.
           23  +The current **binary** command can manipulate little-endian and
           24  +big-endian _integer_ data, but only _native_ floating-point data.
    26     25   This means that binary data from other computer systems that use a
    27     26   different representation of floating-point data can not be directly
    28     27   handled.
    29     28   
    30     29   The lack of format codes to handle "native" integer data means that
    31     30   one has to distinguish the current platform's byte ordering to be
    32         -platform-independent, whenever the '''binary''' command is used.
           31  +platform-independent, whenever the **binary** command is used.
    33     32   
    34     33   Most current computer systems use either little-endian or big-endian
    35     34   byte order and the so-called IEEE representation for the exponent and
    36     35   mantissa.  So, the main variation to deal with is the endian-ness.
    37     36   
    38     37   Some popular file formats, like ESRI's ArcView shape files, use both
    39         -types of byte order.  It is difficult (though not impossible) to
           38  +types of byte order.  It is difficult \(though not impossible\) to
    40     39   handle these files with the current set of format codes.
    41     40   
    42         -It should be noted that there ''is'' more variety among floating-point
           41  +It should be noted that there _is_ more variety among floating-point
    43     42   representation than just the byte order.  This TIP will not solve this
    44     43   more general problem.
    45     44   
    46         -~ Proposed Format Codes
           45  +# Proposed Format Codes
    47     46   
    48     47   Format codes should be available to catch the two main varieties of
    49     48   byte ordering.  There should, both for reasons of symmetry and for
    50     49   practical purposes, also be a full set to deal with "native" data.
    51     50   
    52     51   For integer types there are no codes to deal with native ordering. So:
    53     52   
    54         - * '''t''' (tiny) for short integers, using native ordering.
           53  + * **t** \(tiny\) for short integers, using native ordering.
    55     54   
    56         - * '''n''' (normal) for ordinary integers, using native ordering.
           55  + * **n** \(normal\) for ordinary integers, using native ordering.
    57     56   
    58         - * '''m''' (mirror of "w") for wide integers, using native ordering.
           57  + * **m** \(mirror of "w"\) for wide integers, using native ordering.
    59     58   
    60     59   The floating-point types will be handled via:
    61     60   
    62         - * '''r'''/'''R''' (real) for single-precision reals.
           61  + * **r**/**R** \(real\) for single-precision reals.
    63     62   
    64         - * '''q'''/'''Q''' (mirror of "d") for double-precision reals.
           63  + * **q**/**Q** \(mirror of "d"\) for double-precision reals.
    65     64   
    66     65   where the lower-case is associated with little-endian order and the
    67     66   upper-case with big-endian order.
    68     67   
    69         -~ Implementation Notes
           68  +# Implementation Notes
    70     69   
    71     70   The implementation for the integer types is simple:
    72     71   
    73     72    * The new format codes are synonyms for the current ones, but
    74     73      different ones for each endian-ness.
    75     74   
    76     75   The implementation for the floating-point types is somewhat more
    77     76   complicated, this involves adding byte swapping, if the ordering of
    78     77   the platform does not correspond to that of the format code.
    79     78   
    80         -~ Copyright
           79  +# Copyright
    81     80   
    82     81   This document is placed in the public domain.
           82  +

Name change from tip/13.tip to tip/13.md.

     1         -TIP:            13
     2         -Title:          Web Service for Drafting and Archiving TIPs
     3         -Version:        $Revision: 1.26 $
     4         -Author:         Don Porter <dgp@users.sourceforge.net>
     5         -Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
     6         -State:          Accepted
     7         -Type:           Process
     8         -Vote:           Done
     9         -Created:        21-Nov-2000
    10         -Post-History:   
            1  +# TIP 13: Web Service for Drafting and Archiving TIPs
            2  +	Author:         Don Porter <dgp@users.sourceforge.net>
            3  +	Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
            4  +	State:          Accepted
            5  +	Type:           Process
            6  +	Vote:           Done
            7  +	Created:        21-Nov-2000
            8  +	Post-History:   
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This document proposes the TCT provide a service on the World Wide
    15     14   Web for drafting and archiving TIPs and for providing TIPs in a
    16     15   variety of formats.  A reference implementation is provided, and its
    17     16   server requirements are outlined.
    18     17   
    19         -~ Background
           18  +# Background
    20     19   
    21         -It has been proposed (see [2]) that the TCT manage its projects and
           20  +It has been proposed \(see [[2]](2.md)\) that the TCT manage its projects and
    22     21   procedures through a set of public documents known as Tcl Improvement
    23         -Proposals, or TIPs.  A format for TIPs has been approved (see [3]),
    24         -and although final approval of [2] is still pending, several TIPs
           22  +Proposals, or TIPs.  A format for TIPs has been approved \(see [[3]](3.md)\),
           23  +and although final approval of [[2]](2.md) is still pending, several TIPs
    25     24   have been submitted, discussed, and revised, and a few have been
    26     25   approved, so acceptance of TIPs in some form seems likely.
    27     26   
    28     27   A prototype system has been provided by Donal
    29     28   Fellows <fellowsd@cs.man.ac.uk>
    30         -[http://www.cs.man.ac.uk/fellowsd-bin/TIP/]
           29  +<http://www.cs.man.ac.uk/fellowsd-bin/TIP/> 
    31     30   that delivers TIPs to visitors in a variety of formats.  However,
    32     31   that system lacks archiving of each revision of each TIP, and
    33         -offers no interface (through the web or otherwise) for making
           32  +offers no interface \(through the web or otherwise\) for making
    34     33   revisions to TIPs.  
    35     34   
    36     35   The TIP format was inspired by the format used by the Tcl'ers
    37         -Wiki [http://www.purl.org/thecliff/tcl/wiki/].  The true power
           36  +Wiki <http://www.purl.org/thecliff/tcl/wiki/> .  The true power
    38     37   of the Tcl'ers Wiki, though, is not in the particular format it
    39     38   uses, but in the fact that it empowers the whole Tcl community to
    40     39   contribute to a common set of resources.  The Tcl'ers Wiki
    41     40   shows that valuable resources can arise out of the unrestricted
    42     41   efforts of volunteers from the community.
    43     42   
    44         -~ Problems with Current TIP Infrastructure.
           43  +# Problems with Current TIP Infrastructure.
    45     44   
    46     45   The Fellows web interface to the TIP Document Collection
    47         -[http://www.cs.man.ac.uk/fellowsd-bin/TIP/] offers valuable
           46  +<http://www.cs.man.ac.uk/fellowsd-bin/TIP/>  offers valuable
    48     47   browsing access to TIPs in a variety of formats.  It accomplishes
    49     48   the important goal of making TIPs public.  However, it suffers from
    50     49   two significant shortcomings:
    51     50   
    52     51      * Revisions are only possible through the TIP Editor:
    53     52   
    54         -   > Currently the only way to revise a TIP is to e-mail a new
           53  +	   > Currently the only way to revise a TIP is to e-mail a new
    55     54        revision to the TIP Editor and wait for it to replace the old
    56     55        revision.  As more TIPs are submitted, and as each TIP is more
    57     56        frequently revised, this bottleneck will not be tolerable.
    58     57   
    59         -   > Discussion about TIPs currently takes place in Usenet newsgroups
           58  +	   > Discussion about TIPs currently takes place in Usenet newsgroups
    60     59        and on mailing lists, but because there is no easy access to
    61     60        revising the TIPs themselves, the new information and viewpoints
    62     61        arising in these discussions are not being folded back into the
    63     62        TIPs.  This means the TIPs are failing in their intended role to
    64     63        present a full history of an issue to later readers.  It also
    65     64        means newcomers to a TIP cannot receive a full briefing in one
    66     65        place, but must chase down discussions in mailing list and Usenet
    67     66        archives.  Few people do that, but instead repeat points already
    68         -     made.  The discussions about [6] reflect this problem.
           67  +     made.  The discussions about [[6]](6.md) reflect this problem.
    69     68   
    70     69      * An archive of each revision of each TIP is not maintained:
    71     70   
    72         -   > Although [2] refers to TIPs as being stored in a revision control
           71  +	   > Although [[2]](2.md) refers to TIPs as being stored in a revision control
    73     72        system, probably a CVS repository, the Fellows TIP collection is
    74     73        not maintained in such a system.  Since a TIP is an archive of a
    75     74        public discussion of an issue, it is important to be able to
    76     75        access the history of changes to each TIP.
    77     76   
    78         -   > The ability to retrieve and restore earlier revisions of a TIP
           77  +	   > The ability to retrieve and restore earlier revisions of a TIP
    79     78        will be especially important if public revision is permitted, so
    80     79        that any TIP contents that are incorrectly removed, whether by
    81     80        accident or malice, can be restored.
    82     81   
    83         -~ Proposal
           82  +# Proposal
    84     83   
    85     84   An improved system for archiving and revising TIPs is proposed:
    86     85   
    87     86      1. TIPs will be archived in a CVS repository.
    88     87   
    89     88      1. Anyone with the power to call a TYANNOTT vote will have commit
    90     89         access to this repository through either :pserver: or ssh
    91     90         access.  With this access, they will be able to revise any part
    92         -      (header or body) of any TIP (whether in ''State: Draft'' or
    93         -      not).  Everyone having this access will be trusted to modify
           91  +      \(header or body\) of any TIP \(whether in _State: Draft_ or
           92  +      not\).  Everyone having this access will be trusted to modify
    94     93         TIPs only in conformance with the TIP format and the TCT
    95     94         procedures.
    96     95   
    97     96      1. An enhanced version of the Fellows TIP rendering engine will
    98         -      display an [[Edit]] link at the bottom of each TIP eligible
           97  +      display an [Edit] link at the bottom of each TIP eligible
    99     98         for web-editing when that TIP is rendered in HTML.
   100     99   
   101    100      1. For any TIP in state Draft, and for which a vote is still
   102         -      pending, the [[Edit]] link will lead to an HTML form for
   103         -      submitting a revised TIP.  For other TIPs, no [[Edit]] link
          101  +      pending, the [Edit] link will lead to an HTML form for
          102  +      submitting a revised TIP.  For other TIPs, no [Edit] link
   104    103         will appear, and an attempt to directly access web-editing of
   105    104         such a TIP will lead to a message stating that the TIP may not
   106    105         be edited through the web interface.
   107    106   
   108    107      1. The HTML editing form will display the TIP header, but will not
   109    108         make it available for editing.  The HTML form will require that
   110    109         an e-mail address be entered, and will allow a name to be
................................................................................
   116    115      1. The TIP rendering engine will receive the revisions, and
   117    116         will use CVS client commands to merge the revisions with other
   118    117         revisions and commit the revised TIP to the TIP CVS repository.
   119    118         If a conflict occurs during a merge, the TIP body including the
   120    119         conflicts will be returned to the user in another HTML form to
   121    120         resolve the conflict.
   122    121   
   123         -    > Note that the CVS commit function of the TIP rendering engine
          122  +	    > Note that the CVS commit function of the TIP rendering engine
   124    123         implies that the CGI process in which the TIP rendering engine
   125    124         runs must have a user ID with commit access to the TIP CVS
   126    125         repository.
   127    126   
   128    127      1. In the revised TIP checked in to CVS the submitter of the
   129    128         revision will be added as an Author in the header of that TIP.
   130    129   
   131         -~ Reference Implementation
          130  +# Reference Implementation
   132    131   
   133    132   The modifications to the Fellows TIP rendering engine that add the
   134    133   capabilities proposed above are now merged in.  The TIP rendering
   135    134   engine is maintained and publically available
   136         -[http://sourceforge.net/projects/tiprender/].  To enable the
   137         -web-editing features, set the Tcl variable FEATURE(EDIT) to 1 in
          135  +<http://sourceforge.net/projects/tiprender/> .  To enable the
          136  +web-editing features, set the Tcl variable FEATURE\(EDIT\) to 1 in
   138    137   the file config.tcl.  A working version of the proposed web service
   139         -is available at http://purl.org/tcl/tip/
          138  +is available at <http://purl.org/tcl/tip/>
   140    139   
   141    140   For what it's worth, this TIP was created primarily within a web
   142    141   browser, making revisions through the web interface provided by the
   143    142   reference implementation.
   144    143   
   145    144   One remaining shortcoming of the reference implementation is that it
   146    145   provides no mechanism for uploading images to the TIP repository.
   147    146   Images still need to be submitted through the TIP Editor, or
   148    147   someone else with commit access to the TIP CVS repository.
   149    148   
   150         -~ Server Requirements
          149  +# Server Requirements
   151    150   
   152    151   The reference implementation imposes the following requirements on a
   153    152   server:
   154    153   
   155    154      1. The server provides an HTTP server that serves the public
   156    155         Internet, and supports the CGI interface.
   157    156   
   158    157      1. CVS client software must be installed on the server.
   159    158   
   160    159      1. The CVS repository containing TIPs must be on the server itself.
   161         -      This is due to a CVS limitation that ''loginfo'' scripts run on
          160  +      This is due to a CVS limitation that _loginfo_ scripts run on
   162    161         the machine housing the CVS repository, and the reference
   163         -      implementation uses a ''loginfo'' script to keep the TIPs
          162  +      implementation uses a _loginfo_ script to keep the TIPs
   164    163         presented through the web up to date with the commits to the
   165    164         repository.
   166    165   
   167    166      1. The CVS repository must offer commit access over the Internet
   168    167         using either :pserver: or ssh to everyone with authority to call
   169    168         a TYANNOTT vote.
   170    169   
   171    170      1. The user under which the HTTP server runs its CGI processes must
   172    171         have commit access to the TIP CVS repository.  This may have
   173    172         security implications.
   174    173   
   175         -~ Future Improvements
          174  +# Future Improvements
   176    175   
   177    176   Once the TIPs are housed in a CVS repository, other services should be
   178    177   easier to implement.  Another browsing interface could be provided
   179         -using cvsweb [http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/] to
          178  +using cvsweb <http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/>  to
   180    179   allow anyone in the community to browse TIP history.  Another
   181         -''loginfo'' script could provide e-mail notices when a TIP is revised
          180  +_loginfo_ script could provide e-mail notices when a TIP is revised
   182    181   to users who registered their interest in that TIP.
   183    182   
   184         -~ Acknowledgments
          183  +# Acknowledgments
   185    184   
   186    185   Thanks to Donal Fellows for the original TIP rendering engine and
   187    186   his assistance merging in the changes.  Thanks to Brent Welch for
   188    187   providing the server and his assistance getting it configured for
   189    188   use.  Thanks to Mark Harrison for his assistance with managing
   190    189   browser caching issues.
   191    190   
   192    191   ----
   193    192   
   194         -~ Comments from the TCT
          193  +# Comments from the TCT
   195    194   
   196    195    > It might be a good idea to make the Abstract into a seperate <textarea> and
   197    196      treat that specially; I've been applying the rule that a TIP's abstract
   198         -   should be a single paragraph (it is implicit in the way I generate XML for
   199         -   instance) and that would be much easier to enforce through this route.  It
          197  +   should be a single paragraph \(it is implicit in the way I generate XML for
          198  +   instance\) and that would be much easier to enforce through this route.  It
   200    199      would also have the advantage of discouraging people from placing their
   201    200      whole rationale in the abstract - which I've seen in several first drafts by
   202    201      people who shall remain nameless - and prompting the creation of TIPs more in
   203    202      keeping with the general concept of publishable documents.
   204    203   
   205    204    > It would also be nice if each page had a way of viewing the TIP's revision
   206         -   history (by a link to a suitably setup CVSweb URL?)  The way that SourceForge
          205  +   history \(by a link to a suitably setup CVSweb URL?\)  The way that SourceForge
   207    206      does its CVS-over-the-web is very nice indeed...
   208    207   
   209         - > ''Donal K. Fellows <fellowsd@cs.man.ac.uk>''
          208  + > _Donal K. Fellows <fellowsd@cs.man.ac.uk>_
   210    209   
   211         -~ Author replies to comments
          210  +# Author replies to comments
   212    211   
   213    212   Some comments I see above, or received in e-mail:
   214    213   
   215         - * ''Add a link to [3] on the edit page.  Display [3] in a new window.''
          214  + * _Add a link to [[3]](3.md) on the edit page.  Display [[3]](3.md) in a new window._
   216    215   
   217         - > Link added.  I don't believe in deciding to open new browser windows for
          216  +	 > Link added.  I don't believe in deciding to open new browser windows for
   218    217      the user.  If the user wants to open the link in a new window, she knows
   219    218      how to do that.
   220    219   
   221         - * ''Add an interface to create a new TIP''
          220  + * _Add an interface to create a new TIP_
   222    221   
   223         - > For now, I'm trying to stick with the TIP procedures proposed in [2],
          222  +	 > For now, I'm trying to stick with the TIP procedures proposed in [[2]](2.md),
   224    223      where only the TIP Editor gets to create a new TIP, so all TIPs
   225    224      should still be originally submitted to him.  If the TCT rejects
   226    225      this proposal and adopts a different policy, we can revisit this
   227    226      question.
   228    227   
   229         - * ''Browser caching makes it look like the edits were not made''
          228  + * _Browser caching makes it look like the edits were not made_
   230    229   
   231         - > Based on advice from Mark Harrison and others, I've added HTTP
          230  +	 > Based on advice from Mark Harrison and others, I've added HTTP
   232    231      headers that should prevent caching.  Please try it again.
   233    232   
   234         - * ''I had the server time out on me''
          233  + * _I had the server time out on me_
   235    234   
   236         - > That's troubling.  Can anyone seeing this problem provide any more
          235  +	 > That's troubling.  Can anyone seeing this problem provide any more
   237    236      information.  What were the circumstances, in detail?
   238    237   
   239         - * ''Add links to an interface showing revision history''
          238  + * _Add links to an interface showing revision history_
          239  +
          240  +	 > Check out the [History] links at the bottom of the HTML rendered pages.
          241  +   Thanks to Donal Fellows for coding that up.  \(OK, so we \*did\* reinvent
          242  +   CVSWeb.\)
          243  +
          244  + * _A separate <TEXTAREA> for the Abstract_
   240    245   
   241         - > Check out the [History] links at the bottom of the HTML rendered pages.
   242         -   Thanks to Donal Fellows for coding that up.  (OK, so we *did* reinvent
   243         -   CVSWeb.)
          246  +	 > This is now implemented.  Please give it a try.
   244    247   
   245         - * ''A separate <TEXTAREA> for the Abstract''
   246         -
   247         - > This is now implemented.  Please give it a try.
   248         -
   249         -~ Copyright
          248  +# Copyright
   250    249   
   251    250   This document has been placed in the public domain.
          251  +

Name change from tip/130.tip to tip/130.md.

     1         -TIP:		130
     2         -Title:		Unique DDE server names.
     3         -Version:	$Revision: 1.4 $
     4         -Author:		Pat Thoyts <patthoyts@users.sourceforge.net>
     5         -State:		Final
     6         -Tcl-Version:	8.5
     7         -Created:	23-Mar-2003
     8         -Type:		Project
     9         -Vote:		Done
    10         -Post-History:	
            1  +# TIP 130: Unique DDE server names.
            2  +	Author:		Pat Thoyts <patthoyts@users.sourceforge.net>
            3  +	State:		Final
            4  +	Tcl-Version:	8.5
            5  +	Created:	23-Mar-2003
            6  +	Type:		Project
            7  +	Vote:		Done
            8  +	Post-History:	
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -The ''dde'' package server registration code should ensure that the
           13  +The _dde_ package server registration code should ensure that the
    15     14   server names are unique. The proposed changes will mean end-user
    16     15   visible changes for some scripts.
    17     16   
    18         -~ Rationale
           17  +# Rationale
    19     18   
    20     19   This TIP is really driven by Bug 219293
    21         -[[http://sf.net/tracker/?func=detail&aid=219293&group_id=10894&atid=110894]]
           20  +<http://sf.net/tracker/?func=detail&aid=219293&group_id=10894&atid=110894> 
    22     21   
    23     22   The DDE system actually identifies servers by combination of window ID
    24     23   and a service and topic string identifier. There is nothing to prevent
    25     24   multiple servers having the same string identifiers but it is then a
    26     25   problem to determine which server you need to communicate with.
    27     26   
    28         -The ''tk appname'' command handles a similar situation by making the
           27  +The _tk appname_ command handles a similar situation by making the
    29     28   name unique during registration by appending a numerical suffix to the
    30     29   suggested name and then returning the name registered as the result of
    31     30   the command.
    32     31   
    33         -~ Proposed Changes
           32  +# Proposed Changes
    34     33   
    35         -This TIP proposes to use the ''tk appname'' unique name algorithm
           34  +This TIP proposes to use the _tk appname_ unique name algorithm
    36     35   within the DDE server-name registration code.  This TIP also proposes a
    37         -''-force'' option to this command to force the suggested name to be
    38         -registered.  The ''-force'' option would then provide the current
           36  +_-force_ option to this command to force the suggested name to be
           37  +registered.  The _-force_ option would then provide the current
    39     38   registration scheme.
    40     39   
    41         -~ Reference Implementation
           40  +# Reference Implementation
    42     41   
    43     42   See the patch attached to SF patch 690354
    44         -[https://sourceforge.net/tracker/?func=detail&aid=690354&group_id=10894&atid=310894]
           43  +<https://sourceforge.net/tracker/?func=detail&aid=690354&group_id=10894&atid=310894> 
    45     44   
    46         -~ Consequences
           45  +# Consequences
    47     46   
    48         -Firstly the ''dde servername'' command may register a different name
           47  +Firstly the _dde servername_ command may register a different name
    49     48   than that provided to the command.  Scripts will need to check the
    50     49   name actually registered by either maintaining the result of this
    51         -command, or by executing the ''dde servername'' command without any
           50  +command, or by executing the _dde servername_ command without any
    52     51   arguments.  This may impact scripts that assume the supplied argument
    53     52   was in fact the name registered.
    54     53   
    55     54   Secondly, the name registration code must obtain a list of the dde
    56     55   server names currently registered on the system.  It can do this by
    57         -effectively calling ''dde services TclEval''.  In previous versions of
    58         -the ''dde'' package there is a potential for the ''dde services''
           56  +effectively calling _dde services TclEval_.  In previous versions of
           57  +the _dde_ package there is a potential for the _dde services_
    59     58   command to hang in the presence of applications that are not
    60     59   processing messages.  However, this issue has been addressed by Bug
    61     60   707822's resolution.
    62     61   
    63         -~ Copyright
           62  +# Copyright
    64     63   
    65     64   This document is hereby placed in the public domain.
           65  +

Name change from tip/131.tip to tip/131.md.

     1         -TIP:		131
     2         -Title:		Read My Mind and Do What I Mean
     3         -Version:	$Revision: 1.2 $
     4         -Author:		Joe English <jenglish@flightlab.com>
     5         -State:		Draft
     6         -Type:		Project
     7         -Vote:		No voting
     8         -Tcl-Version:	8.5
     9         -Created:	01-Apr-2003
    10         -Post-History:	
            1  +# TIP 131: Read My Mind and Do What I Mean
            2  +	Author:		Joe English <jenglish@flightlab.com>
            3  +	State:		Draft
            4  +	Type:		Project
            5  +	Vote:		No voting
            6  +	Tcl-Version:	8.5
            7  +	Created:	01-Apr-2003
            8  +	Post-History:	
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14         -A new Tcl command is proposed, ''rmmadwim''.  This is an acronym for
    15         -``Read My Mind and Do What I Mean''.  This command has obvious
           13  +A new Tcl command is proposed, _rmmadwim_.  This is an acronym for
           14  +\`\`Read My Mind and Do What I Mean_.  This command has obvious
    16     15   utility.
    17     16   
    18         -~ Specification
           17  +# Specification
    19     18   
    20         -The ''rmmadwim'' command shall take no arguments.  When invoked, the
           19  +The _rmmadwim_ command shall take no arguments.  When invoked, the
    21     20   Tcl interpreter shall read the programmer's mind and do what he or she
    22     21   intends.
    23     22   
    24         -''NOTE:'' It is very important that ''rmmadwim'' read the
    25         -''programmer's'' mind, not the end user's.  Otherwise the consequences
           23  +_NOTE:_ It is very important that _rmmadwim_ read the
           24  +_programmer's_ mind, not the end user's.  Otherwise the consequences
    26     25   could be disastrous, since end users rarely have a firm grasp of what
    27     26   the original programmer was up to.
    28     27   
    29     28   As a consequence of this command, there is also a corresponding
    30         -function for ''expr'' which applies the same principles to general
           29  +function for _expr_ which applies the same principles to general
    31     30   mathematical computation:
    32     31   
    33         -|  set result [expr {rmmadwim()}]
           32  +	  set result [expr {rmmadwim()}]
    34     33   
    35     34   This extra functionality is easy to enable:
    36     35   
    37         -|  rmmadwim
           36  +	  rmmadwim
    38     37   
    39         -~ Rationale
           38  +# Rationale
    40     39   
    41     40   What Tcl needs in order to succeed in the marketplace is a feature
    42     41   that no other programming language provides, a "killer app" as it
    43     42   were.  The Tk toolkit, Expect, cross-platform portability, scripted
    44         -documents, tkcon, and the [[incr Tcl]] "toaster" example are all well
           43  +documents, tkcon, and the [incr Tcl] "toaster" example are all well
    45     44   and good, but they have clearly failed to push Tcl usage to the point
    46         -of having critical mass.  The ''rmmadwim'' command would provide a
           45  +of having critical mass.  The _rmmadwim_ command would provide a
    47     46   powerful enough incentive that even Perl programmers would be
    48     47   compelled to switch languages.
    49     48   
    50         -~ Reference Implementation
           49  +# Reference Implementation
    51     50   
    52     51   A skeletal implementation is included below.  Clearly some of the
    53     52   details remain to be flushed out, but this is a simple matter of
    54         -programming (SMOP).  It should be a fun weekend project for Richard
           53  +programming \(SMOP\).  It should be a fun weekend project for Richard
    55     54   Suchenwirth.
    56     55   
    57         -File: ''tcl/generic/tclCmdMZ.c''
           56  +File: _tcl/generic/tclCmdMZ.c_
    58     57   
    59         -Function: ''Tcl_RmmAndDWIMObjCmd''
           58  +Function: _Tcl\_RmmAndDWIMObjCmd_
    60     59   
    61         -|       /*ARGSUSED*/
    62         -|   int
    63         -|   Tcl_RmmAndDWIMObjCmd(dummy, interp, objc, objv)
    64         -|       ClientData dummy;                   /* Not used. */
    65         -|       Tcl_Interp *interp;                 /* Current interpreter. */
    66         -|       int objc;                           /* Number of arguments. */
    67         -|       Tcl_Obj *CONST objv[];              /* Argument objects. */
    68         -|   {
    69         -|       int status;
    70         -|       Tcl_Obj *intentions;
    71         -|
    72         -|       if (objc != 1) {
    73         -|           Tcl_WrongNumArgs(interp, 1, objv, NULL);
    74         -|           return TCL_ERROR;
    75         -|       }
    76         -|
    77         -|       status = TclReadProgrammersMind(interp, &intentions);
    78         -|       if (status != TCL_OK) {
    79         -|           return status;
    80         -|       }
    81         -|
    82         -|       status = TclDoWhatIsMeant(interp, intentions);
    83         -|       return status;
    84         -|   }
           60  +	       /*ARGSUSED*/
           61  +	   int
           62  +	   Tcl_RmmAndDWIMObjCmd(dummy, interp, objc, objv)
           63  +	       ClientData dummy;                   /* Not used. */
           64  +	       Tcl_Interp *interp;                 /* Current interpreter. */
           65  +	       int objc;                           /* Number of arguments. */
           66  +	       Tcl_Obj *CONST objv[];              /* Argument objects. */
           67  +	   {
           68  +	       int status;
           69  +	       Tcl_Obj *intentions;
           70  +	
           71  +	       if (objc != 1) {
           72  +	           Tcl_WrongNumArgs(interp, 1, objv, NULL);
           73  +	           return TCL_ERROR;
           74  +	       }
           75  +	
           76  +	       status = TclReadProgrammersMind(interp, &intentions);
           77  +	       if (status != TCL_OK) {
           78  +	           return status;
           79  +	       }
           80  +	
           81  +	       status = TclDoWhatIsMeant(interp, intentions);
           82  +	       return status;
           83  +	   }
    85     84   
    86         -~ Security Implications
           85  +# Security Implications
    87     86   
    88     87   It was pointed out that the ability to read the programmers' mind
    89     88   carries with it certain security and privacy implementations.
    90     89   
    91     90   To address this, the following code should be executed whenever a safe
    92     91   interpreter is created:
    93     92   
    94         -|   #
    95         -|   # Query the programmer's mind to obtain his or her
    96         -|   # P3P settings (See "Platform for Privacy Preferences",
    97         -|   # <URL: http://www.w3.org/P3P >)
    98         -|   #
    99         -|       rmmadwim
   100         -|
   101         -|   #
   102         -|   # Disable any internal commands that are in conflict
   103         -|   # with those settings:
   104         -|   #
   105         -|       rmmadwim
           93  +	   #
           94  +	   # Query the programmer's mind to obtain his or her
           95  +	   # P3P settings (See "Platform for Privacy Preferences",
           96  +	   # <URL: http://www.w3.org/P3P >)
           97  +	   #
           98  +	       rmmadwim
           99  +	
          100  +	   #
          101  +	   # Disable any internal commands that are in conflict
          102  +	   # with those settings:
          103  +	   #
          104  +	       rmmadwim
   106    105   
   107    106   In addition, the Tcl release notes should give a clear indication to
   108    107   programmers about the new security implications for non-Safe
   109    108   interpreters.
   110    109   
   111         -~ Copyright
          110  +# Copyright
   112    111   
   113    112   This TIP is free software: you can redistribute it and/or modify it
   114    113   under the terms of the GNU General Public License; either version 2 of
   115         -the License, or (at Richard Stallman's discretion), any later version.
          114  +the License, or \(at Richard Stallman's discretion\), any later version.
   116    115   
   117    116   Just kidding.  Public domain, as usual.
          117  +

Name change from tip/132.tip to tip/132.md.

     1         -TIP:            132
     2         -Title:          Revised Floating-Point Conversions in Tcl
     3         -Version:        $Revision: 1.14 $
     4         -Author:         Kevin Kenny <kennykb@acm.org>
     5         -Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
     6         -State:          Final
     7         -Type:           Project
     8         -Vote:           Done
     9         -Created:        31-Mar-2003
    10         -Post-History:   
    11         -Keywords:       floating point,IEEE,precision
    12         -Tcl-Version:    8.5
            1  +# TIP 132: Revised Floating-Point Conversions in Tcl
            2  +	Author:         Kevin Kenny <kennykb@acm.org>
            3  +	Author:         Donal K. Fellows <donal.k.fellows@man.ac.uk>
            4  +	State:          Final
            5  +	Type:           Project
            6  +	Vote:           Done
            7  +	Created:        31-Mar-2003
            8  +	Post-History:   
            9  +	Keywords:       floating point,IEEE,precision
           10  +	Tcl-Version:    8.5
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16     15   This TIP proposes several changes to the conversion between floating
    17     16   point numbers and character strings. The changes are made to restore
    18     17   the "everything is a string" contract that Tcl implicitly makes;
    19     18   without them, there are observable differences in the behavior of
    20     19   floating point numbers, depending on the state of the internal
    21     20   representation.
    22     21   
    23         -~ Rationale
           22  +# Rationale
    24     23   
    25         -In today's (8.4) Tcl, there are several gaffes that make
           24  +In today's \(8.4\) Tcl, there are several gaffes that make
    26     25   floating-point arithmetic less useful than it might be, and cause
    27     26   confusion for the users.  Chief among these is that string equality
    28         -does ''not'' imply value equality for floating point numbers:
           27  +does _not_ imply value equality for floating point numbers:
    29     28   
    30         -|    % set tcl_precision 12
    31         -|    12
    32         -|    % set a [expr 1.00000000000123]
    33         -|    1.0
    34         -|    % set b [expr 1.0]
    35         -|    1.0
    36         -|    % expr { $a == $b }
    37         -|    0
    38         -|    % expr { $a eq $b }
    39         -|    1
           29  +	    % set tcl_precision 12
           30  +	    12
           31  +	    % set a [expr 1.00000000000123]
           32  +	    1.0
           33  +	    % set b [expr 1.0]
           34  +	    1.0
           35  +	    % expr { $a == $b }
           36  +	    0
           37  +	    % expr { $a eq $b }
           38  +	    1
    40     39   
    41     40   This behavior flies in the face of Tcl's "everything is a string"
    42         -mantra.  In the interaction above, it is visible that ''a'' and ''b''
    43         -are ''not'' entirely strings; they have identical string
           41  +mantra.  In the interaction above, it is visible that _a_ and _b_
           42  +are _not_ entirely strings; they have identical string
    44     43   representations, but still test to be unequal with "==".  The
    45     44   underlying cause of the behavior is the fact that the default setting
    46         -for ''tcl_precision'' loses precision when converting the
           45  +for _tcl\_precision_ loses precision when converting the
    47     46   floating-point number to a string.  Behaviors like this have caused
    48         -Tcl's ''cognoscenti'' to recommend that all programs set
    49         -''tcl_precision'' to 17; once this setting is made, double-to-string
           47  +Tcl's _cognoscenti_ to recommend that all programs set
           48  +_tcl\_precision_ to 17; once this setting is made, double-to-string
    50     49   conversions are invertible, and everything is once again a string.
    51     50   
    52         -(Why 17? With IEEE-754 arithmetic, 17 decimal digits suffice to
           51  +\(Why 17? With IEEE-754 arithmetic, 17 decimal digits suffice to
    53     52   distinguish between any two floating point numbers, no matter how
    54         -small their difference. No smaller number of digits suffices.)
           53  +small their difference. No smaller number of digits suffices.\)
    55     54   
    56         -Why is ''tcl_precision'' not 17 by default? The reason appears to be
           55  +Why is _tcl\_precision_ not 17 by default? The reason appears to be
    57     56   that when the precision is set that high, the default IEEE-754
    58     57   semantics for floating point conversions cause a certain degree of
    59     58   trouble.  They require that the decimal representation be the nearest
    60     59   decimal representation to the value of the floating-point number that
    61     60   has the given number of significant digits.  This conversion gives
    62     61   rise to peculiarities:
    63     62   
    64         -|    % set tcl_precision 17; expr 0.2
    65         -|    0.20000000000000001
           63  +	    % set tcl_precision 17; expr 0.2
           64  +	    0.20000000000000001
    66     65   
    67     66   The peculiar behavior is, for the most part, suppressed by a lower
    68         -value for ''tcl_precision'':
           67  +value for _tcl\_precision_:
    69     68   
    70         -|    % set tcl_precision 16; expr 0.2
    71         -|    0.2
           69  +	    % set tcl_precision 16; expr 0.2
           70  +	    0.2
    72     71   
    73     72   The lower value, nevertheless, introduces the trouble above.  This TIP
    74     73   proposes a solution to both problems.
    75     74   
    76         -~ Specification
           75  +# Specification
    77     76   
    78     77   This TIP proposes the following changes to the floating point
    79     78   conversions in the Tcl library:
    80     79   
    81         - 1. The default value of ''::tcl_precision'' shall be changed to 0.
    82         -    A value of 0 (currently an error) shall be interpreted to mean
           80  + 1. The default value of _::tcl\_precision_ shall be changed to 0.
           81  +    A value of 0 \(currently an error\) shall be interpreted to mean
    83     82       that a number shall be formatted using
    84     83       the smallest number of decimal digits required to distinguish
    85     84       it from the next floating point number above it and the next
    86         -    floating point number below.  Other values of ''tcl_precision''
           85  +    floating point number below.  Other values of _tcl\_precision_
    87     86       shall continue to work as they do in Tcl 8.4.
    88     87       The documentation shall formally deprecate changing
    89         -    ''::tcl_precision'' to any other value, warning that doing so
           88  +    _::tcl\_precision_ to any other value, warning that doing so
    90     89       risks both loss of precision and inconsistency between string
    91     90       equality and "==".
    92     91   
    93     92    1. The default input conversion of floating-point numbers,
    94         -    ''SetDoubleFromAny'' shall be documented to guarantee precise
    95         -    rounding (generally to within one-half a unit of the least
    96         -    significant place [[1/2 ULP]]).  IEEE-754 rounding semantics are
    97         -    correct for this input.  The ''strtod'' procedure from the
    98         -    standard C library shall ''not'' be used for this conversion,
           93  +    _SetDoubleFromAny_ shall be documented to guarantee precise
           94  +    rounding \(generally to within one-half a unit of the least
           95  +    significant place [1/2 ULP]\).  IEEE-754 rounding semantics are
           96  +    correct for this input.  The _strtod_ procedure from the
           97  +    standard C library shall _not_ be used for this conversion,
    99     98       since so many implementations are buggy; instead, a Tcl
   100     99       implementation shall be developed from scratch based on
   101    100       the algorithms developed by Burger and Dybvig
   102         -    [http://citeseer.ist.psu.edu/28233.html].
   103         -    (It is worthy of note that several
   104         -    platforms already eschew the native ''strtod'' in favour of
   105         -    one provided in the ''compat/'' library, because of known bugs.)
          101  +    <http://citeseer.ist.psu.edu/28233.html> .
          102  +    \(It is worthy of note that several
          103  +    platforms already eschew the native _strtod_ in favour of
          104  +    one provided in the _compat/_ library, because of known bugs.\)
   106    105   
   107         - 1. When ''tcl_precision'' is zero, the output conversion 
   108         -    of floating-point numbers, ''UpdateStringOfDouble,'' shall convert a
          106  + 1. When _tcl\_precision_ is zero, the output conversion 
          107  +    of floating-point numbers, _UpdateStringOfDouble,_ shall convert a
   109    108       floating-point number to the unique string that satisfies the
   110    109       following constraints:
   111    110   
   112         - > * if reconverted to a binary floating point number, it yields a
          111  +	 > \* if reconverted to a binary floating point number, it yields a
   113    112        number that is the closest among all strings having the given
   114    113        number of significant digits.
   115    114   
   116         - > * if there is more than one string that is equally close but
          115  +	 > \* if there is more than one string that is equally close but
   117    116        neither string yields the given number exactly, then the string
   118    117        with the even digit in the least significant place is
   119    118        chosen. 
   120    119   
   121         - > * if there is more than one string with at most the given number of
          120  +	 > \* if there is more than one string with at most the given number of
   122    121        significant digits that yields the given floating-point number,
   123    122        but one has fewer significant digits than the other, then the
   124    123        shorter one is chosen. For example,
   125    124   
   126         -|              % expr 1e23
          125  +		              % expr 1e23
   127    126   
   128         - > > returns ''1e+23'', not ''9.9999999999999992e+22'', even though
          127  +	 > > returns _1e\+23_, not _9.9999999999999992e\+22_, even though
   129    128        the latter is a nearer representation of the exact floating-point
   130    129        value.
   131    130   
   132         - > * if there is more than one string with at most the given number of
          131  +	 > \* if there is more than one string with at most the given number of
   133    132        significant digits that reconverts exactly to the same floating
   134    133        point number, and all such strings are equally long, then the one
   135    134        closest to the given floating point number is chosen.
   136    135   
   137         - > * if a floating point number lies exactly at the midpoint of two
          136  +	 > \* if a floating point number lies exactly at the midpoint of two
   138    137        strings with the same number of significant digits, the one
   139    138        with an even digit in the least significant place is chosen.
   140    139   
   141    140    1. The test suite for Tcl shall be upgraded to include suitable test
   142    141       vectors for assessing correct rounding behavior.  The paper by
   143    142       Verdonk, Cuyt and Verschaeren in the References, and the
   144    143       associated software, present a suitable data set for inclusion.
   145    144   
   146    145    1. The input and output conversions shall allow for the IEEE special
   147         -    values +Inf, -Inf, and NaN (and for denormalized numbers).  The
   148         -    [[expr]] command shall be changed to allow +Inf and -Inf as
          146  +    values \+Inf, -Inf, and NaN \(and for denormalized numbers\).  The
          147  +    [expr] command shall be changed to allow \+Inf and -Inf as
   149    148       the result of an expression; NaN shall still cause an error.
   150         -    Tcl_GetDoubleFromObj shall treat +Inf and -Inf as it does any
          149  +    Tcl\_GetDoubleFromObj shall treat \+Inf and -Inf as it does any
   151    150       ordinary floating point number, and return an error for NaN.
   152    151   
   153         - 1. The [[binary scan]] and [[binary format]] commands shall explicitly
          152  + 1. The [binary scan] and [binary format] commands shall explicitly
   154    153       permit infinities and NaN as values.
   155    154   
   156         -''Donal K. Fellows notes that...'' the '''expr''' command will handle Inf and NaN quite well if asked nicely; it just won't return them.
          155  +_Donal K. Fellows notes that..._ the **expr** command will handle Inf and NaN quite well if asked nicely; it just won't return them.
   157    156   
   158         -| % expr {1 / Inf}
   159         -| 0.0
          157  +	 % expr {1 / Inf}
          158  +	 0.0
   160    159   
   161         -~ References
          160  +# References
   162    161   
   163    162   The basic principles of correctly-rounded floating point conversions
   164    163   have been known for a good many years.  Perhaps the two most seminal
   165    164   papers on modern floating point conversion are:
   166    165   
   167         - > William D. Clinger, ''How to Read Floating Point Numbers
   168         -   Accurately'', Proceedings of the ACM Conference on Programming
          166  + > William D. Clinger, _How to Read Floating Point Numbers
          167  +   Accurately_, Proceedings of the ACM Conference on Programming
   169    168      Language Design and Implementation, June 20-22 1990, pp. 92-101.
   170         -   [http://citeseer.nj.nec.com/clinger90how.html]
          169  +   <http://citeseer.nj.nec.com/clinger90how.html> 
   171    170   
   172         - > Guy L. Steele Jr. and Jon L. White, ''How to print floating-point
   173         -   numbers accurately''. In Proceedings of the ACM Conference on
          171  + > Guy L. Steele Jr. and Jon L. White, _How to print floating-point
          172  +   numbers accurately_. In Proceedings of the ACM Conference on
   174    173      Programming Language Design and Implementation, June 20-22 1990,
   175         -   pp. 112-126.  [http://doi.acm.org/10.1145/93542.93559]
          174  +   pp. 112-126.  <http://doi.acm.org/10.1145/93542.93559> 
   176    175   
   177    176   Both of these papers inspired David Gay to implement a library to do
   178    177   correct rounding in floating point input and output conversions:
   179    178   
   180         - > David M. Gay, ''Correctly rounded binary-decimal and decimal-binary
   181         -   conversions'', Numerical Analysis Manuscript 90-10, AT&T Bell
          179  + > David M. Gay, _Correctly rounded binary-decimal and decimal-binary
          180  +   conversions_, Numerical Analysis Manuscript 90-10, AT&T Bell
   182    181      Laboratories, Murray Hill, New Jersey, November 1990.
   183         -   [http://citeseer.nj.nec.com/gay90correctly.html]
          182  +   <http://citeseer.nj.nec.com/gay90correctly.html> 
   184    183   
   185    184   The algorithms for output conversion that appear in the reference
   186    185   implmentation are a hybrid of Gay's and the ones presented in:
   187    186   
   188         - > Robert G. Burger and R. Kent Dybvig, ''Printing Floating-Point Numbers
   189         -   Quickly and Accurately'', SIGPLAN Conf. on Programming Language Design
          187  + > Robert G. Burger and R. Kent Dybvig, _Printing Floating-Point Numbers
          188  +   Quickly and Accurately_, SIGPLAN Conf. on Programming Language Design
   190    189      and Implementation, 1996, pp. 108-116.
   191         -   [http://citeseer.ist.psu.edu/28233.html]
          190  +   <http://citeseer.ist.psu.edu/28233.html> 
   192    191   
   193    192   A reasonably comprehensive set of test vectors detailing problem cases
   194    193   for rounding conversions is documented in:
   195    194   
   196         - > Brigitte Verdonk, Annie Cuyt, Dennis Verschaeren, ''A precision and
          195  + > Brigitte Verdonk, Annie Cuyt, Dennis Verschaeren, _A precision and
   197    196      range independent tool for testing floating-point arithmetic II:
   198         -   Conversions'', ACM Transactions on Mathematical Software 27:2
   199         -   (March 2001), pp. 119-140.
   200         -   [http://citeseer.nj.nec.com/verdonk99precision.html]
          197  +   Conversions_, ACM Transactions on Mathematical Software 27:2
          198  +   \(March 2001\), pp. 119-140.
          199  +   <http://citeseer.nj.nec.com/verdonk99precision.html> 
   201    200   
   202         -~ Reference Implementation
          201  +# Reference Implementation
   203    202   
   204    203   A partial reference implementation of this TIP is available in CVS on the
   205         -''kennykb-tcl-numerics'' branch.  Since it requires additional third-party
          204  +_kennykb-tcl-numerics_ branch.  Since it requires additional third-party
   206    205   code that is not yet in the core, a different module name is required
   207    206   to check it out:
   208    207   
   209         -| export CVSROOT=:ext:yourname@cvs.sourceforge.net:/cvsroot/tcl
   210         -| cvs -q checkout -rkennykb-tip-132 tcl_numerics
          208  +	 export CVSROOT=:ext:yourname@cvs.sourceforge.net:/cvsroot/tcl
          209  +	 cvs -q checkout -rkennykb-tip-132 tcl_numerics
   211    210   
   212    211   The implementation is essentially complete; it includes changes to
   213    212   the documentation and test suite needed for this TIP.
   214    213   
   215         -~ Acknowledgments
          214  +# Acknowledgments
   216    215   
   217    216   The discussion of just why 17 is magical was prompted by a suggestion
   218    217   from Lars Hellstroem.
   219    218   
   220         -~ Copyright
          219  +# Copyright
   221    220   
   222         -Copyright (c) 2005 by Kevin B. Kenny.  All rights reserved.
          221  +Copyright \(c\) 2005 by Kevin B. Kenny.  All rights reserved.
   223    222   
   224    223   This document may be distributed subject to the terms and conditions
   225    224   set forth in the Open Publication License, version 1.0
   226         -[http://www.opencontent.org/openpub/].
          225  +<http://www.opencontent.org/openpub/> .
          226  +

Name change from tip/133.tip to tip/133.md.

     1         -TIP:            133
     2         -Title:          Extending [expr] Operators
     3         -Version:        $Revision: 1.6 $
     4         -Author:         Richard Suchenwirth <Richard.Suchenwirth-Bauersachs@siemens.com>
     5         -State:          Draft
     6         -Type:           Project
     7         -Vote:           Pending
     8         -Created:        08-Apr-2003
     9         -Post-History:   
    10         -Tcl-Version:    8.7
            1  +# TIP 133: Extending [expr] Operators
            2  +	Author:         Richard Suchenwirth <Richard.Suchenwirth-Bauersachs@siemens.com>
            3  +	State:          Draft
            4  +	Type:           Project
            5  +	Vote:           Pending
            6  +	Created:        08-Apr-2003
            7  +	Post-History:   
            8  +	Tcl-Version:    8.7
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP proposes a way to define new operators for conditions and the
    15         -'''expr''' command.  It also includes demonstrations of how it might work
    16         -in the examples: '''in''' tests inclusion in a list, and '''and''',
    17         -'''or''', and '''not''' are aliases for "'''&&'''", "'''||'''", "'''!'''".
           14  +**expr** command.  It also includes demonstrations of how it might work
           15  +in the examples: **in** tests inclusion in a list, and **and**,
           16  +**or**, and **not** are aliases for "**&&**", "**\|\|**", "**!**".
    18     17   
    19         -~ Rationale
           18  +# Rationale
    20     19   
    21     20   Inclusion of a value in a list is frequently tested with the construct
    22     21   
    23         -|   if {[lsearch -exact $list $value] >= 0} {...}
           22  +	   if {[lsearch -exact $list $value] >= 0} {...}
    24     23   
    25     24   The proposal, first brought by Reinhard Max in the Tcl Chatroom, is to
    26         -allow an ''in'' operator in the language understood by '''expr''', and
    27         -the condition parts of '''for''', '''if''' and '''while''', so that
           25  +allow an _in_ operator in the language understood by **expr**, and
           26  +the condition parts of **for**, **if** and **while**, so that
    28     27   the above can be written as
    29     28   
    30         -|   if {$value in $list} {...}
           29  +	   if {$value in $list} {...}
    31     30   
    32     31   This is shorter to type and much better to read.
    33     32   
    34         -In the same vein, I propose to allow operators "'''and'''",
    35         -"'''or'''", "'''not'''" to be resolved exactly like the current
    36         -"'''&&'''", "'''||'''" resp "'''!'''"  The new "operator aliases" are
           33  +In the same vein, I propose to allow operators "**and**",
           34  +"**or**", "**not**" to be resolved exactly like the current
           35  +"**&&**", "**\|\|**" resp "**!**"  The new "operator aliases" are
    37     36   not shorter than the original operators, but definitely better
    38         -readable - and easier typed too, as no Shift (or Alt-Gr on German
    39         -keyboards) key is needed.
           37  +readable - and easier typed too, as no Shift \(or Alt-Gr on German
           38  +keyboards\) key is needed.
    40     39   
    41     40   When Tcl was young, almost all users knew C, so the C style operators
    42     41   were a good choice.  In recent years, there is tendency that Tcl is
    43     42   used by persons who have no or less experience with C, but come from
    44         -other languages (etc. BASIC variants have the AND, OR, NOT operators)
           43  +other languages \(etc. BASIC variants have the AND, OR, NOT operators\)
    45     44   or have Tcl as a first language. For all these, the option of
    46     45   natural-language operators will make the learning just a little bit
    47     46   easier.
    48     47   
    49         -~ Implementation Proposals
           48  +# Implementation Proposals
    50     49   
    51         -Donal K. Fellows remarked (on an earlier proposal relating to just an
    52         -'''in''' operator) in the Tcl Chatroom: "On the plus side, it
    53         -shouldn't be hard to implement (might need an extra opcode for
    54         -'''lsearch''', but that's pretty straightforward.)"
           50  +Donal K. Fellows remarked \(on an earlier proposal relating to just an
           51  +**in** operator\) in the Tcl Chatroom: "On the plus side, it
           52  +shouldn't be hard to implement \(might need an extra opcode for
           53  +**lsearch**, but that's pretty straightforward.\)"
    55     54   
    56         -Pascal Scheffers proposed an extension mechanism for '''expr''' and
           55  +Pascal Scheffers proposed an extension mechanism for **expr** and
    57     56   conditions, so the proposed extensions to the expression language can
    58     57   be done in Tcl, with the commands:
    59     58   
    60         -| expr_register_operator in  {val list} {expr {[lsearch -exact $list $val]>=0}}
    61         -| expr_register_operator and {p q}      {expr {$p && $q}}
    62         -| expr_register_operator or  {p q}      {expr {$p || $q}}
    63         -| expr_register_operator not {p}        {expr {!$p}}
           59  +	 expr_register_operator in  {val list} {expr {[lsearch -exact $list $val]>=0}}
           60  +	 expr_register_operator and {p q}      {expr {$p && $q}}
           61  +	 expr_register_operator or  {p q}      {expr {$p || $q}}
           62  +	 expr_register_operator not {p}        {expr {!$p}}
    64     63   
    65         -Such operator registrations can have one or two arguments (for unary
    66         -and binary operators, respective) in the second argument. The third
           64  +Such operator registrations can have one or two arguments \(for unary
           65  +and binary operators, respective\) in the second argument. The third
    67     66   argument is a body that is evaluated, with local variables from the
    68     67   argument list substituted, and returns the resulting value, to be
    69     68   substituted for the operator and its operands.
    70     69   
    71         -Alternatively, one could stipulate that '''expr''' interprets its
           70  +Alternatively, one could stipulate that **expr** interprets its
    72     71   arguments in the above sense when called like this:
    73     72   
    74         -| expr operator in  {val list} {expr {[lsearch -exact $list $val]>=0}}
    75         -| expr operator and {p q}      {expr {$p && $q}}
           73  +	 expr operator in  {val list} {expr {[lsearch -exact $list $val]>=0}}
           74  +	 expr operator and {p q}      {expr {$p && $q}}
    76     75   
    77     76   This would currently raise an error, hence cannot break existing code.
    78     77   
    79     78   For a simple start, it shall be an error to define an operator both as
    80     79   unary and binary.
    81     80   
    82     81   Rules for operator precedence, and a way of specifying the precedence
    83     82   level, will still be needed.
    84     83   
    85     84   A feature sometimes discussed in news:comp.lang.tcl, an assignment
    86     85   operator, could in the same way easily be added by users who so want:
    87     86   
    88         -| expr operator = {varName value} {upvar 1 $varName var; set var $value}
           87  +	 expr operator = {varName value} {upvar 1 $varName var; set var $value}
           88  +
           89  +Reinhard Max has also proposed a unary **empty** operator:
    89     90   
    90         -Reinhard Max has also proposed a unary '''empty''' operator:
           91  +	  expr operator empty {list} {expr {[llength $list]==0}}
    91     92   
    92         -|  expr operator empty {list} {expr {[llength $list]==0}}
    93         -
    94         -~ Copyright
           93  +# Copyright
    95     94   
    96     95   This document has been placed in the public domain.
           96  +

Name change from tip/134.tip to tip/134.md.

     1         -TIP:            134
     2         -Title:          Subsystem Per-Thread Data Interfaces
     3         -Version:        $Revision: 1.4 $
     4         -Author:         Colin McCormack <colin@sharedtech.dyndns.org>
     5         -State:          Withdrawn
     6         -Type:           Project
     7         -Vote:           Pending
     8         -Created:        12-May-2003
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 134: Subsystem Per-Thread Data Interfaces
            2  +	Author:         Colin McCormack <colin@sharedtech.dyndns.org>
            3  +	State:          Withdrawn
            4  +	Type:           Project
            5  +	Vote:           Pending
            6  +	Created:        12-May-2003
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   Tcl core subsystems per-thread data is good, because it modularises the
    15     14   core.  None of the structures or access keys are exported, which is
    16     15   bad, because it makes modification to these subsystems difficult in a
    17     16   CVS world.
    18     17   
    19         -~ Rationale
           18  +# Rationale
    20     19   
    21     20   If one wishes to track the CVS while writing modifications to core
    22     21   subsystems one needs to minimally impact the existing source files
    23     22   while adding or changing subsystem functionality.  Since most
    24     23   subsystem global state is kept in Thread Specific Data, and access to
    25     24   this state is necessary for subsystem modifications, providing an
    26     25   interface would ease coding at the core subsystem level.  Modular
    27     26   encapsulation would be preserved by conditionally compiling API
    28     27   elements useful only to subsystem development and not intended for
    29     28   extension development.
    30     29   
    31         -~ Justification
           30  +# Justification
    32     31   
    33     32   The degree of modularity of the core would remain unchanged, access to
    34     33   subsystem TSD would presumably only be used for subsystem development,
    35     34   but would enable that development to proceed more easily - one could
    36     35   extend subsystems as easily as one currently writes extensions.  I
    37     36   think the degree of potential abuse is likely to be low.
    38     37   
    39         -~ Outline of Proposal
           38  +# Outline of Proposal
    40     39   
    41     40   Each Thread Specific Data structure should be named uniquely for each
    42     41   subsystem.
    43     42   
    44     43   Each subsystem should have its own .h header file
    45     44   
    46         -Each subsystem should export a function like ''tclTSD<subsystem>''
           45  +Each subsystem should export a function like _tclTSD<subsystem>_
    47     46   returning pointer to its TSD.  This API should be conditionally
    48     47   compiled, so that it's clear that it's not available to normal
    49     48   extensions.
    50     49   
    51         -~ Implementation
           50  +# Implementation
    52     51   
    53     52   The implementation of this TIP is trivial.
    54     53   
    55         -~ Copyright
           54  +# Copyright
    56     55   
    57     56   This document has been placed in the public domain.
           57  +

Name change from tip/135.tip to tip/135.md.

     1         -TIP:		135
     2         -Title:		Change 'dde servername -exact' Option to -force
     3         -Author:		Pat Thoyts <patthoyts@users.sourceforge.net>
     4         -Type:		Project
     5         -State:		Final
     6         -Vote:		Done
     7         -Version:	$Revision: 1.5 $
     8         -Tcl-Version:	8.5
     9         -Keywords:	dde
    10         -Created:	17-May-2003
    11         -Post-History:	
            1  +# TIP 135: Change 'dde servername -exact' Option to -force
            2  +	Author:		Pat Thoyts <patthoyts@users.sourceforge.net>
            3  +	Type:		Project
            4  +	State:		Final
            5  +	Vote:		Done
            6  +	Tcl-Version:	8.5
            7  +	Keywords:	dde
            8  +	Created:	17-May-2003
            9  +	Post-History:	
           10  +-----
           11  +
           12  +# Abstract
    12     13   
    13         -~ Abstract
    14         -
    15         -[130] provides for unique DDE server name registration.  This TIP
           14  +[[130]](130.md) provides for unique DDE server name registration.  This TIP
    16     15   renames one of the options it defines to better reflect its
    17     16   behaviour.
    18     17   
    19         -~ Rationale
           18  +# Rationale
    20     19   
    21         -The dde extension, as modified by [130], includes an option ''-exact''
           20  +The dde extension, as modified by [[130]](130.md), includes an option _-exact_
    22     21   to force the name to be that specified.  This TIP proposes to change
    23         -this options name to ''-force'' which better reflects its purpose.  As
    24         -[130] has only just been implemented, now is the time to make this
           22  +this options name to _-force_ which better reflects its purpose.  As
           23  +[[130]](130.md) has only just been implemented, now is the time to make this
    25     24   change before it is is included in any public release of Tcl.
    26     25   
    27         -~ Copyright
           26  +# Copyright
    28     27   
    29     28   This document is placed in the public domain.
           29  +

Name change from tip/136.tip to tip/136.md.

     1         -TIP:            136
     2         -Title:          Large List Initialisation
     3         -Version:        $Revision: 1.5 $
     4         -Author:         Simon Geard <simon.geard@ntlworld.com>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        25-May-2003
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 136: Large List Initialisation
            2  +	Author:         Simon Geard <simon.geard@ntlworld.com>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        25-May-2003
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP proposes the addition of a list initialisation command so
    15     14   that large lists can be easily and efficiently initialised.
    16     15   
    17         -~Rationale
           16  +# Rationale
    18     17   
    19         -With the advent of the ''lset'' command in Tcl 8.4 it seems to me that
           18  +With the advent of the _lset_ command in Tcl 8.4 it seems to me that
    20     19   we need a method of efficiently initialising large lists that can then
    21     20   be used as areas of preallocated memory. From a users point of view it
    22     21   can be much easier to preallocate say a 1000 element array and then
    23         -use ''lset'' and ''lindex'' to manipulate it than using ''lappend'' to
           22  +use _lset_ and _lindex_ to manipulate it than using _lappend_ to
    24     23   build it up. Having posted the idea to the tcl-core mailing list
    25     24   various alternatives were suggested to create a list of 1000 x
    26     25   characters:
    27     26   
    28         - 1.	''lappend'' in a loop
           27  + 1.	_lappend_ in a loop
    29     28   
    30         -| unset -nocomplain s
    31         -| for {set i 0} {$i < 1000} {incr i} {lappend s {x}}
           29  +		 unset -nocomplain s
           30  +		 for {set i 0} {$i < 1000} {incr i} {lappend s {x}}
    32     31   
    33         - 2.	''split''ting of a string
           32  + 2.	_split_ting of a string
    34     33   
    35         -| set s [split [string repeat x 1000] ""]
           34  +		 set s [split [string repeat x 1000] ""]
    36     35   
    37     36    3.	Direct construction of the string form
    38     37   
    39         -| set s x[string repeat " x" 999]
           38  +		 set s x[string repeat " x" 999]
    40     39   
    41         -None of these is particularly satisfactory.  (1) seems inefficient
    42         -since there are 1000 lappend operations, (2) is not general enough
    43         -since it doesn't generalise to more than one character and (3) doesn't
    44         -actually create a list.  (2) and (3) also suffer from the problem that
           40  +None of these is particularly satisfactory.  \(1\) seems inefficient
           41  +since there are 1000 lappend operations, \(2\) is not general enough
           42  +since it doesn't generalise to more than one character and \(3\) doesn't
           43  +actually create a list.  \(2\) and \(3\) also suffer from the problem that
    45     44   they are not at all obvious to new users and do nothing to dispel the
    46     45   notion that "everything is a string" in Tcl.
    47     46   
    48         -~Implementation
           47  +# Implementation
           48  +
           49  +I propose the introduction of a new command, _lrepeat_:
    49     50   
    50         -I propose the introduction of a new command, ''lrepeat'':
           51  +	 lrepeat <number> <element1> ?<element2>? ?<element3>? ...
    51     52   
    52         -| lrepeat <number> <element1> ?<element2>? ?<element3>? ...
    53         -
    54         -which returns a list of length <number> * (number of elements). The new list is the given element sequence repeated <number> times.
           53  +which returns a list of length <number> \* \(number of elements\). The new list is the given element sequence repeated <number> times.
    55     54   <number> must be a positive integer and each <element.> a list or
    56     55   string.
    57     56   
    58     57   Examples:
    59     58   
    60         -| lrepeat 100 0                 - returns a list of 100 zeros
    61         -| lrepeat 100 [lrepeat 100 0]   - returns a 100x100 matrix (list of lists) of zeros
    62         -| lrepeat 3 a b c               - returns a nine-element list {a b c a b c a b c}
    63         -| lrepeat 1 a b c               - identical to [list a b c]
           59  +	 lrepeat 100 0                 - returns a list of 100 zeros
           60  +	 lrepeat 100 [lrepeat 100 0]   - returns a 100x100 matrix (list of lists) of zeros
           61  +	 lrepeat 3 a b c               - returns a nine-element list {a b c a b c a b c}
           62  +	 lrepeat 1 a b c               - identical to [list a b c]
    64     63   
    65         -~Reference Implementation
           64  +# Reference Implementation
    66     65   
    67     66   I have implemented this command.  A patch against the Tcl 8.4.3
    68     67   source, which implements the command and provides both tests and
    69     68   documentation, is available from
    70         -http://homepage.ntlworld.com/whiteowl/tcl/tcl843-lrepeat.patch
           69  +<http://homepage.ntlworld.com/whiteowl/tcl/tcl843-lrepeat.patch>
    71     70   The directory also contains timing information and code which demonstrates a performance gain of over ten times for large lists.
    72     71   
    73         -~Copyright
           72  +# Copyright
    74     73   
    75     74   This document has been placed in the public domain.
           75  +

Name change from tip/137.tip to tip/137.md.

     1         -TIP:            137
     2         -Title:          Specifying Script Encodings for [source] and tclsh
     3         -Version:        $Revision: 1.6 $
     4         -Author:         Anton Kovalenko <a_kovalenko@fromru.com>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        29-May-2003
     9         -Post-History:   
    10         -Tcl-Version:    8.5
            1  +# TIP 137: Specifying Script Encodings for [source] and tclsh
            2  +	Author:         Anton Kovalenko <a_kovalenko@fromru.com>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        29-May-2003
            7  +	Post-History:   
            8  +	Tcl-Version:    8.5
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP proposes a way to specify encoding used to read a script 
    15         -with ''source'' command and (tclsh, wish) shell.
           14  +with _source_ command and \(tclsh, wish\) shell.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19     18   Now all Tcl scripts are expected to be in the system encoding.  An
    20     19   author of a script or a package can't specify concrete encoding to
    21     20   source the script or the files of package.  Common practise is to
    22     21   assume that encoding to be superset of ASCII, and not to use non-ASCII
    23     22   characters in the scripts that are targeting the wide audience of
    24     23   potential users.
    25     24   
    26         -There's a way to specify UNICODE literals with \uXXXX sequences.  But
           25  +There's a way to specify UNICODE literals with \\uXXXX sequences.  But
    27     26   it's not an universal and convenient way - this sequences aren't
    28         -substituted in {}-quoted strings, and they can't be edited in WYSIWYG
    29         -editors without special (and hence uncommon) support.
           27  +substituted in \{\}-quoted strings, and they can't be edited in WYSIWYG
           28  +editors without special \(and hence uncommon\) support.
    30     29   
    31         -This TIP proposes to add the ''-encoding'' option support to
    32         -''source'' command and to tclsh and wish.  Thus, package authors will be able
    33         -to specify encoding of the package files in ''pkgIndex.tcl''; and
           30  +This TIP proposes to add the _-encoding_ option support to
           31  +_source_ command and to tclsh and wish.  Thus, package authors will be able
           32  +to specify encoding of the package files in _pkgIndex.tcl_; and
    34     33   script authors will be able to specify the script encoding when
    35         -calling tclsh (either in the first line beginning with ''#!'' or in
    36         -the line where the ''exec tclsh "$0" "$@"'' is located).
           34  +calling tclsh \(either in the first line beginning with _\#!_ or in
           35  +the line where the _exec tclsh "$0" "$@"_ is located\).
    37     36   
    38     37   This TIP also proposes to use utf-8 for all the standard system
    39         -scripts, for ''pkgIndex.tcl'' and ''tclIndex'' files. Now they all are
    40         -supposed to be in the system encoding (message catalogs do not need
           38  +scripts, for _pkgIndex.tcl_ and _tclIndex_ files. Now they all are
           39  +supposed to be in the system encoding \(message catalogs do not need
    41     40   this support, as they are already always loaded using the UTF-8
    42         -encoding scheme), and it could event prevent Tcl itself from running
           41  +encoding scheme\), and it could event prevent Tcl itself from running
    43     42   when system encoding is not a compatible superset of ASCII.
    44     43   
    45         -~ Specification
           44  +# Specification
    46     45   
    47     46   Tclsh will allow the encoding to be specified on the command-line in
    48         -two forms: the first form is ''-encoding name'' as two separate
    49         -arguments, and the second is ''-e:name'' (a single argument.)
    50         -The second form is intended for when the script begins with ''#!'' and
    51         -is because Unix kernels pass extra parameters from the ''#!'' line as
    52         -a single argument. This very short notation (-e:) is chosen because
    53         -some Unices limit the ''#!'' line to the length of 32.
           47  +two forms: the first form is _-encoding name_ as two separate
           48  +arguments, and the second is _-e:name_ \(a single argument.\)
           49  +The second form is intended for when the script begins with _\#!_ and
           50  +is because Unix kernels pass extra parameters from the _\#!_ line as
           51  +a single argument. This very short notation \(-e:\) is chosen because
           52  +some Unices limit the _\#!_ line to the length of 32.
    54     53   
    55         -To implement all these options, this TIP proposes a new C-level public API function Tcl_FSEvalFileEx, which is similar to Tcl_FSEvalFile, but
    56         -takes one extra argument that must be an encoding name or NULL (to use
    57         -system encoding).
           54  +To implement all these options, this TIP proposes a new C-level public API function Tcl\_FSEvalFileEx, which is similar to Tcl\_FSEvalFile, but
           55  +takes one extra argument that must be an encoding name or NULL \(to use
           56  +system encoding\).
    58     57   
    59         -| int Tcl_FSEvalFileEx(Tcl_Interp *interp, Tcl_Obj *pathPtr,
    60         -|                      CONST char *encodingName);
           58  +	 int Tcl_FSEvalFileEx(Tcl_Interp *interp, Tcl_Obj *pathPtr,
           59  +	                      CONST char *encodingName);
    61     60   
    62     61   Common use of this new options will be like this:
    63     62   
    64     63    1. In a script:
    65     64   
    66         -| !#/usr/bin/tclsh -e:utf-8
    67         -| do something...
           65  +		 !#/usr/bin/tclsh -e:utf-8
           66  +		 do something...
           67  +
           68  +	 > or it could be:
           69  +
           70  +		 #!/bin/sh
           71  +		 # I wish to use tclsh \
           72  +		 exec tclsh -encoding utf-8 "$0" "$@"
    68     73   
    69         - > or it could be:
           74  + 2. In a _pkgIndex.tcl_:
    70     75   
    71         -| #!/bin/sh
    72         -| # I wish to use tclsh \
    73         -| exec tclsh -encoding utf-8 "$0" "$@"
           76  +		 package ifneeded pkg 1.02 [list source -encoding utf-8 \
           77  +		      [file join $dir pkg.tcl]]
    74     78   
    75         - 2. In a ''pkgIndex.tcl'':
    76         -
    77         -| package ifneeded pkg 1.02 [list source -encoding utf-8 \
    78         -|      [file join $dir pkg.tcl]]
    79         -
    80         -~ Implementation
           79  +# Implementation
    81     80   
    82     81   The partial implementation of this TIP can be found at
    83         -http://sourceforge.net/projects/tcl as Patch #742683. Some
           82  +<http://sourceforge.net/projects/tcl> as Patch \#742683. Some
    84     83   fixes to source system scripts and pkgIndex'es in utf-8 are not
    85     84   yet there. But with the existing implementation of "-encoding",
    86     85   it would be really easy to implement.
    87     86   
    88         -~ Copyright
           87  +# Copyright
    89     88   
    90     89   This document is placed in the public domain.
           90  +

Name change from tip/138.tip to tip/138.md.

     1         -TIP:		138
     2         -Title:		New TCL_HASH_KEY_SYSTEM_HASH option for Tcl hash tables
     3         -Version:	$Revision: 1.5 $
     4         -Author:		Kevin Kenny <kennykb@acm.org>
     5         -Author:		Joe Mistachkin <joe@mistachkin.com>
     6         -State:		Final
     7         -Type:		Project
     8         -Vote:		Done
     9         -Created:	29-May-2003
    10         -Post-History:	
    11         -Keywords:	thread specific data, hash table, memory allocation
    12         -Tcl-Version:	8.5
            1  +# TIP 138: New TCL_HASH_KEY_SYSTEM_HASH option for Tcl hash tables
            2  +	Author:		Kevin Kenny <kennykb@acm.org>
            3  +	Author:		Joe Mistachkin <joe@mistachkin.com>
            4  +	State:		Final
            5  +	Type:		Project
            6  +	Vote:		Done
            7  +	Created:	29-May-2003
            8  +	Post-History:	
            9  +	Keywords:	thread specific data, hash table, memory allocation
           10  +	Tcl-Version:	8.5
           11  +-----
    13     12   
    14         -~ Abstract
           13  +# Abstract
    15     14   
    16     15   This TIP proposes a new flag in the Tcl hash table API in support of a
    17     16   proposed rework of thread-specific data management.
    18     17   
    19         -~ Introduction
           18  +# Introduction
    20     19   
    21         -The Tcl hash table constructor, ''Tcl_InitCustomHashTable'', provides
           20  +The Tcl hash table constructor, _Tcl\_InitCustomHashTable_, provides
    22     21   a reasonably flexible means of creating a hash table that is managed
    23     22   by the application.  It allows for custom procedures to calculate hash
    24     23   values for keys, to compare keys for equality, and to allocate and
    25     24   free hash table entries.
    26     25   
    27     26   It always, however, allocates the hash table itself by means of
    28         -''ckalloc'' and ''ckfree''. This use of Tcl's main allocator is
           27  +_ckalloc_ and _ckfree_. This use of Tcl's main allocator is
    29     28   normally not a problem, but a recent application of custom hash tables
    30     29   has exposed the need, from time to time, of using the system allocator
    31         -(''TclpSysAlloc'' and ''TclpSysFree'') directly.
           30  +\(_TclpSysAlloc_ and _TclpSysFree_\) directly.
    32     31   
    33     32   The motivating problem is that thread-specific data on certain
    34     33   versions of Windows is limited to only a small number of blocks per
    35         -process (64 on at least one version).  The proposed fix, which Joe
           34  +process \(64 on at least one version\).  The proposed fix, which Joe
    36     35   Mistachkin is pursuing, involves replacing the system calls for
    37     36   managing thread-local storage with calls that manage the
    38     37   thread-specific data blocks in a per-thread hash table.
    39     38   
    40     39   Reviewing and testing the change revealed an unfortunate circular
    41         -dependency.  A call to ''Tcl_InitCustomHashTable'' would attempt to
    42         -allocate the array of hash buckets by a call to ''ckalloc'' - which
    43         -translates to ''TclpAlloc''.  On a threaded build, the first thing
           40  +dependency.  A call to _Tcl\_InitCustomHashTable_ would attempt to
           41  +allocate the array of hash buckets by a call to _ckalloc_ - which
           42  +translates to _TclpAlloc_.  On a threaded build, the first thing
    44     43   done in this routine is to retrieve the allocation cache via
    45         -''TclpGetAllocCache.''  This in turn, once we avoid the use of
    46         -''TlsAlloc'', winds up trying to create a thread-specific data block
           44  +_TclpGetAllocCache._  This in turn, once we avoid the use of
           45  +_TlsAlloc_, winds up trying to create a thread-specific data block
    47     46   to hold the allocation cache.  The new thread-specific data manager in
    48     47   turn must allocate a hash table for the thread-specific data blocks.
    49     48   The outcome is endless recursion.
    50     49   
    51     50   The fix for the problem is simple - have either the allocation cache,
    52     51   the thread-specific data hash, or both, allocated off the system heap
    53     52   rather than the thread-specific allocation cache.  Unfortunately,
    54         -''Tcl_InitCustomHashTable'' provides no way to accomplish this.
           53  +_Tcl\_InitCustomHashTable_ provides no way to accomplish this.
    55     54   
    56         -~ Proposal
           55  +# Proposal
    57     56   
    58         -The ''flags'' word in the ''Tcl_HashKeyType'' data structure shall be
    59         -augmented with an additional value, ''TCL_HASH_KEY_SYSTEM_HASH''.  If
    60         -this bit is set in the structure passed to ''Tcl_InitCustomHashTable'',
           57  +The _flags_ word in the _Tcl\_HashKeyType_ data structure shall be
           58  +augmented with an additional value, _TCL\_HASH\_KEY\_SYSTEM\_HASH_.  If
           59  +this bit is set in the structure passed to _Tcl\_InitCustomHashTable_,
    61     60   then all memory allocated internally to manage the hash keys shall be
    62         -obtained via direct calls to ''TclpSysAlloc'', ''TclpSysRealloc'', and
    63         -''TclpSysFree'' rather than ''Tcl_Alloc'', ''Tcl_Realloc'' and
    64         -''Tcl_Free.''
           61  +obtained via direct calls to _TclpSysAlloc_, _TclpSysRealloc_, and
           62  +_TclpSysFree_ rather than _Tcl\_Alloc_, _Tcl\_Realloc_ and
           63  +_Tcl\_Free._
    65     64   
    66         -~ Alternatives
           65  +# Alternatives
    67     66   
    68     67   The authors considered and rejected the alternative of advancing
    69         -''TCL_HASH_KEY_TYPE_VERSION'' and defining in the structure three new
           68  +_TCL\_HASH\_KEY\_TYPE\_VERSION_ and defining in the structure three new
    70     69   function pointers to allocate, reallocate, and free memory blocks.
    71         -The additional complexity (and associated performance degradation)
           70  +The additional complexity \(and associated performance degradation\)
    72     71   associated with dealing with two structure versions appeared to be
    73     72   unnecessary; it is difficult to imagine a situation where any
    74     73   allocator other than the system allocator or Tcl's own will be desired
    75     74   for the 'buckets' array, which varies widely in size.  Custom
    76     75   small-block allocators make much more sense for the hash values than
    77     76   they do for the table of hash buckets.
    78     77   
    79         -~ Implementation Notes
           78  +# Implementation Notes
    80     79   
    81     80   An implementation of this change is available from the SourceForge
    82     81   patch manager as item 731356.  It is part of a larger overhaul of the
    83     82   thread-specific data manager.
    84     83   
    85         -~ Copyright
           84  +# Copyright
    86     85   
    87     86   This document is placed in the public domain.
           87  +

Name change from tip/139.tip to tip/139.md.

     1         -TIP:		139
     2         -Title:		Publish Part of Tcl's Namespace API
     3         -Author:		Donal K. Fellows <donal.k.fellows@man.ac.uk>
     4         -Created:	03-Jun-2003
     5         -Type:		Project
     6         -State:		Final
     7         -Vote:		Done
     8         -Tcl-Version:	8.5
     9         -Version:	$Revision: 1.5 $
    10         -Post-History:	
            1  +# TIP 139: Publish Part of Tcl's Namespace API
            2  +	Author:		Donal K. Fellows <donal.k.fellows@man.ac.uk>
            3  +	Created:	03-Jun-2003
            4  +	Type:		Project
            5  +	State:		Final
            6  +	Vote:		Done
            7  +	Tcl-Version:	8.5
            8  +	Post-History:	
            9  +-----
    11     10   
    12         -~ Abstract
           11  +# Abstract
    13     12   
    14     13   This TIP makes the simpler parts of Tcl's Namespace API available to
    15     14   the general C-coding public.
    16     15   
    17         -~ Rationale
           16  +# Rationale
    18     17   
    19     18   Tcl has had namespace support for a number of years now, ever since
    20         -version 8.0.  However, the C API for working with namespaces (as
    21         -opposed to the script-level [[namespace]] command) has been hidden
           19  +version 8.0.  However, the C API for working with namespaces \(as
           20  +opposed to the script-level [namespace] command\) has been hidden
    22     21   inside Tcl's private header files for all that time.  This is mainly
    23     22   because of the complexity of some of the interfaces; name resolution
    24     23   is definitely difficult to document.
    25     24   
    26     25   But about half the API is not so encumbered, being the parts that deal
    27     26   with basic features like creation and destruction of namespaces
    28     27   themselves.  It is these simpler parts that this TIP exposes as they
    29     28   have little risk of changing in the future, and I believe they should
    30     29   be made public particularly as it would allow extensions that create
    31     30   commands in namespaces to ensure the existence of the namespace first
    32         -without resorting to applying ''Tcl_Eval'' to a small script.
           31  +without resorting to applying _Tcl\_Eval_ to a small script.
    33     32   
    34     33   This TIP does not call for any alteration to the name, signature or
    35     34   behaviour of any API function at all.  Note that these functions
    36     35   already have "public" names.
    37     36   
    38         -~ Exposed API Functions
           37  +# Exposed API Functions
    39     38   
    40         -There are the following new public functions (with signatures included
    41         -for reference only):
           39  +There are the following new public functions \(with signatures included
           40  +for reference only\):
    42     41   
    43         - Tcl_CreateNamespace:	Creates a new namespace.
           42  + Tcl\_CreateNamespace:	Creates a new namespace.
           43  +
           44  +	    Tcl_Namespace * Tcl_CreateNamespace(Tcl_Interp *interp, CONST char *name,
           45  +		    ClientData clientData, Tcl_NamespaceDeleteProc *deleteProc)
           46  +
           47  + Tcl\_DeleteNamespace:	Deletes an existing namespace.
           48  +
           49  +	    void Tcl_DeleteNamespace(Tcl_Namespace *nsPtr)
           50  +
           51  + Tcl\_AppendExportList:	Retrieves the export patterns for a namespace.
           52  +
           53  +	    int Tcl_AppendExportList(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
           54  +	            Tcl_Obj *objPtr)
           55  +
           56  + Tcl\_Export:		Set/append to the export patterns for a namespace.
           57  +
           58  +	    int Tcl_Export(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
           59  +	            CONST char *pattern, int resetListFirst)
           60  +
           61  + Tcl\_Import:		Import commands matching a pattern into a namespace.
           62  +
           63  +	    int Tcl_Import(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
           64  +	            CONST char *pattern, int allowOverwrite)
           65  +
           66  + Tcl\_ForgetImport:	Remove imports matching a pattern.
           67  +
           68  +	    int Tcl_ForgetImport(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
           69  +	            CONST char *pattern)
           70  +
           71  + Tcl\_GetCurrentNamespace: Retrieve the current namespace.
           72  +
           73  +	    Tcl_Namespace * Tcl_GetCurrentNamespace(Tcl_Interp *interp)
           74  +
           75  + Tcl\_GetGlobalNamespace: Retrieve the global namespace.
           76  +
           77  +	    Tcl_Namespace * Tcl_GetGlobalNamespace(Tcl_Interp *interp)
    44     78   
    45         -|    Tcl_Namespace * Tcl_CreateNamespace(Tcl_Interp *interp, CONST char *name,
    46         -|	    ClientData clientData, Tcl_NamespaceDeleteProc *deleteProc)
    47         -
    48         - Tcl_DeleteNamespace:	Deletes an existing namespace.
    49         -
    50         -|    void Tcl_DeleteNamespace(Tcl_Namespace *nsPtr)
           79  + Tcl\_FindNamespace:	Search for a namespace.
    51     80   
    52         - Tcl_AppendExportList:	Retrieves the export patterns for a namespace.
    53         -
    54         -|    int Tcl_AppendExportList(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
    55         -|            Tcl_Obj *objPtr)
    56         -
    57         - Tcl_Export:		Set/append to the export patterns for a namespace.
    58         -
    59         -|    int Tcl_Export(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
    60         -|            CONST char *pattern, int resetListFirst)
    61         -
    62         - Tcl_Import:		Import commands matching a pattern into a namespace.
           81  +	    Tcl_Namespace * Tcl_FindNamespace(Tcl_Interp *interp, CONST char *name,
           82  +	            Tcl_Namespace *contextNsPtr, int flags)
    63     83   
    64         -|    int Tcl_Import(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
    65         -|            CONST char *pattern, int allowOverwrite)
    66         -
    67         - Tcl_ForgetImport:	Remove imports matching a pattern.
    68         -
    69         -|    int Tcl_ForgetImport(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
    70         -|            CONST char *pattern)
    71         -
    72         - Tcl_GetCurrentNamespace: Retrieve the current namespace.
    73         -
    74         -|    Tcl_Namespace * Tcl_GetCurrentNamespace(Tcl_Interp *interp)
    75         -
    76         - Tcl_GetGlobalNamespace: Retrieve the global namespace.
    77         -
    78         -|    Tcl_Namespace * Tcl_GetGlobalNamespace(Tcl_Interp *interp)
    79         -
    80         - Tcl_FindNamespace:	Search for a namespace.
    81         -
    82         -|    Tcl_Namespace * Tcl_FindNamespace(Tcl_Interp *interp, CONST char *name,
    83         -|            Tcl_Namespace *contextNsPtr, int flags)
    84         -
    85         - Tcl_FindCommand:	Search for a command and return its token,
           84  + Tcl\_FindCommand:	Search for a command and return its token,
    86     85       optionally in a namespace.  Note that command tokens are already
    87         -    returned from ''Tcl_CreateCommand'' and ''Tcl_CreateObjCommand''
           86  +    returned from _Tcl\_CreateCommand_ and _Tcl\_CreateObjCommand_
    88     87       so this is not a new type of result.
    89     88   
    90         -|    Tcl_Command Tcl_FindCommand(Tcl_Interp *interp, CONST char *name,
    91         -|            Tcl_Namespace *contextNsPtr, int flags)
           89  +	    Tcl_Command Tcl_FindCommand(Tcl_Interp *interp, CONST char *name,
           90  +	            Tcl_Namespace *contextNsPtr, int flags)
           91  +
           92  + Tcl\_GetCommandFromObj:	Get a command token given a name.
    92     93   
    93         - Tcl_GetCommandFromObj:	Get a command token given a name.
           94  +	    Tcl_Command Tcl_GetCommandFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr)
    94     95   
    95         -|    Tcl_Command Tcl_GetCommandFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr)
           96  + Tcl\_GetCommandFullName: Get the full name of a command from its token.
    96     97   
    97         - Tcl_GetCommandFullName: Get the full name of a command from its token.
    98         -
    99         -|    void Tcl_GetCommandFullName(Tcl_Interp *interp, Tcl_Command command,
   100         -|            Tcl_Obj *objPtr)
           98  +	    void Tcl_GetCommandFullName(Tcl_Interp *interp, Tcl_Command command,
           99  +	            Tcl_Obj *objPtr)
   101    100   
   102    101   Each of these functions will be declared in future within
   103         -''tcl.decls'' (with the entries in ''tclInt.decls'' deprecated) and
          102  +_tcl.decls_ \(with the entries in _tclInt.decls_ deprecated\) and
   104    103   will also be documented.
   105    104   
   106         -~ Copyright
          105  +# Copyright
   107    106   
   108    107   This document is placed in the public domain.
          108  +

Name change from tip/14.tip to tip/14.md.

     1         -TIP:            14
     2         -Title:          Access to Tk Photo Image Transparency
     3         -Version:        $Revision: 2.5 $
     4         -Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
     5         -State:          Final
     6         -Type:           Project
     7         -Vote:           Done
     8         -Created:        22-Nov-2000
     9         -Post-History:   
    10         -Keywords:       Tk,photo,transparency,internal,access
    11         -Tcl-Version:    8.4.0
            1  +# TIP 14: Access to Tk Photo Image Transparency
            2  +	Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
            3  +	State:          Final
            4  +	Type:           Project
            5  +	Vote:           Done
            6  +	Created:        22-Nov-2000
            7  +	Post-History:   
            8  +	Keywords:       Tk,photo,transparency,internal,access
            9  +	Tcl-Version:    8.4.0
           10  +-----
    12     11   
    13         -~ Abstract
           12  +# Abstract
    14     13   
    15         -It is useful for some code (both extensions and scripts) to have
           14  +It is useful for some code \(both extensions and scripts\) to have
    16     15   access to the transparency information in photo images for various
    17     16   reasons, but this is not currently available, even via an internal
    18         -structure defined in ''generic/tkInt.h''.  This TIP is aimed at making
           17  +structure defined in _generic/tkInt.h_.  This TIP is aimed at making
    19     18   the information available, and in such a way at the C level that
    20     19   backward compatibility is maintained in the future even if the
    21     20   internal structure definitions change.
    22     21   
    23         -~ Rationale
           22  +# Rationale
    24     23   
    25         -I have been working for several years (on-and-off) on an extension for
           24  +I have been working for several years \(on-and-off\) on an extension for
    26     25   Tk that allows it to have non-rectangular windows
    27         -(http://www.cs.man.ac.uk/~fellowsd/tcl/shapeidx.html) which is an
           26  +\(<http://www.cs.man.ac.uk/~fellowsd/tcl/shapeidx.html\)> which is an
    28     27   effect that is great for all sorts of purposes but which comes
    29     28   particularly into its own when used in conjunction with drag-and-drop
    30     29   to make drag tokens that obscure only part of what lies underneath
    31     30   them.  However, one of the most useful ways of specifying the shape of
    32     31   a window turns out to be via images of various kinds, and the natural
    33     32   way to do this is with the transparency data within the image.  The
    34     33   problem is that this data is locked up entirely within structures that
    35         -are completely private to ''generic/tkImgPhoto.c''; none of it is
    36         -visible at all anywhere else, even within the core.  (There is code
           34  +are completely private to _generic/tkImgPhoto.c_; none of it is
           35  +visible at all anywhere else, even within the core.  \(There is code
    37     36   that uses colour data instead to do this sort of trick,
    38         -http://www.sys.uea.ac.uk/~fuzz/tktrans/default.html, but this is a
           37  +<http://www.sys.uea.ac.uk/~fuzz/tktrans/default.html,> but this is a
    39     38   slow process and frankly a little strange if we already have
    40         -transparency data available.)
           39  +transparency data available.\)
    41     40   
    42     41   There is also a more general need for scripts to be able to discover
    43     42   more about the transparent areas of a photo image; at the moment,
    44     43   there is no access at all to that information at the script level.
    45     44   
    46         -~ Changes to the C-Level API
           45  +# Changes to the C-Level API
    47     46   
    48         -To get around this problem, the data member ''validRegion'' of the
    49         -''PhotoMaster'' structure needs to be made available by some
           47  +To get around this problem, the data member _validRegion_ of the
           48  +_PhotoMaster_ structure needs to be made available by some
    50     49   mechanism.  There are two ways of doing this:
    51     50   
    52         - 1. Placing the ''PhotoMaster'' structure, or some version of it, in
    53         -    ''generic/tkInt.h'', or
           51  + 1. Placing the _PhotoMaster_ structure, or some version of it, in
           52  +    _generic/tkInt.h_, or
    54     53   
    55     54    2. Creating a function to access the data member.
    56     55   
    57     56   The first way is very cheap initially, but also very inflexible and
    58         -creates yet another hidden version dependency (such as is tackled in
    59         -[5]) should we decide to change the structure for any reason (we also
           57  +creates yet another hidden version dependency \(such as is tackled in
           58  +[[5]](5.md)\) should we decide to change the structure for any reason \(we also
    60     59   have had problems with this sort of thing in the past in relation to
    61         -the ''Tcl_Interp'' member ''result'', direct access to which has been
           60  +the _Tcl\_Interp_ member _result_, direct access to which has been
    62     61   deprecated for years, but where there is still existing code that does
    63     62   it and which forms one of the largest barriers for some extensions
    64         -from upgrading to Tcl 8.0 or later.)  It is also unnecessary since
           63  +from upgrading to Tcl 8.0 or later.\)  It is also unnecessary since
    65     64   only the core needs to know how to create new instances of the
    66     65   structure.
    67     66   
    68     67   The second way, by contrast, is far more flexible in the future as it
    69     68   will allow us to completely change the internal implementation of
    70     69   photo image transparency without affecting any extensions at all.  The
    71     70   cost of doing this is that a new entry in one of the stub ta