[GRASS-SVN] r61737 - grass-addons
svn_grass at osgeo.org
svn_grass at osgeo.org
Mon Aug 25 13:19:26 PDT 2014
Author: neteler
Date: 2014-08-25 13:19:26 -0700 (Mon, 25 Aug 2014)
New Revision: 61737
Removed:
grass-addons/SUBMITTING_DOCS
grass-addons/SUBMITTING_PYTHON
grass-addons/SUBMITTING_SCRIPTS
grass-addons/SUBMITTING_TCLTK
Modified:
grass-addons/SUBMITTING
Log:
Addons SUBMITTING: moved to trac (trac #2104)
Modified: grass-addons/SUBMITTING
===================================================================
--- grass-addons/SUBMITTING 2014-08-25 20:14:28 UTC (rev 61736)
+++ grass-addons/SUBMITTING 2014-08-25 20:19:26 UTC (rev 61737)
@@ -1,444 +1 @@
-$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://lists.osgeo.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://grass.osgeo.org/devel/index.php#submission
-
-...
-[please add further hints if required]
+See http://trac.osgeo.org/grass/wiki/Submitting
Deleted: grass-addons/SUBMITTING_DOCS
===================================================================
--- grass-addons/SUBMITTING_DOCS 2014-08-25 20:14:28 UTC (rev 61736)
+++ grass-addons/SUBMITTING_DOCS 2014-08-25 20:19:26 UTC (rev 61737)
@@ -1,124 +0,0 @@
-$Date: 2009-03-20 04:42:27 -0800 (Fri, 20 Mar 2009) $
-
-NOTE: Please improve this list!
-
-Dear (new) GRASS GIS 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 ]
-
-
-0. Introduction
-
- 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
-
- - User manual: we write it in simple HTML, storing the manual in a
- file "description.html" within the subdirectory of the module.
- The file contains no header nor footer. The complete HTML file is
- autogenerated during the compilation process (indeed, it is generated
- in a virtual session directly after compilation of the module).
- In this virtual session the module is called internally with
- --html-description which generates the parameters/flags list in
- HTML format, along with "description.html", HTML header and footer
- the final HTML manual page is created and stored in the target
- binaries directory. In a separate process the MAN format is
- generated from the complete HTML files.
-
-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/v.to.db.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/r.terraflow.html for an example.
-
- A number of major sections should be present in each help page.
-
- * = Required
- ! = Suggested
- . = Optional
-
- In recommended order
- --------------------
-
- * <h2>DESCRIPTION</h2>
- ! <h2>NOTE</H2>, <h2>NOTES</h2>
- ! <h2>EXAMPLE</h2>, <h2>EXAMPLES</h2>
- . <h2>TODO</h2>
- . <h2>BUGS</h2>
- . <h2>REFERENCE</h2>, <h2>REFERENCES</h2>
- * <h2>SEE ALSO</h2>
- * <h2>AUTHOR</h2>, <h2>AUTHORS</h2>
-
- Note that the parameter information is auto-generated upon
- compilation. This is done by running the 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>
-
- Note that all tags has a closing tag except for <hr/>, <br/> and <p>.
- Use lower case forms.
-
- (The MAN converter is here: tools/g.html2man/)
-
-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
-
- You can also simply use this script:
- http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh
-
-6. Compress PNG images with
- optipng -o5 file.png
-
-7. See also
- http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
-
-...
-[please add further hints if required]
-
-"Your attention to detail is appreciated."
Deleted: grass-addons/SUBMITTING_PYTHON
===================================================================
--- grass-addons/SUBMITTING_PYTHON 2014-08-25 20:14:28 UTC (rev 61736)
+++ grass-addons/SUBMITTING_PYTHON 2014-08-25 20:19:26 UTC (rev 61737)
@@ -1,109 +0,0 @@
-$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://grass.osgeo.org/devel/index.php#submission
-
-...
-[please add further hints if required]
Deleted: grass-addons/SUBMITTING_SCRIPTS
===================================================================
--- grass-addons/SUBMITTING_SCRIPTS 2014-08-25 20:14:28 UTC (rev 61736)
+++ grass-addons/SUBMITTING_SCRIPTS 2014-08-25 20:19:26 UTC (rev 61737)
@@ -1,248 +0,0 @@
-$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
- - raster goes into raster/
- etc.
-
- 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://grass.osgeo.org/devel/index.php#submission
-
-...
-[please add further hints if required]
Deleted: grass-addons/SUBMITTING_TCLTK
===================================================================
--- grass-addons/SUBMITTING_TCLTK 2014-08-25 20:14:28 UTC (rev 61736)
+++ grass-addons/SUBMITTING_TCLTK 2014-08-25 20:19:26 UTC (rev 61737)
@@ -1,281 +0,0 @@
-$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://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]
More information about the grass-commit
mailing list