$Date: 2012-02-05 12:39:18 -0800 (Sun, 05 Feb 2012) $

NOTE: Please improve this list!

Dear (new) GRASS Developer,

When submitting TCL and TK SCRIPTS to GRASS SVN repository,
please take care of following rules:

[ see SUBMITTING for C code hints ]
[ see SUBMITTING_SCRIPTS for shell script hints ]
[ see SUBMITTING_DOCS for documentation ]
[ see SUBMITTING_PYTHON for Python code hints ]


1.  Use the directory structure to place your program appropriately into
    the source tree
        - general grass tcl/tk libraries and reusable code go into lib/gtcltk
        - user interfaces go in gui/tcltk
        - scripts go in scripts/
            Programs here must have a proper Makefile and description.html

 
2.  Add a header section to the script you submit and make sure you include
    the copyright. The purpose section is meant to contain a general
    overview of the code in the file to assist other programmers that will
    need to make changes to your code.

    Example (fictitious header for a script called r.myscript) :

############################################################################
#
# MODULE:       r.myscript
# AUTHOR(S):    Me <email AT some domain>
# PURPOSE:      Calculates univariate statistics from a GRASS raster map
# COPYRIGHT:    (C) 2005 by the GRASS Development Team
#
#               This program is free software under the GNU General Public
#               License (>=v2). Read the file COPYING that comes with GRASS
#               for details.
#
#############################################################################

    The copyright protects your rights according to GNU General Public
    License (www.gnu.org).


3.  PLEASE take the time to add comments throughout your code explaining what
    the code is doing. It will save a HUGE amount of time and frustration for
    other programmers that need to change or understand your code in the future.
    Many of the programmers working on grass are not heavily invested in tcl
    and tk, so extra documentation and explanation are greatly appreciated.


4.  Test your program with both tcl/tk 8.3 and tcl/tk 8.4.


5.  Always use the gettext macros with [G_msg "..."] for user messages.
    The string must be quoted using quotation marks, not braces, for
    xgettext to find it. The string cannot include variable ($) or
    command ([...]) substitutions. If you need substitutions use
    [format ...].

    Examples:
    button .ok -text [G_msg "Ok"]

    set statusbartext [format [G_msg "Monitor %d running"] $monitor_number]]

    Use positional parameters if substitutions might be rearranged in another language:

    format [G_msg "We produced %1\$d units in location %2\$s"] $num $city
    format [G_msg "In location %2\$s we produced %1\$d units"] $num $city


6.  Use "GRASS_TCLSH" and "GRASS_WISH" environment variables instead of
    "tclsh" and "wish" at the start of Tcl/Tk scripts. This allows users to
    override the default names, so that developers don't need worry about the
    shell names.

    Tcl script:

    	#!/bin/sh
	# the next line restarts using tclsh. Note the backslash: \
	exec $GRASS_TCLSH "$0" "$@"


    Tk script:

    	#!/bin/sh
	# the next line restarts using wish. Note the backslash: \
	exec $GRASS_WISH "$0" "$@"


7.  Do not source files that have already been sourced.

        gui.tcl sources:
            options.tcl 
            select.tcl
            gronsole.tcl

    If your code requires something to be sourced before it note so
    in a comment at the top of the file.


8.  Set tabstops in your editor to 8 spaces.
    When modifying files use the indentation style that is already present.
    Please use consistent indentation style in your new code. Whether you use
    tabs or spaces to indent please be consistent. Where tabs and spaces are
    mixed please remember that a tab is 8 spaces.


9.  Use the tk options database to control the appearance of your user interface.
    In general do not set options on tk widgets unless that option is truly
    specific to that widget. It makes them harder to customize.

    Example: Don't set options like -foreground or -background or -font
    when creating widgets, unless there's a really _really_ specific reason to
    have it that color (like it's demonstrating that color).

    If you want something like a label to look different than everything else
    of that class (other labels) give it a distinctive name, like
    .moduletitlelabel . If you have a bunch of them give them all the same 
    distinctive name. This allows them to have their options controlled by the 
    options database.

    You can put your options at the start of your script (before creating any
    widgets) like this:
    option add *modultitlelabel.background red
    More examples are in lib/gtcltk/options.tcl

    Many common options, like font, background and foreground colors,
    highlighting, scrollbar colors, and help bubble appearance are controlled
    by options.tcl. You can include it at the start of your script with:
    source $env(GISBASE)/etc/gtcltk/options.tcl


10. Avoid using global variables. Thay are a frequent source of bugs, make code
    harder to understand, and make your program difficult to reuse. Additionally,
    putting code into procs usually makes it run faster (it gets compiled).


11. For consistency, use README rather than README.txt for any README files.


12. Use of GRASS commands in shell wrapper.

    Any GRASS program run in an xterm (those which do interactive query) needs
    to use grass-run.sh, e.g.:

    exec -- $env(GISBASE)/etc/grass-xterm-wrapper -e $env(GISBASE)/etc/grass-run.sh g.proj ...

    You should probably also use "-T g.proj -n g.proj" to set the title
    back (otherwise it will be "grass-run.sh", which isn't particularly
    informative).

    The xterm will close as soon as the command completes (whether it
    succeeds or fails). You can use the -hold switch to retain the xterm
    window after the command completes, but you should only do that for
    debugging; having to manually close the xterm window each time would
    be annoying in normal use. Alternatively, redirect stdout/stderr to a
    file, to catch any error messages.


13. Be sure to develop on top of the LATEST GRASS code (which is in
    SVN repository). You can re-check before submission with 'svn
    diff':

    Be sure to create unified ("diff -u") format. "Plain"
    diffs (the default format) are risky, because they will apply without
    warning to code which has been substantially changed; they are also
    harder to read than unified.

    Such diffs should be made from the top-level directory, e.g.
    "cvs diff display/d.vect/main.c"; that way, the diff will
    include the pathname rather than just "main.c".


14. Tell the other developers about the new code using the following e-mail:
    grass-dev@lists.osgeo.org
 
    To subscribe to this mailing list, see
    http://lists.osgeo.org/mailman/listinfo/grass-dev


15. In case of questions feel free to contact the developers at the above
    mailing list.
    http://grass.osgeo.org/devel/index.php#submission


16. Try to evaluate things only once. Tcl compiles the program to bytecode which
    can be interpreted fairly quickly. If there are strings that must still be
    evaluated tcl must parse and either compile or interpret them
    each time they are encountered. In general this means put braces around
    expressions and especially regular expressions (Tcl also compiles regular
    expressions). Multiple evaluation can also lead to bugs.

    Expressions via expr command:
    Slow:
        set y [expr $a * $x + $b]
    Fast:
        set y [expr {$a * $x + $b}]

    Expressions in conditions:
    Slow:
        if [...] {...
    Fast:
        if {[...]} {...

    Regular expressions:
    Very slow:
        regex "x(\[0-9\]+).*not" $string trash number
    Fast:
        regex {x([0-9]+).*not} $string trash number

    If you really want speed:
    If a regular expression needs to be constructed from variables but used
    multiple times store it in a variable that will not be destroyed or
    changed between reuse. Tcl stores the compiled regex with the variable.


17. You might want to decompose lists in a somewhat easy way:

    Difficult and slow:
    # Make x1 y1 x2 y2 the first four things in the list
    set list [commandMakesList]
    set x1 [lindex $list 0]
    set y1 [lindex $list 1]
    set x2 [lindex $list 2]
    set y2 [lindex $list 3]

    Easier and faster:
    # Make x1 y1 x2 y2 the first four things in the list
    foreach {x1 y1 x2 y2} [commandMakesList] {break}

    Be sure to include a comment as to what you are doing.


18. Use the Tcl list functions (list, lappend etc) for manipulating lists.

    For example, use:

        set vals [list $foo $bar]

    rather than:

        set vals "$foo $bar"

    The former will always create a list with two elements, adding braces
    if necessary, while the latter will split $foo and $bar into multiple
    elements if they contain spaces. Additionally the first is faster
    because tcl is not internally converting between strings and lists.

    A related issue is to remember that command lines (as used by exec and
    open "|...") are lists. exec behaves like execl(), spawnl() etc, and
    not like system().

    Overlooking either of these points is likely to result in code which
    fails when a command argument contains a space.


19. Tcl C library:
    Memory allocated with Tcl_Alloc (such as the result of Tcl_Merge)
    must be freed with Tcl_Free. This means that the ->freeProc of
    an interpreter when returning a string using Tcl_Merge should be
    TCL_DYNAMIC. Incorrectly freeing memory with glibc free will
    cause segfaults in Tcl 8.4 and later.


20. When submitting new files to the repository set SVN properties,
    e.g.

      svn:executable : *
      svn:mime-type : text/x-tcl
      svn:keywords : Author Date Id
      svn:eol-style : native

    See
    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html

...
[please add further hints if required]