fix authentication docs and integrate them in index.rst

doc/authentication.txt

@@ -1,3 +1,4 @@
+============================================
 External authentication with SemanticScuttle
 ============================================
 
@@ -12,8 +13,8 @@ active directory server.
 
 Since version 0.96, SemanticScuttle supports user authentication against
 external systems. To provide a wide range of supported systems, we chose
-to utilize PEAR's Authentication package [1].
+to utilize PEAR's `Authentication package`__.
-It does this by providing different "authentication containers" [2],
+It does this by providing different "`authentication containers`__",
 for example Database, IMAP, LDAP, POP3, RADIUS, SAP and SOAP.
 
 Please be aware of the fact that, after successful authentication, the user
@@ -24,21 +25,23 @@ is offline - you won't, execpt you switch it off in the SemanticScuttle
 configuration.
 
 
-[1] http://pear.php.net/package/Auth
+__ http://pear.php.net/package/Auth
-[2] http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php
+__ http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php
 
 
 Basic configuration
 ===================
-The default configuration file data/config.default.php has an own section
+The default configuration file ``data/config.default.php`` has an own section
 on auth options and an explanation of the single entries.
 
 To utilize the external authentication, you need to install the
-PEAR Auth package:
+PEAR Auth package: ::
+
   $ pear install auth
+
 If you do not have a PEAR installation available, you can try to manually
 install the files in the src/ directory. If you choose to do that, the
-src/ directory should look similar to that:
+src/ directory should look similar to that: ::
 
   src/
    Auth.php
@@ -51,24 +54,29 @@ src/ directory should look similar to that:
     header.php
     ..
 
-After that, modify your data/config.php file. The most important change
+After that, modify your ``data/config.php`` file. The most important change
-is to use
+is to use ::
+
   $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
+
 which tells SemanticScuttle to switch to the special authentication service.
 
 Now that's done, you can configure the single auth options:
- $authType = 'MDB2';
-selects the authentication container.
 
- $authOptions
+``$authType = 'MDB2';``
-is an array of options specific to the authentication container. Please
+  selects the authentication container.
-consult the PEAR Auth documentation for more information.
 
- $authDebug = true;
+``$authOptions``
-should be used when setup fails, since it may give important hints
+  is an array of options specific to the authentication container. Please
-where it fails. Please note that login will seem to fail with
+  consult the PEAR Auth documentation for more information.
-debugging activated. Going back to the main page after that will
+
-show that you are logged in.
+``$authDebug = true;``
+  should be used when setup fails, since it may give important hints
+  where it fails.
+
+  Please note that login will seem to fail with
+  debugging activated. Going back to the main page after that will
+  show that you are logged in.
 
 
 
@@ -77,14 +85,14 @@ Authentication examples
 
 General database authentification
 ---------------------------------
-Here you also need the PEAR MDB2 package.
+Here you also need the PEAR `MDB2 package`_.
-The "new_link" option is important!
+The "``new_link``" option is important!
 
-config.php settings:
+``config.php`` settings: ::
--8<------------------
+
-$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
+  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
-$authType = 'MDB2';
+  $authType = 'MDB2';
-$authOptions = array(
+  $authOptions = array(
       'dsn' => array(
           'phptype'  => 'mysql',
           'hostspec' => 'FIXME',
@@ -97,19 +105,18 @@ $authOptions = array(
       'usernamecol' => 'usernameFIXME',
       'passwordcol' => 'passwordFIXME',
       'cryptType'   => 'md5',
-);
+  );
--8<------------------
 
 
 Mantis Bugtracker
 -----------------
-Here you also need the PEAR MDB2 package.
+Here you also need the PEAR `MDB2 package`_.
 
-config.php settings:
+``config.php`` settings: ::
--8<------------------
+
-$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
+  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
-$authType = 'MDB2';
+  $authType = 'MDB2';
-$authOptions = array(
+  $authOptions = array(
       'dsn' => array(
           'phptype'  => 'mysql',
           'hostspec' => 'FIXME',
@@ -122,8 +129,9 @@ $authOptions = array(
       'usernamecol' => 'username',
       'passwordcol' => 'password',
       'cryptType'   => 'md5',
-);
+  );
--8<------------------
+
+.. _MDB2 package: http://pear.php.net/package/MDB2
 
 
 MediaWiki
@@ -132,30 +140,37 @@ Unfortunately, the password column does not contain a simple hashed
 password - for good reasons as described on
 http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column
 
-If you configure your mediawiki to use passwords without salt, you
+If you configure your MediaWiki_ to use passwords without salt, you
 can make it work nevertheless:
 
-MediaWiki LocalSettings.php:
+MediaWiki ``LocalSettings.php``: ::
+
   $wgPasswordSalt = false;
-- after that, users need to change/update their passwords to get them
+
+\- after that, users need to change/update their passwords to get them
 unsalted in the database. You can verify if the passwords are unhashed
-if you do
+if you do ::
+
   SELECT CAST( user_password AS CHAR ) FROM user
-on your MediaWiki database. Passwords prefixed with ":A:" can be used.
+
+on your MediaWiki database. Passwords prefixed with "``:A:``" can be used.
 
 Another problem is that mediawiki user names begin with an uppercase letter.
-You need to modify www/login.php and remove the "utf8_strtolower" function
+You need to modify ``www/login.php`` and remove the "``utf8_strtolower``" function
-call:
+call: ::
+
   $posteduser = trim(utf8_strtolower(POST_USERNAME));
-becomes
+
+becomes ::
+
   $posteduser = trim(POST_USERNAME);
 
 
-config.php settings:
+``config.php`` settings: ::
--8<------------------
+
-$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
+  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
-$authType = 'MDB2';
+  $authType = 'MDB2';
-$authOptions = array(
+  $authOptions = array(
       'dsn' => array(
           'phptype'  => 'mysql',
           'hostspec' => 'FIXME',
@@ -168,22 +183,23 @@ $authOptions = array(
       'usernamecol' => 'user_name',
       'passwordcol' => 'user_password',
       'cryptType'   => 'md5_mediawiki',
-);
+  );
-function md5_mediawiki($password) {
+  function md5_mediawiki($password) {
       return ':A:' . md5($password);
-}
+  }
--8<------------------
 
 
+.. _MediaWiki: http://www.mediawiki.org/wiki/MediaWiki
+
 Active Directory / LDAP
 -----------------------
 Here we authenticate against an active directory server.
 
-config.php settings:
+``config.php`` settings: ::
--8<------------------
+
-$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
+  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
-$authType = 'LDAP';
+  $authType = 'LDAP';
-$authOptions = array(
+  $authOptions = array(
       'host'     => '192.168.1.4',
       'version'  => 3,
       'basedn'   => 'DC=EXAMPLE,DC=ORG',
@@ -192,6 +208,6 @@ $authOptions = array(
       'userattr' => 'sAMAccountName',
       'userfilter' => '(objectClass=user)',
       'attributes' => array(''),
-);
+  );
-$authEmailSuffix = '@example.org';
+  $authEmailSuffix = '@example.org';
--8<------------------
+

doc/index.rst

@@ -17,9 +17,11 @@ First reads
 
 Features
 ========
+- `Custom user authentication`__
 - `SSL Client certificates`__
 - Themes__
 
+__ authentication.html
 __ ssl-client-certificates.html
 __ themes.html