Convert documentation to AsciiDoc

- Rename README to manual.txt and add AsciiDoc markup
- Rewrite some sections of documentation (more outstanding)
- Add "doc" Makefile target
- Update RPM spec file to include HTML output

1 files changed, 0 insertions, 328 deletions

diff --git a/README b/README
deleted file mode 100644
index 36c9a64..0000000
--- a/README
+++ /dev/null
@@ -1,328 +0,0 @@
-Lua CJSON v1.0.4
-================
-
-Lua CJSON is covered by the MIT license. See the file "LICENSE" for
-details.
-
-Lua CJSON provides fast JSON parsing and encoding support for Lua.
-
-Features:
-- 10x to 20x quicker (or more) than the fastest pure Lua JSON modules.
-- Full support for JSON with UTF-8, including decoding surrogate
-  pairs.
-- Optional run-time support for common exceptions to the JSON
-  specification (NaN, Inf,..).
-
-Caveats:
-- UTF-16 and UTF-32 are not supported.
-- Multi-threading within a single Lua state is not supported.
-  However, this is not a recommended configuration under Lua.
-
-To obtain the latest version of Lua CJSON visit:
-
-  http://www.kyne.com.au/~mark/software/lua-cjson.php
-
-Feel free to email me if you have any patches, suggestions, or
-comments.
-
-- Mark Pulford <mark@kyne.com.au>
-
-
-Installing
-==========
-
-Build requirements:
-- Lua (http://www.lua.org/)
-Or:
-- LuaJIT (http://www.luajit.org/)
-
-There are 3 build methods available:
-- Make: POSIX, OSX
-- RPM: Various Linux distributions
-- LuaRocks (http://www.luarocks.org/): POSIX, OSX, Windows
-
-
-Make
-----
-
-Review and update the included Makefile to suit your platform. Next,
-build and install the module:
-
-  # make
-  # make install
-  OR
-  # cp cjson.so [your_module_directory]
-
-
-RPM
----
-
-RPM-based Linux distributions should be able to create a package using
-the included RPM spec file. Install the "rpm-build" package, or
-similar, then:
-
-  # rpmbuild -tb lua-cjson-1.0.4.tar.gz
-
-
-LuaRocks
---------
-
-LuaRocks (http://luarocks.org/) can be used to install and manage Lua
-modules on a wide range of platforms (including Windows).
-
-Extract the Lua CJSON source package into a directory and run:
-
-  # cd lua-cjson-1.0.4; luarocks make
-
-LuaRocks does not support platform specific configuration for Solaris.
-On Solaris, you may need to manually uncomment "USE_INTERNAL_ISINF" in
-the rockspec before building this module.
-
-See the LuaRocks documentation for further details.
-
-
-Lua CJSON API
-=============
-
-Synopsis
---------
-
-  require "cjson"
-  -- Or:
-  local cjson = require "cjson"
-
-  -- Translate Lua value to/from JSON
-  text = cjson.encode(value)
-  value = cjson.decode(text)
-
-  -- Get and/or set CJSON configuration
-  setting = cjson.refuse_invalid_numbers([setting])
-  depth = cjson.encode_max_depth([depth])
-  convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])
-  keep = cjson.encode_keep_buffer([keep])
-
-
-Encoding
---------
-
-  json_text = cjson.encode(value)
-
-cjson.encode() will serialise the following types:
-  * number, string, table, boolean, lightuserdata (NULL) or nil
-
-The remaining Lua types cannot be serialised:
-  * thread, userdata, lightuserdata (non-NULL), function
-
-Numbers are encoded using the standard Lua number format.
-
-ASCII 0 - 31, double-quote, forward-slash, black-slash and ASCII 127
-are escaped when encoding strings. Other octets are passed
-transparently. It is expected the application will perform UTF-8 error
-checking if required.
-
-A Lua table will only be recognised as an array if all keys are type
-"number" and are positive integers (>0). Otherwise CJSON will encode
-the table as a JSON object.
-
-CJSON will also recognise and handle sparse arrays. Missing entries
-will be encoded as "null". Eg:
-  { [3] = "data" }
-becomes:
-  [null,null,"data"]
-
-Note: standards compliant JSON must be encapsulated in either an
-object ({}) or an array ([]). You must pass a table to cjson.encode()
-if you want to generate standards compliant JSON output.
-
-By default, errors will be raised for:
-- Excessively sparse arrays (see below)
-- More than 20 nested tables
-- Invalid numbers (NaN, Infinity)
-
-These defaults can be changed with:
-- cjson.encode_sparse_array()
-- cjson.encode_max_depth()
-- cjson.refuse_invalid_numbers()
-
-Example:
-  data_obj = { true, { foo = "bar" } }
-  data_json = cjson.encode(data_obj)
-
-
-Decoding
---------
-
-  value = cjson.decode(json_text)
-
-cjson.decode() will deserialise any UTF-8 JSON string into a Lua data
-structure. It can return any of the types that cjson.encode()
-supports.
-
-UTF-16 and UTF-32 JSON strings are not supported.
-
-CJSON requires that NULL (\0) and double quote (\") are escaped within
-strings. All escape codes will be decoded and other characters will be
-passed transparently. UTF-8 characters are not validated during
-decoding and should be checked elsewhere if required.
-
-JSON "null" will be converted to a NULL lightuserdata value. This can
-be compared with cjson.null for convenience.
-
-By default, invalid numbers (NaN, Infinity, Hexidecimal) will be
-decoded.
-
-Example:
-  data_json = '[ true, { "foo": "bar" } ]'
-  data_obj = cjson.decode(data_json)
-
-
-Invalid numbers
----------------
-
-  setting = cjson.refuse_invalid_numbers([setting])
-  -- "setting" must be on of:
-  --       false, "encode", "decode", "both", true
-
-CJSON considers numbers which are outside the JSON specification to be
-"invalid". Eg:
-- Infinity
-- NaN
-- Hexadecimal numbers
-
-By default CJSON will decode "invalid" numbers, but will refuse to
-encode them.
-
-This setting can be configured separately for encoding and/or
-decoding:
-- Enabled: an error will be generated if an invalid number is found.
-- Disabled (encoding): NaN and Infinity can be encoded.
-- Disabled (decoding): All numbers supported by strtod(3) will be
-                       parsed.
-
-
-Sparse arrays
--------------
-
-  convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])
-  -- "convert" must be a boolean. Default: false.
-  -- "ratio" must be a positive integer (>0). Default: 2
-  -- "safe" must be a positive integer (>0). Default: 10
-
-A Lua array is sparse if it is missing a value for at least 1 index.
-Lua CJSON encodes missing values as "null". Eg:
-  Lua array:  { [3] = "sparse" }
-  JSON array: [null,null,"sparse"]
-
-CJSON detects excessively sparse arrays by comparing the number of
-items in a Lua array with the maximum index. In particular:
-
-  maximum index > safe AND maximum index > array_items * ratio
-
-By default, attempting to encode excessively sparse arrays will
-generate an error.
-
-If "convert" is set to "true", excessively sparse arrays will be
-encoded as a JSON object:
-  Lua array:  { [1000] = "excessively sparse" }
-  JSON array: {"1000":"excessively sparse"}
-
-Setting "ratio" to 0 disables checking for excessively sparse arrays.
-
-
-Nested tables
--------------
-
-  depth = cjson.encode_max_depth([depth])
-  -- "depth" must be a positive integer (>0).
-
-By default, CJSON will reject data structure with more than 20 nested
-tables.
-
-This check is used to prevent a nested data structure from crashing
-the application. Eg:
-  a = {}; b = { a }; a[1] = b
-
-
-Number precision
-----------------
-
-  precision = cjson.encode_number_precision([precision])
-  -- "precision" must be between 1 and 14 (inclusive)
-
-By default CJSON will output 14 significant digits when converting a
-number to text.
-
-Reducing number precision to 3 can improve performance of number
-heavy conversions by up to 50%.
-
-
-Persistent encoding buffer
---------------------------
-
-  keep = cjson.keep_encode_buffer([keep])
-  -- "keep" must be a boolean
-
-By default, CJSON will reuse the JSON encoding buffer to improve
-performance. The buffer will grow to the largest size required and is
-not freed until CJSON is garbage collected. Setting this option to
-"false" will cause the buffer to be freed after each call to
-cjson.encode().
-
-
-JSON and handling under Lua CJSON
-=================================
-
-Nulls
------
-
-Lua CJSON decodes JSON "null" as a Lua lightuserdata NULL pointer.
-
-As a convenience, "cjson.null" is provided for comparison.
-
-
-Table keys
-----------
-
-JSON object keys must be strings - other types are not supported. Lua
-CJSON will convert numeric keys to a string, and other non-string
-types will generate an error.
-
-JSON object keys are always be decoded as Lua strings.
-
-If all Lua table keys are numbers (not strings), Lua CJSON will
-encode the table as a JSON array. See "Sparse arrays" above for
-more details.
-
-
-Metamethods
------------
-
-Lua CJSON does not use metamethods when serialising tables.
-- next() is used to iterate over tables.
-- rawget() is used to iterate over arrays.
-
-
-Functions, Userdata, Threads
-----------------------------
-
-Lua CJSON will generate an error if asked to serialise Lua functions,
-userdata, lightuserdata or threads.
-
-
-Locales
--------
-
-Lua CJSON uses strtod() and snprintf() to perform numeric conversion
-as they are usually well supported, fast and bug free.
-
-To ensure JSON encoding/decoding works correctly for locales using
-comma decimal separators, Lua CJSON must be compiled with either
-USE_POSIX_USELOCALE or USE_POSIX_SETLOCALE. See the Makefile or the
-rockspec for details.
-
-
-References
-==========
-
-- http://tools.ietf.org/html/rfc4627
-- http://www.json.org/