comments and doc

src/sampleconf/recoll.conf

@@ -33,16 +33,21 @@ topdirs = ~
 # <brief>Files and directories which should be ignored.</brief>
 # 
 # <descr> White space separated list of wildcard patterns (simple ones, not paths, must contain no
-# '/' characters), which will be tested against file and directory names. Have a look at the default
-# configuration for the initial value, some entries may not suit your situation. The easiest way to
-# see it is through the GUI Index configuration "local parameters" panel. The list in the default
-# configuration does not exclude hidden directories (names beginning with a dot), which means that
-# it may index quite a few things that you do not want. On the other hand, email user agents like
-# Thunderbird usually store messages in hidden directories, and you probably want this indexed. One
-# possible solution is to have ".*" in "skippedNames", and add things like "~/.thunderbird"
-# "~/.evolution" to "topdirs".  Not even the file names are indexed for patterns in this list, see
-# the "noContentSuffixes" variable for an alternative approach which indexes the file names. Can be
-# redefined for any subtree.</descr>
+# '/' characters), which will be tested against file and directory names.
+#
+# Have a look at the default configuration for the initial value, some entries may not suit your
+# situation. The easiest way to see it is through the GUI Index configuration "local parameters"
+# panel.
+#
+# The list in the default configuration does not exclude hidden directories (names beginning with a
+# dot), which means that it may index quite a few things that you do not want. On the other hand,
+# email user agents like Thunderbird usually store messages in hidden directories, and you probably
+# want this indexed. One possible solution is to have ".*" in "skippedNames", and add things like
+# "~/.thunderbird" "~/.evolution" to "topdirs".
+#
+# Not even the file names are indexed for patterns in this list, see the "noContentSuffixes"
+# variable for an alternative approach which indexes the file names. Can be redefined for any
+# subtree.</descr>
 #
 #</var>
 skippedNames = #* CVS  Cache cache* .cache caughtspam tmp \
@@ -104,19 +109,26 @@ noContentSuffixes+ =
 # <var name="skippedPaths" type="string">
 #
 # <brief>Absolute paths we should not go into.</brief>
-# <descr>Space-separated list of wildcard expressions for absolute
-# filesystem paths. Must be defined at the top level of the configuration
-# file, not in a subsection. Can contain files and directories. The database and
-# configuration directories will automatically be added. The expressions
-# are matched using 'fnmatch(3)' with the FNM_PATHNAME flag set by
-# default. This means that '/' characters must be matched explicitly. You
-# can set 'skippedPathsFnmPathname' to 0 to disable the use of FNM_PATHNAME
-# (meaning that '/*/dir3' will match '/dir1/dir2/dir3'). The default value
-# contains the usual mount point for removable media to remind you that it
-# is a bad idea to have Recoll work on these (esp. with the monitor: media
-# gets indexed on mount, all data gets erased on unmount). Explicitly
-# adding '/media/xxx' to the 'topdirs' variable will override
-# this.</descr></var>
+#
+# <descr>Space-separated list of wildcard expressions for absolute filesystem paths (for files or
+# directories). The variable must be defined at the top level of the configuration file, not in a
+# subsection.
+#
+# Any value in the list must be textually consistent with the values in topdirs, no attempts are
+# made to resolve symbolic links. In practise, if, as is frequently the case, /home is a link to
+# /usr/home, your default topdirs will have a single entry '~' which will be translated to
+# '/home/yourlogin'. In this case, any skippedPaths entry should start with '/home/yourlogin' *not*
+# with '/usr/home/yourlogin'.
+#
+# The index and configuration directories will automatically be added to the list.
+#
+# The expressions are matched using 'fnmatch(3)' with the FNM_PATHNAME flag set by default. This
+# means that '/' characters must be matched explicitly. You can set 'skippedPathsFnmPathname' to 0
+# to disable the use of FNM_PATHNAME (meaning that '/*/dir3' will match '/dir1/dir2/dir3').
+#
+# The default value contains the usual mount point for removable media to remind you that it is in
+# most cases a bad idea to have Recoll work on these Explicitly adding '/media/xxx' to the 'topdirs'
+# variable will override this.</descr></var>
 skippedPaths = /media
 
 # <var name="skippedPathsFnmPathname" type="bool"><brief>Set to 0 to