[gvfs/wip/udisks2] Add text file describing how to influence what mounts are shown

[David Zeuthen <davidz src gnome org>]

commit 9cd1261803302c6122e2847ed12ca8439078d870
Author: David Zeuthen <davidz redhat com>
Date:   Wed Jan 18 15:17:00 2012 -0500

    Add text file describing how to influence what mounts are shown
    
    Signed-off-by: David Zeuthen <davidz redhat com>

 monitor/udisks2/what-is-shown.txt |   57 +++++++++++++++++++++++++++++++++++++
 1 files changed, 57 insertions(+), 0 deletions(-)
---
diff --git a/monitor/udisks2/what-is-shown.txt b/monitor/udisks2/what-is-shown.txt
new file mode 100644
index 0000000..82aa684
--- /dev/null
+++ b/monitor/udisks2/what-is-shown.txt
@@ -0,0 +1,57 @@
+
+         CONTROLLING WHAT IS SHOWN IN THE USER INTERFACE
+         ===============================================
+
+The gvfs-udisks2-volume-monitor process is responsible for the disks,
+media, mounts and fstab entries shown in the desktop user
+interface. In particular, the Desktop Shell (gnome-shell), the Files
+application (nautilus) as well as any other application use the GLib
+APIs, is using information from this process.
+
+In general, disks or media with mountable filesystems are shown, as
+are fstab entries. These are collectively referred to as "devices" in
+the following.
+
+A device is either mounted (in which case its directory is known) or
+it's not. If it's not mounted, then its directory is known only if its
+referenced in the /etc/fstab file. Similarly, the options for a device
+is either the options the device is currently mounted with or, if not
+currently mounted, options from its /etc/fstab if one is available.
+
+If the directory for a device is known and outside /media, $HOME
+(typically /home/foo) or $XDG_RUNTIME_DIR (typically /run/user/foo)
+then the device is not shown. Additionally, if any of component
+directories starts with a dot ("."), the device is not shown either.
+This policy may be overriden by use of the options comment=gvfs-show
+and comment=gvfs-hide.
+
+The name and icon to use for a device is chosen according to certain
+heuristics - for example, if a device has a filesystem label, it is
+used - if not, some other characteristic is used. The options
+comment=gvfs-name=<value> and comment=gvfs-icon=<value> can be used to
+override this policy with <value> being an URL-encoded string. For
+icons, the Icon Naming Specification
+
+ http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
+
+is used.
+
+Users are advised to use /dev/disk/* symlinks for /etc/fstab entries
+instead of the kernel names sda, sdb and so on.
+
+The Disks application provides an user interface to easily edit
+/etc/fstab entries including these options, see
+
+ http://people.freedesktop.org/~david/palimpsest-fstab-gvfs-show-option.png
+
+EXAMPLES
+--------
+
+# forcibly hide device in user interface
+/dev/disk/by-id/ata-HITACHI_HTS723232A7A364_E3834563KRG2HN-part1   /home/davidz/Data  auto  defaults,comment=gvfs-hide 0 0
+
+# forcibly show device in user interface and with name "My Movies"
+/dev/disk/by-uuid/4CAE8E5B5AF47502   /Movies  auto   defaults,comment=gvfs-show,comment=gvfs-name=My%20Movies
+
+# forcibly show NFS mount in user interface
+10.200.0.210:/tank/media  /mnt/Filer  nfs4  default,users,noauto,comment=gvfs-show  0 0