Updated search's readme to markdown.

git-svn-id: http://code.elgg.org/elgg/trunk@9034 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 239 insertions, 220 deletions

diff --git a/mod/search/README.txt b/mod/search/README.txt
index fe87f3334..851179c58 100644
--- a/mod/search/README.txt
+++ b/mod/search/README.txt
@@ -1,262 +1,281 @@
+= Elgg Search =
+
 Full text search developer's reference.
 
-CONTENTS:
-	1.  Overview
-	2.  Search and Custom Plugins
-	3.  Controlling Search Results
-		3.1  Entities Returned
-		3.2  Custom Search
-	4.  Controlling Search Views
-		4.1  Entities
-		4.2  Listing
-		4.3  Layout
-	5.  Hints and Quirks
+== Contents ==
 
+1. Overview
+2. Search and Custom Plugins
+3. Controlling Search Results
+	1. Entities Returned
+	2. Custom Search
+4. Controlling Search Views
+	1. Entities
+	2. Listing
+	3. Layout
+5. Hints and Quirks
 
-1.  OVERVIEW
 
-	* All entities are searched through title and description using
-	MySQL's native fulltext search when possible, and LIKE %...% when not.
-	This can be overridden on a type/subtype basis.
-	
-	* Entities are displayed in a standard list view consisting of a 
-	title, blurb, and icon of the owning entity.  This can be overridden 
-	on a type/subtype basis.
-	
-	* Search is separated based upon types/subtypes pairs and any 
-	registered custom search.
-	
-	* METADATA, ANNOTATIONS, AND PRIVATE DATA ARE NOT SEARCHED.  
-	These are used in a variety of ways by plugin authors and generally 
-	should not be displayed.  There are exceptions (profile fields and 
-	comments) but if a plugin needs to match against metadata, 
-	annotations, or private data it must register a search hook itself.
+== 1. Overview ==
 
+All entities are searched through title and description using
+MySQL's native fulltext search when possible, and `LIKE %...%` when not.
+This can be overridden on a type/subtype basis.
 
-2.  SEARCH AND CUSTOM PLUGINS
+Entities are displayed in a standard list view consisting of a 
+title, blurb, and icon of the owning entity.  This can be overridden 
+on a type/subtype basis.
 
-	* To appear in search you must register your entity type and subtype
-	by saying in your plugin's init function:
-	
-		register_entity_type($type, $subtype);
-	
-	If you are extending ElggObject with your own class, it is also advised 
-	to add a subtype in your plugin's run_once function by saying:
-	
-		add_subtype($type, $subtype, $class);
+Search is separated based upon types/subtypes pairs and any 
+registered custom search.
 
-	* If your plugin uses ElggEntity's standard title and description, 
-	and you don't need a custom display, there is nothing else you need 
-	to do for your results to appear in search.  If you would like more
-	granular control of search, continue below.
+**METADATA, ANNOTATIONS, AND PRIVATE DATA ARE NOT SEARCHED BY DEFAULT!**
 
-3.0  CONTROLLING SEARCH RESULTS
+These are used in a variety of ways by plugin authors and generally 
+should not be displayed.  There are exceptions (profile fields and 
+comments) but if a plugin needs to match against metadata, 
+annotations, or private data it must register a search hook itself.
 
-	* Search results can be controlled at a object:subtype level.
-	
-	* You can specify your own search types by responding to a hook.
 
-	
-3.1  CONTROLLING SEARCH RESULTS - ENTITIES RETURNED
+== 2. Search and Custom Plugins ==
 
-	* You can override the default search by responding to the search/type
-	or search/type:subtype hook.  Generally, you will be replying to 
-	search/object:subtype.
+To appear in search you must register your entity type and subtype
+by saying in your plugin's init function:
 
-	* Search will first trigger a hook for search/type:subtype.  If no 
-	results are returned (but not FALSE, see below) a hook for search/type 
-	will be triggered.  
-	
-	* FALSE returned for any search hook will halt results for that 
-	type/subtype.
-	
-	* Register plugin hooks like this:
-	
-		register_plugin_hook('search', 'object:my_subtype',
-			'my_subtype_search_hook');
-	
-	* The hooked function is provided with details about the search query
-	in $param.  These include:
-		query
-		offset
-		limit
-		search_type
-		type - Entity type. (Not applicable for custom searches)
-		subtype - Entity subtype.  (Not applicable for custom searches)
-		owner_guid
-		friends - Should only entities by friends of the logged in 
-			user be searched? (@todo)
-		pagination - Show pagination?
-	
-	* The hooked function should respond to search triggers with the 
-	following:
-		array(
-			'count' => A count of ALL entities found,
-			'entities' => An array of entities.
-		)
-	
-	This information is passed directly to the search view, so if you are 
-	registering your own custom hook, you can provide more 
-	information to display in your custom view. 
-	
-	* For each entity in the returned array, search expects two pieces of
-	volatile data: search_matched_title and search_matched_description.
-	Set these by saying:
-	
-		$entity->setVolatileData('data_name', 'data_value');
-		
-	Again, if you are customizing your search views, you can add anything
-	you need.
+	register_entity_type($type, $subtype);
 
+If you are extending ElggObject with your own class, it is also advised 
+to add a subtype in your plugin's run_once function by saying:
 
-3.2  CONTROLLING SEARCH RESULTS - CUSTOM SEARCH
-	
-	* Non-entities, including information from 3rd party applications,
-	can easily be included in search by registering a custom search hook
-	that responds to the search_types/get_types trigger:
-	
-		register_plugin_hook('search_types', 'get_types', 
-			'my_custom_search_hook_function');
+	add_subtype($type, $subtype, $class);
+
+If your plugin uses ElggEntity's standard title and description, 
+and you don't need a custom display, there is nothing else you need 
+to do for your results to appear in search.  If you would like more
+granular control of search, continue below.
+
+
+== 3. Controlling Search Results ==
+
+Search results can be controlled at a object:subtype level.
 	
-	In this function, append to the array sent in $value with the name of 
-	your custom search:
+You can specify your own search types by responding to a hook.
+
+
+=== 3.1 Controlling Search Results - Entities Returned ===
+
+You can override the default search by responding to the search/type
+or search/type:subtype hook.  Generally, you will be replying to 
+search/object:subtype.
+
+Search will first trigger a hook for search/type:subtype.  If no 
+results are returned (but not FALSE, see below) a hook for search/type 
+will be triggered.  
+
+FALSE returned for any search hook will halt results for that 
+type/subtype.
+
+Register plugin hooks like this:
+
+	register_plugin_hook('search', 'object:my_subtype',
+		'my_subtype_search_hook');
+
+The hooked function is provided with details about the search query
+in $param.  These include:
+
+* query
+* offset
+* limit
+* search_type
+* type - Entity type. (Not applicable for custom searches)
+* subtype - Entity subtype.  (Not applicable for custom searches)
+* owner_guid
+* friends - Should only entities by friends of the logged in
+	user be searched? (@todo)
+* pagination - Show pagination?
+
+The hooked function should respond to search triggers with the 
+following:
+
+	array(
+		'count' => A count of ALL entities found,
+		'entities' => An array of entities.
+	)
+
+This information is passed directly to the search view, so if you are 
+registering your own custom hook, you can provide more 
+information to display in your custom view. 
+
+For each entity in the returned array, search expects two pieces of
+volatile data: search_matched_title and search_matched_description.
+Set these by saying:
+
+	$entity->setVolatileData('data_name', 'data_value');
+
+Again, if you are customizing your search views, you can add anything
+you need.
+
+
+=== 3.2  Controlling Search Results - Custom Search ===
 	
-		function my_custom_search_hook_function($hook, $type, 
+Non-entities, including information from 3rd party applications,
+can easily be included in search by registering a custom search hook
+that responds to the search_types/get_types trigger:
+
+	register_plugin_hook('search_types', 'get_types',
+		'my_custom_search_hook_function');
+
+In this function, append to the array sent in $value with the name of 
+your custom search:
+
+	function my_custom_search_hook_function($hook, $type,
 		$value, $params) {
-			$value[] = 'my_custom_search';
-			return $value;
-		}
-	
-	Search will trigger a hook for search/my_custom_search, which your 
-	plugin should respond to as detailed in section 3.1 above.
 
+		$value[] = 'my_custom_search';
+		return $value;
+	}
 
-4.0  CONTROLLING SEARCH VIEWS
-	* Three types views are used for displaying search: entity, listing, 
-	and layout.
+Search will trigger a hook for search/my_custom_search, which your 
+plugin should respond to as detailed in section 3.1 above.
 
-	* Each view has a default that standardizes the display of entities
-	regardless of type, subtype, or search type.
 
-	* The entity and listing views can be customized based upon a type,
-	subtype, or custom search type of the results.
+== 4.0  Controlling Search Views ==
+Three types views are used for displaying search: entity, listing, 
+and layout.
 
-	* The layout view can be customized based upon the original search 
-	type. NB: This can be different to the types for the results.
+Each view has a default that standardizes the display of entities
+regardless of type, subtype, or search type.
 
-	* The entity view controls how each individual result is formatted.
+The entity and listing views can be customized based upon a type,
+subtype, or custom search type of the results.
 
-	* The listing view control how each group of listings is formatted.
+The layout view can be customized based upon the original search 
+type. NB: This can be different to the types for the results.
 
-	* The listing layout controls how each full result set is formatted.
+The entity view controls how each individual result is formatted.
 
+The listing view control how each group of listings is formatted.
 
-4.1  CONTROLLING SEARCH VIEWS - ENTITIES
+The listing layout controls how each full result set is formatted.
 
-	* The default view for entities is search/entity.
 
-	* Search views are separate from the object/entity views because
-	view types might not match entity types.
-	
-	* The default search listing view iterates through each entity
-	found and passes to the entity view.  See 3.3 for more information
-	about listing views.
-	
-	* Entity views are discovered in the following order.  The first search
-	view found is used.
-		search/type/subtype/entity (For entity-based searches only)
-		search/type/entity
-		search/entity
-		
-	* The following parameters are passed in $vars to the entity view by 
-	the default listing view:
-		entity => The current returned entity
-		results => The results from the search/type:subtype hook
-		params => The params passed to the search/type:subtype hook
-		
-	* Example: To create an entity view for an ElggObject of subtype blog,
-	create a file called:
-		views/default/search/object/blog/entity.php
-		
-	To create an entity view for a custom search mysearch, create a file
-	called:
-		views/default/search/mysearch/entity.php
-	
-	
-4.2  CONTROLLING SEARCH VIEWS - LISTING
+=== 4.1  Controlling Search Views - Entities ===
+
+The default view for entities is search/entity.
+
+Search views are separate from the object/entity views because
+view types might not match entity types.
+
+The default search listing view iterates through each entity
+found and passes to the entity view.  See 3.3 for more information
+about listing views.
+
+Entity views are discovered in the following order.  The first search
+view found is used.
+
+	search/type/subtype/entity (For entity-based searches only)
+	search/type/entity
+	search/entity
 
-	* The default search view is search/listing.
+The following parameters are passed in $vars to the entity view by 
+the default listing view:
+
+	entity => The current returned entity
+	results => The results from the search/type:subtype hook
+	params => The params passed to the search/type:subtype hook
+
+Example: To create an entity view for an ElggObject of subtype blog,
+create a file called:
+
+	views/default/search/object/blog/entity.php
+
+To create an entity view for a custom search mysearch, create a file
+called:
+
+	views/default/search/mysearch/entity.php
 	
-	* For each entity in the returned array, search expects two pieces of
-	volatile data: search_matched_title and search_matched_description.
 	
-	* Listing views are discovered in the following order.  The first 
-	search view found is used.
-		search/type/subtype/listing (For entity-based searches only)
-		search/type/listing
-		search/listing
-		
-	* The view is called with the following in $vars:
-		results => The results from the search/type:subtype hook
-		params => The params passed to the search/type:subtype hook
-		
-	* Example: To create a listing view for ElggObjects with the subtype 
-	of blog, create a file called:
-		views/default/search/object/blog/listing.php
-		
-	To create a listing view for the custom search mysearch, create a file
-	called:
-		views/default/search/mysearch/listing.php
+=== 4.2  Controlling Search Views - Listing
+
+The default search view is search/listing.
+
+For each entity in the returned array, search expects two pieces of
+volatile data: search_matched_title and search_matched_description.
+
+Listing views are discovered in the following order.  The first 
+search view found is used.
+	search/type/subtype/listing (For entity-based searches only)
+	search/type/listing
+	search/listing
+
+The view is called with the following in $vars:
+	results => The results from the search/type:subtype hook
+	params => The params passed to the search/type:subtype hook
+
+Example: To create a listing view for ElggObjects with the subtype 
+of blog, create a file called:
+
+	views/default/search/object/blog/listing.php
+
+To create a listing view for the custom search mysearch, create a file
+called:
+
+	views/default/search/mysearch/listing.php
 		
 
-4.3  CONTROLLING SEARCH VIEWS - LAYOUT
-	
-	* The default layout view for search is search/layout, which calls
-	to elgg_view_layout(two_column_left_sidebar', '', $entity_results);
+=== 4.3  Controlling Search Views - Layout ===
 	
-	* Layouts can be overridden only when not searching all entities.
-	
-	* Layout views are discovered in the following order.  The first search
-	view found is used.
-		search/type/subtype/layout (For entity-based searches only)
-		search/type/layout
-		search/layout
-
-	* The following parameters are passed in $vars to the layout view:
-		body => The HTML formatted list of results.
-		params => The original params for the search.
-
-	* Example: To create a layout view for ElggObjects with the subtype 
-	of blog, create a file called:
-		views/default/search/object/blog/layout.php
-		
-	To create a layout view for the custom search mysearch, create a file
-	called:
-		views/default/search/mysearch/layout.php
+The default layout view for search is search/layout, which calls
+to `elgg_view_layout(two_column_left_sidebar', '', $entity_results);`
 
+Layouts can be overridden only when not searching all entities.
 
-5.  HINTS AND QUIRKS
+Layout views are discovered in the following order.  The first search
+view found is used.
 
-	* Use search_get_relevant_substring() to extract and highlight 
-	relevant substrings for the search_match_title and description.
-	
-	* If searching in 3rd party applications, create a temporary 
-	ElggObject to hold the results.  No need to save it since search 
-	uses volatile data.
-		$entity = new ElggObject();
-		$entity->owner_guid = use_magic_to_match_to_a_real_user();
-		$entity->setVolatileData('search_matched_title', 
-			'3rd Party Integration');
-		$entity->setVolatileData('search_matched_description', 
-			'Searching is fun!');
-		
-		return array(
-			'count' => $count,
-			'entities' => array($entity)
-		);
+	search/type/subtype/layout (For entity-based searches only)
+	search/type/layout
+	search/layout
+
+The following parameters are passed in $vars to the layout view:
+
+	body => The HTML formatted list of results.
+	params => The original params for the search.
+
+Example: To create a layout view for ElggObjects with the subtype 
+of blog, create a file called:
+
+	views/default/search/object/blog/layout.php
+
+To create a layout view for the custom search mysearch, create a file
+called:
+
+	views/default/search/mysearch/layout.php
+
+
+== 5.  Hints and Quirks ==
+
+Use search_get_relevant_substring() to extract and highlight 
+relevant substrings for the search_match_title and description.
+
+If searching in 3rd party applications, create a temporary 
+ElggObject to hold the results.  No need to save it since search 
+uses volatile data.
+
+	$entity = new ElggObject();
+	$entity->owner_guid = use_magic_to_match_to_a_real_user();
+	$entity->setVolatileData('search_matched_title',
+		'3rd Party Integration');
+	$entity->setVolatileData('search_matched_description',
+		'Searching is fun!');
+
+	return array(
+		'count' => $count,
+		'entities' => array($entity)
+	);
 
-	* MySQL's fulltext engine returns *ZERO* rows if more than 50% of 
-	the rows searched match.
+MySQL's fulltext engine returns *ZERO* rows if more than 50% of 
+the rows searched match.
 
-	* The default search hooks for users and groups ignore subtypes.
-	See http://trac.elgg.org/elgg/ticket/1499
+The default search hooks for users and groups ignore subtypes.
+See [trac ticket 1499](http://trac.elgg.org/elgg/ticket/1499)