eina vpath - improve docs and add app.tmp and usr.tmp vpaths too

definitely kaes the docs better with lots of sample paths and some
indication of what these may map to in real life.

src/lib/efreet/efreet.c

@@ -86,6 +86,7 @@ _efreet_efreet_app_interface_set(void)
    //   not set or empty, a default equal to $HOME/.local/share should be
    //   used.
    ENV_HOME_SET("XDG_DATA_HOME", ".local/share", data);
+   ENV_HOME_SET("XDG_TMP_HOME", ".local/tmp", tmp);
    // $XDG_CONFIG_HOME defines the base directory relative to which user
    //   specific configuration files should be stored. If $XDG_CONFIG_HOME
    //   is either not set or empty, a default equal to $HOME/.config should

src/lib/eina/eina_internal.h

@@ -59,6 +59,7 @@ struct _Eina_Vpath_Interface_User
    const char *config;
    const char *cache;
    const char *run;
+   const char *tmp;
 };
 
 /**

src/lib/eina/eina_vpath.c

@@ -35,7 +35,7 @@ _eina_vpath_data_get(const char *key)
 }
 
 
-static char*
+static char *
 _fallback_runtime_dir(const char *home)
 {
    char buf[PATH_MAX];
@@ -109,7 +109,7 @@ _fallback_runtime_dir(const char *home)
    return strdup(buf);
 }
 
-static char*
+static char *
 _fallback_home_dir()
 {
    char buf[PATH_MAX];
@@ -178,7 +178,7 @@ eina_vpath_shutdown(void)
    return EINA_TRUE;
 }
 
-EAPI char*
+EAPI char *
 eina_vpath_resolve(const char* path)
 {
    // XXX: implement parse of path then look up in hash if not just create
@@ -306,14 +306,17 @@ eina_vpath_interface_app_set(const char *app_domain, Eina_Prefix *app_pfx)
    _eina_vpath_data_add("app.data", eina_prefix_data_get(app_pfx));
    _eina_vpath_data_add("app.locale", eina_prefix_locale_get(app_pfx));
    snprintf(buf, sizeof(buf), "%s/%s",
-            _eina_vpath_data_get("config"), app_domain);
+            _eina_vpath_data_get("usr.config"), app_domain);
    _eina_vpath_data_add("app.config", buf);
    snprintf(buf, sizeof(buf), "%s/%s",
-            _eina_vpath_data_get("cache"), app_domain);
+            _eina_vpath_data_get("usr.cache"), app_domain);
    _eina_vpath_data_add("app.cache", buf);
    snprintf(buf, sizeof(buf), "%s/%s",
-            _eina_vpath_data_get("data"), app_domain);
+            _eina_vpath_data_get("usr.data"), app_domain);
    _eina_vpath_data_add("app.local", buf);
+   snprintf(buf, sizeof(buf), "%s/%s",
+            _eina_vpath_data_get("usr.tmp"), app_domain);
+   _eina_vpath_data_add("app.tmp", buf);
 }
 
 EAPI void
@@ -342,8 +345,9 @@ eina_vpath_interface_user_set(Eina_Vpath_Interface_User *user)
    ADD(config);
    ADD(cache);
    ADD(run);
+   ADD(tmp);
 #undef ADD
 
    if (free_run)
-     free((char*)user->run);
+     free((char *)user->run);
 }

src/lib/eina/eina_vpath.h

@@ -3,29 +3,89 @@
 
 #include "eina_prefix.h"
 
-/*
- * Eina_vpath
- * eina vpath is a path that can be prefixed with a virtual path.
- *
- * A virutla path can either start with (:XXXXXXXX:) that indicates a virtual path, OR normal with / or ./ or ../ or ~
- * The char sequence in between (: and :) are used as key to lookup the real value.
- * The key has to be set by a interface before, otherwise you will get a error.
- *
- * The symbol ~ is interpretated as the home directory of the running user, and will be replaced.
- * Additional infos: https://phab.enlightenment.org/w/eina_vpath/
- */
-
 /**
- * This datatype is a vpath, this means you can use the syntax described above.
+ * Eina vpath is a path that can be prefixed with a virtual path.
+ *
+ * A virutal path can either start with (:XXXXXXXX:) that indicates a virtual
+ * path with XXXXXXXX as the location, OR a normal path with / or a realative
+ * path like ./ or ../ or even shell common locatiors like ~/ or ~username/
+ *
+ * The string between (: and :) is used as key to lookup the real value.
+ * The key has to be set by an interface before, otherwise you will get an
+ * error.
+ *
+ * Sample paths:
+ *
+ *   ~/myfiles/file.png
+ *   ~bob/dir/file.txt
+ *   /path/to/file.cfg
+ *   ./file/relative/path.txt
+ *   file/relative/path.txt
+ *   (:tmp:)/some-temp-file/file.txt
+ *   (:home:)/myfiles/file.png
+ *
+ *   (:app.dir:)/bin/app-executable
+ *   (:app.bin:)/app-executable-file
+ *   (:app.lib:)/app-library.so
+ *   (:app.data:)/application/datafile.png
+ *   (:app.locale:)/en_US/LC_MESSAGES/app.mo
+ *   (:app.config:)/application-config.xml
+ *   (:app.local:)/application-data-file.jpg
+ *   (:app.tmp:)/some-temp-file/path/file.txt
+ *
+ *   (:usr.desktop:)/file-in-users-desktop-directory.txt
+ *   (:usr.documents:)/letter-to-gradma.doc
+ *   (:usr.downloads:)/file-downloaded-here.zip
+ *   (:usr.music:)/fave-song.mp3
+ *   (:usr.pictures:)/a-photo.,jpg
+ *   (:usr.public:)/some-publicly-shared-file
+ *   (:usr.templates:)/some-template-document.txt
+ *   (:usr.videos:)/some-video-file.mp4
+ *   (:usr.data:)/file-in-user-data-dir
+ *   (:usr.config:)/file-in-user-conifg-dir
+ *   (:usr.cache:)/file-in-user-cache-dir
+ *   (:usr.run:)/file-in-xdg-runtime-dir
+ *   (:usr.tmp:)/some-temp-file/path/file.txt
+ *
+ * Commonly mapped to real path (but may vary):
+ *
+ *   (:tmp:) - /tmp
+ *   (:home:) - ~/
+ *
+ *   (:app.dir:) - /usr - (assuming app install PREFIX of /usr. may be /usr/local or others too)
+ *   (:app.bin:) - /usr/bin - (almost always PREFIX/bin)
+ *   (:app.lib:) - /usr/lib - (almost always PREFIX/lib)
+ *   (:app.data:) - /usr/share/appname - (almost always PREIFX/share/appname)
+ *   (:app.locale:) - /usr/share/locale - (almost always PREFIX/locale)
+ *   (:app.config:) - ~/.config/appname
+ *   (:app.local:) - ~/.local/share/appname
+ *   (:app.tmp:) - ~/.local/tmp/appname
+ *
+ *   (:usr.desktop:) - ~/Desktop
+ *   (:usr.documents:) - ~/Documents
+ *   (:usr.downloads:) - ~/Downloads
+ *   (:usr.music:) - ~/Music
+ *   (:usr.pictures:) - ~/Pictures
+ *   (:usr.public:) - ~/Public
+ *   (:usr.templates:) - ~/Templates
+ *   (:usr.videos:) - ~/Videos
+ *   (:usr.data:) - ~/.local/share
+ *   (:usr.config:) - ~/.config
+ *   (:usr.cache:) - ~/.cache
+ *   (:usr.run:) - /var/run/user/1000
+ *   (:usr.tmp:) - ~/.local/tmp
+ *
+ * Additional info: https://phab.enlightenment.org/w/eina_vpath/
+ *
  */
-typedef const char* Eina_Vpath;
+typedef const char * Eina_Vpath;
 
 /*
  * Translate a virtual path into a normal path.
  *
- * @return a string that is not virtual anymore
+ * @return NULL if failed, or a full normal string file path that is resolved
  *
  */
-EAPI char* eina_vpath_resolve(Eina_Vpath path);
+EAPI char *eina_vpath_resolve(Eina_Vpath path);
 
 #endif