merge from HEAD

Author: Richard Jones

CHANGES.txt

@@ -13,6 +13,7 @@ Fixed:
 - don't set the title to nothing from incoming mail (thanks Bruce Guenter)
 - fix py2.4 strftime() API change bug (sf bug 1087746)
 - fix indexer searching with no valid words (sf bug 1086787)
+- updated searching / indexing docs
 
 
 2004-10-26 0.7.9

doc/customizing.txt

@@ -2098,12 +2098,12 @@ Index View Specifiers
 An index view specifier (URL fragment) looks like this (whitespace has
 been added for clarity)::
 
-     /issue?status=unread,in-progress,resolved&
-            topic=security,ui&
-            :group=+priority&
-            :sort==activity&
-            :filters=status,topic&
-            :columns=title,status,fixer
+    /issue?status=unread,in-progress,resolved&
+        topic=security,ui&
+        @group=priority&
+        @sort=-activity&
+        @filters=status,topic&
+        @columns=title,status,fixer
 
 The index view is determined by two parts of the specifier: the layout
 part and the filter part. The layout part consists of the query
@@ -2128,11 +2128,29 @@ descending order. The filter section shows filters for the "status" and
 "topic" properties, and the table includes columns for the "title",
 "status", and "fixer" properties.
 
+============ =============================================================
+Argument     Description
+============ =============================================================
+@sort        sort by prop name, optionally preceeded with '-' to give
+             descending or nothing for ascending sorting.
+@group       group by prop name, optionally preceeded with '-' or to sort
+             in descending or nothing for ascending order.
+@columns     selects the columns that should be displayed. Default is
+             all.                     
+@filter      indicates which properties are being used in filtering.
+             Default is none.
+propname     selects the values the item properties given by propname must
+             have (very basic search/filter).
+@search_text if supplied, performs a full-text search (message bodies,
+             issue titles, etc)
+============ =============================================================
+
+
 Searching Views
 ---------------
 
 .. note::
-   If you add a new column to the ``:columns`` form variable
+   If you add a new column to the ``@columns`` form variable
    potentials then you will need to add the column to the appropriate
    `index views`_ template so that it is actually displayed.
 
@@ -2142,8 +2160,8 @@ This is one of the class context views. The template used is typically
 
 - sets up additional filtering, as well as performing indexed text
   searching
-- sets the ``:filter`` variable correctly
-- saves the query off if ``:query_name`` is set.
+- sets the ``@filter`` variable correctly
+- saves the query off if ``@query_name`` is set.
 
 The search page should lay out any fields that you wish to allow the
 user to search on. If your schema contains a large number of properties,
@@ -2153,18 +2171,18 @@ Strings, consider having their value indexed, and then they will be
 searchable using the full text indexed search. This is both faster, and
 more useful for the end user.
 
-The two special form values on search pages which are handled by the
-"search" action are:
-
-:search_text
-  Text with which to perform a search of the text index. Results from
-  that search will be used to limit the results of other filters (using
-  an intersection operation)
-:query_name
-  If supplied, the search parameters (including :search_text) will be
-  saved off as a the query item and registered against the user's
-  queries property. The *classic* template schema has this ability, but
-  the *minimal* template schema does not.
+If the search view does specify the "search" ``@action``, then it may also
+provide an additional argument:
+
+============ =============================================================
+Argument     Description
+============ =============================================================
+@query_name  if supplied, the index parameters (including @search_text)
+             will be saved off as a the query item and registered against
+             the user's queries property. Note that the *classic* template
+             schema has this ability, but the *minimal* template schema
+             does not.
+============ =============================================================
 
 
 Item Views

doc/user_guide.txt

@@ -309,30 +309,32 @@ Under the covers
 The searching page converts your selections into the following
 arguments:
 
-========== =============================================================
-Argument   Description
-========== =============================================================
-:sort      sort by prop name, optionally preceeded with '-' to give
-           descending or nothing for ascending sorting.
-:group     group by prop name, optionally preceeded with '-' or to sort
-           in descending or nothing for ascending order.
-:filter    selects which props should be displayed in the filter
-           section. Default is all.           
-:columns   selects the columns that should be displayed. Default is
-           all.                     
-propname   selects the values the item properties given by propname must
-           have (very basic search/filter).
-========== =============================================================
+============ =============================================================
+Argument     Description
+============ =============================================================
+@sort        sort by prop name, optionally preceeded with '-' to give
+             descending or nothing for ascending sorting.
+@group       group by prop name, optionally preceeded with '-' or to sort
+             in descending or nothing for ascending order.
+@columns     selects the columns that should be displayed. Default is
+             all.                     
+@filter      indicates which properties are being used in filtering.
+             Default is none.
+propname     selects the values the item properties given by propname must
+             have (very basic search/filter).
+@search_text performs a full-text search (message bodies, issue titles,
+             etc)
+============ =============================================================
 
 You may manually write URLS that contain these arguments, like so
 (whitespace has been added for clarity)::
 
     /issue?status=unread,in-progress,resolved&
         topic=security,ui&
-        :group=priority&
-        :sort=-activity&
-        :filters=status,topic&
-        :columns=title,status,fixer
+        @group=priority&
+        @sort=-activity&
+        @filters=status,topic&
+        @columns=title,status,fixer
 
 
 Access Controls