﻿

=====================================================================

Copyright 2006  Rob Marsh, SJ  (http://rmarsh.com)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


==== Similar Posts Plugin for WordPress v1.14 =======================

Displays a list of posts similar to the current one by analysing a post's
pattern of word usage. Specifically it extracts the most frequent words
from the post and title, ignoring certain common words, and uses
up to 20 of them to match against other posts. This simple approach
works surprisingly well. 

If you wish to you sharpen up the process you can also add your own 
tags or keywords on a post-by-post basis. 

The admin options page lets you change the number and display of the
list of similar posts. It also lets you import any keywords set
by the Related Posts plugin (which first inspired this one).

Plugin URI: http://rmarsh.com/2006/10/04/similar-posts/
Version: 1.14
Author: Rob Marsh, SJ
Author URI: http://rmarsh.com/


==== Installation Instructions ======================================

1. Upload the whole plugin folder (Similar_Posts) to your 
/wp-content/plugins/ directory.

2. Go to your Admin|Plugins page and activate Similar Posts. This 
will automatically add an index to your posts table to enable fast 
matching. 

In the event of a problem you can create the necessary index
manually using phpMySQLadmin. Run the following
SQL query:

ALTER TABLE `wp_posts` ADD FULLTEXT `post_similar` (
    `post_title` ,
    `post_content`
)

NB You may have chosen a different table prefix, e.g., 'wp1_'
rather than 'wp_'. If so change 'wp_posts' above to match.
 
3. Put <ul><?php similar_posts(); ?></ul> at the place in your WP loop
where you want the list of similar posts to appear. 

4. Use the Admin|Options|Similar Posts page to set how you want
the list of posts displayed.


==== Usage ==========================================================

Put <ul><?php similar_posts(); ?></ul> at any place in the WP loop where 
you want the list of similar posts to appear. In most templates
that might be in your sidebar.php file.

Whenever a post is published or edited Similar Posts generates a set
of terms it will use to match that post against others. The terms 
are stored in a custom field called 'similarterms'. You can add
extra terms to this set or replace it entirely with your own tags. 
Just press 'Update' when you are done. If you ever wish Similar Posts
to regenerate its own terms again just press the 'Delete' button 
next to the field.

The Options|Similar Posts page lets you import any existing
keywords you might have set via the Related Posts plugin.

The way the list is displayed can be set from the Options|Similar Posts
page. You can exclude certain categories of post, for example, or 
change the code that comes before and after the link.

These general options can be overridden in specific cases by 
passing a query-style parameter, e.g.:
	
	<?php similar_posts('limit=10') ?> 
		lists the 10 most similar posts
	<?php similar_posts('none_text=nothing found&show_static=false') ?> 
		lists the default number of posts, excluding static pages, and specifies
		what to display if there are none
		
If you do not specify an option its value is taken from the options page. 
This means you can use the template tag in different ways in different places.

	The full list of parameters is as follows:
	
		limit			maximum number of posts to show (5)
		skip			how many posts to skip before listing (0)
		show_static		include static pages (false)
		show_private	include password-protected posts (false)
		excluded_cats	comma separated list of categories to exclude (by ID) (9999, the default means none)
		excluded_authors	comma separated list of authors to exclude (by ID) (9999, the default means none)
		none_text		what to show if no posts match--can be plain text or a permalink
		before_title	what to show before a link (<li>)
		after_title		what to show after a link(</li>)
		trim_before	remove the first instance of 'before_title' (false)
		show_excerpt	include a snippet of the post after the link (false)
		excerpt_length	how long an excerpt should be (10)
		excerpt_format	'char', the default, does nothing, 'word' trims the excerpt to the last 
						full word, and 'sent' to the full sentence. If the excerpt would be 
						trimmed to nothing no trimming is applied.
		ellipsis		add ' ...' after the excerpt			
		before_excerpt	what to show before an excerpt (<li>)
		after_excerpt	what to show after an excerpt (</li>)
		

==== Version ========================================================

Version 1.14 is an interim bug fix: the various Posts plugins were not working
together; some users were getting a few spurious characters displayed.

Version 1.13 allows parameters to be blank where it makes sense, e.g., before_title, or
to be more complex, e.g., 'before_title=<li class="items">'. Also lets excerpts be
trimmed back to whole words or sentences rather than dangling in mid-word.
NB excerpt_length is now measured in characters and not words as previously. 
Excerpts can also have an optional trailing ellipsis (' ...').

Version 1.12 fixes a bug with the option to show static pages.

Version 1.11 improves the sanity checking of parameter values to avoid
database errors. Also lets you skip over a number of posts if you so wish 
(though this makes more sense for the related Recent Posts plugin).

Version 1.10 lets you exclude posts by particular authors if you so wish.
You can also specify what you want displayed when no matches can
be found.

I have created three other useful post-listing plugins which work with
Similar Posts: Recent Posts, Random Posts, and Recent Comments. Their uses
should be obvious! Their default behaviour is governed from the same
option page as Similar Posts. (Get them at http://rmarsh.com)

Version 1.03 Adds the ability to exclude static pages from the list
of similar posts. You can also exclude certain categories of posts. Note
that the slightly awkward exclusion rules WordPress uses elsewhere
apply here too -- if a post has categories 1, 2, and 3 and posts in
categories 2 and 3 are excluded the post will still show because it has
category 1.

This version also makes two changes to the words which are ignored in 
creating the set of terms used to match similar posts. Since the database 
engine uses an internal list of stop words I have now based the plugin's
own list on that. For more information search for 'fulltext stopwords' at
http://dev.mysql.com/. It also seems that MySQL ignores any two or three-
letter words when it does a fulltext search so I have screened the sets 
of terms accordingly.

If you are looking for help setting up a common words list in a language 
other than English a good resource can be found at:
http://www.ranks.nl/tools/stopwords.html.

Version 1.02 Installs sensible default values of the plugin options and 
changes their internal names to prevent possible conflicts with other 
plugins. Note that you should check your Options|Similar Posts page 
after this update to ensure you have the values you want.
1.02 also fixes a bug whereby stray characters finding their way into
the custom field could crash the plugin. This also addresses a potential
SQL injection problem.

Version 1.01 Restores the capacity to use keywords in addition
to, or instead of, a post's automatically discovered significant 
words. Just add your keywords to the 'similarterms' custom
field when you publish or edit a post (don't forget to press the
'Update' button). If you want the plugin to regenerate a new set 
of terms automatically press the field 'Delete' button.

The options page now lets users of Related Posts import any keywords
they may have assigned to posts into Similar Posts.


==== Under the Hood =================================================

1. By default Similar Posts scans a post each time it needs to
find words to match. For long posts this can add an unwanted
overhead. The plugin can speed up the process by caching the
search terms as a custom field (named 'similarterms'). When
a post is published for the first time or subsequently edited the
custom field gets updated. Since you probably have a lot of posts
you won't want to edit each one manually to cache the terms. 
Instead, the Admin|Options|Similar Posts page lets you process
all your posts in one go. It won't overwrite any terms that are
already cached so there is also a button to clear all terms.

The term-caching cuts the plugin overhead down to a few tens
of microseconds.

2. The Similar_Posts folder contains a file, 'en.words.php', 
which is used to supply the 'stop list' of common words that
you want to exclude as search terms. It is supplied this way
so that if your blog is in a different language you can use an
alternative stop list. 

Similar Posts checks the WPLANG constant to see which
language WordPress is using and looks for a file on that
basis. For example, if the the language code is 'fr' for French,
Similar Posts will look for a file 'fr.words.php'. 

The language files must be in the same directory as 
similar-posts.php.


==== Acknowledgements  ==============================================

Similar Posts is based on Related Posts 2.02 by Alexander Malov
(http://www.w-a-s-a-b-i.com/archives/2006/02/02/wordpress-related-entries-20/)
and Mike Lu (http://mike.blogdns.org/mikelu/archives/2004/07/27/related-post-plugin-v13-en/).

The idea of using a pluggable language-dependant stoplist
comes from Rich Boakes' Autometa plugin (http://boakes.org/autometa?v=0.8).

I have included several good ideas which Ken Cheung applied to the
Related Posts plugin (http://izachy.com).

Recent Posts, Random Posts, and Recent Comments were inspired by
Scott Reilly's excellent 'Customizable Post Listings' plugin at
http://www.coffee2code.com/wp-plugins/.
