added module documentation, improved main documentation

README.md

@@ -18,36 +18,109 @@ it would be a good idea to submit your module to init.sh source base.
 - the init.sh script, which provide a simple framework and libraries to do
 simple taks and embed system dependent functions to provide system independent
 function calls.
-- modules that actually do the job on a system independant way through the use
-of the framework and consisting on very small and simple task.
+- modules that actually do the job, as possible on a system independant way
+through the use of the framework and consisting on very small and simple tasks.
 - multilevel configuration files, being simply Bash variables declaration.
 
 Additionally some module might be ran regularly so it could be integrated in a
 cron-like service.
 
+### Command line
+
+The **init.sh** script allows some command line parameters and some environement
+variables to change it's behaviour.
+
+The parameters are:
+
+- **-m \<list\>, --module \<list\>**: Allows to manually give a module list and
+overide the *MODULE_LIST* variable declaration. The list is a comma separated
+module name. If that option is provided, the module list is mandatory.
+- **-c, --check-only**: Do not launch any actions, only the checks are launched.
+In that situation, no change should be done to the system.
+- **-j, --jump**: Jump the checks and goes directly to system transformation.
+That option should only be run after successfull checks (eg. after using the
+**--checkonly** option).
+- **-k, --keep-going**: The scripts will continue even if errors occurs. Thus
+some unrecoverable errors might stop the script anyway if it not allowing it to
+work. Please use with care as it might leads to unexpected results.
+
+### Loading order and process
+
+The first things the script do is loading its libraries contained in the "lib"
+directory. Any file situated in that directory ending with the .sh extention
+will be loaded in alphabetical order. For that reason, error management
+functions are place in a file called aaa_error.sh, so it can be loaded first and
+catch errors that could occurs while loading library files.
+
+After that a basic command line parameter treatment is done. That allows the use
+of --version and --help options in user space. Those options just display
+informations and don't require any superuser rights and exit at that point of
+execution. Everything that follows will do and the script will exit with error
+at that point if not superuser.
+
+Next will be the log file creation and the loading of configuration files. At
+this point a deeper analysis of command line option will be done, triggering
+errors in case of unconsistency or incompatible options.
+
+Finally checking processes are launched in their declaration order (cf.
+configuration file) and if not error and after a confirmation prompt, final
+configuration process, those that actually makes changes, are launched.
+
+Without the --keep-going option any error will imediatelly stop execution. Some
+errors that could make the script impossible to execute will stop execution,
+even if the --keep-going option is provided.
+
 ### Main configuration file
 
-Writing in progress.
+The main configuration file can be two different file. Either it's completely
+generic and will be named **init.conf.sh** in the "conf" directory, either it
+will be named after the current hostname of the computer in that same "conf"
+directory. Please remember that the actual name will be used until the end of
+the execution of init.sh. If one of your module change the hostname, the new
+name can only be took into account after a new execution of init.sh.
+
+Most of the variable you can declare to configure your host depends on the
+module you will use. Please refer to module header to see hat's available for
+your use case.
+
+It is heavily recommended to use includes technique to shorten your
+configuration file and make a file for your organisation and an other one
+for the Linux distribution you use. Remember that the declaration order matters,
+so you can declare something on your organisation configuration file and
+superseed it in your host configuration file. The only limit will be Bash
+capabilities in terms of variable manipulation.
 
 ### Naming conventions
 
-Because of internal mechanics the dash character is forbidden in module names. Thus Bash language also forbid that character in variable name.
+Because of internal mechanics the dash character is forbidden in module names.
+Thus Bash language also forbid that character in variable name.
 
-An other limit is, even if digits are allowed in module names and variable, they can't be used as a leading character or worse the full name being only made of digits. You can use as many digits you want in names but with at least a leading alphabetical (or underscore) character, whatever the case of that character will be.
+An other limit is, even if digits are allowed in module names and variable, they
+can't be used as a leading character or worse the full name being only made of
+digits. You can use as many digits you want in names but with at least a leading
+alphabetical (or underscore) character, whatever the case of that character will
+be.
 
-You can use upper case and lower case as you wish, with underscore character, even as leading character. Any other special character than alphanumerical or underscore is completely forbidden.
+You can use upper case and lower case as you wish, with underscore character,
+even as leading character. Any other special character than alphanumerical or
+underscore is completely forbidden.
 
-Any submitted module to the central repository will have module name in lower case with underscore to separate words and ease reading, and variable name upper case with the same underscore as word separator.
+Any submitted module to the central repository will have module name in lower
+case with underscore to separate words and ease reading, and variable name upper
+case with the same underscore as word separator.
 
 ### Basic module structure
 
 Please note that modules are not supposed to contain any specific code for a
 platform or a distribution even if nothing block you doing so. It is highly
 recommended to use configurations files to introduce any platform dependent
-code.
+code. Additionally, it will be possible to create system dependent modules using
+naming convention in the style module_name.debian.x86_64.sh (awaited for version
+2 of init.sh).
 
 In the following exemple @template@ have to be replaced with the name of your
-module with the filename @template@.sh. You can automatically create your new module with the following command:
+module with the filename @template@.sh. You can automatically create your new
+module with the following command:
 
 ```shell
 sed -e "s/@template@/module_name/g" -e "/^# .*/d" -e "s/^##/# /" template > \
@@ -59,10 +132,10 @@ standard rules. Considering a numbering as x.y.z:
 
 - x might be incremented in case of major change, rewriting or deferent approach
 on the way to have the job done
-- y might be incremented in case simple finctionnality addition or basic
+- y might be incremented in case simple functionnality addition or basic
 improvements
 - z might be incremented only when correcting problems and/or bugs (+n fix => +n
-increment)
+to increment)
 
 Unless only configuration files have been changed, any change in the code
 implies any increment of a version number in the code **and** a git commit.
@@ -90,21 +163,4 @@ export -f @template@
 export -f precheck_@template@
 ```
 
-### Command line
-
-The **init.sh** script allows some command line parameters and some environement
-variables to change it's behaviour.
-
-The parameters are:
-
-- **-m \<list\>, --module=\<list\>**: Allows to manually give a module list and
-overide the *MODULE_LIST* variable declaration. The list is a comma separated
-module name. If that option is provided, the module list is mandatory.
-- **-c, --check-only**: Do not launch any actions, only the checks are launched.
-In that situation, no change should be done to the system.
-- **-j, --jump**: Jump the checks and goes directly to system transformation.
-That option should only be run after successfull checks (eg. after using the
-**--checkonly** option).
-- **-k, --keep-going**: The scripts will continue even if errors occurs. Thus
-some unrecoverable errors might stop the script anyway if it not allowing it to
-work.
+## Contact and more information