== # What is Habitat ==

Habitat is a very small, super fast, easy-to-install and highly customizable
content management system designed for personal or community use.
Habitat is written in perl, and can use sqlite database as the
backend. It even contains a build-in cgi webserver. Habitat
can be run from a local computer by an individual user, or installed
on a public website serving a group of users.

Habitat is a wiki engine too. Users can quickly build their 
own websites or information archive using this software by
creating, editing and managing wiki pages online. It provides
an efficient collaborative platform for an online community 
to develop software or resources.

Habitat was written by [http://nmr.mgh.harvard.edu/~fangq/ Qianqian Fang] 
who had also founded the collaborative font development project - 
[http://wenq.org/en/ WenQuanYi]. Habitat is a result of 5 years 
continuous improvement of the WenQuanYi Wiki engine. A lot of 
new features were added, such as the user management system,
database backend, hierarchical wiki page namespace, multi-language
support, object-oriented structure and interfaces for plugins.

== # How to install Habitat ==
To download the latest stable release of Habitat, please browse
the download section of [https://sourceforge.net/projects/huc/files/ this page].
<b>If you are using Debian/Ubuntu, please download and install
the deb package. It will set up everything for you 
and you can find Habitat in the "Accessories" menu.</b>

If you want to try out the latest code, you can 
access it from our SVN. On Unix/Linux/Mac OS, you can use the 
following svn command:
  svn co https://huc.svn.sourceforge.net/svnroot/huc/trunk/habitat habitat
On Windows, you might want to install [http://tortoisesvn.net/downloads TortoiseSVN]
to run the above command.

You may run Habitat in 4 modes: Standard, Extended, 
Basic and Tiny. Under "Tiny" mode, you can even get most
things done with a SINGLE cgi script (only 200kB in size)!

It is recommended to run Habitat under the Standard mode.
With this mode, sqlite database is used as
the backend, which not only saves a lot of disk space,
but also makes it super fast for searching and data backup. 

To use the Standard mode, you must make sure the following
perl modules are installed on your system:
  DBI, DBD::Sqlite3, Text::Diff, Text::Patch, Crypt::DES
If you are running a Debian/Ubuntu desktop, you can install all the 
dependencies using the following command:
  sudo apt-get install perl python sqlite3 libdbd-sqlite3-perl \
     libtext-diff-perl libtext-patch-perl libcrypt-des-perl
In most cases, perl and python have already been installed. So, the 
above command only adds about 1M space. If you do not have 
permission to install these modules, you can download the pre-compiled 
modules from our website. Extract the downloaded modules
into a subfolder called "lib" under the Habitat main directory.

The next step is to initialize database, please run the 
following command from Habitat's main folder:
  sqlite3 db/habitatdb.db '.read db/gendb.sql'
For safety reasons, we strongly suggest you setting your own
administrator password and site hash. To do so, you need
to edit a global config file with command:
  nano habitatdb/config
search for <tt>AdminPass</tt> and <tt>CaptchaKey</tt>, replace the values 
in the quotations to whatever password you prefer. Note,
<tt>CaptchaKey</tt> must be a 16digit hex number. You should
also consider moving the <tt>habitatdb</tt> directory to a safe place to 
avoid direct exposing of the <tt>config</tt> file. A suggested place is 
<tt>/var/lib/habitatdb/</tt>. Remember to update the value for <tt>DataDir</tt>
variable at the beginning of index.cgi if you have moved the <tt>habitatdb</tt> folder.

Now it is time to test Habitat. Open a terminal, and
navigate to the Habitat main folder, and run
 ./runlocal.sh
A browser window will pop-up, and the home page will be displayed.
If you prefer to use Chinese (or other languages) as the default 
language, edit "<tt>index.cgi</tt>", search for <tt>LangID="en"</tt>, and
replace en to cn (or other language codes).

== # How to use Habitat ==

If you run Habitat for the first time, please click on the
"[http:?action=newlogin Register]" link on the left to create a username/password
for yourself. You can also apply the admin password you set
previously. Otherwise, you will be considered as an 
anonymous user and Habitat will only display your IP address.

If you want to make you the only person who can make changes, 
you have to login as an administrator (by setting the admin password
in the register page), and set <tt>EditAllowed</tt> to 0 in the <tt>config</tt>
file. If you want to run Habitat for personal use, this is 
highly recommended.

To create or modify pages, simply click on the "[http:?action=edit&id=Home Edit this page]" 
link on the top. Habitat supports many common Wiki markup
rules used by [http://www.usemod.com/cgi-bin/wiki.pl?TextFormattingRules UseModWiki] 
or [http://en.wikipedia.org/wiki/Help:Wiki_markup Wikipedia]. Please check out 
[Local:HabitatTest HabitatTest] and [Local:HabitatNewTest HabitatNewTest]
pages for more details about formatting.

A new feature of Habitat is the support of hierarchical pages.
You can create something like "[[Page/Subpage]]"
or "[[Page/Subpage/Subsubpage]]" to represent more complex
information or resources.

== # Where to get help ==

Please visit the [http://wenq.org/forum/viewforum.php?f=8 Habitat forum]
to get more information and help for using Habitat. We also actively
post new versions or patches at the [http://wenq.org/habitat/ Habitat 
website].

Habitat is an open-source project. You are welcome to contribute 
and become a developer. Please visit 
[http://wenq.org/habitat/ Habitat website] for more details.

== # A bigger picture ==

Habitat is a sub-project of the [http://huc.sf.net Human Understandable Computing]
(HUC) project. The overall goal of HUC is to promote open, safe,
collaborative and intuitive programming models. The focus of
the project is to develop software tools that are written 
in non-obscured scripting languages and driven by human understandable 
text, graphics and multimedia data (such as voice, video or gesture).
Habitat is a demonstration of the basic principles for HUC,
as it is written by high-level scripting language and 
manipulates human understandable text information.

We welcome anyone who embraces the notion of HUC to join
us. We believe that the more software following the principles of
HUC, the more open and safer our software ecosystem will be.