Fixed LP Bug #1137156 by rewriting the feature docs (5.5)

doc/source/reliability/error_pad.rst

@@ -1,51 +1,47 @@
 .. _error_pad:
 
-==========================
- Error Code Compatibility
-==========================
+========================
+Error Code Compatibility
+========================
 
-|Percona Server| with |XtraDB| has error code incompatibilities with |MySQL| 5.5. It is important to maintain compatibility in the error codes used by the servers. For example, scripts that may be run on both servers could contain references to error codes.
+|Percona Server| has error code incompatibilities with |MySQL| 5.5. This could
+cause issues if, for example, scripts that should be run on both servers
+contain the references to error codes.
 
 The reasons for the current incompatibilities are:
 
-  * |Percona Server| with |XtraDB| contains features that have been backported from MyQL 5.5. Some of the |MySQL| 5.5 features added new error codes.
+  * |Percona Server| contains features that have been backported from newer
+    versions of |MySQL|. Some of the these backported features have added new
+    error codes.
 
-  * Some |Percona Server| with |XtraDB| features have added new error codes.
+  * Some |Percona Server| features have added new error codes.
 
-The solution to the first problem is to preserve |MySQL| 5.5 error codes in the |Percona Server|. An example of where this has been done is |Percona Server| feature Query Cache Enhancements. This feature adds error ``ER_QUERY_CACHE_DISABLED`` to the |Percona Server|, which is defined as error code 1651 in |MySQL| 5.5.
+The solution to the first problem is to preserve the |MySQL| error codes in
+|Percona Server|. An example of where this has been done is |Percona Server|
+:ref:`query_cache_enhance` feature. This feature adds new
+``ER_QUERY_CACHE_DISABLED`` error to the |Percona Server|, which is defined as
+an error code ``1651`` in |MySQL|.
 
-After migrating |Percona Server| / |XtraDB| to |MySQL| 5.5, users might experience troubles because of this.
+In case some |Percona Server| features introduce the new new error codes. Users
+might experience issues after migrating from |Percona Server| to |MySQL| where
+this error code already exists as a |MySQL| specific error code.
 
-The solution to the second problem is to insure that unique error codes are chosen, when adding new ones to |Percona Server|, that will never be duplicated during |MySQL| development.
+The avoid this |Percona Server| insures that unique error codes are chosen,
+when new features are being added and that these codes will never be
+duplicated during |MySQL| development.
 
-For example, |MySQL| has a tool ``comp_err`` that generates:
+This has been implemented by extending the |MySQL| :program:`comp_err` tool.
+This tool is used to generate the :file:`errmsg.sys` and error message header
+files.
 
-  - :file:`errmsg.sys` files
+Because :program:`comp_err` assigns the error code numbers sequentially and
+without gaps, to keep the error numbers consistent. :program:`comp_err` now
+padds the empty intervals (from the last error code number) by custom message
+(like ``ER_QUERY_CACHE_DISABLED padding to 1651 error``).
 
-  - header file :file:`include/mysqld_error.h`
-
-  - header file :file:`include/mysqld_ername.h`
-
-from the file :file:`errmsg.txt`.
-
-To keep error numbers consistent, we should add some fictive errors to :file:`errmsg.txt`, because ``comp_err`` assigns error code numbers sequentially, without gaps.
-
-I propose patch to ``comp_err``.
-
-This patch allows usage of a new syntax, with prefix ``PADD``, for example: ::
-
-  PADD_QUERY_CACHE_DISABLED 1651
-    eng "ER_QUERY_CACHE_DISABLED padding to 1651 error"
-  ER_QUERY_CACHE_DISABLED
-    eng "Query cache is disabled; restart the server with query_cache_type=1 to enable it"
-
-comp_err with my patch padds empty intervals (from last error code number to 1651) by error message ``ER_QUERY_CACHE_DISABLED padding to 1651 error``, i.e. and ``ER_QUERY_CACHE_DISABLED`` now has error code 1651 (as desired). I propose to use this patch for Percona errors, for example: ::
-
-  PADD_PERCONA_NEW_ERROR_CODE 4000
-    end "Padd empty space to error code number 4000 (Percona error codes)"
-  ...some percona error codes...
-
-Patch only adds prefix ``PADD_`` and padds error in sys files. All other |MySQL| code (load*.sys files, my_error, etc) works as old one.
+This feature only adds prefix ``PADD_`` and padds error in ``sys`` files. All
+other |MySQL| code (``load*.sys`` files, ``my_error``, etc) works without
+change.
 
 
 Version-Specific Information