[GRASS5] Jan's copyright notice ++

[Frank Warmerdam]

Andreas Lange wrote:
> the file header is as such a nice idea. But wouldn't it be possible to
> get one step further and introduce something that can be processed
> automated (with some documentation system or something homegrown)?
> I feel it is a waste of time to re-write the headers (which are from
> on-liners to several pages of prose) while we have not decided how the
> future development strategy will be.
> 
> If we agree that we want the modules have internal information about
> authors, version, purpose, function, title etc. this should be done in
> one place/with one system.

Andreas,

I think that there is a big difference in effort between settling on a new
style of header, and applying it to code as touched vs. implementing 
auto-extractable function descriptions which would have to be applied to
all interesting functions to be of much use. 
 
> Another question: What should be done with the old comment headers? I am
> clueless if they must be preserved for license reasons or if the info
> should be included into the new headers and then discarded.

I presume we should try to retain information in the PURPOSE field, and
if the copyright isn't GPL, then retain the copyright information in the
COPYRIGHT field. 

On the suggested format, I have a few questions.

/*
* <Id flag - see STYLE_PROGRAMMING for proper syntax>
*
****************************************************************************
* 	               -- GRASS Development Team --
*
* MODULE: 	GRASS gis library

What does MODULE mean?  Is this effectively the directory the files is in?
Would it be "raster" for src/raster/r.in.gdal?   Please explain more fully.

* FILENAME:	env.c

I hate including filenames in standard headers.  It will be included in the
$Id$ after exapansion anyways, and filenames in the header that need to be
hand maintained are often not done properly, and just left with the value 
copied from somewhere else.  I propose this be dropped. 

* AUTHOR(S):	Original author unknown - probably CERL
*  	    	Justin Hickey - Bangkok Thailand - jhickey at hpcc.nectec.or.th
*   	    	Roger Bivand - rsb at reclus.nhh.no
* PURPOSE: 	To provide functionality for GRASS programs to set and get
*  	    	environment variables. The set environment functions can set
*  	    	variables for the duration of the program, or variables can be
*  	    	set permanently by adding them to the GISRC file. The get
*  	    	environment functions simply get the given variable from the
*  	    	environment regardless of whether it is permanent or not. 
*  	    	Functions are also provided to read and write the GISRC file.
*  	    	This file has been rewritten by Justin Hickey.
* DATE CREATED: Jul 14 2000

What is the purpose of DATE CREATED?   Perhaps it should be dropped.

* COPYRIGHT:  	(C) 2000 by the GRASS Development Team
*
*   	    	This program is free software under the GPL (>=v2)
*   	    	Read the file COPYING that comes with GRASS for details.
*
*****************************************************************************/

Beyond the above I would like to see capture of log messages automatically.
I find it enormously useful to be able to scan back through log messages (the
same messages entered on a CVS commit) when looking at source file. 

The following is an example of the header style I normally use.  I think the
most sigificant difference compared to the proposed style is the inclusion of
the $Log$ section to auto-generate checkin logs.  Could we consider dropping
DATE CREATED and FILENAME from the existing style, and adding a $Log$ section?

/******************************************************************************
 * $Id: make_loc.c,v 1.1 2000/10/31 04:39:43 frankw Exp $
 *
 * Project:  libgrass
 * Purpose:  Function to create a new location automatically given a 
 *           "Cell_head", PROJ_INFO and PROJ_UNITS information.
 * Author:   Frank Warmerdam, warmerda at home.com
 *
 ******************************************************************************
 * Copyright (c) 2000, Frank Warmerdam
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 ******************************************************************************
 *
 * $Log: make_loc.c,v $
 * Revision 1.1  2000/10/31 04:39:43  frankw
 * New
 *
 */

---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerda at home.com
light and sound - activate the windows | http://members.home.com/warmerda
and watch the world go round - Rush    | Geospatial Programmer for Rent

---------------------------------------- 
If you want to unsubscribe from GRASS Development Team mailing list write to:
minordomo at geog.uni-hannover.de with
subject 'unsubscribe grass5'