1 files changed, 117 insertions, 0 deletions
diff --git a/funtools/doc/combo.html b/funtools/doc/combo.html
new file mode 100644
index 0000000..ab0bc28
--- /dev/null
+++ b/funtools/doc/combo.html
@@ -0,0 +1,117 @@
+<!-- =defdoc funcombine funcombine n -->
+<HTML>
+<HEAD>
+<TITLE>Combining Region and Table Filters</TITLE>
+</HEAD>
+<BODY>
+
+<!-- =section funcombine NAME -->
+<H2><A NAME="funcombine">FunCombine: Combining Region and Table Filters</A></H2>
+
+<!-- =section funcombine SYNOPSIS -->
+<H2>Summary</H2>
+<P>
+This document discusses the conventions for combining region and table
+filters, especially with regards to the comma operator.
+
+
+<!-- =section funcombine DESCRIPTION -->
+<H2><A NAME="conventions">Comma Conventions</A></H2>
+<P>
+Filter specifications consist of a series of boolean expressions,
+separated by commas. These expressions can be table filters,
+spatial region filters, or combinations thereof. Unfortunately,
+common usage requires that the comma operator must act differently
+in different situations. Therefore, while its use is intuitive in
+most cases, commas can be a source of confusion.
+
+<P>
+According to long-standing usage in IRAF, when a comma separates two
+table filters, it takes on the meaning of a boolean <B>and</B>. Thus:
+<PRE>
+  foo.fits[pha==1,pi==2]
+</PRE>
+is equivalent to:
+<PRE>
+  foo.fits[pha==1 && pi==2]
+</PRE>
+
+When a comma separates two spatial region filters, however, it has
+traditionally taken on the meaning of a boolean <B>or</B>. Thus:
+<PRE>
+  foo.fits[circle(10,10,3),ellipse(20,20,8,5)]
+</PRE>
+is equivalent to:
+<PRE>
+  foo.fits[circle(10,10,3) || ellipse(20,20,8,5)]
+</PRE>
+(except that in the former case, each region is given a unique id
+in programs such as funcnts).
+
+<P>
+Region and table filters can be combined:
+<PRE>
+  foo.fits[circle(10,10,3),pi=1:5]
+</PRE>
+or even:
+<PRE>
+  foo.fits[pha==1&&circle(10,10,3),pi==2&&ellipse(20,20,8,5)]
+</PRE>
+In these cases, it is not obvious whether the command should utilize an
+<B>or</B> or <B>and</B> operator. We therefore arbitrarily chose to
+implement the following rule:
+<UL>
+<LI> if both expressions contain a region, the operator used is <B>or</B>.
+<LI> if one (or both) expression(s) does not contain a region, the operator
+used is <B>and</B>.
+</UL>
+This rule handles the cases of pure regions and pure column filters properly.
+It unambiguously assigns the boolean <B>and</B> to all mixed cases. Thus:
+<PRE>
+  foo.fits[circle(10,10,3),pi=1:5]
+</PRE>
+and
+<PRE>
+  foo.fits[pi=1:5,circle(10,10,3)]
+</PRE>
+both are equivalent to:
+<PRE>
+  foo.fits[circle(10,10,3) && pi=1:5]
+</PRE>
+
+<P>
+[NB: This arbitrary rule <b>replaces the previous arbitrary rule</b>
+(pre-funtools 1.2.3) which stated:
+<UL>
+<LI> if the 2nd expression contains a region, the operator used is <B>or</B>.
+<LI> if the 2nd expression does not contain a region, the operator
+used is <B>and</B>.
+</UL>
+In that scenario, the <B>or</B> operator was implied by:
+<PRE>
+  pha==4,circle 5 5 1
+</PRE>
+while the <B>and</B> operator was implied by
+<PRE>
+  circle 5 5 1,pha==4
+</PRE>
+Experience showed that this non-commutative treatment of the comma
+operator was confusing and led to unexpected results.]
+
+<P>
+The comma rule must be considered provisional: comments and complaints
+are welcome to help clarify the matter. Better still, we recommend
+that the comma operator be avoided in such cases in favor of an
+explicit boolean operator.
+
+<!-- =section funcombine SEE ALSO -->
+<!-- =text See funtools(n) for a list of Funtools help pages -->
+<!-- =stop -->
+
+<P>
+<A HREF="./help.html">Go to Funtools Help Index</A>
+
+<H5>Last updated: November 16, 2005</H5>
+
+</BODY>
+</HTML>