Merge lp:~kent/libmemcached/KBDocs4 into lp:~tangent-org/libmemcached/trunk

[KentBozlinski]

Updates to formatting of first ~dozen .rst files.

=== modified file 'docs/bin/memaslap.rst'
--- docs/bin/memaslap.rst	2011-06-24 19:25:01 +0000
+++ docs/bin/memaslap.rst	2011-06-24 22:27:28 +0000
@@ -18,12 +18,14 @@
 -----------
 
 
-memaslap is a load generation and benchmark tool for :program:`memcached()`
-servers. It generates configurable workload such as threads, concurrencies, connections, run time, overwrite, miss rate, key size, value size, get/set proportion, expected throughput, and so on. Furthermore, it also testss data
+:program:`memaslap` is a load generation and benchmark tool for memcached
+servers. It generates configurable workload such as threads, concurrencies, 
+connections, run time, overwrite, miss rate, key size, value size, get/set 
+proportion, expected throughput, and so on. Furthermore, it also testss data
 verification, expire-time verification, UDP, binary protocol, facebook test,
 replication test, multi-get and reconnection, etc.
 
-Memslap manages network connections like memcached with
+Memaslap manages network connections like memcached with
 libevent. Each thread of memaslap is bound with a CPU core, all
 the threads don't communicate with each other, and there are several socket
 connections in each thread. Each connection keeps key size distribution,
@@ -194,9 +196,9 @@
 
 Because each thread is self-governed, memaslap can assign
 different threads to handle different memcached servers. This is just one of
-the ways in which memaslap testss multiple servers. The only
+the ways in which memaslap tests multiple servers. The only
 limitation is that the number of servers cannot be greater than the number
-of threads. The other way to tests multiple servers is for replication
+of threads. The other way to test multiple servers is for replication
 test. Each concurrency has one socket connection to each memcached server.
 For the implementation, memaslap can set some objects to one
 memcached server, and get these objects from the other servers.
@@ -208,7 +210,7 @@
 Memslap testss both the ASCII protocol and binary protocol,
 but it runs on the ASCII protocol by default. 
 Memslap by default runs on the TCP protocol, but it also
-testss UDP. Because UDP is unreliable, dropped packages and out-of-order
+tests UDP. Because UDP is unreliable, dropped packages and out-of-order
 packages may occur. Memslap creates a memory buffer to handle
 these problems. Memslap tries to read all the response data of
 one command from the server and reorders the response data. If some packages
@@ -314,7 +316,7 @@
 concurrency is 16. The user can use “—threads” and “--concurrency” to
 specify these variables.
 
-If the system testss setting CPU affinity and the number of threads
+If the system tests setting CPU affinity and the number of threads
 specified by the user is greater than 1, memaslap will try to
 bind each thread to a different CPU core. So if you want to get the best
 performance memaslap, it is better to specify the number of

=== modified file 'docs/hashkit_create.rst'
--- docs/hashkit_create.rst	2011-06-19 08:25:48 +0000
+++ docs/hashkit_create.rst	2011-06-24 22:27:28 +0000
@@ -48,12 +48,12 @@
 ------------
 
 
-:c:func:`hashkit_create()` and :c:func:`hashkit_clone()` will return NULL on failure or
-non-NULL on success.
+:c:func:`hashkit_create()` and :c:func:`hashkit_clone()` will return NULL on 
+failure or non-NULL on success.
 
 :c:func:`hashkit_is_allocated()` returns true if the memory for the hashkit
-object was allocated inside of :c:func:`hashkit_create()` or :c:func:`hashkit_clone()`,
-otherwise it is false and was user-supplied memory.
+object was allocated inside of :c:fucn:`hashkit_create()` or 
+:c:func:`hashkit_clone()`, otherwise it is false and was user-supplied memory.
 
 
 ----
@@ -63,3 +63,13 @@
 
 To find out more information please check:
 `http://libmemcached.org/ <http://libmemcached.org/>`_
+
+
+
+--------
+SEE ALSO
+--------
+
+
+:manpage:`hashkit_create(3)` :manpage:`hashkit_value(3)` :manpage:`hashkit_set_hash_fn(3)`
+

=== modified file 'docs/hashkit_functions.rst'
--- docs/hashkit_functions.rst	2011-05-24 01:36:22 +0000
+++ docs/hashkit_functions.rst	2011-06-24 22:27:28 +0000
@@ -71,6 +71,5 @@
 --------
 
 
-hashkit_create(3) hashkit_value(3) hashkit_set_hash_fn(3)
-hashkit_set_continuum_hash_fn(3)
+:manpage:`hashkit_create(3)` :manpage:`hashkit_value(3)` :manpage:`hashkit_set_hash_fn(3)` :manpage:`hashkit_set_continuum_hash_fn(3)`
 

=== modified file 'docs/hashkit_value.rst'
--- docs/hashkit_value.rst	2011-05-24 01:36:22 +0000
+++ docs/hashkit_value.rst	2011-06-24 22:27:28 +0000
@@ -26,7 +26,7 @@
 -----------
 
 
-The hashkit_value() function generates a 32-bit hash value from the
+The :c:func:`hashkit_value()` function generates a 32-bit hash value from the
 given key and key_length. The hash argument is an initialized hashkit
 object, and distribution type and hash function is used from this
 object while generating the value.
@@ -54,5 +54,5 @@
 --------
 
 
-hashkit_create(3) hashkit_set_distribution(3) hashkit_set_hash_fn(3)
+:manpage:`hashkit_create(3)` :manpage:`hashkit_set_distribution(3)` :manpage:`hashkit_set_hash_fn(3)`
 

=== modified file 'docs/libhashkit.rst'
--- docs/libhashkit.rst	2011-06-19 02:44:48 +0000
+++ docs/libhashkit.rst	2011-06-24 22:27:28 +0000
@@ -15,7 +15,8 @@
 DESCRIPTION
 -----------
 
-:program:'libhashkit'  is a small and thread-safe client library that provides a collection of useful hashing algorithm. libhashkit is distributed with libmemcached.
+
+libhashkit  is a small and thread-safe client library that provides a collection of useful hashing algorithm. libhashkit is distributed with libmemcached.
 
 
 ----

=== modified file 'docs/libmemcached.rst'
--- docs/libmemcached.rst	2011-06-19 02:44:48 +0000
+++ docs/libmemcached.rst	2011-06-24 22:27:28 +0000
@@ -33,7 +33,7 @@
 system, generic in nature, but intended for use in speeding up dynamic web
 applications by alleviating database load." `http://danga.com/memcached/ <http://danga.com/memcached/>`_
 
-\ **libmemcached**\  is a small, thread-safe client library for the
+:program:`libmemcached` is a small, thread-safe client library for the
 memcached protocol. The code has all been written to allow
 for both web and embedded usage. It handles the work behind routing
 individual keys to specific servers specified by the developer (and values are
@@ -41,16 +41,17 @@
 a modular and consistent method of object distribution.
 
 There are multiple implemented routing and hashing methods. See the
-memcached_behavior_set() manpage for more information.
+:c:func:`memcached_behavior_set()` manpage for more information.
 
-All operations are performed against a :c:type:`memcached_st`  structure.
+All operations are performed against a :c:type:`memcached_st` structure.
 These structures can either be dynamically allocated or statically
-allocated and then initialized by memcached_create(). Functions have been
-written in order to encapsulate the :c:type:`memcached_st` . It is not
+allocated and then initialized by :c:func:`memcached_create()`. Functions have 
+been written in order to encapsulate the :c:type:`memcached_st`. It is not
 recommended that you operate directly against the structure.
 
-Nearly all functions return a :c:type:`memcached_return_t`\  value.
-This value can be translated to a printable string with memcached_strerror(3).
+Nearly all functions return a :c:type:`memcached_return_t` value.
+This value can be translated to a printable string with 
+:c:type:`memcached_strerror()`.
 
 Objects are stored on servers by hashing keys. The hash value maps the key to a particular server. All clients understand how this hashing works, so it is possibly to reliably both push data to a server and retrieve data from a server.
 
@@ -58,7 +59,7 @@
 
 Namespaces are supported, and can be used to partition caches so that multiple applications can use the same memcached servers.
 
-:c:type:`memcached_st`  structures are thread-safe, but each thread must
+:c:type:`memcached_st` structures are thread-safe, but each thread must
 contain its own structure (that is, if you want to share these among
 threads you must provide your own locking). No global variables are
 used in this library.
@@ -70,7 +71,7 @@
 AC_SUBST(DEPS_CFLAGS)
 AC_SUBST(DEPS_LIBS)
 
-Some features of the library must be enabled through memcached_behavior_set().
+Some features of the library must be enabled through :c:func:`memcached_behavior_set()`.
 
 Hope you enjoy it!
 
@@ -131,10 +132,9 @@
 
 
 When using threads or forked processes it is important to keep one instance
-of :c:type:`memcached_st`  per process or thread. Without creating your own locking
-structures you can not share a single :c:type:`memcached_st`. However, you can call
-memcached_quit(3) on a :c:type:`memcached_st`  and then use the resulting cloned
-structure.
+of :c:type:`memcached_st` per process or thread. Without creating your own 
+locking structures you can not share a single :c:type:`memcached_st`. However, 
+you can call :c:func:`memcached_quit()` on a :c:type:`memcached_st` and then use the resulting cloned structure.
 
 
 ----

=== modified file 'docs/libmemcached_configuration.rst'
--- docs/libmemcached_configuration.rst	2011-06-24 19:25:01 +0000
+++ docs/libmemcached_configuration.rst	2011-06-24 22:27:28 +0000
@@ -185,7 +185,7 @@
 ------
 
 
-memcached() returns a pointer to the memcached_st that was
+:c:func:`memcached()` returns a pointer to the memcached_st that was
 created (or initialized).  On an allocation failure, it returns NULL.
 
 

=== modified file 'docs/libmemcached_examples.rst'
--- docs/libmemcached_examples.rst	2011-05-24 01:36:22 +0000
+++ docs/libmemcached_examples.rst	2011-06-24 22:27:28 +0000
@@ -21,6 +21,7 @@
 
 .. code-block:: c
 
+Configuring with servers::
    const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com"
    memcached_st *memc= memcached(config_string, strlen(config_string);
    {
@@ -29,7 +30,8 @@
    memcached_free(memc);
 
 
-In the above code you create a \ ``memcached_st``\  object with three server by making use of :manpage:`memcached_create_with_options(3)`.
+In the above code you create a :c:type:`memcached_st` object with three server 
+by making use of :c:func:`memcached_create_with_options()`.
 
 
 --------------------------
@@ -40,6 +42,8 @@
 
 .. code-block:: c
 
+Creating a pool of Servers::
+
   const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com"; 
   
   memcached_pool_st* pool= memcached_pool(config_string, strlen(config_string));
@@ -62,10 +66,10 @@
 
 
 
-In the above code you create a \ ``memcached_pool_st``\  object with three
-server by making use of :manpage:`memcached_pool(3)`.
+In the above code you create a :c:type:`memcached_pool_st` object with three
+server by making use of :c:func:`memcached_pool()`.
 
-When memcached_pool_destroy() all memory will be released that is associated
+When :c:func:`memcached_pool_destroy()` all memory will be released that is associated
 with the pool.
 
 
@@ -77,6 +81,8 @@
 
 .. code-block:: c
 
+Adding a value to the Server::
+
    char *key= "foo";
    char *value= "value";
 
@@ -99,19 +105,21 @@
 
 .. code-block:: c
 
+Fetching multiple Values::
+
    memcached_return_t rc;
    char *keys[]= {"fudge", "son", "food"};
    size_t key_length[]= {5, 3, 4};
    unsigned int x;
    uint32_t flags;
- 
+
    char return_key[MEMCACHED_MAX_KEY];
    size_t return_key_length;
    char *return_value;
    size_t return_value_length;
- 
+
    rc= memcached_mget(memc, keys, key_length, 3);
- 
+
    x= 0;
    while ((return_value= memcached_fetch(memc, return_key, &return_key_length, 
                                          &return_value_length, &flags, &rc)))
@@ -122,7 +130,7 @@
 
 
 Notice that you freed values returned from memcached_fetch(). The define
-\ ``MEMCACHED_MAX_KEY``\  is provided for usage.
+:c:type:`MEMCACHED_MAX_KEY` is provided for usage.
 
 
 

=== modified file 'docs/libmemcachedutil.rst'
--- docs/libmemcachedutil.rst	2011-05-24 01:36:22 +0000
+++ docs/libmemcachedutil.rst	2011-06-24 22:27:28 +0000
@@ -23,8 +23,8 @@
 -----------
 
 
-\ **libmemcachedutil**\  is a small and thread-safe client library that provides
-extra functionality built on top of \ **libmemcached**\ .
+:program:`libmemcachedutil`  is a small and thread-safe client library that 
+provides extra functionality built on top of :program:`libmemcached`.
 
 
 -------
@@ -32,10 +32,10 @@
 -------
 
 
-Do not try to access an instance of \ ``memcached_st``\  from multiple threads
+Do not try to access an instance of :c:type:`memcached_st` from multiple threads
 at the same time. If you want to access memcached from multiple threads
-you should either clone the \ ``memcached_st``\ , or use the memcached pool
-implementation. see memcached_pool_create(3).
+you should either clone the :c:type:`memcached_st`, or use the memcached pool
+implementation. see :c:func:`memcached_pool_create()`.
 
 
 ----
@@ -52,6 +52,5 @@
 --------
 
 
-:manpage:`libmemcached(3)`
-:manpage:`memcached_pool_create(3)` :manpage:`memcached_pool_destroy(3)` :manpage:`memcached_pool_pop(3)` :manpage:`memcached_pool_push(3)`
+:manpage:`libmemcached(3)` :manpage:`memcached_pool_create(3)` :manpage:`memcached_pool_destroy(3)` :manpage:`memcached_pool_pop(3)` :manpage:`memcached_pool_push(3)`
 

=== modified file 'docs/memcached_analyze.rst'
--- docs/memcached_analyze.rst	2011-05-24 01:36:22 +0000
+++ docs/memcached_analyze.rst	2011-06-24 22:27:28 +0000
@@ -24,16 +24,16 @@
 -----------
 
 
-libmemcached(3) has the ability to query a memcached server (or collection
-of servers) for their current state. Queries to find state return a
-\ ``memcached_analysis_st``\  structure. You are responsible for freeing this structure.
-
-memcached_analyze() analyzes useful information based on the provided servers
-and sets the result to the \ ``memcached_analysis_st``\  structure. The return value
-must be freed by the calling application.
-
-A command line tool, memstat(1) with the option --analyze, is provided so that
-you do not have to write an application to use this method.
+:program:`libmemcached` has the ability to query a memcached server (or 
+collection of servers) for their current state. Queries to find state return a
+:c:type:`memcached_analysis_st` structure. You are responsible for freeing this structure.
+
+:c:func:`memcached_analyze()` analyzes useful information based on the 
+provided servers and sets the result to the :c:type:`memcached_analysis_st` 
+structure. The return value must be freed by the calling application.
+
+A command line tool, :c:func:`memstat()` with the option :option:`--analyze`, 
+is provided so that you do not have to write an application to use this method.
 
 
 ------
@@ -41,11 +41,11 @@
 ------
 
 
-A pointer to the allocated \ ``memcached_analysis_st``\  structure on success and
-a NULL pointer on failure. You may inspect the error detail by checking the
-\ ``memcached_return_t``\  value.
+A pointer to the allocated :c:type:`memcached_analysis_st` structure on 
+success and a NULL pointer on failure. You may inspect the error detail by 
+checking the :c:type:`memcached_return_t` value.
 
-Any method returning a \ ``memcached_analysis_st``\  expects you to free the
+Any method returning a :c:type:`memcached_analysis_st` expects you to free the
 memory allocated for it.
 
 

=== modified file 'docs/memcached_append.rst'
--- docs/memcached_append.rst	2011-05-24 01:36:22 +0000
+++ docs/memcached_append.rst	2011-06-24 22:27:28 +0000
@@ -30,43 +30,48 @@
 -----------
 
 
-memcached_prepend() and memcached_append are used to 
+:c:func:`memcached_prepend()` and memcached_append are used to 
 modify information on a server. All methods take a key, and its length to
-store the object. Keys are currently limited to 250 characters when using either a version of memcached(1) which is 1.4 or below, or when using the text protocol.
-You must supply both a value and a length. Optionally you
+store the object. Keys are currently limited to 250 characters when using 
+either a version of memcached which is 1.4 or below, or when using the text 
+protocol. You must supply both a value and a length. Optionally you
 may test an expiration time for the object and a 16 byte value (it is
-meant to be used as a bitmap). "flags" is a 4byte space that is stored alongside of the main value. Many sub libraries make use of this field, so in most cases users should avoid making use of it.
-
-memcached_prepend() places a segment of data before the last piece of data 
-stored. Currently expiration and key are not used in the server.
-
-memcached_append() places a segment of data at the end of the last piece of 
-data stored. Currently expiration and key are not used in the server.
-
-memcached_prepend_by_key() and memcached_append_by_key_by_key(,
-methods both behave in a similar method as the non key 
-methods. The difference is that they use their group_key parameter to map
-objects to particular servers.
-
-If you are looking for performance, memcached_set() with non-blocking IO is 
-the fastest way to store data on the server.
-
-All of the above functions are testsed with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
-behavior enabled. However, when using these operations with this behavior on, there 
-are limits to the size of the payload being sent to the server.  The reason for 
-these limits is that the Memcached Server does not allow multi-datagram requests
+meant to be used as a bitmap). "flags" is a 4byte space that is stored 
+alongside of the main value. Many sub libraries make use of this field, 
+so in most cases users should avoid making use of it.
+
+:c:func:`memcached_prepend()` places a segment of data before the last piece 
+of data stored. Currently expiration and key are not used in the server.
+
+:c:func:`memcached_append()` places a segment of data at the end of the last 
+piece of data stored. Currently expiration and key are not used in the server.
+
+:c:func:`memcached_prepend_by_key()` and 
+:c:func:`memcached_append_by_key_by_key()` methods both behave in a similar 
+method as the non key methods. The difference is that they use their 
+group_key parameter to map objects to particular servers.
+
+If you are looking for performance, :c:func:`memcached_set()` with non-blocking
+IO is the fastest way to store data on the server.
+
+All of the above functions are testsed with the 
+:c:type:`MEMCACHED_BEHAVIOR_USE_UDP` behavior enabled. However, when using 
+these operations with this behavior on, there are limits to the size of the 
+payload being sent to the server.  The reason for these limits is that the 
+Memcached Server does not allow multi-datagram requests
 and the current server implementation sets a datagram size to 1400 bytes. Due 
 to protocol overhead, the actual limit of the user supplied data is less than 
 1400 bytes and depends on the protocol in use as, well as the operation being 
-executed. When running with the binary protocol, \ `` MEMCACHED_BEHAVIOR_BINARY_PROTOCOL``\ , 
-the size of the key,value, flags and expiry combined may not exceed 1368 bytes. 
-When running with the ASCII protocol, the exact limit fluctuates depending on 
-which function is being executed and whether the function is a cas operation 
-or not. For non-cas ASCII set operations, there are at least 1335 bytes available 
-to split among the key, key_prefix, and value; for cas ASCII operations there are 
-at least 1318 bytes available to split among the key, key_prefix and value. If the
-total size of the command, including overhead, exceeds 1400 bytes, a \ ``MEMCACHED_WRITE_FAILURE``\ 
-will be returned.
+executed. When running with the binary protocol, 
+:c:type:`MEMCACHED_BEHAVIOR_BINARY_PROTOCOL`, the size of the key,value, 
+flags and expiry combined may not exceed 1368 bytes. When running with the 
+ASCII protocol, the exact limit fluctuates depending on which function is 
+being executed and whether the function is a cas operation or not. For 
+non-cas ASCII set operations, there are at least 1335 bytes available 
+to split among the key, key_prefix, and value; for cas ASCII operations 
+there are at least 1318 bytes available to split among the key, key_prefix 
+and value. If the total size of the command, including overhead, exceeds 
+1400 bytes, a :c:type:`MEMCACHED_WRITE_FAILURE` will be returned.
 
 
 ------
@@ -74,9 +79,10 @@
 ------
 
 
-All methods return a value of type \ ``memcached_return_t``\ .
-On success the value will be \ ``MEMCACHED_SUCCESS``\ .
-Use memcached_strerror() to translate this value to a printable string.
+All methods return a value of type :c:type:`memcached_return_t`.
+On success the value will be :c:type:`MEMCACHED_SUCCESS`.
+Use :c:func:`memcached_strerror()` to translate this value to a printable 
+string.
 
 
 ----
@@ -93,5 +99,5 @@
 --------
 
 
-memcached(1) libmemached(3) memcached_strerror(3) memcached_set(3) memcached_add(3) memcached_cas(3) memcached_replace(3)
+:manpage:`memcached(1)` :manpage:`libmemached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_set(3)` :manpage:`memcached_add(3)` :manpage:`memcached_cas(3)` :manpage:`memcached_replace(3)`