From 7fe048153fe5675bd87e8269d60797613a45fc59 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 25 Apr 2024 17:24:34 -0400 Subject: [PATCH 1/2] init: renaming location to project for grass.py init script --- lib/init/grass.html | 89 +++++++++++++++++------------------ lib/init/grass.py | 111 +++++++++++++++++++++++++------------------- 2 files changed, 107 insertions(+), 93 deletions(-) diff --git a/lib/init/grass.html b/lib/init/grass.html index b80cb319338..46577d5e4d7 100644 --- a/lib/init/grass.html +++ b/lib/init/grass.html @@ -5,8 +5,8 @@

SYNOPSIS

grass [-h | -help | --help] [-v | --version] | [-c | -c geofile | -c EPSG:code[:datum_trans]] | -e | -f | [--text | --gtext | --gui] | --config | -[--tmp-location | --tmp-mapset] - [[[<GISDBASE>/]<LOCATION>/] +[--tmp-project | --tmp-mapset] + [[[<GISDBASE>/]<PROJECT>/] <MAPSET>] [--exec EXECUTABLE] @@ -21,19 +21,19 @@

Flags:

Prints the version of GRASS and exits
-c -
Creates new GRASS unprojected location in specified GISDBASE +
Creates new GRASS project (location) without coordinate reference system in specified GISDBASE
-c geofile -
Creates new GRASS projected location in specified GISDBASE based on georeferenced file +
Creates new GRASS project in specified GISDBASE with coordinate reference system based on georeferenced file
-c EPSG:code -
Creates new GRASS projected location in specified GISDBASE with given EPSG code +
Creates new GRASS project in specified GISDBASE with coordinate reference system specified by EPSG code
-c EPSG:code:datum_trans -
Creates new GRASS projected location in specified GISDBASE with given EPSG code and datum transform parameters +
Creates new GRASS project in specified GISDBASE with coordinate reference system specified by EPSG code and datum transform parameters
-e -
Exit after creation of location or mapset. Only with -c flag +
Exit after creation of project or mapset. Only with -c flag
-f
Forces removal of .gislock if exists (use with care!). Only with --text flag @@ -54,15 +54,15 @@

Flags:

--exec EXECUTABLE
Execute GRASS module or script. The provided executable will be executed in a GRASS GIS non-interactive session. -
--tmp-location -
Run using a temporary location which is created based on the given +
--tmp-project +
Run using a temporary project which is created based on the given coordinate reference system and deleted at the end of the execution (use with the --exec flag). The active mapset will be the PERMANENT mapset.
--tmp-mapset
Run using a temporary mapset which is created in the specified -location and deleted at the end of the execution +project and deleted at the end of the execution (use with the --exec flag). @@ -74,11 +74,12 @@

Parameters:

Initial database directory which should be a fully qualified path (e.g., /usr/local/share/grassdata) -
LOCATION -
Initial location directory which is a subdirectory of GISDBASE +
PROJECT +
Initial project directory which is a subdirectory of GISDBASE + (project was previously called location)
MAPSET -
Initial mapset directory which is a subdirectory of LOCATION +
Initial mapset directory which is a subdirectory of PROJECT Note: These parameters must be specified in one of the @@ -86,8 +87,8 @@

Parameters:

     MAPSET
-    LOCATION/MAPSET
-    GISDBASE/LOCATION/MAPSET
+    PROJECT/MAPSET
+    GISDBASE/PROJECT/MAPSET

DESCRIPTION

@@ -141,7 +142,7 @@

Config flag

SAMPLE DATA

The GRASS GIS project provides several free sample geospatial datasets -as ready-to-use locations. They are available to download at +as ready-to-use projects. They are available to download at https://grass.osgeo.org/download/sample-data/. The "North Carolina data set" is a modern package of geospatial data from @@ -247,20 +248,20 @@

EXAMPLES

grass
Start GRASS using the default user interface. The user will be - prompted to choose the appropriate location and mapset. + prompted to choose the appropriate project and mapset.
grass --gui
Start GRASS using the graphical user interface. The user will be - prompted to choose the appropriate location and mapset. + prompted to choose the appropriate project and mapset.
grass --text
Start GRASS using the text-based user interface. Appropriate -location and mapset must be set by environmental variables (see +project and mapset must be set by environmental variables (see examples below) otherwise taken from the last GRASS session.
grass --gtext
Start GRASS using the text-based user interface. The user will be - prompted to choose the appropriate location and mapset. + prompted to choose the appropriate project and mapset.
grass $HOME/grassdata/spearfish70/user1
Start GRASS using the default user interface and automatically @@ -268,27 +269,27 @@

EXAMPLES

grass --gui -
Start GRASS using the graphical user interface and try to - obtain the location and mapset from environment variables. + obtain the project and mapset from environment variables. -
grass -c EPSG:4326 $HOME/grassdata/mylocation -
Creates a new GRASS location with EPSG code 4326 (latitude-longitude, WGS84) +
grass -c EPSG:4326 $HOME/grassdata/myproject +
Creates a new GRASS project with EPSG code 4326 (latitude-longitude, WGS84) in the specified GISDBASE -
grass -c EPSG:5514:3 $HOME/grassdata/mylocation -
Creates a new GRASS location with EPSG code 5514 (S-JTSK / Krovak +
grass -c EPSG:5514:3 $HOME/grassdata/myproject +
Creates a new GRASS project with EPSG code 5514 (S-JTSK / Krovak East North - SJTSK) with datum transformation parameters used in Czech Republic in the specified GISDBASE
grass -c XY $HOME/grassdata/gnomonic --exec g.proj -c proj4='+proj=gnom +lat_0=90 +lon_0=-50' -
Creates a new GRASS location from PROJ definition string +
Creates a new GRASS project from PROJ definition string (here: gnomonic) in the specified GISDBASE -
grass -c myvector.shp $HOME/grassdata/mylocation -
Creates a new GRASS location based on georeferenced Shapefile +
grass -c myvector.shp $HOME/grassdata/myproject +
Creates a new GRASS project based on georeferenced Shapefile -
grass -c myraster.tif $HOME/grassdata/mylocation -
Creates a new GRASS location based on georeferenced GeoTIFF file +
grass -c myraster.tif $HOME/grassdata/myproject +
Creates a new GRASS project based on georeferenced GeoTIFF file

Batch jobs with the exec interface

@@ -300,7 +301,7 @@

Batch jobs with the exec interface

Region issues ignored. --> -Creating a new Location based on a geodata file's projection (-c) +Creating a new project based on a geodata file's projection (-c) and exit (-e) immediately: 
@@ -374,45 +375,45 @@ 
Execution of shell and Python scripts instead of single commands

     print(vector)
-

Using temporary location

+

Using temporary project

-Creating a new temporary location based on a georeferenced file's -projection coordinate reference system (CRS) and simultaneously starting +Creating a new temporary project based on a georeferenced file's +coordinate reference system (CRS) and simultaneously starting computation in a shell script: 
-grass --tmp-location elevation.tiff --exec test.sh
+grass --tmp-project elevation.tiff --exec test.sh
The same, but using an EPSG code and a Python script: 
-grass --tmp-location EPSG:3358 --exec test.py
+grass --tmp-project EPSG:3358 --exec test.py
-Finally, for special cases, we can create an XY location without any CRS: +Finally, for special cases, we can create an XY project without any CRS: 
-grass --tmp-location XY --exec test.py
+grass --tmp-project XY --exec test.py
-Temporary location is automatically deleted after computation, +Temporary project is automatically deleted after computation, so the script is expected to export, link or otherwise preserve the output data before ending.

A single command can be also executed, e.g. to examine properties of the -temporary location: +temporary project: 

-grass --tmp-location EPSG:3358 --exec g.proj -p
+grass --tmp-project EPSG:3358 --exec g.proj -p
-A temporary XY location with single command is useful, e.g. to show +A temporary XY project with single command is useful, e.g. to show help text of a module: 
-grass --tmp-location XY --exec r.neighbors --help
+grass --tmp-project XY --exec r.neighbors --help
@@ -420,7 +421,7 @@

Using temporary mapset

A single command can be executed, e.g., to examine properties of a -location (here using the NC SPM sample location): +project (here using the NC SPM sample dataset): 

 grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec g.proj -p
diff --git a/lib/init/grass.py b/lib/init/grass.py
index b29d638d116..b306f31d94d 100755
--- a/lib/init/grass.py
+++ b/lib/init/grass.py
@@ -309,10 +309,10 @@ def f(fmt, *args):
   $CMD_NAME [-h | --help] [-v | --version]
           [-c | -c geofile | -c EPSG:code[:datum_trans] | -c XY]
           [-e] [-f] [--text | --gtext | --gui] [--config param]
-          [[[GISDBASE/]LOCATION/]MAPSET]
-  $CMD_NAME [FLAG]... GISDBASE/LOCATION/MAPSET --exec EXECUTABLE [EPARAM]...
-  $CMD_NAME --tmp-location [geofile | EPSG | XY] --exec EXECUTABLE [EPARAM]...
-  $CMD_NAME --tmp-mapset GISDBASE/LOCATION/ --exec EXECUTABLE [EPARAM]...
+          [[[GISDBASE/]PROJECT/]MAPSET]
+  $CMD_NAME [FLAG]... GISDBASE/PROJECT/MAPSET --exec EXECUTABLE [EPARAM]...
+  $CMD_NAME --tmp-project [geofile | EPSG | XY] --exec EXECUTABLE [EPARAM]...
+  $CMD_NAME --tmp-mapset GISDBASE/PROJECT/ --exec EXECUTABLE [EPARAM]...
 
 {flags}:
   -h or --help                   {help_flag}
@@ -330,6 +330,8 @@ def f(fmt, *args):
                                    {config_detail}
   --exec EXECUTABLE              {exec_}
                                    {exec_detail}
+  --tmp-project                  {tmp_project}
+                                   {tmp_project_detail}
   --tmp-location                 {tmp_location}
                                    {tmp_location_detail}
   --tmp-mapset                   {tmp_mapset}
@@ -338,11 +340,11 @@ def f(fmt, *args):
 {params}:
   GISDBASE                       {gisdbase}
                                    {gisdbase_detail}
-  LOCATION                       {location}
-                                   {location_detail}
+  PROJECT                        {project}
+                                   {project_detail}
   MAPSET                         {mapset}
 
-  GISDBASE/LOCATION/MAPSET       {full_mapset}
+  GISDBASE/PROJECT/MAPSET        {full_mapset}
 
   EXECUTABLE                     {executable}
   EPARAM                         {executable_params}
@@ -364,10 +366,8 @@ def help_message(default_gui):
             flags=_("Flags"),
             help_flag=_("print this help message"),
             version_flag=_("show version information and exit"),
-            create=_("create given database, location or mapset if it doesn't exist"),
-            exit_after=_(
-                "exit after creation of location or mapset. Only with -c flag"
-            ),
+            create=_("create given database, project or mapset if it doesn't exist"),
+            exit_after=_("exit after creation of project or mapset. Only with -c flag"),
             force_removal=_(
                 "force removal of .gislock if exists (use with care!)."
                 " Only with --text flag"
@@ -384,14 +384,14 @@ def help_message(default_gui):
             ),
             params=_("Parameters"),
             gisdbase=_("initial GRASS database directory"),
-            gisdbase_detail=_("directory containing Locations"),
-            location=_("initial GRASS Location"),
-            location_detail=_(
-                "directory containing Mapsets with one common"
-                " coordinate system (projection)"
+            gisdbase_detail=_("directory containing GRASS projects"),
+            project=_("initial GRASS project (location)"),
+            project_detail=_(
+                "directory containing mapsets with one common"
+                " coordinate reference system"
             ),
-            mapset=_("initial GRASS Mapset"),
-            full_mapset=_("fully qualified initial Mapset directory"),
+            mapset=_("initial GRASS mapset"),
+            full_mapset=_("fully qualified initial mapset directory"),
             env_vars=_("Environment variables relevant for startup"),
             gui_var=_("select GUI (text, gui, gtext)"),
             html_var=_("set html web browser for help pages"),
@@ -407,14 +407,14 @@ def help_message(default_gui):
             executable=_("GRASS module, script or any other executable"),
             executable_params=_("parameters of the executable"),
             standard_flags=_("standard flags"),
-            tmp_location=_("create temporary location (use with the --exec flag)"),
-            tmp_location_detail=_(
+            tmp_location=_("deprecated, use --tmp-project instead"),
+            tmp_location_detail=_("location was renamed to project"),
+            tmp_project=_("create temporary project (use with the --exec flag)"),
+            tmp_project_detail=_(
                 "created in a temporary directory and deleted at exit"
             ),
             tmp_mapset=_("create temporary mapset (use with the --exec flag)"),
-            tmp_mapset_detail=_(
-                "created in the specified location and deleted at exit"
-            ),
+            tmp_mapset_detail=_("created in the specified project and deleted at exit"),
         )
     )
     s = t.substitute(
@@ -985,23 +985,23 @@ def cannot_create_location_reason(gisdbase, location):
     path = os.path.join(gisdbase, location)
     if is_location_valid(gisdbase, location):
         return _(
-            "Unable to create new location because"
-            " the location <{location}>"
+            "Unable to create new project because"
+            " the project <{location}>"
             " already exists."
         ).format(**locals())
     elif os.path.isfile(path):
         return _(
-            "Unable to create new location <{location}> because" " <{path}> is a file."
+            "Unable to create new project <{location}> because" " <{path}> is a file."
         ).format(**locals())
     elif os.path.isdir(path):
         return _(
-            "Unable to create new location <{location}> because"
+            "Unable to create new project <{location}> because"
             " the directory <{path}>"
             " already exists."
         ).format(**locals())
     else:
         return _(
-            "Unable to create new location in"
+            "Unable to create new project in"
             " the directory <{path}>"
             " for an unknown reason."
         ).format(**locals())
@@ -1064,11 +1064,11 @@ def set_mapset(
         # set gisdbase to temporary directory
         gisdbase = tmpdir
         # we are already in a unique directory, so we can use fixed name
-        location_name = "tmploc"
+        location_name = "tmpproject"
         # we need only one mapset
         mapset = "PERMANENT"
         debug(
-            "Using temporary location <{gdb}{sep}{lc}>".format(
+            "Using temporary project <{gdb}{sep}{lc}>".format(
                 gdb=gisdbase, lc=location_name, sep=os.path.sep
             )
         )
@@ -1129,11 +1129,11 @@ def set_mapset(
                         fatal(cannot_create_location_reason(gisdbase, location_name))
                     # create new location based on the provided EPSG/...
                     if not geofile:
-                        fatal(_("Provide CRS to create a location"))
+                        fatal(_("Provide CRS to create a project"))
                     if not tmp_location:
                         # Report report only when new location is not temporary.
                         message(
-                            _("Creating new GRASS GIS location <{}>...").format(
+                            _("Creating new GRASS GIS project <{}>...").format(
                                 location_name
                             )
                         )
@@ -1167,7 +1167,7 @@ def set_mapset(
                                 _(
                                     "No CRS is needed for creating mapset <{mapset}>, "
                                     "but <{geofile}> was provided as CRS."
-                                    " Did you mean to create a new location?"
+                                    " Did you mean to create a new project?"
                                 ).format(mapset=mapset, geofile=geofile)
                             )
                         if not tmp_mapset:
@@ -1203,7 +1203,7 @@ def set_mapset(
     else:
         fatal(
             _(
-                "GRASS GIS database directory, location and mapset"
+                "GRASS GIS database directory, project and mapset"
                 " not set properly."
                 " Use GUI or command line to set them."
             )
@@ -1908,7 +1908,7 @@ def csh_startup(location, grass_env_file):
 
     f.write("alias _location g.gisenv get=LOCATION_NAME\n")
     f.write("alias _mapset g.gisenv get=MAPSET\n")
-    f.write("alias precmd 'echo \"Mapset <`_mapset`> in Location <`_location`>\"'\n")
+    f.write("alias precmd 'echo \"Mapset <`_mapset`> in project <`_location`>\"'\n")
     f.write('set prompt="GRASS > "\n')
 
     # csh shell rc file left for backward compatibility
@@ -2282,7 +2282,7 @@ def add_mapset_arguments(parser, mapset_as_option):
             "--tmp-mapset",
             metavar="PATH",
             type=str,
-            help=_("use temporary mapset in location %(metavar)s"),
+            help=_("use temporary mapset in project %(metavar)s"),
         )
     else:
         parser.add_argument(
@@ -2290,19 +2290,25 @@ def add_mapset_arguments(parser, mapset_as_option):
             metavar="PATH",
             type=str,
             nargs="?",
-            help=_("path to mapset (or location if creating one)"),
+            help=_("path to mapset (or project if creating one)"),
         )
         parser.add_argument(
             "--tmp-mapset", action="store_true", help=_("use temporary mapset")
         )
     parser.add_argument(
-        "--tmp-location",
+        "--tmp-project",
         metavar="CRS",
         type=str,
         help=_(
-            "use temporary location with %(metavar)s (EPSG, georeferenced file, ...)"
+            "use temporary project with %(metavar)s (EPSG, georeferenced file, ...)"
         ),
     )
+    parser.add_argument(
+        "--tmp-location",
+        metavar="CRS",
+        type=str,
+        help=_("deprecated, use --tmp-project instead"),
+    )
     parser.add_argument(
         "-f",
         "--force-remove-lock",
@@ -2318,6 +2324,13 @@ def update_params_with_mapset_arguments(params, args):
     if args.tmp_location:
         params.tmp_location = True
         params.geofile = args.tmp_location
+        sys.stdout.write(
+            _("Option --tmp-location is deprecated, use --tmp-project instead\n")
+        )
+        sys.stdout.flush()
+    if args.tmp_project:
+        params.tmp_location = True
+        params.geofile = args.tmp_project
     if args.tmp_mapset:
         params.tmp_mapset = True
     if args.mapset:
@@ -2414,10 +2427,10 @@ def validate_cmdline(params):
     if params.exit_grass and not params.create_new:
         fatal(_("Flag -e requires also flag -c"))
     if params.create_new and not params.mapset:
-        fatal(_("Flag -c requires name of location or mapset"))
+        fatal(_("Flag -c requires name of project or mapset"))
     if params.tmp_location and params.tmp_mapset:
         fatal(
-            _("Either --tmp-location or --tmp-mapset can be used, not both").format(
+            _("Either --tmp-project or --tmp-mapset can be used, not both").format(
                 params.mapset
             )
         )
@@ -2425,14 +2438,14 @@ def validate_cmdline(params):
         fatal(
             _(
                 "Coordinate reference system argument (e.g. EPSG)"
-                " is needed for --tmp-location"
+                " is needed for --tmp-project"
             )
         )
     if params.tmp_location and params.mapset:
         fatal(
             _(
                 "Only one argument (e.g. EPSG) is needed for"
-                " --tmp-location, mapset name <{}> provided"
+                " --tmp-project, mapset name <{}> provided"
             ).format(params.mapset)
         )
     # For now, we allow, but not advertise/document, --tmp-location
@@ -2530,12 +2543,12 @@ def main():
                     " the '--gui' switch\n"
                     "     {cmd_name} --gui\n"
                     " - Launch with path to "
-                    "the location/mapset as an argument\n"
-                    "     {cmd_name} /path/to/location/mapset`\n"
-                    " - Create a location with '-c' and launch in its"
+                    "the project/mapset as an argument\n"
+                    "     {cmd_name} /path/to/project/mapset`\n"
+                    " - Create a project with '-c' and launch in its"
                     " PERMANENT mapset\n"
-                    "     {cmd_name} -c EPSG:number /path/to/location\n"
-                    "     {cmd_name} -c geofile /path/to/location\n"
+                    "     {cmd_name} -c EPSG:number /path/to/project\n"
+                    "     {cmd_name} -c geofile /path/to/project\n"
                     " - Create manually the GISRC file ({gisrcrc})\n"
                     " - Use '--help' for further options\n"
                     "     {cmd_name} --help\n"
@@ -2602,7 +2615,7 @@ def main():
                 elif not default_location:
                     fatal(
                         _(
-                            "Failed to start GRASS GIS, no default location to copy in"
+                            "Failed to start GRASS GIS, no default project to copy in"
                             " the installation or copying failed."
                         )
                     )

From 8fdc782c09a6dee0c4008837b80447dd513f4dd4 Mon Sep 17 00:00:00 2001
From: Anna Petrasova 
Date: Fri, 26 Apr 2024 15:25:26 -0400
Subject: [PATCH 2/2] review

---
 lib/init/grass.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/init/grass.html b/lib/init/grass.html
index 46577d5e4d7..094c2348267 100644
--- a/lib/init/grass.html
+++ b/lib/init/grass.html
@@ -20,17 +20,17 @@ 
Flags:

 
-v | --version
 
 Prints the version of GRASS and exits
 
-
-c
+
-c XY
 
 Creates new GRASS project (location) without coordinate reference system in specified GISDBASE
 
 
-c geofile
 
 Creates new GRASS project in specified GISDBASE with coordinate reference system based on georeferenced file
 
 
-c EPSG:code
-
 Creates new GRASS project in specified GISDBASE with coordinate reference system specified by EPSG code
+
 Creates new GRASS project in specified GISDBASE with coordinate reference system defined by EPSG code
 
 
-c EPSG:code:datum_trans
-
 Creates new GRASS project in specified GISDBASE with coordinate reference system specified by EPSG code and datum transform parameters
+
 Creates new GRASS project in specified GISDBASE with coordinate reference system defined by EPSG code and datum transform parameters
 
 
-e
 
 Exit after creation of project or mapset. Only with -c flag