rewrite so it's understandable without knowing about the related command-line options

doc/preferred_content.mdwn

@@ -39,8 +39,8 @@ files that `git annex get --auto` will want to get, and `git annex find
 will want to drop.
 
 The expressions are very similar to the matching options documented
-on the [[git-annex]] man page. At the command line, you can use those
+on the [[git-annex-matching-options]] man page.
-options in commands like this:
+At the command line, you can use those options in commands like this:
 
 	git annex get --include='*.mp3' --and -'(' --not --largerthan=100mb -')'
 
@@ -48,12 +48,17 @@ The equivalent preferred content expression looks like this:
 
 	include=*.mp3 and (not largerthan=100mb)
 
-So, just remove the dashes, basically. However, there are some differences
+So, just remove the dashes, basically. But, there are some differences
-from the command line options to keep in mind:
+between the command line options and expressions, so see the documentation
+below to get the full story.
 
-### difference: file matching
+## expressions
 
-While --include and --exclude match files relative to the current
+* `include=glob` and `exclude=glob`
+
+  Match files to include, or exclude.
+
+  While --include=glob and --exclude=glob match files relative to the current
   directory, preferred content expressions always match files relative to the
   top of the git repository. 
 
@@ -63,16 +68,11 @@ to not retain those files, like this:
 
 	exclude=*/archive/*
 
-### difference: no "in="
+* `copies=number`
 
-Preferred content expressions have no direct equivalent to `--in`.
+  Matches only files that git-annex believes to have the specified number
-
+  of copies, or more. Note that it does not check remotes to verify that
-Often, it's best to add repositories to groups, and match against
+  the copies still exist.
-the groups in a preferred content expression. So rather than
-`--in=usbdrive`, put all the USB drives into a "transfer" group,
-and use "copies=transfer:1"
-
-### difference: dropping
 
   To decide if content should be dropped, git-annex evaluates the preferred
   content expression under the assumption that the content has *already* been
@@ -82,11 +82,72 @@ content be dropped only when there are currently 3 copies of it, including
   the repo it's being dropped from. This is different than running `git annex
   drop --copies=2`, which will drop files that currently have 2 copies.
 
-### difference: "present"
+* `copies=trustlevel:number`
 
-There's a special "present" keyword you can use in a preferred content
+  Matches only files that git-annex believes have the specified number
-expression. This means that content is wanted if it's present,
+  copies, on remotes with the specified trust level. For example,
-and not otherwise. This leaves it up to you to use git-annex manually
+  `copies=trusted:2`
+
+  To match any trust level at or higher than a given level,
+  use 'trustlevel+'. For example, `--copies=semitrusted+:2`
+
+* `copies=groupname:number`
+
+  Matches only files that git-annex believes have the specified number of
+  copies, on remotes in the specified group. For example,
+  `copies=archive:2`
+
+  Preferred content expressions have no equivilant to the `--in`
+  option, but groups can accomplish similar things. You can add
+  repositories to groups, and match against the groups in a
+  preferred content expression. So rather than `--in=usbdrive`,
+  put all the USB drives into a "transfer" group, and use
+  `copies=transfer:1`
+
+* `lackingcopies=number`
+
+  Matches only files that git-annex believes need the specified number or
+  more additional copies to be made in order to satisfy their numcopies
+  settings.
+
+* `approxlackingcopies=number`
+
+  Like lackingcopies, but does not look at .gitattributes annex.numcopies
+  settings. This makes it significantly faster.
+
+* `inbackend=name`
+
+  Matches only files whose content is stored using the specified key-value
+  backend.
+
+* `inallgroup=groupname`
+
+  Matches only files that git-annex believes are present in all repositories
+  in the specified group.
+
+* `smallerthan=size` and `largerthan=size`
+
+  Matches only files whose content is smaller than, or larger than the
+  specified size.
+
+  The size can be specified with any commonly used units, for example,
+  "0.5 gb" or "100 KiloBytes"
+
+* `metadata=field=glob`
+
+  Matches only files that have a metadata field attached with a value that
+  matches the glob. The values of metadata fields are matched case
+  insensitively.
+
+  To match a tag "done", use `metadata=tag=done`
+
+  To match author metadata, use `metadata=author=* Smith"
+
+* `present`
+
+  Makes content be wanted if it's present, but not otherwise.
+
+  This leaves it up to you to use git-annex manually
   to move content around. You can use this to avoid preferred content
   settings from affecting a subdirectory. For example:
 
@@ -96,19 +157,17 @@ Note that `not present` is a very bad thing to put in a preferred content
   expression. It'll make it want to get content that's not present, and
   drop content that is present! Don't go there..
 
-### difference: "inpreferreddir"
+* `inpreferreddir`
 
-There's a special "inpreferreddir" keyword you can use in a
+  Makes content be preferred if it's in a directory (located anywhere
-preferred content expression of a special remote. This means that the
+  in the tree) with a particular name. 
-content is preferred if it's in a directory (located anywhere in the tree)
-with a special name.
 
   The name of the directory can be configured using 
   `git annex enableremote $remote preferreddir=$dirname`
 
   (If no directory name is configured, it uses "public" by default.)
 
-### difference: "standard"
+* `standard`
 
   git-annex comes with some built-in preferred content expressions, that
   can be used with repositories that are in some [[standard_groups]].
@@ -121,9 +180,9 @@ groups, "standard" will match anything.. so don't do that!)
 
   Most often, the whole preferred content expression is simply "standard".
   But, you can do more complicated things, for example:
-"`standard or include=otherdir/*`"
+  `standard or include=otherdir/*`
 
-### difference: "groupwanted"
+* `groupwanted`
 
   The "groupwanted" keyword can be used to refer to a preferred content
   expression that is associated with a group. This is like the "standard"
@@ -158,42 +217,39 @@ wants to contain 3 copies of each file:
 		git annex wanted $repo groupwanted
 	done
 
-### difference: metadata matching
+* `unused`
 
-This:
+  Matches only keys that `git annex unused` has determined to be unused.
 
-	git annex get --metadata tag=done
+  This is related the the --unused option.
-
+  However, putting `unused` in a preferred content expression 
-becomes
+  doesn't make git-annex consider those unused keys. So when git-annex is
-
-	metadata=tag=done
-
-### difference: unused
-
-The --unused option makes git-annex operate on every key that `git annex
-unused` has determined to be unused. The corresponding `unused` keyword
-in a preferred content expression also matches those keys. 
-
-However, using `unused` in a preferred content expression 
-doesn't make git-annex consider those keys. So when git-annex is
   only checking preferred content expressions against files in the
   repository (which are obviously used), `unused` in a preferred
   content expression won't match anything.
 
   So when is `unused` useful in a preferred content expression?
 
-* The git-annex assistant periodically scans for unused files, and
+  1. Using `git annex sync --content --all` will operate on all files,
+    including unused ones, and take `unused` in preferred content expressions
+    into account.
+  2. The git-annex assistant periodically scans for unused files, and
     moves them to some repository whose preferred content expression
     matches "unused". (Or, if annex.expireunused is set, it may just delete
     them.)
-* Using `git annex sync --content --all` will operate on all files,
-  including unused ones, and take `unused` in preferred content expressions
-  into account.
 
-### difference: anything
+* `anything`
 
-The "anything" keyword can be used in a preferred content expression
+  Matches any version of any file.
-to match any version of any file.
+
+* `not expression`
+
+  Inverts what the expression matches. For example, `not include=archive/*`
+  is the same as `exclude=archive/*`
+
+* `and` / `or` / `( expression )`
+
+  These can be used to build up more complicated expressions.
 
 ## upgrades