/**
\mainpage libbash

\version @VERSION@ \ref ChangeLog_page "ChangeLog"

\author
	Hai Zaar \n Gil Ran
	
\date
	@docdate@

\par License
	GPL version 3

\par
\par Quick jump
    - \ref MainPage_General
    - \ref MainPage_Using "Using libbash"
    - \ref MainPage_Installing "Installing"
    - \ref libbash_developer_faq "FAQ"
    - \ref MainPage_FurtherReading "Further reading"
\par

\section MainPage_General General
\c libbash is a tool that enables bash dynamic-like shared libraries.

\subsection MainPage_What What is libbbash?

Actually its a tool for managing bash scripts that contain functions you may
want to use in various scripts.

To achieve its goal, it uses some kind of "dynamic loader" that you call to load
desired bash library (actually just to \c source bash code). 

\subsection MainPage_Why Why libbash?
In short - \b code \b reuse. That seems to be the problem of many bash programmers.
The bash lacks any built-in method of separating code into libraries.

Suppose you've written some great bash script. You've surelly splitted it to some
functions that do parameter parsing, etc... Now you want to reuse that code in some
other script. What do you do? The general solution is to cut out that reusable code
from your first script, put it in separate file, and then \c source it from both scripts.

Well, this may work fine, but what if your two scripts are completely unrelated and, in
fact, belong to completely different projects, that do not share any common files. So
you need to keep a copy of that reusable code in each project, and ... down we go...

The libbash was born to address the above problem. It may be seen as script organizer. It
holds "reusable code" in centralized place (typically \c /lib/bash/). Then you can use it 
to check what libraries are available, what functions they provide and actually source 
desired code.
\subsection MainPage_MoreInfo More information
- \ref libbash_developer_faq "libbash FAQ"
- \ref libbash_libraries_list "Available libraries"

\section MainPage_Using Using libbash

\subsection MainPage_Minimal Minimal survival guide
First, list bash libraries available on your system
\verbatim
#> ldbash -l
Libraries:
	getopts
	hashstash
\endverbatim
Well, if it does not tell you much, run \c man \c getopts for example.
When you've decided to go with getopts, you run
\verbatim
#> ldbash -e getopts
External:
        getopts:
                getopt_long
\endverbatim
The above means that \c getopts library provides \c getopt_long function
(use \c man to find out what it does and how to use it). 

From now on can start writing your script that uses \c getopt_long. The 
question you ask now is: "How do I load that function to my script?" The
aswer is very simple. Consider:
\verbatim
#> ldbash -L getopts
source /usr/lib/bash/getopts.sh; source /usr/lib/bash/hashstash.sh;
\endverbatim
So all you need to do in your script is to add the following line:
\verbatim
eval `ldbash -L getopts`
\endverbatim

\note You may noticed that you are actually sourcing two files: \c getopts.sh
and some mysterous \c hashstash.sh. The reason is that getopts reported that it
requires hashstash and libbash tracked that request and fulfilled it.

\subsection MainPage_Synopsys Synopsys
\par \c ldbash \c [\c -h \c | \c --help] 
	Show help message.

\par \c ldbash \c [\c -l \c | \c --list] 
	List available libraries.

\par \c ldbash \c [\c -L \c | \c --load \c lib,\c [\c lib\c ] \c ...] 
	Load library. \n
	Actually, it gives you a string that should be evaled (using eval (1)). After running eval(1) you will be able to use the library's functions.

\par \c ldbash \c [\c -U \c | \c --unload \c lib,\c [\c lib\c ] \c ...] 
	Unload a library.
	Actually, it gives you a string that should be evaled (using eval (1)). After running eval(1) the library's functions will no longer be usable.

\par \c ldbash \c [\c -e \c |  \c --externlist \c lib,\c [\c lib\c ] \c ...]
	List all the functions that a specific library exports.

\par \c ldbash \c [\c --externlist-all]
	List all the functions that listed libraries export.

\par \c ldbash \c [\c --i \c | \c --internlist \c lib,\c [\c lib\c ] \c ...]
	List all the functions that are defined in a specific library, but are not exported.

\par \c ldbash \c [\c --internlist-all]
	List all the functions that are defined in a listed library, but are not exported.

\section MainPage_Installing Installing libbash

\subsection MainPage_Requirement Requirements
Actually, you need nothing except of bash. On the other hand, some (third party) libraries can use additional 
tools, that may not be available on your system. Anyway currently, there are none.

\c libbash was tested in \e bash \e 3\e .x. It may also work with \e 2\e .0x versions, but this is 'not supported' :)

Although you will need \e Doxygen to generate html documentation (the one you are reading at this moment).

\section MainPage_FurtherReading Further reading
- \ref libbash_developer "How to create and install your own libraries"
- ldbash - Dynamic loader for libbash libraries.
	- \ref ldbash_man "man page"
- ldbashconfig - Creates or updates cache file for libbash libraries.
	- \ref ldbashconfig_man "man page"

*/
