[GRASS-SVN] r45880 - grass/trunk
svn_grass at osgeo.org
svn_grass at osgeo.org
Sat Apr 9 08:43:50 EDT 2011
Author: martinl
Date: 2011-04-09 05:43:50 -0700 (Sat, 09 Apr 2011)
New Revision: 45880
Removed:
grass/trunk/SUBMITTING_SCRIPTS
Modified:
grass/trunk/SUBMITTING
grass/trunk/SUBMITTING_DOCS
grass/trunk/SUBMITTING_PYTHON
Log:
update SUBMITTINGS for GRASS7, shell script rules removed
Modified: grass/trunk/SUBMITTING
===================================================================
--- grass/trunk/SUBMITTING 2011-04-09 03:58:52 UTC (rev 45879)
+++ grass/trunk/SUBMITTING 2011-04-09 12:43:50 UTC (rev 45880)
@@ -1,19 +1,14 @@
-$Date$
-
NOTE: Please improve this list!
-Dear (new) GRASS Developer,
+Dear (new) GRASS developer,
-When submitting C code to GRASS SVN repository, please take care of
+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 ]
+[ see also SUBMITTING_PYTHON for Python code hints ]
+[ see alse SUBMITTING_DOCS for documentation ]
-
-1. Get and read the GRASS 6 Programmer's Manual here:
+1. Get and read the GRASS Programmer's Manual here:
http://grass.osgeo.org/programming7/
or generate it from this source code (the programmer's manual is
@@ -25,39 +20,32 @@
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/
+ - raster modules go into raster/
+ - vector modules go 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. If you
+ are modifying an existing file you may under no circumstances
+ remove prior copyright or licensing text that is not your own,
+ even for a major rewrite. If any original code or code that is in
+ part derived from another's original work remains, it must be
+ properly cited.
-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. If you are modifying an existing
- file you may under no circumstances remove prior copyright or licensing
- text that is not your own, even for a major rewrite. If any original
- code or code that is in part derived from another's original work
- remains, it must be properly cited.
-
Example (ficticious header for a file called color.c) :
/****************************************************************************
*
- * MODULE: d.rast (or new higher level module name (eg GRASS core))
- * AUTHOR(S): Original author unknown - probably CERL
- * John Doe <jdoe at somewhere 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 there is no sorting
- * functionality.
- * COPYRIGHT: (C) 2010 by the GRASS Development Team
+ * MODULE: g.foo
+ * AUTHOR(S): John Doe <jdoe at somewhere org>
+ * PURPOSE: Provide short description of module here...
+ * COPYRIGHT: (C) 2010 by John Doe, and the GRASS Development Team
*
* This program is free software under the GNU General Public
* License (>=v2). Read the COPYING file that comes with GRASS
@@ -69,8 +57,7 @@
License (www.gnu.org).
-4. - deleted.
- We don't want the $ID$ in source code any more as it causes problems
+4. We don't want the $ID$ in source code any more as it causes problems
for the SVN branches.
@@ -113,6 +100,8 @@
void G_something(void)
{
/* Snipped out code */
+
+ return;
}
int G_something_else(int x, int y)
@@ -123,7 +112,8 @@
}
-8. Module exit status is defined as EXIT_SUCCESS or EXIT_FAILURE, e.g.
+8. Module exit status is defined as EXIT_SUCCESS or EXIT_FAILURE
+ (declared in stdlib.h), e.g.
{
...
@@ -135,13 +125,13 @@
}
-9. Use fprintf instead of printf. But:
+9. Use fprintf() instead of printf()
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
+ 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.
@@ -194,7 +184,6 @@
G_setenv() instead of setenv()
G_unsetenv() instead of unsetenv()
G_sleep() instead of sleep()
- G_system() instead of system()
Could somebody please add others (please verify that they are
useful and safe first)
@@ -289,7 +278,7 @@
Examples: see below examples or others
raster/r.info/Makefile
- vector/v.digit/Makefile
+ vector/v.edit/Makefile
If you are unsure, please ask on the GRASS Developers list.
@@ -311,7 +300,6 @@
23. Add/update, if required the related GUI menus:
- gui/tcltk/gis.m/gmmenu.tcl
gui/wxpython/xml/menudata.xml
@@ -374,7 +362,7 @@
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
+ http://lists.osgeo.org/mailman/listinfo/grass-qa
29. When submitting new files to the repository set SVN properties,
@@ -428,6 +416,8 @@
(please update the list...)
+ For your convenience use the tools/module_svn_propset.sh script.
+
30. Use doxygen style for source code documentation. It is required
for GRASS libraries, but also recommended for GRASS modules.
@@ -438,26 +428,23 @@
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
+ 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()
@@ -481,7 +468,7 @@
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
+ http://grass.osgeo.org/devel/index.php#submission
...
[please add further hints if required]
Modified: grass/trunk/SUBMITTING_DOCS
===================================================================
--- grass/trunk/SUBMITTING_DOCS 2011-04-09 03:58:52 UTC (rev 45879)
+++ grass/trunk/SUBMITTING_DOCS 2011-04-09 12:43:50 UTC (rev 45880)
@@ -1,15 +1,11 @@
-$Date$
-
NOTE: Please improve this list!
-Dear (new) GRASS Developer,
+Dear (new) GRASS developer,
-When submitting documentation to GRASS SVN repository, please take
+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 for C hints ]
[ see SUBMITTING_PYTHON for Python code hints ]
@@ -17,7 +13,7 @@
There are two types of documentation
- Libraries programmers docs: we use doxygen and document the functions
- directly in the source code. See lib/*/*.c and lib/*/*.dox for examples
+ directly in the source code. See lib/gis/*.c and lib/gis/gislib.dox for examples
- User manual: we write it in simple HTML, storing the manual in a
file '<module>.html' within the subdirectory of the module.
@@ -75,7 +71,7 @@
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
+ v.to.db map=soils type=area option=area column=area_size unit=h
</pre></div>
The online WWW man pages is updated every Saturday (from SVN
@@ -85,9 +81,9 @@
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>
+ <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:
Modified: grass/trunk/SUBMITTING_PYTHON
===================================================================
--- grass/trunk/SUBMITTING_PYTHON 2011-04-09 03:58:52 UTC (rev 45879)
+++ grass/trunk/SUBMITTING_PYTHON 2011-04-09 12:43:50 UTC (rev 45880)
@@ -1,114 +1,186 @@
-$Date$
-
NOTE: Please improve this list!
-Dear (new) GRASS Developer,
+Dear (new) GRASS developer,
-When submitting Python code to GRASS SVN repository, please take
+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 for C hints ]
[ see SUBMITTING_DOCS for documentation ]
-1. Indentation
+0. Indentation
- As Python determines nesting based upon indentation, it
- isn't just a stylistic issue.
+ 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
+1. Instructions for the GRASS script parser can be found in the g.parser
+ module's help page.
+ http://grass.osgeo.org/grass70/manuals/html70_user/g.parser.html
-2. Add a header section to the script you submit and make sure you
+2. Use the directory structure to place your script appropriately into
+ the source tree
+ - scripts go into scripts/
+
+ Also add a Makefile and a <module>.html file into this directory.
+ See existing Python scripts for examples.
+
+3. 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):
+ Example (fictitious header for a script called g.myscript):
"""
-MODULE: r.myscript
+MODULE: g.myscript
-AUTHOR(S): Me <email AT some domain>
+AUTHOR(S): John Doe <email AT some domain>
-PURPOSE: Calculates univariate statistics from a GRASS raster map
+PURPOSE: Describe your script here...
-COPYRIGHT: (C) 2007 by the GRASS Development Team
+COPYRIGHT: (C) 2007 John Doe, and 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).
+ 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:
-3. - deleted.
- We don't want the $ ID $ in source code any more as it causes problems
+ d.rast --script
+
+ Just select an existing module which is close to your application to save
+ efforts.
+
+4. We don't want the $ ID $ in source code any more as it causes problems
for the branches.
+5. Create and use secure temporary files and directories. Use the
+ grass.tempfile() or grass.tempdir() functions to do this. e.g.
-4. PLEASE take the time to add comments throughout your code explaining what
+ # setup temporary file
+ TMP = grass.tempfile()
+ if TMP is None:
+ grass.fatal("Unable to create temporary files")
+
+6. Use grass.findfile() when there is a need to test if a map exists.
+
+ # test for input raster map
+ result = grass.find_file(name = map_name, element = 'cell', quiet = True)
+ if not result['file']
+ grass.fatal("Raster map <%s> not found" % map_name)
+
+ # test for input vector map
+ result = grass.find_file(name = map_name, element = 'vector', quiet = True)
+ if not result['file']
+ grass.fatal("Vector map <%s> not found" % map_name)
+
+ ... and so forth. See 'g.manual g.findfile' for details.
+
+7. For any informational output, use the grass.message()
+ function. For error messages should be used grass.fatal_error() or
+ grass.error() and for warnings grass.warning(). For debugging
+ purposes grass.debug().
+
+ #normal message:
+ grass.message("Done")
+
+ # warning:
+ grass.warning("No input values found, using default values")
+
+ # error:
+ grass.error("No map found")
+
+ # fatal error:
+ grass.fatal_error("No map found, exiting")
+
+ # debug output (use g.gisenv to enable/disable)
+ grass.debug("Our calculated value is: %d" % value)
+
+ Try to omit any usage of the 'print' command for informational output.
+
+8. 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.
+9. 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.
+10. 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':
+11. 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.
+ 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".
+ 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
+12. When submitting new files to the repository set SVN properties,
+ usually for directory
svn:ignore : *.pyc
- or e.g. for Python file
+ 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
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
-9. wxGUI (gui/wxpython)
+13. wxGUI (gui/wxpython)
- See http://wiki.wxpython.org/wxPython_Style_Guide
+ See http://wiki.wxpython.org/wxPython_Style_Guide
+ Major rules:
-10. Tell the other developers about the new code using the following e-mail:
- grass-dev at lists.osgeo.org
+ - use named parameters in functions, e.g.
+
+ dlg = wx.FileDialog(parent = self, message = _("Choose file to save current workspace"),
+ wildcard = _("GRASS Workspace File (*.gxw)|*.gxw"), style = wx.FD_SAVE)
+
+ instead of
+
+ dlg = wx.FileDialog(self, _("Choose file to save current workspace"),
+ _("GRASS Workspace File (*.gxw)|*.gxw"), wx.FD_SAVE)
+
+ - use wx.ID_ANY instead of `-1`
+
+ - use gcmd.GError(), gcmd.GWarning and gcmd.GMessage instead of wx.MessageBox()
+
+ - use gcmd.RunCommand() instead of grass.run_command() or grass.read_command()
+
+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
+ To subscribe to this mailing list, see
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
-11. In case of questions feel free to contact the developers at the above
- mailing list.
- http://www.grass-gis.org/devel/index.php#submission
+15. In case of questions feel free to contact the developers at the above
+ mailing list.
+ http://grass.osgeo.org/devel/index.php#submission
...
[please add further hints if required]
Deleted: grass/trunk/SUBMITTING_SCRIPTS
===================================================================
--- grass/trunk/SUBMITTING_SCRIPTS 2011-04-09 03:58:52 UTC (rev 45879)
+++ grass/trunk/SUBMITTING_SCRIPTS 2011-04-09 12:43:50 UTC (rev 45880)
@@ -1,250 +0,0 @@
-$Date$
-
-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]
-
-
-"Your attention to detail is appreciated."
More information about the grass-commit
mailing list