changeset 812:39fc3b341002 pytest2

docs: added user docs about searching
author Thomas Waldmann <tw AT waldmann-edv DOT de>
date Wed, 31 Aug 2011 18:42:07 +0200
parents d7b0946924f9
children 66fee7ba0264
files docs/index.rst docs/user/search.rst
diffstat 2 files changed, 157 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/docs/index.rst	Wed Aug 31 14:48:53 2011 +0200
+++ b/docs/index.rst	Wed Aug 31 18:42:07 2011 +0200
@@ -21,6 +21,7 @@
    :maxdepth: 2
 
    user/markups
+   user/search
 
 Administrating MoinMoin
 =======================
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/user/search.rst	Wed Aug 31 18:42:07 2011 +0200
@@ -0,0 +1,156 @@
+=====================
+Searching and Finding
+=====================
+
+Entering search queries
+=======================
+
+Usually there is a simple and rather short search query input field offered by
+the theme - if you submit a query from there, it will search in item names and
+content (but only in the current stuff, not in non-current revisions) and display
+the search results to you.
+
+On that search results view, you will get a bigger search query input field
+(e.g. for refining your query) and you may also choose to additionally search
+in non-current revision item revisions (selecting that will search in all
+revisions).
+
+Simple search queries
+=====================
+Just enter one or few simple words into the query input field and hit ``Enter``.
+
+If you give multiple words, it will only find documents containing ALL those
+words ("AND" is the default).
+
+You can use AND (default), OR, NOT to refine your search.
+
+Examples
+--------
+Search for "wiki"::
+
+  wiki
+
+Search for documents containing "wiki" AND "moin"::
+
+  wiki moin
+
+  or (does the same):
+
+  wiki AND moin
+
+Search for documents containing "wiki" OR "moin"::
+
+  wiki OR moin
+
+Search for documents containing "wiki" and NOT "bad"::
+
+  wiki NOT bad
+
+Using wildcards
+===============
+
+If you want to enter word fragments or if you are not sure about spelling or
+word form, use wildcards for the parts you do not know:
+
++----------------+-----------------------------------+
+| Wildcard       | Matches                           |
++----------------+-----------------------------------+
+| ``?``          | one arbitrary character           |
++----------------+-----------------------------------+
+| ``*``          | any count of arbitrary characters |
++----------------+-----------------------------------+
+
+Examples
+--------
+Search for something like wiki, wika, wikb, ...::
+
+  wik?
+
+Search for something like wiki, willi, wi, ...::
+
+  w*i
+
+You can also use it for poor man's language independant word stemming.
+
+Matches on clean, cleaner, cleanest, cleaning, ...::
+
+  clean*
+
+Searching in specific fields
+============================
+
+As long as you do not specify otherwise, moin will search in ``name``,
+``name_exact`` and ``content`` fields.
+
+To specify the field to search in, just use the `fieldname:searchterm` syntax.
+
++-----------------------+-------------------------------------------------------+
+| Field name            | Field value                                           |
++-----------------------+-------------------------------------------------------+
+| ``wikiname``          | wiki name, e.g. ITWiki, EngineeringWiki, SalesWiki    |
++-----------------------+-------------------------------------------------------+
+| ``name``              | document name, e.g. Home, MyWikiPage                  |
++-----------------------+-------------------------------------------------------+
+| ``name_exact``        | same as ``name``, but is not tokenized                |
++-----------------------+-------------------------------------------------------+
+| ``content``           | document contents, e.g. This is some example content. |
++-----------------------+-------------------------------------------------------+
+| ``contenttype``       | document type, e.g. text/plain;charset=utf-8          |
++-----------------------+-------------------------------------------------------+
+| ``tags``              | tags of the document, e.g. important, hard, todo      |
++-----------------------+-------------------------------------------------------+
+| ``language``          | (main) language of the document contents, e.g. en     |
++-----------------------+-------------------------------------------------------+
+| ``mtime``             | document modification (submission) time, 201112312359 |
++-----------------------+-------------------------------------------------------+
+| ``address``           | submitter IP address, e.g. 127.0.0.1                  |
++-----------------------+-------------------------------------------------------+
+| ``hostname``          | submitter DNS name, e.g. foo.example.org              |
++-----------------------+-------------------------------------------------------+
+| ``acl``               | access control list (see below)                       |
++-----------------------+-------------------------------------------------------+
+| ``itemlinks``         | link targets of the document, e.g. OtherItem          |
++-----------------------+-------------------------------------------------------+
+| ``itemtransclusions`` | transclusion targets of the document, e.g. OtherItem  |
++-----------------------+-------------------------------------------------------+
+
+Examples
+--------
+Search in metadata fields::
+
+  contenttype:text
+  contenttype:image/jpeg
+  tags:todo
+  mtime:201108
+  address:127.0.0.1
+  language:en
+  hostname:localhost
+
+Search items with an item ACL that explicitly gives Joe read rights::
+
+  acl:Joe:+read
+
+Limiting search to a specific wiki (in a wiki farm's shared index)::
+
+  wikiname:SomeWiki
+
+Notes
+=====
+moin uses indexed search - keep in mind that this has some special properties:
+
+ * as it is using an index, it is rather fast usually
+ * because it is only using the index, it can only find what was put there
+ * if you use wildcards, it will still use the index, but in a different, slower way
+
+E.g.:
+
+ * "foobar" is put into the index somehow
+ * you search for "ooba" - you will not find it, because only "foobar" was put into the index
+ * solution: search for "foobar" - fast and will find it
+ * solution: search for "*ooba*" - slow, but will find it
+
+More infos
+==========
+
+See the `Whoosh query language docs <http://packages.python.org/Whoosh/querylang.html>`_.
+