Updated README to clarify installation instructions; added brief back…

…ground, pre-requisites and FAQ

README

@@ -2,16 +2,70 @@ SMF and MediaWiki Integration
 =============================
 Author: SleePy (sleepy at simplemachines dot org)
 Original Author: Ryan Wagoner (rswagoner at gmail dot com)
-Version: 1.13
+Version: 1.14
+Last Modification Date: 2012.02.06
+Last Modified By: J. Noir (jnoir at jnoir dot eu)
 
-Place this file in your wiki/extenstions folder. If you
-encouter an issue be sure to read the known issues below.
+How does it work?
+=================
+
+Auth_SMF.php manages the Authentication between MediaWiki and an
+already existing SMF forum. By means of cookies and their management
+by Auth_SMF.php, SMF and MediaWiki can "talk" one to each other, and
+therefore seamlessly bridge both environments.
+
+Users are created in MediaWiki the first time they access the Wiki
+when logged into the forum also. In other words, when a registered
+user from your forum is logged in, and access the wiki for the first
+time, he/she will be automaticaly and immediately registered and logged
+into the wiki with the pre-assigned rights.
+
+This extension provides just the framework for bridging MediaWiki and
+SMF: each administrator is expected to perform the integration (themes,
+linking, etc.)
+
+Pre-requisites
+==============
+
+Before you start, it is recommended that you:
+
+- Read this file completely and understand all the steps required
+
+- Use the same database for MediaWiki and SMF. Use a prefix such as 
+wiki_ to identify MediaWiki's tables.
+
+- Have a fully working, independent MediaWiki installation in the server.
+
+- Perform a full backup of files and database(s). A restore should not be
+required, but it does not hurt to be on the safe side.
+
+
+How to install
+==============
+
+Follow this instructions to bridge MediaWiki and SMF.
+
+1- Download Auth_SMF.php to your computer and then upload this file in 
+the 'extensions' folder of your MediaWiki installation. 
+
+2.- Download the file LocalSettings.php that is located in the root
+folder of your MediaWiki installation.
+
+3.- Edit LocalSettings.php (but make sure not use Notepad, TextEdit or
+other text editor that adds byte order marks to files, or you will
+break your wiki). See http://en.wikipedia.org/wiki/Byte_order_mark
+for more information about byte order marks.
+
+4.- If you have setup your wiki to require users to be registered 
+before being allowed to edit or create pages, the following entry 
+should be already created in LocalSettings.php:
 
-Add to LocalSettings.php
-========================
 # This requires a user be logged into the wiki to make changes.
 $wgGroupPermissions['*']['edit'] = false; // MediaWiki Setting
 
+5.- Scroll down to the end of the file, then copy and paste the
+following content:
+
 # If you experience the issue where you appear to be logged in
 # eventhough you are logged out then disable the page cache.
 #$wgEnableParserCache = false;
@@ -30,8 +84,9 @@ $wgSMFPath = "../forum";
 # This works best if you are using SMF database sessions (default).
 # Make sure "Use database driven sessions" is checked in the
 # SMF Admin -> Server Settings -> Feature Configuration section
-# NOTE: Make sure to configure the wgCookeDomain below
+# NOTE: Make sure to configure the $wgCookieDomain below
 #$wgSMFLogin = true;
+#$wgCookieDomain = 'domain.com';
 
 # Members in these SMF groups will not be allowed to sign into wiki.
 # This is useful for denying access to wiki and a easy anti-spam
@@ -50,8 +105,8 @@ $wgSMFPath = "../forum";
 # SMF to wiki group translation.  This allows us to assign wiki groups
 # to those in certain SMF groups.
 #$wgSMFSpecialGroups = array(
-#	// SMF Group ID => Wiki group name.
-#	5 => 'autoconfirmed',
+#  // SMF Group ID => Wiki group name,
+#	5 => 'autoconfirmed'
 #);
 
 # THIS MUST BE ADDED.  This prevents direct access to the Auth file.
@@ -61,3 +116,66 @@ define('SMF_IN_WIKI', true);
 require_once "$IP/extensions/Auth_SMF.php";
 $wgAuth = new Auth_SMF();
 
+6.- Upload the LocalSettings.php and overwrite the existing one 
+(remember that it is always a good idea to have a backup)
+
+7.- Test your integration. If everything went fine, you should have
+full authentication bridging. If not, continue reading for some
+troubleshooting guidance.
+
+Known Issues / FAQ
+==================
+
+Q.- Authentication does not work. I login to my forum but when I then go
+to my wiki, I am not identified. If I click the "Login/Register" link I
+am taken to the forum's login page, but my session is still active.
+
+A.- It may be that some global variabled such as $user don't have any 
+data set up at the point when you access your wiki, and in the case of 
+$user, then $smf_member_id is never set so the authentication fails down 
+the line. Edit Auth_SMF.php and change the line 176, from
+
+$smf_member_id = $user->getOption('smf_member_id');
+
+to 
+
+$smf_member_id =  $user_settings['id_member'];
+
+(Huge kudos to andre nickatina for identifying this)
+
+Q.- Authentication does not work and I am using MediaWiki 1.18 or higher
+and PHP 5.3 or higher.
+
+A.- See http://www.simplemachines.org/community/index.php?topic=465986.0
+
+Q.- Authentication is working and permissions are being granted, however 
+when I try to edit pages, I receive a message edition was not successful 
+due to loss of session data. It recommends to log off and login again, 
+but that does not help.
+
+A.- Make sure that $wgCookieDomain is set to the name of your domain
+without prefixes (e.g.: if your forum is located at http://www.myforum.com
+then it should be configured as $wgCookieDomain = 'myforum.com'; )
+
+Q.- I cannot login with the Administrator account created during MediaWiki's 
+installation
+
+A.- This is the expected behaviour. The account created at installation time
+is part of MediaWiki, not of your forum. This extension bridges SMF to
+MediaWiki, but not the other way round (in other words, SMF is the principal
+and MediaWiki is a student ;-)
+
+Q.- I can authenticate with my forum's administrator, however I cannot see how
+to assign some extra rights for some users (e.g., for forum moderators).
+
+A.- That's part of the 'bureaucrat' role. You will need to assign your
+administrator to that role first. For some possible techniques, see 
+http://www.mediawiki.org/wiki/Manual:Setting_user_rights_in_MediaWiki
+
+Q.- How can I link my wiki from my forum ?
+
+A.- See http://www.simplemachines.org/community/index.php?topic=261880.0
+
+Q.- How can I "bridge" the favicon from my forum ?
+
+A.- Edit LocalSettings.php and use $wgFavicon = "/path/to/your/icon.ico";