restructure and update / fix some expressions in introduction page of…

… the doc

docs/introduction.rst

@@ -6,19 +6,27 @@ python library provides generic access to configuration files in various
 formats with configuration merge along with config template and schema
 validation/generation support.
 
-python-anyconfig provides very simple and unified APIs for various
-configuration files:
+- Home: https://github.com/ssato/python-anyconfig
+- (Latest) Doc: http://python-anyconfig.readthedocs.org/en/latest/
+- PyPI: https://pypi.python.org/pypi/anyconfig
+- Copr RPM repos: https://copr.fedoraproject.org/coprs/ssato/python-anyconfig/
 
-- anyconfig.load() to load configuration files and it will return a dict-like object represents configuration loaded
-- anyconfig.loads() to load a configuration string and ...
-- anyconfig.dump() to dump a configuration file from a dict or dict-like object represents some configurations
-- anyconfig.dumps() to dump a configuration string from ...
-- anyconfig.validate() to validate configuration files with JSON schema [#]_ . Both configuration files and schema files can be written in any formats anyconfig supports.
-- anyconfig.gen_schema() to generate a object represents JSON schema for given configuration file[s] to validate it/them later.
+Features
+----------
 
-python-anyconfig enables to load configuration files in various formats in the
-same manner without taking care of each file format in some cases like the
-followings:
+python-anyconfig provides very simple and unified APIs for configuration files
+in various formats:
+
+- anyconfig.load() to load configuration files and return a dict-like object represents configuration itself loaded
+- anyconfig.loads() to load configuration from a string just like json.loads does
+- anyconfig.dump() to dump a configuration file from a dict or dict-like object represents configuration
+- anyconfig.dumps() to dump a configuration string from a dict or dict-like object represents configuration
+- anyconfig.validate() to validate configuration loaded with anyconfig.load() with JSON schema [#]_ (object) also loaded with anyconfig.load(). anyconfig.load() may help loading JSON schema file[s] in any formats anyconfig supports.
+- anyconfig.gen_schema() to generate a JSON schema object for given configuration file[s] to validate it/them later.
+
+It enables to load a configuration file and configuration files in various
+formats in the same manner, and in some cases, even there is no need to take
+care of the actual format of configuration file[s] like the followings:
 
 .. code-block:: python
 
@@ -53,11 +61,11 @@ followings:
   # overwritten by the later ones:
   conf6 = anyconfig.load("/etc/foo.d/*.json", merge=anyconfig.MS_REPLACE)
 
-Also, python-anyconfig can process configuration files which are actually
+Also, it can process configuration files which are actually
 `jinja2-based template <http://jinja.pocoo.org>`_ files:
 
-- Can generate an actual configuration from prepared half-baked config files template with given context to render the template later.
-- It's possible to 'include' config files from given config files your applications with using jinja2's 'include' directive.
+- Enables to load a substantial configuration rendered from half-baked configuration template files with given context
+- Enables to load a series of configuration files indirectly 'include'-d from a/some configuration file[s] with using jinja2's 'include' directive.
 
 .. code-block:: console
 
@@ -76,8 +84,8 @@ Also, python-anyconfig can process configuration files which are actually
   In [6]: anyconfig.load("/tmp/b.yml", ac_template=True, ac_context=dict(a='ccc'))
   Out[6]: {'a': 'ccc'}
 
-And python-anyconfig also enables to validate configuration files in various
-format with using JSON schema like the followings:
+And python-anyconfig enables to validate configuration files in various format
+with using JSON schema like the followings:
 
 .. code-block:: python
 
@@ -106,13 +114,13 @@ anyconfig_cli to process configuration files and:
 - Convert a/multiple configuration file[s] to another configuration files in different formats
 - Get configuration value in a/multiple configuration file[s]
 - Validate configuration file[s] with JSON schema
-- Generate JSON schema from given configuration file[s]
+- Generate JSON schema for given configuration file[s]
 
 .. [#] This name took an example from the 'anydbm' python standard library.
 .. [#] http://json-schema.org
 
 Supported configuration formats
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 python-anyconfig supports various (configuration) file formats if the required
 module is available and the corresponding backend is ready to use:
@@ -128,8 +136,8 @@ module is available and the corresponding backend is ready to use:
    ConifgObj, configobj, ``configobj`` [#]_, Likewise.
    MessagePack, msgpack, ``msgpack-python`` [#]_, Likewise.
 
-The supported formats (types) of python-anyconfig on your system is able to be
-listed by 'anyconfig_cli -L' like this:
+The supported formats of python-anyconfig on your system is able to be listed
+by 'anyconfig_cli -L' like this:
 
 .. code-block:: console
 
@@ -146,9 +154,9 @@ or with the API 'anyconfig.list_types()' will show them:
 
    In [9]:
 
-python-anyconfig utilizes plugin mechanism provided by setuptools [#]_ and
-other formats may be supported by corresponding pluggale backends (see the next
-sub section also) like Java properties format.
+It utilizes plugin mechanism provided by setuptools [#]_ and other formats may
+be supported by corresponding pluggale backends (see the next sub section also)
+like Java properties format.
 
 - Java properties file w/ pyjavaproperties [#]_ (experimental):
 
@@ -221,25 +229,36 @@ There is a couple of ways to install python-anyconfig:
 
 - Build from source: Of course you can build and/or install python modules in usual way such like 'python setup.py bdist', 'pip install git+https://github.com/ssato/python-anyconfig/' and so on.
 
-Hack
-=======
+Help and feedbak
+-----------------
 
-Help wanted!
---------------
+If you have any issues / feature request / bug reports with python-anyconfig,
+please open an issue ticket on github.com
+(https://github.com/ssato/python-anyconfig/issues).
 
-These areas are still insufficient, I guess.
+The following areas are still insufficient, I think.
 
 - Make python-anyconfig robust for invalid inputs
 - Documentation:
 
-  - Especially API docs need more love! CLI doc is non-fulfilling.
+  - Especially API docs need more fixes and enhancements! CLI doc is non-fulfilling also.
   - English is not my native lang and there are many wrong and hard-to-understand expressions.
 
-Any feedbacks, helps, suggestions are welcome! Please open issues on github.com
-site if you have any problems on anyconfig!
+Any feedbacks, helps, suggestions are welcome! Please open github issues for
+these kind of problems also!
+
+Hacking
+--------
+
+How to test
+^^^^^^^^^^^^^
+
+Run '[WITH_COVERAGE=1] ./pkg/runtest.sh [path_to_python_code]' or 'tox' for tests.
+
+About test-time requirements, please take a look at pkg/test_requirements.txt.
 
 How to write backend plugin modules
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Backend class must inherit anyconfig.backend.Parser and need some member
 variables and method ('load_impl' and 'dumps_impl' at minimum) implementations.
@@ -250,11 +269,4 @@ examples to write backend modules, I think.
 Also, please take a look at some example backend plugin modules mentioned in
 the `Supported configuration formats`_ section.
 
-How to test
--------------
-
-Try to run '[WITH_COVERAGE=1] ./pkg/runtest.sh [path_to_python_code]' or 'tox'.
-
-About test-time requirements, please take a look at pkg/test_requirements.txt.
-
 .. vim:sw=2:ts=2:et: