[GRASS-SVN] r31203 - grass-addons

svn_grass at osgeo.org svn_grass at osgeo.org
Fri May 2 08:08:33 EDT 2008


Author: neteler
Date: 2008-05-02 08:08:32 -0400 (Fri, 02 May 2008)
New Revision: 31203

Added:
   grass-addons/SUBMITTING
   grass-addons/SUBMITTING_DOCS
   grass-addons/SUBMITTING_PYTHON
   grass-addons/SUBMITTING_SCRIPTS
   grass-addons/SUBMITTING_TCLTK
Log:
added back submitting scripts

Added: grass-addons/SUBMITTING
===================================================================
--- grass-addons/SUBMITTING	                        (rev 0)
+++ grass-addons/SUBMITTING	2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,444 @@
+$Date: 2008-02-14 12:26:15 +0100 (Thu, 14 Feb 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting C code to GRASS SVN repository, please take care of
+following rules:
+
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+1.  Get and read the GRASS 6 Programmer's Manual here:
+    http://download.osgeo.org/grass/grass6_progman/
+
+    or generate it from this source code (the programmer's manual is
+    integrated in the source code in doxygen style):
+      make htmldocs
+      make pdfdocs
+
+
+2.  Use the directory structure to place your module appropriately into
+    the source tree
+    	- libes go into lib/
+    	- raster goes into raster/
+    	- vector goes into vector/
+    	- ...
+
+    Consider to take a look at "GNU Coding Standards"
+    http://www.gnu.org/prep/standards.html
+
+    In future, there will be a centralized contribution directory.
+
+
+3.  Add a header section to each file 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 (ficticious header for a file called color.c) :
+
+/****************************************************************************
+ *
+ * MODULE:       d.rast (or new higher level module name (eg GRASS core) 
+ *               for 6.1)
+ * AUTHOR(S):    Original author unknown - probably CERL
+ *               John Doe - jdoe at some.where.org
+ * PURPOSE:      To provide storage and manipulation of colors used for 
+ *               rendering the raster. The colors are stored in a doubly linked
+ *               list which must be initialized with InitColors() before it can
+ *               be used. Note that most linked list functionality (add,
+ *               remove, get) is supported, but their is no sorting
+ *               functionality.
+ * 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).
+
+
+4.  - deleted.
+    We don't want the $ ID $ in source code any more as it causes problems
+    for the SVN branches.
+
+
+5.  To ensure that the software system continues to work, please include
+
+	#include <grass/config.h>
+
+    in your files and make use of the various system dependencies
+    contained therein.  As one example of this, see lib/gmath/fft.c.
+    Please refrain from declaring system functions within the
+    software; include the proper header files (conditionally dependent
+    on config.h macros if necessary) instead.
+
+
+6. Order of include headers
+
+    In general, headers should be included in the order:
+ 
+    1. Core system headers (stdio.h, ctype.h, ...)
+    2. Headers for non-core system components (X11, libraries).
+    3. Headers for core systems of the package being compiled (grass/gis.h, grass/glocale.h, ...)
+    4. Headers for the specific library/program being compiled (geodesic.h, ...)
+ 
+    Each class of header has an obligation to be compatible with those
+    above it in the list, but not those below it.
+
+
+7.  Always specify the return type for ALL functions including those that
+    return type "void", and insert return statements for ALL functions.
+    Also, use ANSI C prototypes to declare your functions. 
+    For module return values, see "Exit status" below.
+
+    Examples:
+    
+    void G_something(void);
+    int G_something_else(int, int);
+    
+    void G_something(void)
+    {
+    	/* Snipped out code */
+	
+	return;
+    }
+    
+    int G_something_else(int x, int y)
+    {
+    	/* Snipped out code */
+	
+	return(0);
+    }
+
+
+8.  Module exit status is defined as EXIT_SUCCESS or EXIT_FAILURE, e.g.
+
+    {
+      ...
+      if (G_parser (argc, argv))
+          exit (EXIT_FAILURE);
+
+      ...
+      exit (EXIT_SUCCESS);
+    }
+
+
+9.  Use fprintf instead of printf. But:
+    
+    For errors and warnings please use the G_fatal_error() and
+    G_warning() functions. General messages for the user should use
+    G_message() while debug messages should use G_debug() whenever
+    possible. There are two variants to G_message(): G_verbose_message()
+    which will only display the message if in verbose mode, and
+    G_important_message() which will always show the message unless
+    the module is running in --quiet mode. G_fatal_error() and
+    G_warning() will always be displayed regardless of verbosity setting.
+    Messages sent to any of these functions will be printed to stderr.
+
+    G_message() output is not expected to be sent to pipe or file.
+
+    Always use the gettext macros with _("") for user messages,
+    example:
+      G_fatal_error (_("Vector map <%s> not found"), name); 
+
+
+    Pipe/file data output:
+    For data output redirected to pipe or file, please use fprintf() and 
+    specify the stdout stream as follows:
+
+      fprintf(stdout, ...);
+      fflush(stdout);
+
+      fflush(stdout) always required when using fprintf(stdout, ...).
+
+
+10. Use the GRASS library function G_asprintf() instead of the
+    standard C functions asprintf(), vsnprintf() and snprintf(). These
+    functions are not portable or have other issues.  Example:
+
+    char *msg;
+
+    G_asprintf(&msg, "%s", parameters);
+    do_something_with_msg();
+    G_free(msg);
+
+    Note that you should free memory when G_asprintf() is used.
+
+
+11. Use the following GRASS library functions instead of the standard C
+    functions. The reason for this is that the following functions ensure
+    good programming practice (e.g. always checking if memory was allocated)
+    and/or improves portability. PLEASE refer to the programmers manual
+    for the proper use (e.g. determining if any casts are needed for arguments
+    or return values) of these library functions. They may perform a task
+    slightly different from their corresponding C library function, and thus,
+    their use may not be the same.
+    
+    	G_malloc() instead of malloc()
+	G_calloc() instead of calloc()
+	G_realloc() instead of realloc()
+	G_free() instead of free()
+	G_getenv() instead of getenv()
+	G_setenv() instead of setenv()
+	G_unsetenv() instead of unsetenv()
+	G_sleep() instead of sleep()
+
+	Could somebody please add others (please verify that they are
+	useful and safe first)
+
+
+12. Use function names which fulfil the official GNU naming convention.
+    http://www.gnu.org/prep/standards/html_node/Names.html#Names
+
+    Instead of naming a function like: MyNewFunction() use underscores
+    for seperation and lower case letters: my_new_function().
+
+
+13. Don't use the C++ comment style! This confuses several compilers.
+    Use instead:
+       /* C-comments */
+
+    If you want to comment code portions, use
+       #ifdef notdef 
+            portion_to_be_commented;
+       #endif
+    This is safe comparing to nested /* comments */
+
+    Functions in the library must be documented in doxygen style to
+    get them into the programmer's manual (generate with 
+      make pdfdocs  or
+      make htmldocs
+    ). See lib/gis/*.c for examples.
+
+
+14. 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 may have to change your code in the future.
+
+
+15. To promote a consistent coding style, please use the "indent" program
+    on all new C modules using the following switches:
+    
+     $ indent -nbad -bap -bbb -nbbo -nbc -br -bli1 -bls -cbi0 -ncdb -nce \
+        -ci4 -cli0 -ncs -d0 -di0 -fc1 -nfca -hnl -i4 -ip4 -l80 -lc80 -lp \
+	-npcs -pi4 -nprs -npsl -sbi0 -sc -nsob -ss -ts8  main.c
+
+    Existing code should not be re-indented except in extreme cases, as this
+    will make "diff" comparisons with older versions impossible. If indent is 
+    needed, do not check in any changes other than the indentation in the same 
+    commit! Do add the indent switches and any indent warning messages to the 
+    SVN log. Any change or fix mixed in with an indent is very hard to track 
+    making it hard for others to follow the change or fix any new bugs.
+
+
+16. Platform dependent code:
+    Do not remove #ifdef __CYGWIN__ and/or #ifndef __CYGWIN__ lines and 
+    their encapsulated lines from source code (one example was that someone
+    removed drand48 definition.)
+
+
+17. Suggested compiler flags:
+    We suggest to use very strict compiler flags to capture errors
+    at the very beginning. Here our list of flags, please use them
+    to configure you development version of GRASS:
+
+    GNU/Linux:
+
+       MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
+       MYCXXFLAGS="-g -Wall"
+       
+       CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ... 
+
+    MacOSX:     [to be suggested]
+
+    MS-Windows: [to be suggested]
+
+
+18. Make sure a new line is at the end of each file.
+
+
+19. When writing Makefiles, use the current standard.
+
+    If you have to use commands, please check for:
+    
+            avoid     | use instead
+    ------------------+---------------
+    make target       | $(MAKE) target
+    mkdir target      | $(MKDIR) target
+    cp  (executable)  | $(INSTALL) -m 755 file target
+    cp  (normal file) | $(INSTALL) -m 644 file target
+    ar                | $(AR)
+
+    rm: be VERY careful with recursive remove.
+
+    Examples: see below examples or others
+              raster/r.info/Makefile
+              vector/v.digit/Makefile
+
+    If you are unsure, please ask on the GRASS Developers list.
+
+    
+20. Have a look at ./INSTALL
+
+
+21. Have a function included in your module which writes to the history
+    file of the map (e.g. command line, parameters etc.). See e.g.
+    raster/r.patch/main.c
+
+    (the same applies to vector and g3d modules!)
+
+
+22. Standard parser options: use G_define_standard_option() whenever possible
+    to define standard module command line options. This will save you time,
+    create fewer bugs, and make things easier on the translators.
+    See lib/gis/parser.c for details of the function definition.
+
+
+23. Add/update, if required the related GUI menus:
+     gui/tcltk/gis.m/gmmenu.tcl
+
+
+24. For consistency, use README rather than README.txt for any README files.
+
+
+25. GRASS/Environment variables:
+    If you add a new variable, please follow the naming convention.
+    All variables are described in
+    lib/init/variables.html
+
+
+26. 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.
+    "svn diff display/d.vect/main.c"; that way, the diff will
+    include the pathname rather than just "main.c".
+
+
+27. Try to use module names which describe shortly the intended purpose of the module.
+
+    The first letters for module name should be:
+	d. 	- display commands
+	db. 	- database commands
+	g. 	- general GIS management commands
+	i. 	- imagery commands
+	m.	- miscellaneous tool commands
+	ps. 	- postscript commands
+	r. 	- raster commands
+	r3. 	- raster3D commands
+	v. 	- vector commands
+
+    Some additional naming conventions
+    * export modules:     (type).out.(format) eg: r.out.arc,  v.out.ascii
+    * import module:      (type).in.(format)  eg: r.in.arc, v.in.ascii
+    * conversion modules: (type).to.(type)    eg: r.to.vect, v.to.rast, r3.to.rast
+
+    Avoid module names with more than two dots in the name. 
+    Example:
+       instead of r.to.rast3.elev use r.to.rast3elev    
+
+
+28. Use the grass test suite to test your modules.
+
+    http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
+
+    You can easily write specific tests for your modules.
+
+    If your module is part of GRASS and you created some standard test
+    cases, please contact the developers to add your tests to the
+    default test suite.  This will automatize complex test scenarios
+    and assure to find bugs much faster, if changes were made to your
+    modules or to the grass library.
+
+    Consider to subscribe to the GRASS Quality Assessment System to
+    get immediate notification about the code quality:
+
+    http://www.grass-gis.org/mailman/listinfo/grass-qa
+
+
+29. When submitting new files to the repository set SVN properties,
+    usually for directory
+
+      svn:ignore : *.tmp.html
+      		   *OBJ*
+
+    or e.g. for C-file
+    
+      svn:mime-type : text/x-csrc
+      svn:keywords : Author Date Id
+      svn:eol-style : native
+
+    See
+    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+30. Use doxygen style for source code documentation. It is required
+    for GRASS libraries, but also recommended for GRASS modules.
+
+    Do not use structural command inside documentation block since it
+    leads to some duplication of information (e.g. do not use \fn
+    command in comment blocks). The exception is \file command for
+    documenting a file, in this case structural command is required.
+
+    For files
+
+    /**
+       \file snap.c
+   
+       \brief Vector library - Clean vector map (snap lines)
+
+       (C) 2001-2008 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.
+   
+       \author Radim Blazek
+   
+       \date 2001-2008
+    */
+
+    For functions
+
+    /**
+       \brief Snap lines in vector map to existing vertex in threshold
+
+       For details see Vect_snap_lines_list()
+
+       \param[in] Map input vector map 
+       \param[in] type type of lines to be snap
+       \param[in] thresh threshold value for snapping
+       \param[out] Err vector map where lines representing snap are written or NULL
+       \param[out] msgout file pointer where messages will be written or NULL
+       
+       \return	   
+    */
+
+
+31. Tell the other developers about the new code using the following e-mail:
+    grass-dev at lists.osgeo.org
+ 
+    To subscribe to this mailing list, see
+    http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+32. In case of questions feel free to contact the developers at the above
+    mailing list.
+    http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]

Added: grass-addons/SUBMITTING_DOCS
===================================================================
--- grass-addons/SUBMITTING_DOCS	                        (rev 0)
+++ grass-addons/SUBMITTING_DOCS	2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,77 @@
+$Date: 2008-02-26 03:58:34 +0100 (Tue, 26 Feb 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting documentation to GRASS SVN repository, please take
+care of following rules:
+
+[ see SUBMITTING for C hints ]
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+1. Editing of HTML pages
+   To avoid insertion of too complicated HTML tags (see also below),
+   we strongly suggest to use a plain text editor rather than a
+   HTML editor for editing.
+
+
+2. Module manual page:
+   Place the documentation in HTML format into 'description.html'.
+   The easiest way to do this is to study an existing HTML page
+   (to get the page style, e.g. vector/v.to.db/description.html).
+   With a few exceptions header and footer are NOT allowed.
+   You can add figures (PNG format), the figure name prefix should be the 
+   module name. See raster/r.terraflow/description.html for an example.
+
+   Note that the parameter information is auto-generated upon
+   compilation. This is done by running module in a virtual session
+   after compilation (see the output of 'make'). To subsequently
+   verify the final HTML page, check the resulting HTML pages which
+   will be stored with the name of the module.
+
+   Examples (please add some) should be coded like this:
+
+   <div class="code"><pre>
+   v.to.db map=soils type=area option=area col=area_size unit=h
+   </pre></div>
+ 
+   The online WWW man pages is updated every Saturday (from SVN
+   repository).
+
+
+3. Usage of limited HTML tags
+   Since the MAN conversion of g.html2man is limited, please use
+   no other HTML tags than:
+   <A> <B> <BLINK> <BODY> <BR> <CODE> <DD> <DL> <DT> <EM> 
+   <H2> <H3> <H4>  <HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P>
+   <PRE> <SUP> <TABLE> <TD> <TH> <TITLE> <TR> <UL>
+
+
+4. Suggested HTML markup protocol:
+   Module names (i.e., v.category) should be emphsized with <em>,
+   and boldface <b> for flags and parameter names. Shell commands, 
+   names, values, etc. should use <tt>. Empahsized phrases should use 
+   italics <i>. The SEE ALSO section of each page should also be 
+   alphabetized. 	  		
+
+
+5. When submitting new files to the repository set SVN properties,
+   e.g. for HTML file
+    
+       svn:mime-type : text/html
+       svn:keywords : Author Date Id
+       svn:eol-style : native
+
+   See
+   http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+6. See also
+   http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation
+
+...
+[please add further hints if required]

Added: grass-addons/SUBMITTING_PYTHON
===================================================================
--- grass-addons/SUBMITTING_PYTHON	                        (rev 0)
+++ grass-addons/SUBMITTING_PYTHON	2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,109 @@
+$Date: 2008-01-06 12:42:32 +0100 (Sun, 06 Jan 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting Python code to GRASS SVN repository, please take
+care of following rules:
+
+[ see SUBMITTING for C hints ]
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_DOCS for documentation ]
+
+
+1.  Indentation
+
+    As Python determines nesting based upon indentation, it
+    isn't just a stylistic issue.
+
+    Please use 4-space indentation (GNU Emacs python-mode default).
+
+    See also "Python Style Guide" by Guido van Rossum
+    http://www.python.org/doc/essays/styleguide.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 over view of the code in the file to assist other
+    programmers that will need to make changes to your code. For this
+    purpose use Python Docstring, see
+    http://epydoc.sourceforge.net/docstrings.html
+
+    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) 2007 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.  - deleted.
+    We don't want the $ ID $ in source code any more as it causes problems
+    for the branches.
+
+
+4. 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 may have to change your code in the future.
+
+
+5. Make sure a new line is at the end of each file.
+
+
+6. For consistency, use README rather than README.txt for any README files.
+
+
+7. 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.
+   "svn diff gui/wxpython/wxgui.py"; that way, the diff will
+   include the pathname rather than just "wxgui.py".
+
+
+8. When submitting new files to the repository set SVN properties,
+   usually for directory
+
+      svn:ignore : *.pyc
+
+   or e.g. for Python file
+    
+      svn:mime-type : text/python
+      svn:keywords : Author Date Id
+      svn:eol-style : native
+
+   See
+   http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+8. Tell the other developers about the new code using the following e-mail:
+   grass-dev at lists.osgeo.org
+ 
+   To subscribe to this mailing list, see
+   http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+9. In case of questions feel free to contact the developers at the above
+   mailing list.
+   http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]

Added: grass-addons/SUBMITTING_SCRIPTS
===================================================================
--- grass-addons/SUBMITTING_SCRIPTS	                        (rev 0)
+++ grass-addons/SUBMITTING_SCRIPTS	2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,247 @@
+$Date: 2008-01-06 12:42:32 +0100 (Sun, 06 Jan 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting SHELL scripts to GRASS SVN repositiory,
+please take care of following rules:
+
+[ see SUBMITTING for C code hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+0.  Instructions for the GRASS script parser can be found in the g.parser 
+    module's help page.
+    http://grass.osgeo.org/grass63/manuals/html63_user/g.parser.html
+
+
+1.  Use the directory structure to place your script appropriately into
+    the source tree
+    	- scripts go into scripts/
+
+    Consider to take a look at [please suggest Shell tutorial].
+ 
+    Also add a Makefile and a description.html file into this directory.
+    See existing scripts for examples.
+
+
+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 (ficticious header for a script called r.myscript) :
+
+#!/bin/sh
+
+############################################################################
+#
+# 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).
+    You can easily autogenerate the header and parameters from an existing
+    module using the --script flag. Example:
+
+     d.rast --script
+
+    Just select an existing module which is close to your application to save
+    efforts.
+
+
+3.  - deleted.
+    We don't want the $ ID $ in scripts any more as it
+    causes problems for the SVN branches.
+
+
+4.  As a general principle, shell variables should almost always be quoted.
+    Use only secure temp files, see g.tempfile and scripts/* for examples.
+
+
+5.  [This rule is currently under review]  If you search for a command in $PATH, do NOT
+    use the "which" command or the "type -p" command. Both commands are not
+    supported on all platforms, thus causing problems for some people. As an
+    alternative, please use code similar to the following shell script snippet
+    which will perform the same function. In this case, the path of the grass60
+    command is saved if grass60 is found in $PATH. This won't recognize aliased
+    command name.
+
+	# Search for grass5 command in user's path
+	for i in `echo $PATH | sed 's/^:/.:/
+    	    	    		    s/::/:.:/g
+				    s/:$/:./
+				    s/:/ /g'`
+	do
+	    if [ -f $i/grass5 ] ; then
+    		
+		# Save the path of the grass60 command
+		GRASS_PATH=$i/grass60
+		# Use the first one in user's path
+		break
+	    fi
+	done
+
+<?>
+    If you must use "which", use as follows:
+
+	# check if we have awk
+	if [ ! -x "`which awk`" ] ; then
+	    g.message -e "awk required, please install awk or gawk first" 
+	    exit 1
+	fi
+</?>
+
+
+6.  Add a test to check if the user is in GRASS before starting main part 
+    of script. Result of running the script is unpredicable otherwise.
+
+	if [ -z "$GISBASE" ] ; then
+	    echo "You must be in GRASS GIS to run this program." 1>&2
+	    exit 1
+	fi
+
+    This is the only case, where g.message module (see below) can not be used.
+    In all other cases, you should prefer it's usage over the 'echo' command.
+
+
+7.  Create and use secure temporary files and directories. Use the g.tempfile
+    module to do this. e.g.
+
+	# setup temporary file
+	TMP="`g.tempfile pid=$$`"
+	if [ $? -ne 0 ] || [ -z "$TMP" ] ; then
+	    g.message -e "unable to create temporary files"
+	    exit 1
+	fi
+
+    For temportary directories remove the newly created file and mkdir using 
+    the same name. Beware of commands like "rm -f ${TMP}*" as this becomes
+    "rm -f *" if $TMP is unset (hence the test above).
+
+
+8.  Testing the existence of variables. For portability, use
+	if [ -z "$VARIABLE" ] ; then
+    instead of
+	if [ "$VARIABLE" == "" ] ; then
+
+    and
+
+	if [ -n "$VARIABLE" ] ; then
+    instead of
+	if [ "$VARIABLE" != "" ] ; then
+
+
+9.  Internationalization proofing Awk: In some areas (e.g. some European
+    countries) the decimal place is held with a comma instead of a dot.
+    When scanning variables awk doesn't understand this, so scripts need to 
+    temporarily discard locale settings before calling awk.
+
+	# set environment so that awk works properly in all languages
+	unset LC_ALL
+	LC_NUMERIC=C
+        export LC_NUMERIC
+
+	awk '{print $1}'
+
+
+10. Use g.findfile when there is a need to test if a map exists.
+
+	# test for input raster map
+	g.findfile element=cell file="$INPUT" > /dev/null
+	if [ $? -eq 0 ] ; then
+	  g.message -e "Raster map <$GIS_OPT_MAP> not found in mapset search path"
+	  exit 1
+	fi
+
+	# test for input vector map
+	eval `g.findfile element=vector file=$GIS_OPT_MAP`
+	if [ ! "$file" ] ; then
+	   g.message -e "Vector map <$GIS_OPT_MAP> not found in mapset search path"
+	   exit 1
+	fi
+
+    ... and so forth. See 'g.manual g.findfile' for details.
+
+
+11. For any informational output, use the g.message modul. This module should
+    be also used for error messages and warnings. You can also use it for
+    debugging purposes. 
+
+	#normal message:
+	g.message "Done"
+
+	# warning:
+        g.message -w "No input values found, using default values"
+
+	# error:
+        g.message -e "No map found, exiting."
+
+	# debug output (use g.gisenv to enable/disable)
+        g.message -d "Our calculated value is: $value"
+
+    Try to omit any usage of the 'echo' command for informational output.
+
+
+12. For consistency, use README rather than README.txt for any README files.
+
+
+13. Be sure to develop on top of the LATEST GRASS code (which is in SVN).
+    You can re-check before submission with 'cvs 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. For portability, scripts must work on any POSIX compliant shell, and
+    therefore may not include any Bashisms. Test with ash for errors:
+
+	ash -n scriptname
+
+
+15. When submitting new files to the repository set SVN properties,
+    usually for directory
+
+      svn:ignore : *.tmp.html
+
+    or e.g. for script file
+    
+      svn:executable : *
+      svn:mime-type : text/x-sh
+      svn:keywords : Author Date Id
+      svn:eol-style : native
+
+    See
+    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+16. Tell the other developers about the new code using the following e-mail:
+    grass-dev at lists.osgeo.org
+ 
+    To subscribe to this mailing list, see
+    http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+17. In case of questions feel free to contact the developers at the above
+    mailing list.
+    http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]

Added: grass-addons/SUBMITTING_TCLTK
===================================================================
--- grass-addons/SUBMITTING_TCLTK	                        (rev 0)
+++ grass-addons/SUBMITTING_TCLTK	2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,281 @@
+$Date: 2008-01-06 12:42:32 +0100 (Sun, 06 Jan 2008) $
+
+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 at 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://www.grass-gis.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]



More information about the grass-commit mailing list