#
#
# patch "monotone.texi"
#  from [474ecd5f8c4bab15311547985c67b0d3f1780a0b]
#    to [5d2e2aeacc15586b5cfd80946e0b023240103b7a]
# 
# patch "tests/extended-selectors/__driver__.lua"
#  from [3c8ad96220f4124d1454522547da95cabb8e0d08]
#    to [56708a4dc0c67cb857f5458b50a437d8b545122f]
#
============================================================
--- monotone.texi	474ecd5f8c4bab15311547985c67b0d3f1780a0b
+++ monotone.texi	5d2e2aeacc15586b5cfd80946e0b023240103b7a
@@ -2878,13 +2878,68 @@ @heading Composite selectors
 
 @heading Composite selectors
 
-Selectors may be combined with the @code{/} character. The combination
-acts as database intersection (or logical @code{and}). For example,
+Selectors may be combined with @code{and} and @code{or} operators and
+parentheses, and may be modified using a syntax similar to C function calls.
+The recognized special characters are @code{/}, @code{|}, @code{,}, @code{(}
+and @code{)}, and @code{\} (forward slash, pipe, comma, left and right
+parentheses, and backslash); to use any of these characters in a selector value,
+precede it with a backslash (@code{\}).
+
+The @code{and} operator is the @code{/} character. For example,
 the selector @code{a:graydon/d:2004-04} can be used to select a
 revision which has an @code{author} cert beginning with @code{graydon}
address@hidden well as} a @code{date} cert beginning with @code{2004-04}. The
address@hidden/} character can be escaped using the @code{\} character if necessary.
address@hidden well as} a @code{date} cert beginning with @code{2004-04}.
 
+The @code{or} operator is the @code{|} character. For example, the selector
address@hidden:some-feature-branch|h:other-feature-branch} can be used to select the
+heads of two specific branches.
+
+There are also several selector functions defined, which take one or more
+selectors as arguments. These are:
address@hidden
address@hidden @code{difference(A,B)}
+Set difference; this returns all revisions selected by A but not by B. For
+example, @code{difference(a:graydon,b:net.venge.monotone)} would return all
+revisions which have an @code{author} cert beginning with @code{graydon} which
+are not in the branch @code{net.venge.monotone}.
address@hidden @code{lca(A,B)}
+Least common ancestors; this is identical to
address@hidden((ancestors(A)|A)/(ancestors(B)|B))},
+but it may be faster and is certainly more convenient to type. For example,
address@hidden(h:net.venge.monotone,h:net.venge.monotone.extended-selectors)} would
+return the last propagate between the given branches, or the branch point if
+there were no subsequent propagates yet. This could be particularly useful with
+the @code{diff} command, to see exactly what has changed on a given branch.
address@hidden @code{max(A)}
+Erase ancestors; this returns all revisions selected by @code{A} which are not
+ancestors of other revisions selected by @code{A}. For example,
address@hidden(b:net.venge.monotone/a:graydon)} would return the latest revision(s)
+on branch @code{net.venge.monotone} which have an @code{author} cert beginning
+with @code{graydon}.
address@hidden @code{ancestors(A)}
+Strict ancestors; returns all revisions which are an ancestor of a revision
+selected by @code{A}. For example, @code{ancestors(b:net.venge.monotone)}
+would return all revisions in branch @code{net.venge.monotone} except for the
+branch heads, and all revisions in branches which have been merged back into
address@hidden
address@hidden @code{descendants(A)}
+Strict descendants; returns all revisions which are a descendant of a revision
+selected by @code{A}. For example,
address@hidden(b:net.venge.monotone/a:graydon)} would return all revisions
+which are descended from a revision which is in branch @code{net.venge.monotone}
+and has an @code{author} cert beginning with @code{graydon}.
address@hidden @code{parents(A)}
+Returns all revisions which are a parent of a revision selected by @code{A}.
+For example, @code{parents(m:*foobar*)} would return the parents of any
+revisions which have @code{comment} or @code{changelog} certs containing the
+word @code{foobar}.
address@hidden @code{children(A)}
+Returns all revisions which are a child of a revision selected by @code{A}.
+For example, @code{children(m:*foobar*)} would return the children of any
+revisions which have @code{comment} or @code{changelog} certs containing the
+word @code{foobar}.
address@hidden table
+
 @heading Selector expansion
 
 Before selectors are passed to the database, they are expanded using a
============================================================
--- tests/extended-selectors/__driver__.lua	3c8ad96220f4124d1454522547da95cabb8e0d08
+++ tests/extended-selectors/__driver__.lua	56708a4dc0c67cb857f5458b50a437d8b545122f
@@ -86,3 +86,7 @@ expect("children(lca(h:otherbranch,h:tes
 expect("descendants("..lhs..")", m, other, other_2)
 expect("parents(lca(h:otherbranch,h:testbranch))", root)
 expect("children(lca(h:otherbranch,h:testbranch))", m, other)
+
+other_head = merge(other_2, m, "otherbranch", "Jack")
+expect("max((ancestors(h:testbranch)|h:testbranch)/(ancestors(h:otherbranch)|h:otherbranch))", m)
+expect("lca(h:testbranch,h:otherbranch)", m)
\ No newline at end of file