1 files changed, 157 insertions, 0 deletions
diff --git a/funtools/doc/pod/funcombine.pod b/funtools/doc/pod/funcombine.pod
new file mode 100644
index 0000000..946d304
--- /dev/null
+++ b/funtools/doc/pod/funcombine.pod
@@ -0,0 +1,157 @@
+=pod
+
+=head1 NAME
+
+
+
+B<FunCombine: Combining Region and Table Filters>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+This document discusses the conventions for combining region and table
+filters, especially with regards to the comma operator.
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+B<Comma Conventions>
+
+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.
+
+
+According to long-standing usage in IRAF, when a comma separates two
+table filters, it takes on the meaning of a boolean B<and>. Thus:
+
+  foo.fits[pha==1,pi==2]
+
+is equivalent to:
+
+  foo.fits[pha==1 && pi==2]
+
+
+When a comma separates two spatial region filters, however, it has
+traditionally taken on the meaning of a boolean B<or>. Thus:
+
+  foo.fits[circle(10,10,3),ellipse(20,20,8,5)]
+
+is equivalent to:
+
+  foo.fits[circle(10,10,3) || ellipse(20,20,8,5)]
+
+(except that in the former case, each region is given a unique id
+in programs such as funcnts).
+
+
+Region and table filters can be combined:
+
+  foo.fits[circle(10,10,3),pi=1:5]
+
+or even:
+
+  foo.fits[pha==1&&circle(10,10,3),pi==2&&ellipse(20,20,8,5)]
+
+In these cases, it is not obvious whether the command should utilize an
+B<or> or B<and> operator. We therefore arbitrarily chose to
+implement the following rule:
+
+
+=over 4
+
+
+
+
+=item *
+
+if both expressions contain a region, the operator used is B<or>.
+
+
+=item *
+
+if one (or both) expression(s) does not contain a region, the operator
+used is B<and>.
+
+
+=back
+
+
+This rule handles the cases of pure regions and pure column filters properly.
+It unambiguously assigns the boolean B<and> to all mixed cases. Thus:
+
+  foo.fits[circle(10,10,3),pi=1:5]
+
+and
+
+  foo.fits[pi=1:5,circle(10,10,3)]
+
+both are equivalent to:
+
+  foo.fits[circle(10,10,3) && pi=1:5]
+
+
+
+[NB: This arbitrary rule B<replaces the previous arbitrary rule>
+(pre-funtools 1.2.3) which stated:
+
+
+=over 4
+
+
+
+
+=item *
+
+if the 2nd expression contains a region, the operator used is B<or>.
+
+
+=item *
+
+if the 2nd expression does not contain a region, the operator
+used is B<and>.
+
+
+=back
+
+
+In that scenario, the B<or> operator was implied by:
+
+  pha==4,circle 5 5 1
+
+while the B<and> operator was implied by
+
+  circle 5 5 1,pha==4
+
+Experience showed that this non-commutative treatment of the comma
+operator was confusing and led to unexpected results.]
+
+
+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.
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+
+=cut