Document and fix default-sort-order preference

 This patch resolves three related issues:

The first issue was that the GSettings schema for Caja did not include an
entry to sort by the "btime", or creation date, of files.  If the user chose
such an option in the Caja Preferences, GSettings would produce a warning
(often out-of-sight, as it was usually redirected into the user's
.xsession-errors file), and Caja would not actually change the default
sort-order of files.  This patch adds the btime as a valid setting in the
schema.

The second issue was that. because of the above (an entry in the settings
schema was missing), some of the alternative sort orders listed in the schema
(everything after and including "atime") were not assigned the same numbers
as the sort orders listed elsewhere in the Caja source code.  Specifically,
in icon- and compact-views, if the default sort-order was "emblems", the
observed / actual sort-order would be the entry before "emblems", namely
"atime" -- so instead of sorting by the names of associated emblems, Caja
would sort by each file's access time.  An array in the code for the
list-view also was missing many values and included some values out of order,
so the default sort-order setting affected directories viewed in list-view
mode seemingly randomly.  The former is taken care of using the fix described
in the above paragraph; the latter is fixed in this patch by adding /
reorganizing the array for the list-view sort-orders appropriately.

The third issue (admittedly, a lesser issue) was that the documentation for
the default-sort-order setting was lacking -- it at least did not list all
the possible values that the setting could accept.  In this patch, I resolve
this issue by listing all values in the setting's description, and also go
into more detail about what each value does.  (However, perhaps I included
a little too much detail.  It'll only benefit [supposed power users who may
already know this stuff] who use GSettings or DConf directly, and it'll
certainly be a headache for translators.  I'll admit that.)

2 files changed, 36 insertions, 7 deletions

diff --git a/libcaja-private/org.mate.caja.gschema.xml b/libcaja-private/org.mate.caja.gschema.xml
index 399efdc7..0f3bc015 100644
--- a/libcaja-private/org.mate.caja.gschema.xml
+++ b/libcaja-private/org.mate.caja.gschema.xml
@@ -35,11 +35,12 @@
     <value nick="size" value="3"/>
     <value nick="type" value="4"/>
     <value nick="mtime" value="5"/>
-    <value nick="atime" value="6"/>
-    <value nick="emblems" value="7"/>
-    <value nick="trash-time" value="8"/>
-    <value nick="size_on_disk" value="9"/>
-    <value nick="extension" value="10"/>
+    <value nick="btime" value="6"/>
+    <value nick="atime" value="7"/>
+    <value nick="emblems" value="8"/>
+    <value nick="trash-time" value="9"/>
+    <value nick="size_on_disk" value="10"/>
+    <value nick="extension" value="11"/>
   </enum>
 
   <enum id="org.mate.caja.ZoomLevel">
@@ -186,7 +187,33 @@
       </aliases>
       <default>'name'</default>
       <summary>Default sort order</summary>
-      <description>The default sort-order for items in the icon view. Possible values are "name", "size", "type", "mtime", and "emblems".</description>
+      <description>
+       The default sort-order for items in all view modes. Possible values are:
+
+       - "manually":  In icon- and compact-view modes, lets the user place and organize items any way the user wants them to be organized, simply by dragging each item to where the user desires.  In list-view mode, this setting is equivalent to "name" (see immediately below).
+
+       - "name":  Sort items by their name; for example, a file named "a.txt" will be sorted before a file named "b.txt".  This is the default.
+
+       - "directory":  Sort items by their full pathname.  For example, a file named "b.txt" under the directory "/home/a" will be sorted before a file named "a.txt" under the directory "/home/zzz".  Since Caja usually only displays files under one directory at any particular time, this setting will usually be equivalent to the "name" option (above), except in the Caja search tool, which can traverse files under multiple subdirectories.
+
+       - "size":  Sort items by their file size, or if the items are directories, by the number of items they contain.
+
+       - "type":  Sort items by their human-readable type description.  Such type descriptions take the form of, for instance, "plain text document" or "SVG image".  The type of the file is not necessarily related to the file's "extension" (see below).
+
+       - "mtime":  Sort items by their respective times of last modification.
+
+       - "btime":  Sort items by the date and time on which each file was created.  Note that not all files have a recorded creation time, so this setting may not always work as expected, especially on removable media that are "formatted" with legacy filesystems such as FAT.
+
+       - "atime":  Sort items by the date and time on which each file was last accessed.  Usually, "accessed" refers to the last time the file was read by a user or a program.  Note that, for performance reasons, some filesystems do not update this timestamp every time the file is read, so this field may be inaccurate.
+
+       - "emblems":  Sort items by the names of the emblems (if any) associated with each item.
+
+       - "trash-time":  Sort items by the date and time on which the file was moved to the Trash.  This setting is rarely useful, as it only applies to files currently in the Trash.
+
+       - "size_on_disk":  Sort by the amount of actual disk space each item consumes.  This figure is usually slightly larger than the conventional size of the file, since most filesystems pad files out to an even multiple of the "block size", which on many filesystems is 4096 bytes or about 4 kilobytes.  A few files may use less space on the disk than the conventional file size may indicate, due to a feature of some filesystems known as "holes".  This setting will not necessarily sort directories by the number of files they contain, since the amount of disk space used by a directory is not necessarily related to the number of files in a directory; other factors that can contribute to a directory's actual size include the length of the names of each file within the directory, and, interestingly, how many files the directory used to contain.
+
+       - "extension":  Sort by each item's file extension (if any).  The file's extension is a part of the file's name, and may not reflect the actual contents of the file, unlike the "type" setting (above).
+      </description>
     </key>
     <key name="default-sort-in-reverse-order" type="b">
       <default>false</default>
diff --git a/src/file-manager/fm-list-view.c b/src/file-manager/fm-list-view.c
index 87bb5d9e..b5a61459 100644
--- a/src/file-manager/fm-list-view.c
+++ b/src/file-manager/fm-list-view.c
@@ -179,12 +179,14 @@ get_default_sort_order (CajaFile *file, gboolean *reversed)
         "name",
         "uri",
         "size",
-        "size_on_disk",
         "type",
         "date_modified",
+        "date_created",
         "date_accessed",
         "emblems",
         "trashed_on",
+        "size_on_disk",
+        "extension",
         NULL
     };