Expand docs with more smoc details

Author: df7cb

doc/functions.sgm

@@ -612,6 +612,12 @@
           <para>
             Adjusts the order of an smoc to be more or less precise.
           </para>
+          <para>
+            When order is smaller than smoc's maximal order, the MOC resolution
+            is degraded to the new order, and its maximal order is set to that
+            order. When order is larger than the smoc's maximal order, smoc's
+            shape is not modified, but its maximal order is raised to order.
+          </para>
 
           <funcsynopsis>
             <funcprototype>
@@ -624,8 +630,18 @@
             </funcprototype>
           </funcsynopsis>
           <para>
-            Aggregate functions for smoc union and intersection.
+            <type>smoc</type> union and intersection are available as aggregate functions
+            that compute the aggretated area over a given column.
           </para>
+          <example>
+            <title>Computing the overall coverage of a catalog</title>
+            <programlisting>
+<![CDATA[SELECT sum(coverage) FROM ivoa;]]>
+<![CDATA[    sum]]>
+<![CDATA[-----------]]>
+<![CDATA[ 0/0-11 6/]]>
+            </programlisting>
+          </example>
 
         </sect2>
 

doc/indices.sgm

@@ -78,10 +78,22 @@
           to create smoc indices. An index speeds up the execution
           time of operators <link
           linkend="op.over"><literal>&lt;@</literal></link>, <link
-          linkend="op.over"><literal>@</literal></link>, <link
+          linkend="op.over"><literal>@&gt;</literal></link>, <link
           linkend="op.over"><literal>&amp;&amp;</literal></link>, <link
           linkend="op.equal"><literal>=</literal></link>, and <link
-          linkend="op.equal"><literal>!=</literal></link>.
+          linkend="op.equal"><literal>&lt;&gt;</literal></link>.
+        </para>
+        <para>
+          The index works by casting all contained smocs to a fixed level, and
+          for each pixel at that level, storing which smocs overlap with that
+          pixel. This is especially beneficial for "overlaps" queries using
+          the <literal>&amp;&amp;</literal> operator. Two levels of granularity
+          are provided: the default opclass <literal>smoc_gin_ops</literal>
+          works on level 5 with a resolution of 12288 pixels, while the
+          opclass <literal>smoc_gin_ops_fine</literal> works on level 8 with
+          786432 pixels. The downside of that approach is that storing large
+          smocs like "all sky" (<literal>0/0-11</literal>) produces a large
+          number of index entries.
         </para>
         <example>
           <title>Index of smoc coverage objects</title>
@@ -91,6 +103,8 @@
 <![CDATA[);]]>
 <![CDATA[-- Put in data now]]>
 <![CDATA[CREATE INDEX ON ivoa USING GIN (coverage);]]>
+<![CDATA[-- Alternative index with more detail]]>
+<![CDATA[CREATE INDEX ivoa_fine_idx ON ivoa USING GIN (coverage smoc_gin_ops_fine);]]>
           </programlisting>
         </example>
 

doc/operators.sgm

@@ -513,6 +513,14 @@
                 <type>smoc</type> operators
             </title>
 
+            <para>
+                A unique feature of MOCs compared to the other
+                <application>pgSphere</application>
+                objects is that their unions and intersections are again MOCs.
+                Hence, smocs support two special operators which both yield
+                <type>smoc</type> as output:
+            </para>
+
             <para>
               Union:
             </para>

doc/types.sgm

@@ -717,7 +717,10 @@ i             syntax is a somewhat complex.
               union, intersection and equality operations between them. In order
               to accomplish this task, we based the system on a regular and
               hierarchical partitioning of the sphere, a process called
-              tessellation.
+              tessellation, yielding pixels of different size. At level 0, the
+              sky is divided into 12 pixels numbered 0 to 11. At the maximally
+              defined level 29, there are 12 * 4^29 = 3458764513820540928
+              pixels.
             </para>
             <para>
               The MOC standard is described at http://www.ivoa.net/documents/MOC/