$Id: SUBMITTING_SCRIPTS,v 1.6.4.1 2006/10/31 09:19:48 markus Exp $

NOTE: Please improve this list!

Dear (new) GRASS Developer,

When submitting SHELL SCRIPTS to GRASS CVS repositiory,
please take care of following rules:

[ see SUBMITTING for C code hints ]
[ see SUBMITTING_TCLTK for tcl and tk hints ]

0.  Instructions for the GRASS script parser can be found in the g.parser 
    module's help page.
    http://grass.ibiblio.org/grass62/manuals/html62_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]                                     

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).

3.  - deleted.
    We don't want the $ ID $ in scripts any more as it
    causes problems for the CVS 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.  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
	    echo "ERROR: awk required, please install awk or gawk first" 1>&2
	    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

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
	    echo "ERROR: unable to create temporary files" 1>&2
	    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
	export LC_NUMERIC=C

	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
	  echo "Input map not found" 1>&2
	  exit 1
	fi

11. Send solely informational output to stderr, not stdout.
	echo "Done." 1>&2

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 CVS).
    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 -u 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@grass.itc.it
 
    To subscribe to this mailing list, see
    http://grass.itc.it/devel/index.php

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

...
[please add further hints if required]
