fileset: add a help topic

fileset: add a help topic

Add crosslinking with patterns topic.

--- a/mercurial/help.py	Sat Jun 18 16:53:49 2011 -0500
+++ b/mercurial/help.py	Sat Jun 18 16:53:49 2011 -0500
@@ -7,7 +7,7 @@
 
 from i18n import gettext, _
 import sys, os
-import extensions, revset, templatekw, templatefilters
+import extensions, revset, fileset, templatekw, templatefilters
 import util
 
 def listexts(header, exts, indent=1):
@@ -61,6 +61,7 @@
     (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
      loaddoc('multirevs')),
     (['revset', 'revsets'], _("Specifying Revision Sets"), loaddoc('revsets')),
+    (['fileset', 'filesets'], _("Specifying File Sets"), loaddoc('filesets')),
     (['diffs'], _('Diff Formats'), loaddoc('diffs')),
     (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
     (['templating', 'templates'], _('Template Usage'),
@@ -102,6 +103,7 @@
         return makeitemsdoc(topic, doc, marker, symbols)
     addtopichook(topic, add)
 
+addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
 addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
 addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
 addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/filesets.txt	Sat Jun 18 16:53:49 2011 -0500
@@ -0,0 +1,65 @@
+Mercurial supports a functional language for selecting a set of
+files. 
+
+Like other file patterns, this pattern type is indicated by a prefix,
+'set:'. The language supports a number of predicates which are joined
+by infix operators. Parenthesis can be used for grouping.
+
+Identifiers such as filenames or patterns must be quoted with single
+or double quotes if they contain characters outside of
+``[.*{}[]?/\_a-zA-Z0-9\x80-\xff]`` or if they match one of the
+predefined predicates. This generally applies to file patterns other
+than globs and arguments for predicates.
+
+Special characters can be used in quoted identifiers by escaping them,
+e.g., ``\n`` is interpreted as a newline. To prevent them from being
+interpreted, strings can be prefixed with ``r``, e.g. ``r'...'``.
+
+There is a single prefix operator:
+
+``not x``
+  Files not in x. Short form is ``! x``.
+
+These are the supported infix operators:
+
+``x and y``
+  The intersection of files in x and y. Short form is ``x & y``.
+
+``x or y``
+  The union of files in x and y. There are two alternative short
+  forms: ``x | y`` and ``x + y``.
+
+``x - y``
+  Files in x but not in y.
+
+The following predicates are supported:
+
+.. predicatesmarker
+
+Some sample queries:
+
+- Show status of files that appear to be binary in the working directory::
+
+    hg status -A "set:binary()"
+
+- Forget files that are in .hgignore but are already tracked::
+
+    hg forget "set:hgignore() and not ignored()"
+
+- Find text files that contain a string::
+
+    hg locate "set:grep(magic) and not binary()"
+
+- Find C files in a non-standard encoding::
+
+    hg locate "set:**.c and not encoding(ascii)"
+
+- Revert copies of large binary files::
+
+    hg revert "set:copied() and binary() and size('>1M')"
+
+- Remove files listed in files.lst that contain the letter a or b::
+
+    hg remove "set: 'listfile:foo.lst' and (**a* or **b*)"
+
+See also :hg:`help patterns`.

--- a/mercurial/help/patterns.txt	Sat Jun 18 16:53:49 2011 -0500
+++ b/mercurial/help/patterns.txt	Sat Jun 18 16:53:49 2011 -0500
@@ -49,3 +49,5 @@
 
   listfile:list.txt  read list from list.txt with one file pattern per line
   listfile0:list.txt read list from list.txt with null byte delimiters
+
+See also :hg:`help filesets`.

--- a/tests/test-globalopts.t	Sat Jun 18 16:53:49 2011 -0500
+++ b/tests/test-globalopts.t	Sat Jun 18 16:53:49 2011 -0500
@@ -338,6 +338,7 @@
    diffs        Diff Formats
    environment  Environment Variables
    extensions   Using additional features
+   filesets     Specifying File Sets
    glossary     Glossary
    hgignore     syntax for Mercurial ignore files
    hgweb        Configuring hgweb
@@ -418,6 +419,7 @@
    diffs        Diff Formats
    environment  Environment Variables
    extensions   Using additional features
+   filesets     Specifying File Sets
    glossary     Glossary
    hgignore     syntax for Mercurial ignore files
    hgweb        Configuring hgweb

--- a/tests/test-help.t	Sat Jun 18 16:53:49 2011 -0500
+++ b/tests/test-help.t	Sat Jun 18 16:53:49 2011 -0500
@@ -108,6 +108,7 @@
    diffs        Diff Formats
    environment  Environment Variables
    extensions   Using additional features
+   filesets     Specifying File Sets
    glossary     Glossary
    hgignore     syntax for Mercurial ignore files
    hgweb        Configuring hgweb
@@ -182,6 +183,7 @@
    diffs        Diff Formats
    environment  Environment Variables
    extensions   Using additional features
+   filesets     Specifying File Sets
    glossary     Glossary
    hgignore     syntax for Mercurial ignore files
    hgweb        Configuring hgweb
@@ -699,6 +701,7 @@
    diffs        Diff Formats
    environment  Environment Variables
    extensions   Using additional features
+   filesets     Specifying File Sets
    glossary     Glossary
    hgignore     syntax for Mercurial ignore files
    hgweb        Configuring hgweb