4 files changed, 153 insertions, 16 deletions
diff --git a/askbot/doc/source/changelog.rst b/askbot/doc/source/changelog.rst
index d88cd734..eb45eed2 100644
--- a/askbot/doc/source/changelog.rst
+++ b/askbot/doc/source/changelog.rst
@@ -3,6 +3,11 @@ Changes in Askbot
 
 Development version
 -------------------
+  adding "extra options" to the ldap session (Evgeny)
+* Tag moderation (Evgeny)
+* Editable optional three level category selector for the tags (Evgeny)
+* Tag editor adding tags as they are typed (Evgeny)
+* Added optional support for unicode slugs (Evgeny)
 * Option to disable feedback form for the anonymos users (Evgeny)
 * Optional restriction to have confirmed email address to join forum (Evgeny)
 * Optional list of allowed email addresses and email domain name for the new users (Evgeny)
diff --git a/askbot/doc/source/debugging.rst b/askbot/doc/source/debugging.rst
index 4b46ee58..af865b12 100644
--- a/askbot/doc/source/debugging.rst
+++ b/askbot/doc/source/debugging.rst
@@ -7,6 +7,41 @@ Debugging Askbot (and other Django applications)
 This document describes techniques that can be used to debug Askbot and other Django projects
 If you discover new debugging techniques, please add here.
 
+.. _runserver:
+Use development server for debugging
+------------------------------------
+
+Django comes with a handy development webserver that can be started with the command::
+
+    python manage.py runserver
+
+With the combination of runserver,
+the :ref:`python debugger <pdb>`,
+and even inserted "print" statements directly in the code
+it is possible to "look into" the program as it runs.
+
+Inspect the log file
+--------------------
+
+By default askbot will log errors into file `log/askbot.log` within the
+project directory. See what's inside that file.
+
+Note that in the production setups there are many log files - for the
+production webserver, database, etc.
+
+.. _pdb:
+Use Python debugger
+-------------------
+
+In the problematic portion of the code, insert lines::
+
+    import pdb
+    pdb.set_trace()
+
+Then fire up the :ref:`runserver <runserver>` and step through the program.
+When you see prompt starting with `(pdb)`
+type `help` and see what options there are.
+
 Use logging in code
 ---------------------
 
diff --git a/askbot/doc/source/live-settings.rst b/askbot/doc/source/live-settings.rst
index e154a257..12546e6c 100644
--- a/askbot/doc/source/live-settings.rst
+++ b/askbot/doc/source/live-settings.rst
@@ -19,3 +19,40 @@ No-one but the site administrators can change those settings.
     At the moment this command is not available from the web-interface
     but this will be fixed in the future.
 
+.. _live-settings-options:
+Entering live settings in settings.py file
+==========================================
+
+You might want to bypass live settings and enter them directly
+in the ``settings.py`` file in the ``LIVESETTINGS_OPTIONS`` dictionary.
+
+Having live settings overridden from the ``settings.py`` file may
+somewhat speed up your site
+and
+decrease a chance that the values could be accessed
+by an unauthorized person.
+
+Please see an example below::
+
+    LIVESETTINGS_OPTIONS = {
+        1: {
+            'DB' : True,
+            'SETTINGS': {
+                'EMAIL': {
+                    'REPLY_BY_EMAIL': True
+                }
+            }
+    }
+
+Firstly, the number "1" is site id. Most
+likely the number should be the same as the value of ``SITE_ID`` setting.
+
+The value for the site id key is a nested dictionary with two keys:
+``'DB'`` (if True - then the rest of settings will be taken from the database) 
+and ``'SETTINGS'`` - a dictionary with the actual settings.
+In this example ``'EMAIL'`` is the settings group
+and
+``'REPLY_BY_EMAIL'`` is the setting name, with ``True`` being the value.
+
+Setting group names and setting names can be looked up in files within 
+``askbot/conf`` directory.
diff --git a/askbot/doc/source/optional-modules.rst b/askbot/doc/source/optional-modules.rst
index 25bb5cc8..c8f2dba3 100644
--- a/askbot/doc/source/optional-modules.rst
+++ b/askbot/doc/source/optional-modules.rst
@@ -83,24 +83,84 @@ To enable authentication via LDAP
 
     pip install python-ldap
 
-After that, add configuration parameters in :ref:`live settings <live-settings>`, section
-"Keys to connect the site with external services ..." 
-(url ``/settings/EXTERNAL_KEYS``, relative to the domain name)
+After that, add configuration parameters in :ref:`live settings <live-settings>`,
+section "LDAP settings" 
+(url ``/settings/LDAP_SETTINGS``, relative to the forum base url)
 
 .. note::
-    Location of these parameters is likely to change in the future.
-    When that happens, an update notice will appear in the documentation.
-
-The parameters are:
-
-* "Use LDAP authentication for the password login" - enable/disable the feature.
-  When enabled, the user name and password will be routed to use the LDAP protocol.
-  Default system password authentication will be overridden.
-* "LDAP service provider name" - any string - just come up with a name for the provider service.
-* "URL fro the LDAP service" - a correct url to access the service.
-* "Explain how to change the LDAP password"
-  - askbot does not provide a method to change LDAP passwords
-  , therefore - use this field to explain users how they can change their passwords.
+    While it is possible to configure LDAP via web interface,
+    it is actually more safe to add them in your ``settings.py`` file in the
+    :ref:`LIVESETTINGS_OPTIONS <live-settings-options>` dictionary.
+    Consider that a breach in security of your forum might open
+    malicious access into your LDAP directory.
+
+The parameters are (note that some have pre-set defaults that might work for you)::
+
+* in Login Provider Settings select "enable local login"
+  - this makes login/password form available
+* enable/disable LDAP for password login -
+  must check that, to connect the login/password form to LDAP flow
+* create accounts automatically or not (``LDAP_AUTOCREATE_USERS``)
+* protocol version (``LDAP_PROTOCOL_VERSION``) (version 2 is insecure and deprecated)
+* ldap url (``LDAP_URL``)
+* base distinguished name, 'dn' in LDAP parlance (``LDAP_BASEDN``)
+* user id field name (``LDAP_USERID_FIELD``)
+* email field name (``LDAP_EMAIL_FIELD``)
+* user name filter template (``LDAP_USERNAME_FILTER_TEMPLATE``)
+  must have two string placeholders.
+* given (first) name field (``LDAP_GIVEN_NAME_FIELD``)
+* surname (last name) field (``LDAP_SURNAME_FIELD``)
+* common name field (``LDAP_COMMON_NAME_FIELD``)
+  either given and surname should be used or common name.
+  All three are not necessary - either first two or common.
+  These fields are used to extract users first and last names.
+* Format of common name (``LDAP_COMMON_NAME_FIELD_FORMAT``)
+  values can be only 'first,last' or 'last,first' - used to 
+  extract last and first names from common name
+
+There are three more optional parameters that must go to the ``settings.py`` file::
+
+* ``LDAP_LOGIN_DN``
+* ``LDAP_PASSWORD``
+* ``LDAP_EXTRA_OPTIONS``, a list of two-item tuples - of names and values of
+  the options. Option names must be upper case strings all starting with ``OPT_``
+  as described in the `python ldap library documentation <http://www.python-ldap.org/doc/html/ldap.html#options>`_. An often used option is (`OPT_REFERRALS`, 0).
+* ``LDAP_AUTHENTICATE_FUNCTION`` - dotted python path to optional function that
+  can override the default `ldap_authenticate` function. This function allows to
+  completely customize the LDAP login procedure.
+  To see what is expected of this function (input parameters and the return value) -
+  look at the end of the doc string at
+  `askbot.deps.django_authopenid.ldap_auth.ldap_authenticate_default`.
+  One use case for the custom function is determining to which group
+  a user might belong or check any additional access rules that might be
+  stored in your LDAP directory. Another use case - is the case when 
+  the default procedure just does not work for you.
+* ``LDAP_AUTHENICATE_FAILURE_FUNCTION`` - python dotted path to an additional function
+  that may be called after a unsuccessful authentication.
+  This function can be used to set custom error messages to the login form.
+  The function should take two parameters (in the following order): user_info, login_form.
+  user_info - is the same dictionary
+  that is returned by the `ldap_authenticate` function.
+* ``LDAP_CREATE_USER_FUNCTION`` - python dotted path to function that will create
+  the ldap user, should actually return a user association object, like
+  ``askbot.deps.django_authopenid.ldap_auth.ldap_create_user_default``.
+  Function takes return value of the ldap authenticate function as a sole parameter.
+
+
+Use these when you have the "directory master passsword" - 
+for a specific user who can access the rest of the directory,
+these were not added to the live settings due to security concerns.
+
+``LDAP_USER`` and ``LDAP_PASSWORD`` will be used only if both are provided!
+
+Since LDAP authentication requires so many parameters,
+you might need to :ref:`debug <debugging>` the settings.
+The function to look at is `askbot.deps.django_authopenid.backends.ldap_authenticate`.
+If you have problems with LDAP please contact us at support@askbot.com.
+
+The easiest way to debug - insert ``import pdb; pdb.set_trace()`` line into function
+`askbot.deps.django_authopenid.backends.ldap_authenticate`,
+start the ``runserver`` and step through.
 
 Uploaded avatars
 ================