[meld] Fill out file filtering documentation

[Kai Willadsen <kaiw src gnome org>]

commit 6d52c6b8c2bbe04be1905bea8197f3dce713e0fc
Author: Kai Willadsen <kai willadsen gmail com>
Date:   Sun Jun 3 11:22:35 2012 +1000

    Fill out file filtering documentation

 help/C/filtering-files.page |  116 +++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 112 insertions(+), 4 deletions(-)
---
diff --git a/help/C/filtering-files.page b/help/C/filtering-files.page
index 71cdff4..acfc6eb 100644
--- a/help/C/filtering-files.page
+++ b/help/C/filtering-files.page
@@ -20,7 +20,7 @@ folder. Alternatively, you might want to ignore all the files in your
 and what kind of differences you see. You can filter based on
 <link xref="file-state-filter">differences between a file across
 folders</link> or <link xref="file-name-filter">file and folder
-names</link>. You can also tell <app>Meld</app> to treat file names
+names</link>. You can also tell <app>Meld</app> to treat filenames
 as being <link xref="file-case-filter">case insensitive</link>.
 Finally, you can use <link xref="text-filters">text filters</link> to
 change what both folder and file comparisons see.
@@ -41,22 +41,130 @@ change what both folder and file comparisons see.
 <title>File differences filtering</title>
 
 <p>
+In a folder comparison, each line contains a single file or folder
+that is present in at least one of the folders being compared. Each of
+these lines is classified as being either <em>Modifed</em>, <em>New</em>
+or <em>Same</em>:
 </p>
+<terms>
+  <item>
+    <title>Modified</title>
+    <p>The file exists in multiple folders, but the files are different</p>
+  </item>
+  <item>
+    <title>New</title>
+    <p>The file exists in one folder but not in the others</p>
+  </item>
+  <item>
+    <title>Same</title>
+    <p>The file exists in all folders, and is the same everywhere</p>
+  </item>
+</terms>
+<p>
+You can change which types of differences you see in your current
+comparison by using the <gui style="button">Same</gui>,
+<gui style="button">New</gui> and <gui style="button">Modified</gui>
+buttons on the toolbar or the
+<guiseq><gui style="menu">View</gui><gui style="menuitem">File Status</gui></guiseq>
+menu.
+</p>
+
+<note style="tip">
+  <p>
+  Currently, you can only filter files based on their state; folders
+  can't be filtered in this way. For example, you can't tell
+  <app>Meld</app> to ignore all folders that contain only new files. A
+  folder containing only "New" files would show up as empty, but still
+  present.
+  </p>
+</note>
+
 </section>
 
 
 
 <section id="file-name-filter">
-<title>File name filtering</title>
+<title>Filename filtering</title>
 
 <p>
+<app>Meld</app> comes with a useful set of filename filters that let you
+ignore uninteresting files and folders like common backup files and the
+metadata folders of version control systems. Each filename filter can be
+separately activated or deactivated from the
+<gui style="button">Filters</gui> button on the toolbar or the
+<guiseq><gui style="menu">View</gui><gui style="menuitem">File Filters</gui></guiseq>
+menu.
 </p>
+
+<p>
+You can add, remove or change filename filters from the
+<gui style="tab">File Filters</gui> section of the <gui>Preferences</gui>
+dialog. Filename filters specify patterns of filenames that will
+<em>not</em> be looked at when performing a folder comparison. Any file
+that matches an active filter won't even show up in the tree comparison.
+Filename filters match both files and folders; if a folder matches
+a filter, it and all of its contents are ignored.
+</p>
+
+<p>
+Filename filters match according to shell glob patterns. For example,
+<code>*.jpg</code> will match all filenames ending in <code>.jpg</code>.
+The following table lists all of the shell glob characters that
+<app>Meld</app> recognises.
+</p>
+
+<table frame="top bottom">
+  <title>Shell glob patterns</title>
+
+  <thead>
+    <tr>
+      <td><p>Wildcard</p></td><td><p>Matches</p></td>
+    </tr>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td><p><code>*</code></p></td>
+      <td><p>anything (i.e., zero or more characters)</p></td>
+    </tr>
+    <tr>
+      <td><p><code>?</code></p></td>
+      <td><p>exactly one character</p></td>
+    </tr>
+    <tr>
+      <td><p><code>[abc]</code></p></td>
+      <td><p>any one of the listed characters</p></td>
+    </tr>
+    <tr>
+      <td><p><code>[!abc]</code></p></td>
+      <td><p>anything <em>except</em> one of the listed characters</p></td>
+    </tr>
+    <tr>
+      <td><p><code>{cat,dog}</code></p></td>
+      <td><p>either "cat" or "dog"</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<note style="tip">
+  <p>
+  Changing a filter's <gui>Active</gui> setting in the
+  <gui>Preferences</gui> dialog changes whether that filter is active
+  <em>by default</em>.
+  </p>
+
+  <p>
+  Activating a filter from the menu or the toolbar turns the filter on
+  or off for <em>this comparison only</em>.
+  </p>
+</note>
+
 </section>
 
 
 
 <section id="file-case-filter">
-<title>Case insensitive file names</title>
+<title>Case insensitive filenames</title>
 
 <p>
 Files are compared across directories according to their name. This
@@ -67,7 +175,7 @@ all be seen as different files.
 
 <p>
 When comparing folders on some filesystems (e.g., HFS+ or FAT) you may
-wish to make <app>Meld</app> treat file names as case insensitive. You
+wish to make <app>Meld</app> treat filenames as case insensitive. You
 can do this by selecting
 <guiseq><gui style="menu">View</gui><gui style="menuitem">Ignore filename case</gui></guiseq>
 from the menus.