Merge lp:~hingo/drizzle/7.1-docs-reviewfixes into lp:~drizzle-trunk/drizzle/development

[Henrik Ingo]

Fixes to Daniel's new documentation as discussed / reviewed on drizzle-discuss.

=== modified file 'docs/administration/authentication.rst'
--- docs/administration/authentication.rst	2011-10-23 17:13:20 +0000
+++ docs/administration/authentication.rst	2011-11-14 22:39:27 +0000
@@ -2,26 +2,38 @@
 ==============
 
 Authentication is any process by which you verify that someone is who they
-claim they are. [1]_  Drizzle authentication is handled by plugins; there
-are no grant or privilege tables.
-
-One or more authentication plugin must be loaded, else no connections can
+claim they are. [1]_  
+
+Drizzle authentication is handled by plugins; by default there is no single
+source where users are defined, such as a system user table, but each
+authentication plugin will use different sources to verify the usernames
+and passwords. (The plugin auth_schema does however keep users in a table inside
+Drizzle, much like the familiar MySQL way of authenticating users works.). 
+*Choosing an authentication plugin, configuring it, and disabling all other 
+authentication plugins should be one of your first administrative tasks.*
+
+One or more authentication plugins must be loaded, else no connections can
 be made to Drizzle.  On most systems, the :doc:`/plugins/auth_all/index`
 plugin is loaded by default which, as its name suggests, allows all
 connections regardless of username or password.  (Some distributions enable
 the :doc:`/plugins/auth_file/index` plugin by default instead).
 
-`Choosing an authentication plugin, configuring it, and disabling all other
-authentication plugins should be one of your first administrative tasks.`
+The :doc:`/plugins/auth_schema/index` plugin first shipped with ``Drizzle 7.1 
+Beta 2011.10.28``. This plugin provides an authentication method that is
+both secure and easy to use, and it is similar to how MySQL authentication
+works so will be familiar to many users. If you don't know which authentication
+plugin to use, you should start with configuring 
+:doc:`/plugins/auth_schema/index`. Likewise we warmly recommend distributors to
+consider enabling this plugin by default.
 
 The following authentication plugins are included with Drizzle:
 
-* :doc:`/plugins/auth_all/index`
-* :doc:`/plugins/auth_file/index`
-* :doc:`/plugins/auth_http/index`
-* :doc:`/plugins/auth_ldap/index`
-* :doc:`/plugins/auth_pam/index`
-* :doc:`/plugins/auth_schema/index`
+* :doc:`/plugins/auth_all/index` - Allow all connections without checking username or password.
+* :doc:`/plugins/auth_file/index` - Define users and passwords in a text file that is read on startup.
+* :doc:`/plugins/auth_http/index` - Authenticate the username and password against a http server.
+* :doc:`/plugins/auth_ldap/index` - Define users and passwords in a LDAP directory.
+* :doc:`/plugins/auth_pam/index` - Authenticate the username and password against system user accounts via PAM.
+* :doc:`/plugins/auth_schema/index` - Define users and passwords in a system table.
 
 Protocols
 ---------
@@ -48,7 +60,7 @@
 :ref:`auth_all_plugin`     Any
 :ref:`auth_file_plugin`    mysql
 :ref:`auth_http_plugin`    mysql-plugin-auth
-:ref:`auth_ldap_plugin`    mysql-plugin-auth
+:ref:`auth_ldap_plugin`    Any
 :ref:`auth_pam_plugin`     mysql-plugin-auth
 :ref:`auth_schema_plugin`  mysql
 =========================  ==================

=== modified file 'docs/administration/authorization.rst'
--- docs/administration/authorization.rst	2011-10-23 05:45:09 +0000
+++ docs/administration/authorization.rst	2011-11-14 22:39:27 +0000
@@ -2,13 +2,31 @@
 =============
 
 Authorization is finding out if the person, once identified, is permitted to
-have the resource. [1]_  Drizzle authorization is handled by plugins; there
-are no grant or privilege tables.
+have the resource. [1]_  
+
+Drizzle authorization is handled by plugins. There is no single
+source where users or access rights are defined, such as a system user table, 
+but each auhtorization plugin will use different sources to define or store
+access rights. By default no authorization plugin is loaded, this means that
+any logged in user is authorized to access all database objects and do anything
+he wants (everyone is super user).
 
 The following authorization plugins are included with Drizzle:
 
-* :doc:`/plugins/regex_policy/index`
-* :doc:`/plugins/simple_user_policy/index`
+* :doc:`/plugins/regex_policy/index` - ALLOW or REJECT access by matching a regular expression against the table name.
+* :doc:`/plugins/simple_user_policy/index` - Allow a user to only access a schema that matches their username.
+
+Limitations
+-----------
+
+At the moment there doesn't exist a plugin which would implement anything 
+resembling the traditional SQL standard GRANT and REVOKE type of authorization.
+You are invited to share your opinion on whether that level of authorization
+control is necessary in a modern database.
+
+Note that at the moment there also is no plugin that would distinguish between
+read and write operations, rather access is always granted to schemas and tables
+in an all or nothing fashion.
 
 -------------------------------------------------------------------------------
 

=== modified file 'docs/administration/drizzled.rst'
--- docs/administration/drizzled.rst	2011-10-23 05:45:09 +0000
+++ docs/administration/drizzled.rst	2011-11-14 22:39:27 +0000
@@ -77,13 +77,21 @@
 
 The ``shutdown`` command is case-sensitive.
 
-Output
-------
+Output and Logging
+------------------
 
 :program:`drizzled` does *not* close or redirect output to ``STDOUT`` or
 ``STDERR`` to a log file or logging facility like :program:`syslog`.
-You should redirect ``STDOUT`` and ``STDERR`` to a log file as in the above
-script example for starting Drizzle manually.
+When starting Drizzle, you should redirect ``STDOUT`` and ``STDERR`` to a log 
+file or to /dev/null, as in the above script example when starting Drizzle.
+
+When running :program:`drizzled` manually from a console, just allowing the
+output to be printed for you can of course be useful.
+
+Note that beginning with the first ``Drizzle 7.1 Beta 2011.10.28`` drizzled
+will also log messages via syslog and this is *in addition* to using ``STDOUT``
+and ``STDERR``.
+
 
 Signaling
 ---------

=== modified file 'docs/administration/logging.rst'
--- docs/administration/logging.rst	2011-10-23 16:01:37 +0000
+++ docs/administration/logging.rst	2011-11-14 22:39:27 +0000
@@ -12,11 +12,11 @@
 redirected to a log file when
 :ref:`starting Drizzle <starting_and_stopping_drizzled>`.
 
-Since :program:`syslog` is the standard UNIX logging facility,
-the :ref:`syslog_plugin` plugin is also loaded by default which will log error
-messages to the system log (:file:`/var/log/syslog` on Ubuntu for example).
-However, you must start :program:`drizzled` with
-:option:`--syslog.errmsg-enable` to enable this feature.
+Note that beginning with the first ``Drizzle 7.1 Beta 2011.10.28`` drizzled
+will **also** log messages via syslog and this is *in addition* to using 
+``STDOUT`` and ``STDERR``. This functionality is provided by the 
+:ref:`syslog_plugin` plugin. (For example on Ubuntu these messages are written
+to :file:`/var/log/syslog`).
 
 Queries
 -------

=== modified file 'docs/administration/plugins.rst'
--- docs/administration/plugins.rst	2011-10-23 05:45:09 +0000
+++ docs/administration/plugins.rst	2011-11-14 22:39:27 +0000
@@ -14,34 +14,69 @@
 
 Drizzle loads these plugins by default (see :option:`--plugin-load`):
 
-* auth_all (:ref:`auth_all_plugin`)
-* ascii (:ref:`ascii_plugin`)
-* benchmark (:ref:`benchmark_plugin`) 
-* charlength (:ref:`charlength_plugin`) 
-* compression (:ref:`compression_plugin`) 
-* connection_id (:ref:`connection_id_plugin`) 
-* crc32 (:ref:`crc32_plugin`) 
-* default_replicator (:ref:`default_replicator_plugin`) 
-* drizzle_protocol (:ref:`drizzle_protocol_plugin`)
-* errmsg_stderr (:ref:`errmsg_stderr_plugin`) 
-* filtered_replicator (:ref:`filtered_replicator_plugin`) 
-* hex_functions (:ref:`hex_functions_plugin`) 
-* innobase (:ref:`innobase_plugin`)
-* length (:ref:`length_plugin`) 
-* logging_stats (:ref:`logging_stats_plugin`)
-* math_functions (:ref:`math_functions_plugin`)
-* md5 (:ref:`md5_plugin`)
-* memory (:ref:`memory_plugin`)
-* multi_thread (:ref:`multi_thread_plugin`)
-* myisam (:ref:`myisam_plugin`)
-* mysql_protocol (:ref:`mysql_protocol_plugin`)
-* mysql_unix_socket_protocol (:ref:`mysql_unix_socket_protocol_plugin`)
-* rand_function (:ref:`rand_function_plugin`)
-* reverse_function (:ref:`reverse_function_plugin`)
-* sleep (:ref:`sleep_plugin`)
-* show_schema_proto (:ref:`show_schema_proto_plugin`)
-* substr_functions (:ref:`substr_functions_plugin`)
-* syslog (:ref:`syslog_plugin`)
-* transaction_log (:ref:`transaction_log_plugin`)
-* uuid_function (:ref:`uuid_function_plugin`)
-* version (:ref:`version_plugin`)
+ * :ref:`ascii_plugin` - Return the ASCII value of a character (ascii)
+ * :ref:`auth_all_plugin` - Data Dictionary for utility tables (auth_all)
+ * :ref:`benchmark_plugin` - Measure time for repeated calls to a function. (benchmark)
+ * :ref:`catalog_plugin` - Basic Catalog functions, data dictionary, and system. (catalog)
+ * :ref:`charlength_plugin` - Return the number of characters in a string (charlength)
+ * :ref:`collation_dictionary_plugin` - Data Dictionary for schema, table, column, indexes, etc (collation_dictionary)
+ * :ref:`compression_plugin` - UDFs for compression functions (compression)
+ * :ref:`connection_id_plugin` - Return the current connection_id (connection_id)
+ * :ref:`console_plugin` - Console Client (console)
+ * :ref:`crc32_plugin` - CRC32 Function (crc32)
+ * :ref:`default_replicator_plugin` - Default Replicator (default_replicator)
+ * :ref:`drizzle_protocol_plugin` - Drizzle Protocol (drizzle_protocol)
+ * :ref:`errmsg_stderr_plugin` - Error Messages to stderr (errmsg_stderr)
+ * :ref:`error_dictionary_plugin` - Data Dictionary for Errors. (error_dictionary)
+ * :ref:`function_engine_plugin` - Function Engine provides the infrastructure for Table Functions,etc. (function_engine)
+ * :ref:`hex_functions_plugin` - Convert a string to HEX() or from UNHEX() (hex_functions)
+ * :ref:`information_schema_dictionary_plugin` - Data Dictionary for ANSI information schema, etc (information_schema_dictionary)
+ * :ref:`innobase_plugin` - Supports transactions, row-level locking, and foreign keys (innobase)
+ * :ref:`ipv6_function_plugin` - IPV6() function (ipv6_function)
+ * :ref:`js_plugin` - Execute JavaScript code with supplied arguments (js)
+ * :ref:`length_plugin` - Return the byte length of a string (length)
+ * :ref:`logging_stats_plugin` - User Statistics as DATA_DICTIONARY tables (logging_stats)
+ * :ref:`math_functions_plugin` - Math Functions. (math_functions)
+ * :ref:`md5_plugin` - UDF for computing md5sum (md5)
+ * :ref:`memory_plugin` - Hash based, stored in memory, useful for temporary tables (memory)
+ * :ref:`multi_thread_plugin` - One Thread Per Session Scheduler (multi_thread)
+ * :ref:`myisam_plugin` - Default engine as of MySQL 3.23 with great performance (myisam)
+ * :ref:`mysql_protocol_plugin` - MySQL Protocol Module (mysql_protocol)
+ * :ref:`mysql_unix_socket_protocol_plugin` - MySQL Unix Socket Protocol (mysql_unix_socket_protocol)
+ * :ref:`protocol_dictionary_plugin` - Provides dictionary for protocol counters. (protocol_dictionary)
+ * :ref:`rand_function_plugin` - RAND Function (rand_function)
+ * :ref:`registry_dictionary_plugin` - Provides dictionary for plugin registry system. (registry_dictionary)
+ * :ref:`replication_dictionary_plugin` - Replication Dictionary (replication_dictionary)
+ * :ref:`reverse_function_plugin` - reverses a string (reverse_function)
+ * :ref:`schema_dictionary_plugin` - Data Dictionary for schema, table, column, indexes, etc (schema_dictionary)
+ * :ref:`schema_engine_plugin` - This implements the default file based Schema engine. (schema_engine)
+ * :ref:`session_dictionary_plugin` - Dictionary for session information, aka proccesslist, user defined variables, etc. (session_dictionary)
+ * :ref:`show_dictionary_plugin` - Dictionary for show commands. (show_dictionary)
+ * :ref:`show_schema_proto_plugin` - Shows text representation of schema definition proto (show_schema_proto)
+ * :ref:`signal_handler_plugin` - Default Signal Handler (signal_handler)
+ * :ref:`sleep_plugin` - SLEEP Function (sleep)
+ * :ref:`status_dictionary_plugin` - Dictionary for status, statement, and variable information. (status_dictionary)
+ * :ref:`string_functions_plugin` - String Functions. (string_functions)
+ * :ref:`substr_functions_plugin` - SUBSTR and SUBSTR (substr_functions)
+ * :ref:`syslog_plugin` - Syslog (syslog)
+ * :ref:`table_cache_dictionary_plugin` - Data Dictionary for table and table definition cache. (table_cache_dictionary)
+ * :ref:`transaction_log_plugin` - Transaction Log (transaction_log)
+ * :ref:`user_locks_plugin` - User level locking and barrier functions (user_locks)
+ * :ref:`utility_functions_plugin` - Utility Functions. (utility_functions)
+ * :ref:`uuid_function_plugin` - UUID() function using libuuid (uuid_function)
+ * :ref:`version_plugin` - Print Drizzle version (version)
+
+You can list information about the loaded plugins with:
+
+.. code-block:: mysql
+
+    SELECT * FROM DATA_DICTIONARY.MODULES;
+
+Note to editors: The above list of functions can be regenerated at any time with:
+
+.. code-block:: mysql
+
+    drizzle --silent -e "SELECT CONCAT(' * ', ':ref:\`', MODULE_LIBRARY, '_plugin\` - ', MODULE_DESCRIPTION, ' (', MODULE_LIBRARY, ')') 
+    FROM DATA_DICTIONARY.MODULES ORDER BY MODULE_LIBRARY;"
+
+

=== modified file 'docs/configuration/options.rst'
--- docs/configuration/options.rst	2011-11-06 00:00:03 +0000
+++ docs/configuration/options.rst	2011-11-14 22:39:27 +0000
@@ -23,7 +23,7 @@
 ``drizzled --plugin-add PLUGIN --help`` where ``PLUGIN`` is the name of any
 plugin.  For example:
 
-.. code-block:: bash
+.. code-block:: none
 
    $ drizzled --plugin-add query_log --help
    sbin/drizzled  Ver 2011.08.25.2411 for pc-linux-gnu on i686 (Source distribution (trunk))
@@ -149,9 +149,9 @@
 in this directory.)
 
 A good strategy for configuring Drizzle with multiple config files is to
-put :ref:`drizzled_options` in :file:`/etc/drizzle/drizzled.cnf`
+put general :ref:`drizzled_options` in :file:`/etc/drizzle/drizzled.cnf`
 (:file:`/etc/drizzle` is the default :option:`--config-dir` value)
-and plugin options in spearate config files in
+and any options related to a plugin in a separate config file in
 :file:`/etc/drizzle/conf.d/`.  For example:
 
 .. code-block:: bash
@@ -168,15 +168,20 @@
 
 .. code-block:: ini
 
+   server-id=42
+   core-file
+
+.. code-block:: bash
+
+   $ cat /etc/drizzle/conf.d/auth-file
+
+.. code-block:: ini
+
+   # drizzled option to load the auth_file plugin
    plugin-remove=auth_all
    plugin-add=auth_file
-
-.. code-block:: bash
-
-   $ cat /etc/drizzle/conf.d/auth-file
-
-.. code-block:: ini
-
+   
+   # Options for the plugin itself
    [auth-file]
    users=/etc/drizzle/users
 

=== modified file 'docs/contributing/more_ways.rst'
--- docs/contributing/more_ways.rst	2011-10-23 05:45:09 +0000
+++ docs/contributing/more_ways.rst	2011-11-14 22:39:27 +0000
@@ -18,4 +18,6 @@
 
 Drizzle is an Associated Project at the
 `Software in the Public Interest (SPI) <http://spi-inc.org/>`_.  You
-can make a financial donation to Drizzle through the SPI.
+can `make a financial donation to Drizzle 
+<https://co.clickandpledge.com/advanced/default.aspx?wid=46722>`_ through the 
+SPI.

=== modified file 'docs/installing/from_source.rst'
--- docs/installing/from_source.rst	2011-10-23 05:45:09 +0000
+++ docs/installing/from_source.rst	2011-11-14 22:39:27 +0000
@@ -1,11 +1,38 @@
 Installing Drizzle from Source
 ==============================
 
+* :ref:`obtain-source`
+* :ref:`compile-source`
 * :ref:`dependencies`
 * :ref:`ubuntu-install`
 * :ref:`debian-install`
-* :ref:`obtain-source`
-* :ref:`compile-source`
+* :ref:`redhat-install`
+
+.. _obtain-source:
+
+Obtaining the Source
+--------------------
+The latest source release can always be found on our `LaunchPad site
+<https://launchpad.net/drizzle>`_. Alternatively, the bzr source from our stable
+trunk can be obtained by doing:
+
+.. code-block:: bash
+
+   bzr branch lp:drizzle
+
+.. _compile-source:
+
+Compiling the Source
+--------------------
+Compiling is done by performing the standard automake commands from the top level directory inside the source:
+
+.. code-block:: bash
+
+   ./config/autorun.sh
+   ./configure
+   make
+   make install
+
 
 .. _dependencies:
 
@@ -53,6 +80,7 @@
  * libpam0g-dev
  * libprotobuf-dev (>= 2.1.0)
  * libtokyocabinet-dev (>= 1.4.23)
+ * libv8-dev
  * systemtap-sdt-dev
  * libnotifymm-dev
  * doxygen
@@ -60,8 +88,8 @@
 
 .. _ubuntu-install:
 
-Ubuntu Install Commands
------------------------
+Installing Build Dependencies on Ubuntu
+---------------------------------------
 
 The following commands work on Ubuntu to install the tools and libraries needed to build Drizzle:
 
@@ -74,8 +102,8 @@
 
 .. _debian-install:
 
-Debian Install Commands
------------------------
+Installing Build Dependencies on Debian
+---------------------------------------
 
 Since apt-repository isn't in Debian, you can instead add the Maverick PPA to /etc/apt/sources.list as follows:
 
@@ -109,28 +137,37 @@
 
   apt-get install drizzle 
 
-.. _obtain-source:
-
-Obtaining the Source
---------------------
-The latest source release can always be found on our `LaunchPad site
-<https://launchpad.net/drizzle>`_. Alternatively, the bzr source from our stable
-trunk can be obtained by doing:
-
-.. code-block:: bash
-
-   bzr branch lp:drizzle
-
-.. _compile-source:
-
-Compiling the Source
---------------------
-Compiling is done by performing the standard automake commands from the top level directory inside the source:
-
-.. code-block:: bash
-
-   ./config/autorun.sh
-   ./configure
-   make
-   make install
+.. _redhat-install:
+
+Installing Build Dependencies on Red Hat or Fedora
+--------------------------------------------------
+
+Depending on whether you use Red Hat (RHEL) or Fedora, you should add the
+repositories as explained in :doc:`redhat`.
+
+After that, install the following packages:
+
+ * bzr
+ * boost-devel
+ * autoconf
+ * automake
+ * gcc
+ * gcc-c++
+ * libtool
+ * gperf
+ * libuuid-devel (part of e2fsprogs-devel on older RedHat based distributions)
+ * zlib-devel
+ * pcre-devel
+ * readline-devel
+ * flex
+ * bison
+
+Note that you should be able to install all of the above simply with
+
+.. code-block:: bash
+
+  yum-builddep drizzle
+
+
+
 

=== modified file 'docs/installing/redhat.rst'
--- docs/installing/redhat.rst	2011-10-23 05:45:09 +0000
+++ docs/installing/redhat.rst	2011-11-14 22:39:27 +0000
@@ -73,23 +73,3 @@
 
    sudo yum install drizzle7-server drizzle7-client
 
-Compiling from Source
----------------------
-To compile from source you will need to add the repositories described above, and then install the following packages:
-
- * bzr
- * boost-devel
- * autoconf
- * automake
- * gcc
- * gcc-c++
- * libtool
- * gperf
- * libuuid-devel (part of e2fsprogs-devel on older RedHat based distributions)
- * zlib-devel
- * pcre-devel
- * readline-devel
- * flex
- * bison
-
-You will then be able to compile from source in the normal way.

=== modified file 'plugin/auth_pam/docs/index.rst'
--- plugin/auth_pam/docs/index.rst	2011-11-06 00:00:03 +0000
+++ plugin/auth_pam/docs/index.rst	2011-11-14 22:39:27 +0000
@@ -81,7 +81,7 @@
 
 Then connect to Drizzle like:
 
-.. code-block:: bash
+.. code-block:: none
 
    $ bin/drizzle -P --protocol mysql-plugin-auth
    Enter password: [Enter your system password here]
@@ -99,9 +99,9 @@
 protocol sends the password in plaintext to Drizzle, which
 is required for PAM based authentication.
 
-Note that you don't need to specify the ``-u`` or ``--user`` argument, since
-Drizzle will default to using your system username, which is exactly what we
-want when using auth_pam.
+Note that you typically don't need to specify the ``-u`` or ``--user`` argument, 
+since Drizzle will default to using your system username, which is exactly what 
+we want when using auth_pam.
 
 .. _auth_pam_security:
 

=== modified file 'plugin/js/docs/index.rst'
--- plugin/js/docs/index.rst	2011-10-01 10:06:00 +0000
+++ plugin/js/docs/index.rst	2011-11-14 22:39:27 +0000
@@ -1,3 +1,5 @@
+.. _js_plugin:
+
 JS
 ===========