g.filename: Create dir in mapset only when asked (#1687)

The previous behavior is creating the corresponding directory in the current
mapset anytime the module is executed (the intention was only when the path is
in the current mapset according to the doc).

Creating the directory makes sense in general given the intended use of the module
(get path for a file in mapset, possibly in order to create it).
Given that there is a distinction between creation of an element (dir) and file
(even when file is a directory), having the functionality in a module
allows for treating the element case in a special way (not implemented yet, but see #1681).
However, notably, the module is used only in one v6 addon as of now.

However, given the primary function of this module (constructing a path regardless of
its existence), writing operation is unexpected, so the new default is not writing
anything and creation needs to be explicitly requested using a new -c flag
which causes fatal error when the constructed path is not in the current mapset
(asking for creation of something outside of the current mapset is considered a usage error).

general/g.filename/g.filename.html

@@ -63,13 +63,20 @@ base files as well as use existing ones.
 
 <p>
 If the mapset is the current mapset, <em>g.filename</em>
-automatically creates the <em>element</em> specified if it
-doesn't already exist.  This makes it easy to add new files
-to the data base without having to worry about the
-existence of the required data base directories.  (This
+can automatically create the <em>element</em> specified if it
+doesn't already exist when <b>-c</b> flag is used. This makes it easy
+to add new files to the data base without having to worry about the
+existence of the required data base directories. (This
 program will not create a new mapset, however, if that
 specified does not currently exist.)
 
+<p>
+This module should not be used to create directories which are at the level
+of what this module refer to as files, i.e., directory which carries a name
+specified by a user (such as vector map directories) should not be created
+using this module. Standard library functions coming with any given language
+are a more appropriate tool for that.
+
 <p>The program exits with a 0 if everything is ok;  it exits
 with a non-zero value if there is an error, in which case
 file=<em>'full_file_pathname'</em> is not output.

general/g.filename/main.c

@@ -32,6 +32,7 @@ int main(int argc, char *argv[])
     struct Option *opt1;
     struct Option *opt2;
     struct Option *opt3;
+    struct Flag *flag_create;
 
     G_gisinit(argv[0]);
 
@@ -61,6 +62,11 @@ int main(int argc, char *argv[])
     opt2->required = NO;
     opt2->description = _("Name of a mapset (default: current)");
 
+    flag_create = G_define_flag();
+    flag_create->key = 'c';
+    flag_create->label = _("Create element directory in the current mapset");
+    flag_create->description =
+        _("If element directory for database file does not exist, create it");
 
     if (G_parser(argc, argv))
 	exit(EXIT_FAILURE);
@@ -76,7 +82,16 @@ int main(int argc, char *argv[])
     if (strcmp(mapset, ".") == 0 || strcmp(mapset, "") == 0)
 	mapset = G_mapset();
 
-    G_make_mapset_element(element);
+    /* Create element directory if requested and in current mapset. */
+    if (flag_create) {
+        if (strcmp(mapset, G_mapset()) != 0) {
+            G_fatal_error("Cannot create <%s> (flag -%c):"
+                          " <%s> is not the current mapset (%s)",
+                          element, flag_create->key, mapset, G_mapset());
+        }
+        G_make_mapset_element(element);
+    }
+
     G_file_name(path, element, name, mapset);
 
     fprintf(stdout, "file='%s'\n", path);