correct markdown of some descriptive files

Aurélio A. Heckert
1 parent 70a3c042
Showing 11 changed files with 563 additions and 782 deletions Show diff stats
AUTHORS.md
INSTALL.awstats.md
INSTALL.chat.md
INSTALL.email.md
INSTALL.md
INSTALL.multitenancy.md
INSTALL.varnish.md
README.md
README.rails.md
RELEASING.md
plugins/anti_spam/README.md
-If you are not listed here, but should be, please write to the noosfero mailing
-list: http://listas.softwarelivre.org/cgi-bin/mailman/listinfo/noosfero-dev
-(this list requires subscription to post, but since you are an author of
-noosfero, that's not a problem).
+If you are not listed here, but should be, please write to the noosfero mailing list: http://listas.softwarelivre.org/cgi-bin/mailman/listinfo/noosfero-dev (this list requires subscription to post, but since you are an author of noosfero, that's not a problem).
 Developers
 ==========
-= AWStats setup for Noosfero
+AWStats setup for Noosfero
+==========================
-AWStats is a free powerful and featureful tool that generates advanced web,
-streaming, ftp or mail server statistics, graphically.
+AWStats is a free powerful and featureful tool that generates advanced web, streaming, ftp or mail server statistics, graphically.
-See http://awstats.sourceforge.net/
+See http://awstats.sourceforge.net
 This guide supposes that the Noosfero server is running GNU/Linux Debian Squeeze.
-1. Install AWStats
+### 1. Install AWStats
-# apt-get install awstats libgeo-ip-perl geoip-database
+    # apt-get install awstats libgeo-ip-perl geoip-database
-2. Basic setup
+### 2. Basic setup
 Create AWStats config file:
+`/etc/awstats/awstats.<domain>.conf`
- * /etc/awstats/awstats.<domain>.conf
+    Include "/etc/awstats/awstats.conf"
+    Include "/etc/noosfero/awstats-noosfero.conf"
+    SiteDomain="<domain>"
+    HostAliases="<domain-aliases>"
-Include "/etc/awstats/awstats.conf"
-Include "/etc/noosfero/awstats-noosfero.conf"
-SiteDomain="<domain>"
-HostAliases="<domain-aliases>"
+`<domain>` should be the domain used in your Noosfero server (eg.: `softwarelivre.org`) and the `<domain-aliases>` should be a list with all aliases that you configured in apache (eg.: `www.softwarelivre.org`, `www2.softwarelivre.org`, etc).
-<domain> should be the domain used in your Noosfero server (eg.:
-softwarelivre.org) and the <domain-aliases> should be a list with all aliases
-that you configured in apache (eg.: www.softwarelivre.org
-www2.softwarelivre.org etc).
+This setup is considering that the Noosfero server is running varnish (see `INSTALL.varnish`) and [varnishncsa-vhost](http://gitorious.org/varnisnncsa-vhost).
-This setup is considering that the Noosfero server is running varnish (see
-INSTALL.varnish) and varnishncsa-vhost [1].
-
-[1] http://gitorious.org/varnisnncsa-vhost
-
-3. Running AWStats for the first time
+### 3. Running AWStats for the first time
 Run awstats by hand via command line:
-# /usr/lib/cgi-bin/awstats.pl -config=<domain>
+    # /usr/lib/cgi-bin/awstats.pl -config=<domain>
 You should see something as below as output of this command:
-# /usr/lib/cgi-bin/awstats.pl -config=softwarelivre.org
-Create/Update database for config "/etc/awstats/awstats.softwarelivre.org.conf" by AWStats version 6.7 (build 1.892)
-From data in log file "/var/log/varnish/varnishncsa-vhost.log"...
-Phase 1 : First bypass old records, searching new record...
-Searching new records from beginning of log file...
-Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
-Jumped lines in file: 0
-Parsed lines in file: 452
- Found 0 dropped records,
- Found 0 corrupted records,
- Found 0 old records,
- Found 452 new qualified records.
+    # /usr/lib/cgi-bin/awstats.pl -config=softwarelivre.org
+    Create/Update database for config "/etc/awstats/awstats.softwarelivre.org.conf" by AWStats version 6.7 (build 1.892)
+    From data in log file "/var/log/varnish/varnishncsa-vhost.log"...
+    Phase 1 : First bypass old records, searching new record...
+    Searching new records from beginning of log file...
+    Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
+    Jumped lines in file: 0
+    Parsed lines in file: 452
+     Found 0 dropped records,
+     Found 0 corrupted records,
+     Found 0 old records,
+     Found 452 new qualified records.
-4. Setup frontend
+### 4. Setup frontend
-You should create a new subdomain to have access to the AWStats, usually
-something like tools.<domain> (eg.: tools.softwarelivre.org). Don't include
-this subdomain in HostAliases in the AWStats neither in SiteAlias in the
-Apache.
+You should create a new subdomain to have access to the AWStats, usually something like tools.<domain> (eg.: tools.softwarelivre.org). Don't include this subdomain in HostAliases in the AWStats neither in SiteAlias in the Apache.
-# cp /usr/share/doc/awstats/examples/apache.conf /etc/apache2/conf.d/awstats.conf
-# invoke-rc.d apache2 restart
+    # cp /usr/share/doc/awstats/examples/apache.conf /etc/apache2/conf.d/awstats.conf
+    # invoke-rc.d apache2 restart
-ps.: Don't forget to change the port /etc/apache/sites-enabled/000-default to
-8080.
+ps.: Don't forget to change the port `/etc/apache/sites-enabled/000-default` to `8080`.
-Try: http://tools.<domain>/cgi-bin/awstats.pl?config=<domain>
-(eg.: http://tools.softwarelivre.org/cgi-bin/awstats.pl?config=softwarelivre.org).
+Try: `http://tools.<domain>/cgi-bin/awstats.pl?config=<domain>`
+(eg.: `http://tools.softwarelivre.org/cgi-bin/awstats.pl?config=softwarelivre.org`).
-5. Schedule AWStats in crontab
+### 5. Schedule AWStats in crontab
- * /etc/cron.d/awstats
+`/etc/cron.d/awstats`
-0,10,20,30,40,50 * * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl -a -f /etc/awstats/awstats.<domain>.conf -a -r /var/log/apache/access.log ] && /usr/lib/cgi-bin/awstats.pl -config=<domain> -update >/dev/null
+    0,10,20,30,40,50 * * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl -a -f /etc/awstats/awstats.<domain>.conf -a -r /var/log/apache/access.log ] && /usr/lib/cgi-bin/awstats.pl -config=<domain> -update >/dev/null
 Done, check the AWStats frontend after one or two days to see if everything is working properly.
-== XMPP/Chat Client Setup
+XMPP/Chat Client Setup
+======================
 To configure XMPP/BOSH in Noosfero you need:
@@ -8,96 +9,87 @@ To configure XMPP/BOSH in Noosfero you need:
 If you use Debian 6.0 (squeeze):
-# apt-get install librestclient-ruby pidgin-data ruby1.8-dev
-# gem install SystemTimer
+    # apt-get install librestclient-ruby pidgin-data ruby1.8-dev
+    # gem install SystemTimer
-The samples of config file to configure a XMPP/BOSH server with
-ejabberd, postgresql and apache2 can be found at util/chat directory.
+The samples of config file to configure a XMPP/BOSH server with ejabberd, postgresql and apache2 can be found at util/chat directory.
-== XMPP/Chat Server Setup
+XMPP/Chat Server Setup
+======================
 This is a step-by-step guide to get a XMPP service working, in a Debian system.
-1. Install the required packages
+## 1. Install the required packages
-# apt-get install ejabberd odbc-postgresql
+    # apt-get install ejabberd odbc-postgresql
-2. Ejabberd configuration
+## 2. Ejabberd configuration
-All the following changes must be done in config file:
+All the following changes must be done in config file: `/etc/ejabberd/ejabberd.cfg`
- /etc/ejabberd/ejabberd.cfg
+### 2.1. Set the default admin user
- 2.1. Set the default admin user
+    { acl, admin, { user, "john", "www.example.com" } }.
+    { acl, admin, { user, "bart", "www.example.com" } }.
-{ acl, admin, { user, "john", "www.example.com" } }.
-{ acl, admin, { user, "bart", "www.example.com" } }.
+### 2.2. Set the default host
- 2.2. Set the default host
+    { hosts, [ "www.example.com" ] }.
-{ hosts, [ "www.example.com" ] }.
+### 2.3. Http-Bind activation
- 2.3. Http-Bind activation
+    { 5280, ejabberd_http, [
+          http_bind,
+          web_admin
+       ]
+    }
-{ 5280, ejabberd_http, [
-      http_bind,
-      web_admin
-   ]
-}
+    (...)
-(...)
+    { modules, [
+       {mod_http_bind, []},
+       ...
+    ] }.
-{ modules, [
-   {mod_http_bind, []},
-   ...
-] }.
+Ejabberd creates semi-anonymous rooms by default, but Noosfero's Jabber client needs non-anonymous room, then we need to change default params of creation rooms in ejabberd to create non-anonymous rooms.
-Ejabberd creates semi-anonymous rooms by default, but Noosfero's Jabber client
-needs non-anonymous room, then we need to change default params of creation
-rooms in ejabberd to create non-anonymous rooms.
+In non-anonymous rooms the jabber service sends the new occupant's full JID to all occupants in the room [[1]].
-In non-anonymous rooms the jabber service sends the new occupant's full JID to
-all occupants in the room[1].
+Add option "`{default_room_options, [{anonymous, false}]}`" to `/etc/ejabberd/ejabberd.cfg` in mod_muc session. See below:
-Add option "{default_room_options, [{anonymous, false}]}" to
-/etc/ejabberd/ejabberd.cfg in mod_muc session. See below:
+    { mod_muc, [
+       %%{host, "conference.@HOST@"},
+       {access, muc},
+       {access_create, muc},
+       {access_persistent, muc},
+       {access_admin, muc_admin},
+       {max_users, 500},
+       {default_room_options, [{anonymous, false}]}
+    ]},
-{ mod_muc, [
-   %%{host, "conference.@HOST@"},
-   {access, muc},
-   {access_create, muc},
-   {access_persistent, muc},
-   {access_admin, muc_admin},
-   {max_users, 500},
-   {default_room_options, [{anonymous, false}]}
-]},
+[1]: http://xmpp.org/extensions/xep-0045.html#enter-nonanon
-[1] - http://xmpp.org/extensions/xep-0045.html#enter-nonanon
-
- 2.4. Authentication method
+### 2.4. Authentication method
 To use Postgresql through ODBC, the following modifications must be done:
  * Disable the default method:
-
-{auth_method, internal}.
+   `{auth_method, internal}.`
  * Enable autheticantion through ODBC:
-
-{auth_method, odbc}.
+   `{auth_method, odbc}.`
  * Set database server name
+   `{odbc_server, "DSN=PostgreSQLEjabberdNoosfero"}.`
-{odbc_server, "DSN=PostgreSQLEjabberdNoosfero"}.
+### 2.5. Increase the shaper traffic limit
- 2.5. Increase the shaper traffic limit
+    { shaper, normal, { maxrate, 10000000 } }.
-{ shaper, normal, { maxrate, 10000000 } }.
-
- 2.6. Disable unused modules
+### 2.6. Disable unused modules
 Unused modules can be disabled, for example:
@@ -110,149 +102,135 @@ Unused modules can be disabled, for example:
  * mod_register
- 2.7. Enable ODBC modules
+### 2.7. Enable ODBC modules
  * mod_privacy -> mod_privacy_odbc
  * mod_private -> mod_private_odbc
  * mod_roster  -> mod_roster_odbc
-3. Configuring Postgresql
+## 3. Configuring Postgresql
 Login as noosfero user, and execute:
-   $ psql noosfero < /path/to/noosfero/util/chat/postgresql/ejabberd.sql
-
-Where 'noosfero' may need to be replace by the name of the database used for
-Noosfero.
+    $ psql noosfero < /path/to/noosfero/util/chat/postgresql/ejabberd.sql
-This will create a new schema inside the noosfero database, called 'ejabberd'.
+Where `noosfero` may need to be replace by the name of the database used for Noosfero.
-Note 'noosfero' user should have permission to create Postgresql schemas. Also,
-there should be at least one domain with 'is_default = true' in 'domains'
-table, otherwise people won't be able to see their friends online.
+This will create a new schema inside the noosfero database, called `ejabberd`.
+Note `noosfero` user should have permission to create Postgresql schemas. Also, there should be at least one domain with `is_default = true` in `domains` table, otherwise people won't be able to see their friends online.
-4. ODBC configuration
+## 4. ODBC configuration
 The following files must be created:
- * /etc/odbc.ini
+`/etc/odbc.ini`:
-[PostgreSQLEjabberdNoosfero]
-Description      = PostgreSQL Noosfero ejabberd database
-Driver           = PostgreSQL Unicode
-Trace            = No
-TraceFile        = /tmp/psqlodbc.log
-Database         = noosfero
-Servername       = localhost
-UserName         = <DBUSER>
-Password         = <DBPASS>
-Port             =
-ReadOnly         = No
-RowVersioning    = No
-ShowSystemTables = No
-ShowOidColumn    = No
-FakeOidIndex     = No
-ConnSettings     = SET search_path TO ejabberd
+    [PostgreSQLEjabberdNoosfero]
+    Description      = PostgreSQL Noosfero ejabberd database
+    Driver           = PostgreSQL Unicode
+    Trace            = No
+    TraceFile        = /tmp/psqlodbc.log
+    Database         = noosfero
+    Servername       = localhost
+    UserName         = <DBUSER>
+    Password         = <DBPASS>
+    Port             =
+    ReadOnly         = No
+    RowVersioning    = No
+    ShowSystemTables = No
+    ShowOidColumn    = No
+    FakeOidIndex     = No
+    ConnSettings     = SET search_path TO ejabberd
- * /etc/odbcinst.ini
+`/etc/odbcinst.ini`:
-[PostgreSQL Unicode]
-Description = PostgreSQL ODBC driver (Unicode version)
-Driver      = /usr/lib/odbc/psqlodbcw.so
-Setup       = /usr/lib/odbc/libodbcpsqlS.so
-Debug       = 0
-CommLog     = 1
-UsageCount  = 3
+    [PostgreSQL Unicode]
+    Description = PostgreSQL ODBC driver (Unicode version)
+    Driver      = /usr/lib/odbc/psqlodbcw.so
+    Setup       = /usr/lib/odbc/libodbcpsqlS.so
+    Debug       = 0
+    CommLog     = 1
+    UsageCount  = 3
- 4.1 testing all:
+## 4.1 testing all:
-# isql 'PostgreSQLEjabberdNoosfero'
+    # isql 'PostgreSQLEjabberdNoosfero'
-If the configuration was done right, the message "Connected!"
-will be displayed.
+If the configuration was done right, the message "Connected!" will be displayed.
-5. Enabling kernel polling and SMP in /etc/default/ejabberd
+## 5. Enabling kernel polling and SMP in `/etc/default/ejabberd`
-POLL=true
-SMP=auto
+    POLL=true
+    SMP=auto
+## 6. Increase the file descriptors limit for user ejabberd
-6. Increase the file descriptors limit for user ejabberd
+### 6.1. Uncomment this line in file `/etc/pam.d/su`:
- 6.1. Uncomment this line in file /etc/pam.d/su:
+    session required pam_limits.so
-session required pam_limits.so
+### 6.2. Add this lines to file `/etc/security/limits.conf`:
-
- 6.2. Add this lines to file /etc/security/limits.conf:
-
-ejabberd       hard    nofile  65536
-ejabberd       soft    nofile  65536
+    ejabberd       hard    nofile  65536
+    ejabberd       soft    nofile  65536
 Now, test the configuration:
-# cat /proc/<EJABBERD_BEAM_PROCESS_PID>/limits
-
+    # cat /proc/<EJABBERD_BEAM_PROCESS_PID>/limits
-7. Apache Configuration
+## 7. Apache Configuration
 Apache server must be configurated as follow:
- * /etc/apache2/sites-enabled/noosfero
+`/etc/apache2/sites-enabled/noosfero`:
-RewriteEngine On
-Include /usr/share/noosfero/util/chat/apache/xmpp.conf
+    RewriteEngine On
+    Include /usr/share/noosfero/util/chat/apache/xmpp.conf
- * /etc/apache2/apache2.conf:
+`/etc/apache2/apache2.conf`:
-<IfModule mpm_worker_module>
-   StartServers          8
-   MinSpareThreads       25
-   MaxSpareThreads       75
-   ThreadLimit           128
-   ThreadsPerChild       128
-   MaxClients            2048
-   MaxRequestsPerChild   0
-</IfModule>
+    <IfModule mpm_worker_module>
+       StartServers          8
+       MinSpareThreads       25
+       MaxSpareThreads       75
+       ThreadLimit           128
+       ThreadsPerChild       128
+       MaxClients            2048
+       MaxRequestsPerChild   0
+    </IfModule>
 Note: module proxy_http must be enabled:
-# a2enmod proxy_http
+    # a2enmod proxy_http
-8. DNS configuration
+## 8. DNS configuration
-For this point, we assume you are using BIND as your DNS server. You need to
-add the following entries to the DNS zone file corresponding to the domain
-of your noosfero site:
+For this point, we assume you are using BIND as your DNS server. You need to add the following entries to the DNS zone file corresponding to the domain of your noosfero site:
-_xmpp-client._tcp   SRV   5 100 5222 master
-conference   CNAME master
-_xmpp-client._tcp.conference   SRV   5 100 5222 master
+    _xmpp-client._tcp   SRV   5 100 5222 master
+    conference   CNAME master
+    _xmpp-client._tcp.conference   SRV   5 100 5222 master
-If you are running a DNS server other than BIND, you will have to figure out
-how to create equivalente rules for your zone file. Patches to this
-documentation are welcome.
+If you are running a DNS server other than BIND, you will have to figure out how to create equivalente rules for your zone file. Patches to this documentation are welcome.
-9. Testing this Setup
+## 9. Testing this Setup
 Adjust shell limits to proceed with some benchmarks and load tests: 
-# ulimit −s 256
-# ulimit −n 8192
-# echo 10 > /proc/sys/net/ipv4/tcp_syn_retries
+    # ulimit −s 256
+    # ulimit −n 8192
+    # echo 10 > /proc/sys/net/ipv4/tcp_syn_retries
 To measure the bandwidth between server and client:
  * at server side:
-
-# iperf −s
+   `# iperf −s`
  * at client side:
-
-# iperf −c server_ip
+   `# iperf −c server_ip`
 For heavy load tests, clone and use this software:
-git clone http://git.holoscopio.com/git/metal/tester.git
+    $ git clone http://git.holoscopio.com/git/metal/tester.git
-= Noosfero email setup
+Noosfero email setup
+====================
-If you know mail systems well, you just need to make sure that the local MTA,
-listening on localhost:25, is able to deliver e-mails to the internet. Any mail
-server will do it. You can stop reading now.
+If you know mail systems well, you just need to make sure that the local MTA, listening on localhost:25, is able to deliver e-mails to the internet. Any mail server will do it. You can stop reading now.
-If you are not an email specialist, then follow the instructions below. We
-suggest that you use the Postfix mail server, since it is easy to configure and
-very reliable. Just follow the instructions below.
+If you are not an email specialist, then follow the instructions below. We suggest that you use the Postfix mail server, since it is easy to configure and very reliable. Just follow the instructions below.
 To install Postfix:
-# apt-get install postfix
+    # apt-get install postfix
-During the installation process, you will be asked a few questions. Your answer
-to them will vary in 2 cases:
+During the installation process, you will be asked a few questions. Your answer to them will vary in 2 cases:
-Case 1: you can send e-mails directly to the internet. This will be the case
-for most commercial private servers. Your answers should be:
+**Case 1**: you can send e-mails directly to the internet. This will be the case for most commercial private servers. Your answers should be:
-  General type of mail configuration: Internet site
-  System mail name: the name of your domain, e.g. "mysocialnetwork.com"
+ * General type of mail configuration: Internet site
+ * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
-Case 2: you cannot, or don't want to, send e-mail directly to the internet.
-This happens for example if your server is not allowed to make outbound
-connections on port 25, or if you want to concentrate all your outbound mail
-through a single SMTP server. Your answers in this case should be:
+**Case 2**: you cannot, or don't want to, send e-mail directly to the internet. This happens for example if your server is not allowed to make outbound connections on port 25, or if you want to concentrate all your outbound mail through a single SMTP server. Your answers in this case should be:
-  General type of mail configuration: Internet with smarthost
-  System mail name: the name of your domain, e.g. "mysocialnetwork.com"
-  SMTP relay host: smtp.yourprovider.com
+ * General type of mail configuration: Internet with smarthost
+ * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
+ * SMTP relay host: smtp.yourprovider.com
-Note that smtp.yourprovider.com must allow your server to deliver e-mails
-through it. You should probably ask your servive provider about this.
+Note that smtp.yourprovider.com must allow your server to deliver e-mails through it. You should probably ask your servive provider about this.
-There is another possibility: if you are installing on a shared server, and
-don't have permission to configure the local MTA, you can instruct Noosfero to
-send e-mails directly through an external server. Please note that this should
-be your last option, since contacting an external SMTP server directly may slow
-down your Noosfero application server. To configure Noosfero to send e-mails
-through an external SMTP server, follow the instructions on
-http://noosfero.org/Development/SMTPMailSending
+There is another possibility: if you are installing on a shared server, and don't have permission to configure the local MTA, you can instruct Noosfero to send e-mails directly through an external server. Please note that this should be your last option, since contacting an external SMTP server directly may slow down your Noosfero application server. To configure Noosfero to send e-mails through an external SMTP server, follow the instructions on http://noosfero.org/Development/SMTPMailSending
-= Noosfero installation instructions from source for production environments
+Noosfero installation instructions from source for production environments
+==========================================================================
-The instructions below can be used for setting up a Noosfero production
-environment from the Noosfero sources.
+The instructions below can be used for setting up a Noosfero production environment from the Noosfero sources.
-Before you start installing Noosfero manually, see the information about the
-Noosfero Debian package at http://noosfero.org/Development/DebianPackage. Using
-the Debian packages on a Debian stable system is the recommended method for
-installing production environments.
+Before you start installing Noosfero manually, see the information about the Noosfero Debian package at http://noosfero.org/Development/DebianPackage. Using the Debian packages on a Debian stable system is the recommended method for installing production environments.
-If you want to setup a development environment instead of a production one,
-stop reading this file right now and read the file HACKING instead.
+If you want to setup a development environment instead of a production one, stop reading this file right now and read the file `HACKING.md` instead.
-For a complete installation guide, please see the following web page:
-http://noosfero.org/Development/HowToInstall
+For a complete installation guide, please see the following web page: http://noosfero.org/Development/HowToInstall
-If you have problems with the setup, please feel free to ask questions in the
-development mailing list.
+If you have problems with the setup, please feel free to ask questions in the development mailing list.
-== Requirements
+Requirements
+------------
-DISCLAIMER: this installation procedure is tested with Debian stable, which is
-currently the only recommended operating system for production usage. It is
-possible that you can install it on other systems, and if you do so, please
-report it on one of the Noosfero mailing lists, and please send a patch
-updating these instructions.
+**DISCLAIMER**: this installation procedure is tested with Debian stable, which is currently the only recommended operating system for production usage. It is possible that you can install it on other systems, and if you do so, please report it on one of the Noosfero mailing lists, and please send a patch updating these instructions.
-Noosfero is written in Ruby with the "Rails
-framework":http://www.rubyonrails.org, so the process of setting it up is
-pretty similar to other Rails applications.
+Noosfero is written in Ruby with the "[Rails framework](http://www.rubyonrails.org)", so the process of setting it up is pretty similar to other Rails applications.
-You need to install some packages Noosfero depends on.  On Debian GNU/Linux or
-Debian-based systems, all of these packages are available through the Debian
-archive. You can install them with the following command:
+You need to install some packages Noosfero depends on. On Debian GNU/Linux or Debian-based systems, all of these packages are available through the Debian archive. You can install them with the following command:
- # apt-get install ruby rake po4a libgettext-ruby-util libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libdaemons-ruby thin tango-icon-theme libhpricot-ruby
+    # apt-get install ruby rake po4a libgettext-ruby-util libgettext-ruby1.8 \
+      libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libhpricot-ruby \
+      libwill-paginate-ruby iso-codes libfeedparser-ruby libdaemons-ruby thin \
+      tango-icon-theme
-On other systems, they may or may not be available through your regular package
-management system. Below are the links to their homepages.
+On other systems, they may or may not be available through your regular package management system. Below are the links to their homepages.
-* Ruby: http://www.ruby-lang.org/
-* Rake: http://rake.rubyforge.org/
-* po4a: http://po4a.alioth.debian.org/
+* Ruby: http://www.ruby-lang.org
+* Rake: http://rake.rubyforge.org
+* po4a: http://po4a.alioth.debian.org
 * Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby
 * rcov: http://eigenclass.org/hiki/rcov
-* RMagick: http://rmagick.rubyforge.org/
-* RedCloth: http://redcloth.org/
+* RMagick: http://rmagick.rubyforge.org
+* RedCloth: http://redcloth.org
 * will_paginate: http://github.com/mislav/will_paginate/wikis
-* iso-codes: http://pkg-isocodes.alioth.debian.org/
+* iso-codes: http://pkg-isocodes.alioth.debian.org
 * feedparser: http://packages.debian.org/sid/libfeedparser-ruby
-* Daemons - http://daemons.rubyforge.org/
-* Thin: http://code.macournoyer.com/thin/
+* Daemons - http://daemons.rubyforge.org
+* Thin: http://code.macournoyer.com/thin
 * tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library
-* Hpricot: http://hpricot.com/
+* Hpricot: http://hpricot.com
 If you manage to install Noosfero successfully on other systems than Debian,
 please feel free to contact the Noosfero development mailing with the
@@ -62,30 +51,21 @@ As root user
 Install memcached. On Debian:
-# apt-get install memcached
+    # apt-get install memcached
-Study whether you need to raise the ammount of memory it uses for caching,
-depending on the demand you expect for your site. If you are going to run a
-high-traffic site, you will want to raise the ammount of memory reserved for
-caching.
+Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site. If you are going to run a high-traffic site, you will want to raise the ammount of memory reserved for caching.
-It is recommended that you run noosfero with its own user account. To create
-such an account, please do the following:
+It is recommended that you run noosfero with its own user account. To create such an account, please do the following:
-# adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero
+    # adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero
-(note that you can change the $HOME directory of the user if you wish, here we
-are using /var/lib/noosfero)
+(note that you can change the `$HOME` directory of the user if you wish, here we are using `/var/lib/noosfero`)
-The --system option will tell adduser to create a system user, i.e. this user
-will not have a password and cannot login to the system directly. To become
-this user, you have to use sudo:
+The `--system` option will tell adduser to create a system user, i.e. this user will not have a password and cannot login to the system directly. To become this user, you have to use sudo:
-# sudo -u noosfero -i
-
-or
-
-# su - noosfero
+    # sudo -u noosfero -i
+    or
+    # su - noosfero
 As noosfero user
 ================
@@ -93,325 +73,262 @@ As noosfero user
 downloading from git
 --------------------
-Here we are cloning the noosfero repository from git. Note: you will need to
-install git before.
+Here we are cloning the noosfero repository from git. Note: you will need to install git before.
-$ git clone git://gitorious.org/noosfero/noosfero.git current
-$ cd current
-$ git checkout -b stable origin/stable
+    $ git clone git://gitorious.org/noosfero/noosfero.git current
+    $ cd current
+    $ git checkout -b stable origin/stable
 downloading tarball
 -------------------
 Note: replace 0.39.0 below from the latest stable version.
-$ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz
-$ tar -zxvf noosfero-0.39.0.tar.gz
-$ ln -s noosfero-0.39.0 current
-$ cd current
+    $ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz
+    $ tar -zxvf noosfero-0.39.0.tar.gz
+    $ ln -s noosfero-0.39.0 current
+    $ cd current
 Create the thin configuration file:
-$ thin -C config/thin.yml -e production config
+    $ thin -C config/thin.yml -e production config
-Edit config/thin.yml to suit your needs. Make sure your apache
-configuration matches the thin cluster configuration, specially in respect
-to the ports and numbers of thin instances.
+Edit config/thin.yml to suit your needs. Make sure your apache configuration matches the thin cluster configuration, specially in respect to the ports and numbers of thin instances.
-Note: currently Noosfero only supports Rails 2.3.5, which is the version in
-Debian Squeeze. If you have a Rails version newer than that, Noosfero will
-probably not work. You can install Rails 2.3.5 into your Noosfero installation
-with the following procedure:
+*Note*: currently Noosfero only supports Rails 2.3.5, which is the version in Debian Squeeze. If you have a Rails version newer than that, Noosfero will probably not work. You can install Rails 2.3.5 into your Noosfero installation with the following procedure:
-$ cd /var/lib/noosfero/current/vendor
-$ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.3.5.orig.tar.gz
-$ tar xzf rails_2.3.5.orig.tar.gz
-$ ln -s rails-2.3.5 rails
+    $ cd /var/lib/noosfero/current/vendor
+    $ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.3.5.orig.tar.gz
+    $ tar xzf rails_2.3.5.orig.tar.gz
+    $ ln -s rails-2.3.5 rails
 As root user
 ============
 Setup Noosfero log and tmp directories:
-# cd /var/lib/noosfero/current
-# ./etc/init.d/noosfero setup
+    # cd /var/lib/noosfero/current
+    # ./etc/init.d/noosfero setup
-Now it's time to setup the database. In this example we are using PostgreSQL,
-so if you are planning to use a different database this steps won't apply.
+Now it's time to setup the database. In this example we are using PostgreSQL, so if you are planning to use a different database this steps won't apply.
-# apt-get install postgresql libpgsql-ruby
-# su postgres -c 'createuser noosfero -S -d -R'
+    # apt-get install postgresql libpgsql-ruby
+    # su postgres -c 'createuser noosfero -S -d -R'
-By default Rails will try to connect on postgresql through 5432 port,
-you can check it on /etc/postgresql/8.4/main/postgresql.conf file.
+By default Rails will try to connect on postgresql through 5432 port, you can check it on `/etc/postgresql/8.4/main/postgresql.conf` file.
 Restart postgresql:
+    # invoke-rc.d postgresql restart
-# invoke-rc.d postgresql restart
-
-Noosfero needs a functional e-mail setup to work: the local mail system should
-be able to deliver e-mail to the internet, either directly or through an
-external SMTP server. Please check the documentation at the INSTALL.email file.
+Noosfero needs a functional e-mail setup to work: the local mail system should be able to deliver e-mail to the internet, either directly or through an external SMTP server. Please check the documentation at the INSTALL.email file.
 As noosfero user
 ================
 Now create the databases:
-$ cd /var/lib/noosfero/current
-$ createdb noosfero_production
-$ createdb noosfero_development
-$ createdb noosfero_test
+    $ cd /var/lib/noosfero/current
+    $ createdb noosfero_production
+    $ createdb noosfero_development
+    $ createdb noosfero_test
-The development and test databases are actually optional. If you are creating a
-stricly production server, you will probably not need them.
+The development and test databases are actually optional. If you are creating a stricly production server, you will probably not need them.
-Now we want to configure Noosfero for accessing the database we just created.
-To do that, you can 1) copy config/database.yml.pgsql to config/database.yml,
-or create config/database.yml from scratch with the following content:
+Now we want to configure Noosfero for accessing the database we just created. To do that, you can 1) copy `config/database.yml.pgsql` to `config/database.yml`, or create `config/database.yml` from scratch with the following content:
-  production:
-    adapter: postgresql
-    encoding: unicode
-    database: noosfero_production
-    username: noosfero
+    production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero_production
+      username: noosfero
 Now, to test the database access, you can fire the Rails database console:
-$ ./script/dbconsole production
+    $ ./script/dbconsole production
-If it connects to your database, then everything is fine. If you got an error
-message, then you have to check your database configuration.
+If it connects to your database, then everything is fine. If you got an error message, then you have to check your database configuration.
 Create the database structure:
-$ RAILS_ENV=production rake db:schema:load
+    $ RAILS_ENV=production rake db:schema:load
 Compile the translations:
-$ RAILS_ENV=production rake noosfero:translations:compile
+    $ RAILS_ENV=production rake noosfero:translations:compile
-Now we must create some initial data. To create your default environment
-(the first one), run the command below:
+Now we must create some initial data. To create your default environment (the first one), run the command below:
-$ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)'
+    $ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)'
 (of course, replace "My environment" with your environment's name!)
-And now you have to add the domain name you will be using for your noosfero
-site to the list of domains of that default environment you just created:
+And now you have to add the domain name you will be using for your noosfero site to the list of domains of that default environment you just created:
-$ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')"
+    $ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')"
 (replace "your.domain.com" with your actual domain name)
 Add at least one user as admin of environment:
-$ RAILS_ENV=production ./script/runner "User.create(:login => 'adminuser', :email => 'admin@example.com', :password => 'admin', :password_confirmation => 'admin', :environment => Environment.default, :activated_at => Time.new)"
+    $ RAILS_ENV=production ./script/runner "User.create(:login => 'adminuser', :email => 'admin@example.com', :password => 'admin', :password_confirmation => 'admin', :environment => Environment.default, :activated_at => Time.new)"
-(replace "adminuser", "admin@example.com", "admin" with the login, email
-and password of your environment administrator)
+(replace "adminuser", "admin@example.com", "admin" with the login, email and password of your environment administrator)
 To start the Noosfero application servers:
-$ ./script/production start
+    $ ./script/production start
-At this point you have a functional Noosfero installation running, the only
-thing left is to configure your webserver as a reverse proxy to pass requests
-to them.
+At this point you have a functional Noosfero installation running, the only thing left is to configure your webserver as a reverse proxy to pass requests to them.
-==================
 Apache instalation
 ==================
-# apt-get install apache2
+    # apt-get install apache2
 Apache configuration
 --------------------
 First you have to enable the following some apache modules:
-  deflate
-  expires
-  proxy
-  proxy_balancer
-  proxy_http
-  rewrite
+ * deflate
+ * expires
+ * proxy
+ * proxy_balancer
+ * proxy_http
+ * rewrite
-On Debian GNU/Linux system, these modules can be enabled with the following
-command line, as root:
+On Debian GNU/Linux system, these modules can be enabled with the following command line, as root:
-# a2enmod deflate expires proxy proxy_balancer proxy_http rewrite
+    # a2enmod deflate expires proxy proxy_balancer proxy_http rewrite
 In other systems the way by which you enable apache modules may be different.
-Now with the Apache configuration. You can use the template below, replacing
-/var/lib/noosfero/current with the directory in which your noosfero
-installation is, your.domain.com with the domain name of your noosfero site.
-We are assuming that you are running two thin instances on ports 3000 and
-3001. If your setup is different you'll need to adjust <Proxy> section. If you
-don't understand something in the configuration, please refer to the apache
-documentation.
-
-Add a file called "mysite" (or whatever name you want to give to your noosfero
-site) to /etc/apache2/sites-available with the following content, and customize
-as needed (as usual, make sure you replace "your.domain.com" with you actual
-domain name, and "/var/lib/noosfero/current" with the directory where Noosfero
-is installed):
-
-  <VirtualHost *:80>
-    ServerName your.domain.com
-
-    DocumentRoot "/var/lib/noosfero/current/public"
-    <Directory "/var/lib/noosfero/current/public">
-      Options FollowSymLinks
-      AllowOverride None
-      Order Allow,Deny
-      Allow from all
-    </Directory>
+Now with the Apache configuration. You can use the template below, replacing `/var/lib/noosfero/current` with the directory in which your noosfero installation is, your.domain.com with the domain name of your noosfero site. We are assuming that you are running two thin instances on ports 3000 and 3001. If your setup is different you'll need to adjust `<Proxy>` section. If you don't understand something in the configuration, please refer to the apache documentation.
+
+Add a file called "mysite" (or whatever name you want to give to your noosfero site) to `/etc/apache2/sites-available` with the following content, and customize as needed (as usual, make sure you replace "your.domain.com" with you actual domain name, and "`/var/lib/noosfero/current`" with the directory where Noosfero is installed):
-    RewriteEngine On
+    <VirtualHost *:80>
+      ServerName your.domain.com
-    # Rewrite index to check for static index.html
-    RewriteRule ^/$ /index.html [QSA]
+      DocumentRoot "/var/lib/noosfero/current/public"
+      <Directory "/var/lib/noosfero/current/public">
+        Options FollowSymLinks
+        AllowOverride None
+        Order Allow,Deny
+        Allow from all
+      </Directory>
-    # Rewrite to check for Rails cached page
-    RewriteRule ^([^.]+)$ $1.html [QSA]
+      RewriteEngine On
-    RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
-    RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]
+      # Rewrite index to check for static index.html
+      RewriteRule ^/$ /index.html [QSA]
-    ErrorDocument 503 /503.html
+      # Rewrite to check for Rails cached page
+      RewriteRule ^([^.]+)$ $1.html [QSA]
-    ErrorLog /var/log/apache2/noosfero.log
-    LogLevel warn
-    CustomLog /var/log/apache2/noosfero.access.log combined
+      RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
+      RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]
-    Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf
+      ErrorDocument 503 /503.html
-  </VirtualHost>
+      ErrorLog /var/log/apache2/noosfero.log
+      LogLevel warn
+      CustomLog /var/log/apache2/noosfero.access.log combined
-  <Proxy balancer://noosfero>
-    BalancerMember http://127.0.0.1:3000
-    BalancerMember http://127.0.0.1:3001
-    Order Allow,Deny
-    Allow from All
-  </Proxy>
+      Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf
-The cache.conf file included in the end of the <VirtualHost> section is
-important, since it will tell apache to pass expiration and cache headers to
-clients so that the site feels faster for users. Do we need to say that using
-that configuration is strongly recommended?
+    </VirtualHost>
-Enable that site with (as root, replace "mysite" with the actual name you gave
-to your site configuration):
+    <Proxy balancer://noosfero>
+      BalancerMember http://127.0.0.1:3000
+      BalancerMember http://127.0.0.1:3001
+      Order Allow,Deny
+      Allow from All
+    </Proxy>
-# a2ensite mysite
+The cache.conf file included in the end of the <VirtualHost> section is important, since it will tell apache to pass expiration and cache headers to clients so that the site feels faster for users. Do we need to say that using that configuration is strongly recommended?
+
+Enable that site with (as root, replace "mysite" with the actual name you gave to your site configuration):
+
+    # a2ensite mysite
 Now restart your apache server (as root):
-# invoke-rc.d apache2 restart
+    # invoke-rc.d apache2 restart
 Enabling exception notifications
 ================================
-This is an optional step. You will need it only if you want to receive e-mail
-notifications when some exception occurs on Noosfero.
+This is an optional step. You will need it only if you want to receive e-mail notifications when some exception occurs on Noosfero.
-First, install this version of the gem.
-Others versions may not be compatible with Noosfero:
+First, install this version of the gem. Others versions may not be compatible with Noosfero:
-# gem install exception_notification -v 1.0.20090728
+    # gem install exception_notification -v 1.0.20090728
-You can configure the e-mails that will receive the notifications.
-Change the file config/noosfero.yml as the following example, replacing the
-e-mails by real ones:
+You can configure the e-mails that will receive the notifications. Change the file config/noosfero.yml as the following example, replacing the e-mails by real ones:
-  production:
-    exception_recipients: [admin@example.com, you@example.com]
+    production:
+      exception_recipients: [admin@example.com, you@example.com]
-============
 Maintainance
 ============
-To ease the maintainance, install a symbolic link for the Noosfero startup
-script in your server and add it to the system initialization and shutdown
-sequences (as root):
-
-# ln -s /var/lib/noosfero/current/etc/init.d/noosfero /etc/init.d/noosfero
-# update-rc.d noosfero defaults
- Adding system startup for /etc/init.d/noosfero ...
-   /etc/rc0.d/K20noosfero -> ../init.d/noosfero
-   /etc/rc1.d/K20noosfero -> ../init.d/noosfero
-   /etc/rc6.d/K20noosfero -> ../init.d/noosfero
-   /etc/rc2.d/S20noosfero -> ../init.d/noosfero
-   /etc/rc3.d/S20noosfero -> ../init.d/noosfero
-   /etc/rc4.d/S20noosfero -> ../init.d/noosfero
-   /etc/rc5.d/S20noosfero -> ../init.d/noosfero
+To ease the maintainance, install a symbolic link for the Noosfero startup script in your server and add it to the system initialization and shutdown sequences (as root):
+
+    # ln -s /var/lib/noosfero/current/etc/init.d/noosfero /etc/init.d/noosfero
+    # update-rc.d noosfero defaults
+     Adding system startup for /etc/init.d/noosfero ...
+       /etc/rc0.d/K20noosfero -> ../init.d/noosfero
+       /etc/rc1.d/K20noosfero -> ../init.d/noosfero
+       /etc/rc6.d/K20noosfero -> ../init.d/noosfero
+       /etc/rc2.d/S20noosfero -> ../init.d/noosfero
+       /etc/rc3.d/S20noosfero -> ../init.d/noosfero
+       /etc/rc4.d/S20noosfero -> ../init.d/noosfero
+       /etc/rc5.d/S20noosfero -> ../init.d/noosfero
 Now to start Noosfero, you do as root:
-# invoke-rc.d noosfero start
+    # invoke-rc.d noosfero start
 To stop Noosfero:
-# invoke-rc.d noosfero start
+    # invoke-rc.d noosfero start
 To restart Noosfero:
-# invoke-rc.d noosfero restart
+    # invoke-rc.d noosfero restart
-Noosfero will be automatically started during system boot, and automatically
-stopped if the system shuts down for some reason (or during the shutdown part
-of a reboot).
+Noosfero will be automatically started during system boot, and automatically stopped if the system shuts down for some reason (or during the shutdown part of a reboot).
-=============
 Rotating logs
 =============
-Noosfero provides an example logrotate configuation to rotate its logs. To use
-it, create a symbolic link in /etc/logrotate.d/:
+Noosfero provides an example logrotate configuation to rotate its logs. To use it, create a symbolic link in `/etc/logrotate.d/`:
-# cd /etc/logrotate.d/
-# ln -s /var/lib/noosfero/current/etc/logrotate.d/noosfero
+    # cd /etc/logrotate.d/
+    # ln -s /var/lib/noosfero/current/etc/logrotate.d/noosfero
-Note that the provided file assumes Noosfero logging is being done in
-/var/log/noosfero (which is the case if you followed the instructions above
-correctly). If the logs are stored elsewhere, it's recommended that you copy
-the file over to /etc/logrotate.d/ and modify it to point to your local log
-directly.
+Note that the provided file assumes Noosfero logging is being done in `/var/log/noosfero` (which is the case if you followed the instructions above correctly). If the logs are stored elsewhere, it's recommended that you copy the file over to `/etc/logrotate.d/` and modify it to point to your local log directly.
-=========
 Upgrading
 =========
-If you followed the steps in this document and installed Noosfero from the git
-repository, then upgrading is easy. First, you need to allow the noosfero user
-to restart the memcached server with sudo, by adding the following line in
-/etc/sudoers:
+If you followed the steps in this document and installed Noosfero from the git repository, then upgrading is easy. First, you need to allow the noosfero user to restart the memcached server with sudo, by adding the following line in `/etc/sudoers`:
-noosfero ALL=NOPASSWD: /etc/init.d/memcached
+    noosfero ALL=NOPASSWD: /etc/init.d/memcached
 Then, to perform an upgrade, do the following as the noosfero user:
-$ cd /var/lib/noosfero/current
-$ ./script/git-upgrade
+    $ cd /var/lib/noosfero/current
+    $ ./script/git-upgrade
-The git-upgrade script will take care of everything for you. It will first stop
-the service, then fetch the current source code, upgrade database, compile
-translations, and then start the service again.
+The `git-upgrade` script will take care of everything for you. It will first stop the service, then fetch the current source code, upgrade database, compile translations, and then start the service again.
-Note 1: make sure your local git repository is following the "stable" branch,
-just like the instructions above. The "master" branch is not recommended for
-use in production environments.
+*Note 1*: make sure your local git repository is following the "stable" branch, just like the instructions above. The `master` branch is **not** recommended for use in production environments.
-Note 2: always read the release notes before upgrading. Sometimes there will be
-steps that must be performed manually. If that is the case, you can invoke the
-git-upgrade script with the special parameter "--shell" that will give you a
-shell after the upgrade, which you can use to perform any manual steps
-required:
+*Note 2*: always read the release notes before upgrading. Sometimes there will be steps that must be performed manually. If that is the case, you can invoke the `git-upgrade` script with the special parameter `--shell` that will give you a shell after the upgrade, which you can use to perform any manual steps required:
-$ ./script/git-upgrade --shell
+    $ ./script/git-upgrade --shell
-== Multitenancy support
+Multitenancy support
+====================
-Multitenancy refers to a principle in software architecture where a
-single instance of the software runs on a server, serving multiple
-client organizations (tenants). Multitenancy is contrasted with a
-multi-instance architecture where separate software instances (or
-hardware systems) are set up for different client organizations. With
-a multitenant architecture, a software application is designed to
-virtually partition its data and configuration, and each client
-organization works with a customized virtual application instance.
+Multitenancy refers to a principle in software architecture where a single instance of the software runs on a server, serving multiple client organizations (tenants). Multitenancy is contrasted with a multi-instance architecture where separate software instances (or hardware systems) are set up for different client organizations. With a multitenant architecture, a software application is designed to virtually partition its data and configuration, and each client organization works with a customized virtual application instance.
 Today this feature is available only for PostgreSQL databases.
-This document assumes that you have a new fully PostgresSQL default Noosfero
-installation as explained at the INSTALL file.
+This document assumes that you have a new fully PostgresSQL default Noosfero installation as explained at the `INSTALL.md` file.
-== Separated data
+Separated data
+--------------
 The items below are separated for each hosted environment:
@@ -25,139 +19,115 @@ The items below are separated for each hosted environment:
 * Feed updater
 * Delayed Job Workers
-== Database configuration file
+Database configuration file
+---------------------------
-The file config/database.yml must follow a structure in order to
-achieve multitenancy support. In this example, we will set 3
-different environments: env1, env2 and env3.
+The file config/database.yml must follow a structure in order to achieve multitenancy support. In this example, we will set 3 different environments: env1, env2 and env3.
 Each "hosted" environment must have an entry like this:
-env1_production:
-  adapter: postgresql
-  encoding: unicode
-  database: noosfero
-  schema_search_path: public
-  username: noosfero
-  domains:
-    - env1.com
-    - env1.org
-
-env2_production:
-  adapter: postgresql
-  encoding: unicode
-  database: noosfero
-  schema_search_path: env2
-  username: noosfero
-  domains:
-    - env2.com
-    - env2.org
-
-env3_production:
-  adapter: postgresql
-  encoding: unicode
-  database: noosfero
-  schema_search_path: env3
-  username: noosfero
-  domains:
-    - env3.com
-    - env3.net
-
-The "hosted" environments define, besides the schema_search_path, a
-list of domains that, when accessed, tells which database the
-application should use. Also, the environment name must end with
-'_hosting', where 'hosting' is the name of the hosting environment.
+    env1_production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero
+      schema_search_path: public
+      username: noosfero
+      domains:
+        - env1.com
+        - env1.org
+
+    env2_production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero
+      schema_search_path: env2
+      username: noosfero
+      domains:
+        - env2.com
+        - env2.org
+
+    env3_production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero
+      schema_search_path: env3
+      username: noosfero
+      domains:
+        - env3.com
+        - env3.net
+
+The "hosted" environments define, besides the `schema_search_path`, a list of domains that, when accessed, tells which database the application should use. Also, the environment name must end with "`_<hosting>`", where `<hosting>` is the name of the hosting environment.
 You must also tell the application which is the default environment.
-production:
-  env1_production
+    production:
+      env1_production
-On the example above there are only three hosted environments, but it
-can be more than three. The schemas 'env2' and 'env3' must already
-exist in the same database of the hosting environment. As postgres
-user, you can create them typing:
+On the example above there are only three hosted environments, but it can be more than three. The schemas `env2` and `env3` must already exist in the same database of the hosting environment. As postgres user, you can create them typing:
-$ psql database_name -c "CREATE SCHEMA env2 AUTHORIZATION database_user"
-$ psql database_name -c "CREATE SCHEMA env3 AUTHORIZATION database_user"
+    $ psql database_name -c "CREATE SCHEMA env2 AUTHORIZATION database_user"
+    $ psql database_name -c "CREATE SCHEMA env3 AUTHORIZATION database_user"
-Replace database_name and database_user above with your stuff.
+Replace `database_name` and `database_user` above with your stuff.
-So, yet on this same example, when a user accesses http://env2.com or
-http://env2.org, the Noosfero application running on production will
-turn the database schema to 'env2'. When the access is from domains
-http://env3.com or http://env3.net, the schema to be loaded will be
-'env3'.
+So, yet on this same example, when a user accesses http://env2.com or http://env2.org, the Noosfero application running on production will turn the database schema to `env2`. When the access is from domains http://env3.com or http://env3.net, the schema to be loaded will be `env3`.
-There is an example of this file in config/database.yml.multitenancy
+There is an example of this file in `config/database.yml.multitenancy`
-== Preparing the database
+Preparing the database
+----------------------
 Now create the environments:
-$ RAILS_ENV=production rake multitenancy:create
+    $ RAILS_ENV=production rake multitenancy:create
-This command above will create the hosted environment files equal to
-their hosting environment, here called 'production'.
+This command above will create the hosted environment files equal to their hosting environment, here called 'production'.
 Run db:schema:load for each other environment:
-$ RAILS_ENV=env2_production rake db:schema:load
-$ RAILS_ENV=env3_production rake db:schema:load
+    $ RAILS_ENV=env2_production rake db:schema:load
+    $ RAILS_ENV=env3_production rake db:schema:load
-Then run the migrations for the hosting environment, and it will
-run for each of its hosted environments:
+Then run the migrations for the hosting environment, and it will run for each of its hosted environments:
-RAILS_ENV=production rake db:migrate
+    RAILS_ENV=production rake db:migrate
-== Start Noosfero
+Start Noosfero
+--------------
 Run Noosfero init file as root:
-# invoke-rc.d noosfero start
+    # invoke-rc.d noosfero start
-== Solr
+Feed updater & Delayed job
+--------------------------
-It's necessary to run only one instance of Solr. Don't worry
-about this, Noosfero initializer had already done this for you.
+Just for your information, a daemon of `feed-updater` and `delayed_job` must be running for each environment. Noosfero initializer do this, relax.
-== Feed updater & Delayed job
+Uploaded files
+--------------
-Just for your information, a daemon of feed-updater and delayed_job
-must be running for each environment. Noosfero initializer do this,
-relax.
+When running with PostgreSQL, Noosfero uploads stuff to a folder named the same way as the running schema. Inside the upload folder root, for example, will be `public/image_uploads/env2` and `public/image_uploads/env3`.
-== Uploaded files
+Adding multitenancy support to an existing Noosfero environment
+---------------------------------------------------------------
-When running with PostgreSQL, Noosfero uploads stuff to a folder named
-the same way as the running schema. Inside the upload folder root, for
-example, will be public/image_uploads/env2 and public/image_uploads/env3.
+If you already have a Noosfero environment, you can turn it multitenant by following the steps below in addition to the previous steps:
-== Adding multitenancy support to an existing Noosfero environment
+### 1. Reindex your database
-If you already have a Noosfero environment, you can turn it multitenant
-by following the steps below in addition to the previous steps:
+Rebuild the Solr index by running the following task just for your hosting environment, do this as noosfero user:
-1. Reindex your database
+    $ RAILS_ENV=production rake multitenancy:reindex
-Rebuild the Solr index by running the following task just
-for your hosting environment, do this as noosfero user:
+### 2. Move the uploaded files to the right place
-$ RAILS_ENV=production rake multitenancy:reindex
+Add a directory with the same name as your schema name (by default this name is `public`) in the root of each upload directory, for example, `public/articles/0000` will be moved to `public/articles/public/0000`. Do this with the directories `public/image_uploads`, `public/articles` and `public/thumbnails`.
-2. Move the uploaded files to the right place
+### 3. Fix paths on activities
-Add a directory with the same name as your schema name (by default this
-name is 'public') in the root of each upload directory, for example,
-public/articles/0000 will be moved to public/articles/public/0000. Do this
-with the directories public/image_uploads, public/articles and public/thumbnails.
+The profile activities store static paths to the images, so it's necessary to fix these paths. You can do this easily by setting an alias on your webserver. On Apache you can add the three rules below, where 'public' is the schema name:
-3. Fix paths on activities
-
-The profile activities store static paths to the images, so it's necessary to fix
-these paths. You can do this easily by setting an alias on your webserver.
-On Apache you can add the three rules below, where 'public' is the schema name:
-
-  RewriteRule ^/articles(.+) /articles/public$1
-  RewriteRule ^/image_uploads(.+) /image_uploads/public$1
-  RewriteRule ^/thumbnails(.+) /thumbnails/public$1
+    RewriteRule ^/articles(.+) /articles/public$1
+    RewriteRule ^/image_uploads(.+) /image_uploads/public$1
+    RewriteRule ^/thumbnails(.+) /thumbnails/public$1
-= Setting up Varnish for your Noosfero site
+Setting up Varnish for your Noosfero site
+=========================================
-Varnish is a HTTP caching server, and using it together with Noosfero is highly
-recommended. See http://www.varnish-cache.org/ for more information on Varnish.
+Varnish is a HTTP caching server, and using it together with Noosfero is highly recommended. See http://www.varnish-cache.org/ for more information on Varnish.
 Varnish can be set up to use with Noosfero with the following steps:
-1) setup Noosfero with apache according to the INSTALL file. If you used the
-Debian package to install noosfero, you don't need to do anything about this.
+1) setup Noosfero with apache according to the `INSTALL.md` file. If you used the Debian package to install noosfero, you don't need to do anything about this.
 2) install Varnish
-  # apt-get install varnish
+    # apt-get install varnish
 Install the RPAF apache module (or skip this step if not using apache):
-  # apt-get install libapache2-mod-rpaf
+    # apt-get install libapache2-mod-rpaf
-3) Change Apache to listen on port 8080 instead of 80
+3) Change Apache to listen on port `8080` instead of `80`
-3a) Edit /etc/apache2/ports.conf, and:
+3a) Edit `/etc/apache2/ports.conf`, and:
-  * change 'NameVirtualHost *:80' to 'NameVirtualHost *:8080'
-  * change 'Listen 80' to 'Listen 127.0.0.1:8080'
+  * change `NameVirtualHost *:80` to `NameVirtualHost *:8080`
+  * change `Listen 80` to `Listen 127.0.0.1:8080`
-3b) Edit /etc/apache2/sites-enabled/*, and change '<VirtualHost *:80>' to
-'<VirtualHost *:8080>'
+3b) Edit `/etc/apache2/sites-enabled/*`, and change `<VirtualHost *:80>` to `<VirtualHost *:8080>`
 3c) Restart apache
-  # invoke-rc.d apache2 restart
+    # invoke-rc.d apache2 restart
 4) Varnish configuration
-4a) Edit /etc/default/varnish
+4a) Edit `/etc/default/varnish`
-   * change the line that says "START=no" to say "START=yes"
-   * change '-a :6081' to '-a :80'
+   * change the line that says `START=no` to say `START=yes`
+   * change `-a :6081` to `-a :80`
-4b) Edit /etc/varnish/default.vcl and add the following lines at the end:
+4b) Edit `/etc/varnish/default.vcl` and add the following lines at the end:
-  include "/etc/noosfero/varnish-noosfero.vcl";
-  include "/etc/noosfero/varnish-accept-language.vcl";
+    include "/etc/noosfero/varnish-noosfero.vcl";
+    include "/etc/noosfero/varnish-accept-language.vcl";
-On manual installations, change "/etc/noosfero/*" to
-"{Rails.root}/etc/noosfero/*"
+On manual installations, change `/etc/noosfero/*` to `{Rails.root}/etc/noosfero/*`
-NOTE: it is very important that the *.vcl files are included in that order,
-i.e. *first* include "varnish-noosfero.vcl", and *after*
-"noosfero-accept-language.cvl".
+**NOTE**: it is very important that the `*.vcl` files are included in that order, i.e. *first* include `varnish-noosfero.vcl`, and *after* `noosfero-accept-language.cvl`.
 4c) Restart Varnish
-  # invoke-rc.d varnish restart
+    # invoke-rc.d varnish restart
 5) Enable varnish logging:
-5a) Edit /etc/default/varnishncsa and uncomment the line that contains:
+5a) Edit `/etc/default/varnishncsa` and uncomment the line that contains:
-VARNISHNCSA_ENABLED=1
+    VARNISHNCSA_ENABLED=1
-The varnish log will be written to /var/log/varnish/varnishncsa.log in an
-apache-compatible format. You should change your statistics generation software
-(e.g. awstats) to use that instead of apache logs.
+The varnish log will be written to `/var/log/varnish/varnishncsa.log` in an apache-compatible format. You should change your statistics generation software (e.g. awstats) to use that instead of apache logs.
 5b) Restart Varnish Logging service
-  # invoke-rc.d varnishncsa restart
+    # invoke-rc.d varnishncsa restart
-Thanks to Cosimo Streppone for varnish-accept-language. See
-http://github.com/cosimo/varnish-accept-language for more information.
+Thanks to Cosimo Streppone for varnish-accept-language. See http://github.com/cosimo/varnish-accept-language for more information.
 Noosfero - a web-based social platform
 ======================================
-http://www.noosfero.org/
+http://www.noosfero.org
 Documentation
 -------------
 The following documentation is available:
-File                  Purpose
-~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-INSTALL               install instructions
-INSTALL.awstats       install instructions - access statistics service
-INSTALL.chat          install instructions - chat service
-INSTALL.email         install instructions - email service
-INSTALL.multitenancy  install instructions - multiple sites
-INSTALL.varnish       install instructions - varnish HTTP caching (recommended)
-HACKING               development instruction
-RELEASING             instructions for doing releases
-doc/noosfero/*        user documentation (available through the app itself)
+    File                     Purpose
+    -----------------------  --------------------------------------------------------
+    INSTALL.md               install instructions
+    INSTALL.awstats.md       install instructions - access statistics service
+    INSTALL.chat.md          install instructions - chat service
+    INSTALL.email.md         install instructions - email service
+    INSTALL.multitenancy.md  install instructions - multiple sites
+    INSTALL.varnish.md       install instructions - varnish HTTP caching (recommended)
+    HACKING.md               development instruction
+    RELEASING.md             instructions for doing releases
+    doc/noosfero/*           user documentation (available through the app itself)
 Authors and copyright
@@ -26,8 +26,8 @@ Authors and copyright
 Authorship and copyright information is available in the files listed below.
-File                  Purpose
-~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-AUTHORS               list of authors (updated at each release)
-COPYRIGHT             Copyright statement for the project
-COPYING               Full text of the project license
+    File                  Purpose
+    --------------------  -----------------------------------------
+    AUTHORS.md            list of authors (updated at each release)
+    COPYRIGHT             Copyright statement for the project
+    COPYING               Full text of the project license
-== Welcome to Rails
-
-Rails is a web-application and persistence framework that includes everything
-needed to create database-backed web-applications according to the
-Model-View-Control pattern of separation. This pattern splits the view (also
-called the presentation) into "dumb" templates that are primarily responsible
-for inserting pre-built data in between HTML tags. The model contains the
-"smart" domain objects (such as Account, Product, Person, Post) that holds all
-the business logic and knows how to persist themselves to a database. The
-controller handles the incoming requests (such as Save New Account, Update
-Product, Show Post) by manipulating the model and directing data to the view.
-
-In Rails, the model is handled by what's called an object-relational mapping
-layer entitled Active Record. This layer allows you to present the data from
-database rows as objects and embellish these data objects with business logic
-methods. You can read more about Active Record in 
-link:files/vendor/rails/activerecord/README.html.
-
-The controller and view are handled by the Action Pack, which handles both
-layers by its two parts: Action View and Action Controller. These two layers
-are bundled in a single package due to their heavy interdependence. This is
-unlike the relationship between the Active Record and Action Pack that is much
-more separate. Each of these packages can be used independently outside of
-Rails.  You can read more about Action Pack in 
-link:files/vendor/rails/actionpack/README.html.
-
-
-== Getting started
-
-1. Start the web server: <tt>ruby script/server</tt> (run with --help for options)
-2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
-3. Follow the guidelines to start developing your application
+Welcome to Rails
+================
+Rails is a web-application and persistence framework that includes everything needed to create database-backed web-applications according to the Model-View-Control pattern of separation. This pattern splits the view (also called the presentation) into "dumb" templates that are primarily responsible for inserting pre-built data in between HTML tags. The model contains the "smart" domain objects (such as Account, Product, Person, Post) that holds all the business logic and knows how to persist themselves to a database. The controller handles the incoming requests (such as Save New Account, Update Product, Show Post) by manipulating the model and directing data to the view.
-== Web servers
+In Rails, the model is handled by what's called an object-relational mapping layer entitled Active Record. This layer allows you to present the data from database rows as objects and embellish these data objects with business logic methods. You can read more about Active Record in `.../rails/activerecord/README.html`.
-Rails uses the built-in web server in Ruby called WEBrick by default, so you don't
-have to install or configure anything to play around. 
+The controller and view are handled by the Action Pack, which handles both layers by its two parts: Action View and Action Controller. These two layers are bundled in a single package due to their heavy interdependence. This is unlike the relationship between the Active Record and Action Pack that is much more separate. Each of these packages can be used independently outside of Rails. You can read more about Action Pack in `.../rails/actionpack/README.html`.
-If you have lighttpd installed, though, it'll be used instead when running script/server.
-It's considerably faster than WEBrick and suited for production use, but requires additional
-installation and currently only works well on OS X/Unix (Windows users are encouraged
-to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from
-http://www.lighttpd.net.
-If you want something that's halfway between WEBrick and lighttpd, we heartily recommend
-Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that
-also works very well with Windows. See more at http://mongrel.rubyforge.org/.
+Getting started
+---------------
-But of course its also possible to run Rails with the premiere open source web server Apache.
-To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want
-to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
+1. Start the web server: `ruby script/server` (run with `--help` for options)
+2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
+3. Follow the guidelines to start developing your application
-See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
+Web servers
+-----------
-== Example for Apache conf
+Rails uses the built-in web server in Ruby called WEBrick by default, so you don't have to install or configure anything to play around. 
-  <VirtualHost *:80>
-    ServerName rails
-    DocumentRoot /path/application/public/
-    ErrorLog /path/application/log/server.log
-  
-    <Directory /path/application/public/>
-      Options ExecCGI FollowSymLinks
-      AllowOverride all
-      Allow from all
-      Order allow,deny
-    </Directory>
-  </VirtualHost>
+If you have lighttpd installed, though, it'll be used instead when running script/server. It's considerably faster than WEBrick and suited for production use, but requires additional installation and currently only works well on OS X/Unix (Windows users are encouraged to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from http://www.lighttpd.net.
-NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI
-should be on and ".cgi" should respond. All requests from 127.0.0.1 go
-through CGI, so no Apache restart is necessary for changes. All other requests
-go through FCGI (or mod_ruby), which requires a restart to show changes.
+If you want something that's halfway between WEBrick and lighttpd, we heartily recommend Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that also works very well with Windows. See more at http://mongrel.rubyforge.org/.
+But of course its also possible to run Rails with the premiere open source web server Apache. To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
-== Debugging Rails
+See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
-Have "tail -f" commands running on both the server.log, production.log, and
-test.log files. Rails will automatically display debugging and runtime
-information to these files. Debugging info will also be shown in the browser
-on requests from 127.0.0.1.
+Example for Apache conf
+-----------------------
+    <VirtualHost *:80>
+      ServerName rails
+      DocumentRoot /path/application/public/
+      ErrorLog /path/application/log/server.log
+    
+      <Directory /path/application/public/>
+        Options ExecCGI FollowSymLinks
+        AllowOverride all
+        Allow from all
+        Order allow,deny
+      </Directory>
+    </VirtualHost>
-== Breakpoints
+NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI should be on and ".cgi" should respond. All requests from 127.0.0.1 go through CGI, so no Apache restart is necessary for changes. All other requests go through FCGI (or mod_ruby), which requires a restart to show changes.
-Breakpoint support is available through the script/breakpointer client. This
-means that you can break out of execution at any point in the code, investigate
-and change the model, AND then resume execution! Example:
+Debugging Rails
+---------------
-  class WeblogController < ActionController::Base
-    def index
-      @posts = Post.find_all
-      breakpoint "Breaking out from the list"
+Have "tail -f" commands running on both the server.log, production.log, and test.log files. Rails will automatically display debugging and runtime information to these files. Debugging info will also be shown in the browser on requests from 127.0.0.1.
+
+Breakpoints
+-----------
+
+Breakpoint support is available through the script/breakpointer client. This means that you can break out of execution at any point in the code, investigate and change the model, AND then resume execution! Example:
+
+    class WeblogController < ActionController::Base
+      def index
+        @posts = Post.find_all
+        breakpoint "Breaking out from the list"
+      end
     end
-  end
-So the controller will accept the action, run the first line, then present you
-with a IRB prompt in the breakpointer window. Here you can do things like:
+So the controller will accept the action, run the first line, then present you with a IRB prompt in the breakpointer window. Here you can do things like:
 Executing breakpoint "Breaking out from the list" at .../webrick_server.rb:16 in 'breakpoint'
-  >> @posts.inspect
-  => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, 
-       #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
-  >> @posts.first.title = "hello from a breakpoint"
-  => "hello from a breakpoint"
+    >> @posts.inspect
+    => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, 
+         #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
+    >> @posts.first.title = "hello from a breakpoint"
+    => "hello from a breakpoint"
 ...and even better is that you can examine how your runtime objects actually work:
-  >> f = @posts.first 
-  => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
-  >> f.
-  Display all 152 possibilities? (y or n)
+    >> f = @posts.first 
+    => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
+    >> f.
+    Display all 152 possibilities? (y or n)
 Finally, when you're ready to resume execution, you press CTRL-D
+Console
+-------
-== Console
-
-You can interact with the domain model by starting the console through script/console. 
-Here you'll have all parts of the application configured, just like it is when the
-application is running. You can inspect domain models, change values, and save to the
-database. Starting the script without arguments will launch it in the development environment.
-Passing an argument will specify a different environment, like <tt>script/console production</tt>.
+You can interact with the domain model by starting the console through script/console. Here you'll have all parts of the application configured, just like it is when the application is running. You can inspect domain models, change values, and save to the database. Starting the script without arguments will launch it in the development environment. Passing an argument will specify a different environment, like `script/console production`.
-To reload your controllers and models after launching the console run <tt>reload!</tt>
+To reload your controllers and models after launching the console run `reload!`
+Description of contents
+-----------------------
-
-== Description of contents
-
-app
+* `app`
   Holds all the code that's specific to this particular application.
-app/controllers
-  Holds controllers that should be named like weblog_controller.rb for
-  automated URL mapping. All controllers should descend from
-  ActionController::Base.
+* `app/controllers`
+  Holds controllers that should be named like weblog_controller.rb for automated URL mapping. All controllers should descend from `ActionController::Base`.
-app/models
-  Holds models that should be named like post.rb.
-  Most models will descend from ActiveRecord::Base.
+* `app/models`
+  Holds models that should be named like post.rb. Most models will descend from `ActiveRecord::Base`.
-app/views
-  Holds the template files for the view that should be named like
-  weblog/index.rhtml for the WeblogController#index action. All views use eRuby
-  syntax. This directory can also be used to keep stylesheets, images, and so on
-  that can be symlinked to public.
+* `app/views`
+  Holds the template files for the view that should be named like `weblog/index.rhtml` for the `WeblogController#index` action. All views use eRuby syntax. This directory can also be used to keep stylesheets, images, and so on that can be symlinked to public.
-app/helpers
-  Holds view helpers that should be named like weblog_helper.rb.
+* `app/helpers`
+  Holds view helpers that should be named like `weblog_helper.rb`.
-app/apis
+* `app/apis`
   Holds API classes for web services.
-config
+* `config`
   Configuration files for the Rails environment, the routing map, the database, and other dependencies.
-components
+* `components`
   Self-contained mini-applications that can bundle together controllers, models, and views.
-db
-  Contains the database schema in schema.rb.  db/migrate contains all
-  the sequence of Migrations for your schema.
+* `db`
+  Contains the database schema in `schema.rb`.
+
+* `db/migrate`
+  Contains all the sequence of Migrations for your schema.
-lib
-  Application specific libraries. Basically, any kind of custom code that doesn't
-  belong under controllers, models, or helpers. This directory is in the load path.
+* `lib`
+  Application specific libraries. Basically, any kind of custom code that doesn't belong under controllers, models, or helpers. This directory is in the load path.
-public
-  The directory available for the web server. Contains subdirectories for images, stylesheets,
-  and javascripts. Also contains the dispatchers and the default HTML files.
+* `public`
+  The directory available for the web server. Contains subdirectories for images, stylesheets, and javascripts. Also contains the dispatchers and the default HTML files.
-script
+* `script`
   Helper scripts for automation and generation.
-test
+* `test`
   Unit and functional tests along with fixtures.
-vendor
-  External libraries that the application depends on. Also includes the plugins subdirectory.
-  This directory is in the load path.
+* `vendor`
+  External libraries that the application depends on. Also includes the plugins subdirectory. This directory is in the load path.
-= Noosfero release tasks
+Noosfero release tasks
+======================
 This file documents release-related activities.
-== Working with translations
+Working with translations
+-------------------------
-* Update translation files: <tt>rake updatepo</tt>. Then <tt>git commit</tt> them.
+* Update translation files: `rake updatepo`. Then `git commit` them.
 * Send the PO files to the translators.
-* Get the PO files back from translators, put in po/ under the correct language
-  name (e.,g. po/pt_BR/) and <tt>git commit</tt>.
-* test translations: <tt>rake makemo</tt> and browse the application on the web.
+* Get the PO files back from translators, put in `po/` under the correct language name (e.,g. `po/pt_BR/`) and `git commit`.
+* test translations: `rake makemo` and browse the application on the web.
-== Releasing noosfero
+Releasing noosfero
+------------------
 Considering you are on a Debian GNU/Linux or Debian-based system
- # apt-get install devscripts debhelper
+
+    # apt-get install devscripts debhelper
 To prepare a release of noosfero, you must follow the steps below:
 * Finish all requirements and bugs assigned to the to-be-released version
 * Make sure all tests pass
 * Write release notes at the version's wiki topic
-* Generate packages with <tt>rake noosfero:release[(stable|test)]</tt>. This task will:
+* Generate packages with `rake noosfero:release[(stable|test)]`. This task will:
   * Update the version in lib/noosfero.rb and debian/changelog.
   * Create the tarbal and the deb pkg under pkg/ directory.
   * Create a git tag and push it.
@@ -28,13 +31,9 @@ To prepare a release of noosfero, you must follow the steps below:
 * Test that the tarball and deb package are ok
 * Go to the version's wiki topic and edit it to reflect the new reality
 * Edit the topic WebPreferences and update DEBIAN_REPOSITORY_TOPICS setting
-* Attach the generated packages to that topic. Before attaching calculate the
-  sha1 of the package (with sha1sum and paste the SHA1 hash as comment in the
-  attachment form)
+* Attach the generated packages to that topic. Before attaching calculate the sha1 of the package (with sha1sum and paste the SHA1 hash as comment in the attachment form)
 * Download the attached and verify the MD5 hash
 * Update an eventual demonstration version that you run.
-* Write an announcement e-mail to the relevant mailing lists pointing to the
-  release notes, and maybe to the demonstration version.
+* Write an announcement e-mail to the relevant mailing lists pointing to the release notes, and maybe to the demonstration version.
-If you had any problem during these steps, you can do <tt>rake clobber_package</tt> to
-completely delete the generated packages and start the process again.
+If you had any problem during these steps, you can do `rake clobber_package` to completely delete the generated packages and start the process again.
 README - AntiSpam (AntiSpam Plugin)
-=======================================
+===================================
-Plugin that checks comments against a spam checking service compatible
-with the Akismet API.
+Plugin that checks comments against a spam checking service compatible with the Akismet API.
 Enable Plugin
@@ -10,12 +9,12 @@ Enable Plugin
 Also, you need to enable AntiSpam Plugin at your Noosfero:
-cd <your_noosfero_dir>
-./script/noosfero-plugins enable anti_spam
+    cd <your_noosfero_dir>
+    ./script/noosfero-plugins enable anti_spam
 Activate Plugin
--------------
+---------------
 As a Noosfero administrator user, go to administrator panel:
1	-If you are not listed here, but should be, please write to the noosfero mailing
2	-list: http://listas.softwarelivre.org/cgi-bin/mailman/listinfo/noosfero-dev
3	-(this list requires subscription to post, but since you are an author of
4	-noosfero, that's not a problem).	1	+If you are not listed here, but should be, please write to the noosfero mailing list: http://listas.softwarelivre.org/cgi-bin/mailman/listinfo/noosfero-dev (this list requires subscription to post, but since you are an author of noosfero, that's not a problem).
5		2
6	Developers	3	Developers
7	==========	4	==========
1	-= Noosfero email setup	1	+Noosfero email setup
		2	+====================
2		3
3	-If you know mail systems well, you just need to make sure that the local MTA,
4	-listening on localhost:25, is able to deliver e-mails to the internet. Any mail
5	-server will do it. You can stop reading now.	4	+If you know mail systems well, you just need to make sure that the local MTA, listening on localhost:25, is able to deliver e-mails to the internet. Any mail server will do it. You can stop reading now.
6		5
7	-If you are not an email specialist, then follow the instructions below. We
8	-suggest that you use the Postfix mail server, since it is easy to configure and
9	-very reliable. Just follow the instructions below.	6	+If you are not an email specialist, then follow the instructions below. We suggest that you use the Postfix mail server, since it is easy to configure and very reliable. Just follow the instructions below.
10		7
11	To install Postfix:	8	To install Postfix:
12		9
13	-# apt-get install postfix	10	+ # apt-get install postfix
14		11
15	-During the installation process, you will be asked a few questions. Your answer
16	-to them will vary in 2 cases:	12	+During the installation process, you will be asked a few questions. Your answer to them will vary in 2 cases:
17		13
18	-Case 1: you can send e-mails directly to the internet. This will be the case
19	-for most commercial private servers. Your answers should be:	14	+Case 1: you can send e-mails directly to the internet. This will be the case for most commercial private servers. Your answers should be:
20		15
21	- General type of mail configuration: Internet site
22	- System mail name: the name of your domain, e.g. "mysocialnetwork.com"	16	+ * General type of mail configuration: Internet site
		17	+ * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
23		18
24	-Case 2: you cannot, or don't want to, send e-mail directly to the internet.
25	-This happens for example if your server is not allowed to make outbound
26	-connections on port 25, or if you want to concentrate all your outbound mail
27	-through a single SMTP server. Your answers in this case should be:	19	+Case 2: you cannot, or don't want to, send e-mail directly to the internet. This happens for example if your server is not allowed to make outbound connections on port 25, or if you want to concentrate all your outbound mail through a single SMTP server. Your answers in this case should be:
28		20
29	- General type of mail configuration: Internet with smarthost
30	- System mail name: the name of your domain, e.g. "mysocialnetwork.com"
31	- SMTP relay host: smtp.yourprovider.com	21	+ * General type of mail configuration: Internet with smarthost
		22	+ * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
		23	+ * SMTP relay host: smtp.yourprovider.com
32		24
33	-Note that smtp.yourprovider.com must allow your server to deliver e-mails
34	-through it. You should probably ask your servive provider about this.	25	+Note that smtp.yourprovider.com must allow your server to deliver e-mails through it. You should probably ask your servive provider about this.
35		26
36	-There is another possibility: if you are installing on a shared server, and
37	-don't have permission to configure the local MTA, you can instruct Noosfero to
38	-send e-mails directly through an external server. Please note that this should
39	-be your last option, since contacting an external SMTP server directly may slow
40	-down your Noosfero application server. To configure Noosfero to send e-mails
41	-through an external SMTP server, follow the instructions on
42	-http://noosfero.org/Development/SMTPMailSending	27	+There is another possibility: if you are installing on a shared server, and don't have permission to configure the local MTA, you can instruct Noosfero to send e-mails directly through an external server. Please note that this should be your last option, since contacting an external SMTP server directly may slow down your Noosfero application server. To configure Noosfero to send e-mails through an external SMTP server, follow the instructions on http://noosfero.org/Development/SMTPMailSending
43		28
1	-= Setting up Varnish for your Noosfero site	1	+Setting up Varnish for your Noosfero site
		2	+=========================================
2		3
3	-Varnish is a HTTP caching server, and using it together with Noosfero is highly
4	-recommended. See http://www.varnish-cache.org/ for more information on Varnish.	4	+Varnish is a HTTP caching server, and using it together with Noosfero is highly recommended. See http://www.varnish-cache.org/ for more information on Varnish.
5		5
6	Varnish can be set up to use with Noosfero with the following steps:	6	Varnish can be set up to use with Noosfero with the following steps:
7		7
8	-1) setup Noosfero with apache according to the INSTALL file. If you used the
9	-Debian package to install noosfero, you don't need to do anything about this.	8	+1) setup Noosfero with apache according to the `INSTALL.md` file. If you used the Debian package to install noosfero, you don't need to do anything about this.
10		9
11	2) install Varnish	10	2) install Varnish
12		11
13	- # apt-get install varnish	12	+ # apt-get install varnish
14		13
15	Install the RPAF apache module (or skip this step if not using apache):	14	Install the RPAF apache module (or skip this step if not using apache):
16		15
17	- # apt-get install libapache2-mod-rpaf	16	+ # apt-get install libapache2-mod-rpaf
18		17
19	-3) Change Apache to listen on port 8080 instead of 80	18	+3) Change Apache to listen on port `8080` instead of `80`
20		19
21	-3a) Edit /etc/apache2/ports.conf, and:	20	+3a) Edit `/etc/apache2/ports.conf`, and:
22		21
23	- * change 'NameVirtualHost :80' to 'NameVirtualHost :8080'
24	- * change 'Listen 80' to 'Listen 127.0.0.1:8080'	22	+ * change `NameVirtualHost :80` to `NameVirtualHost :8080`
		23	+ * change `Listen 80` to `Listen 127.0.0.1:8080`
25		24
26	-3b) Edit /etc/apache2/sites-enabled/, and change '<VirtualHost :80>' to
27	-'<VirtualHost *:8080>'	25	+3b) Edit `/etc/apache2/sites-enabled/`, and change `<VirtualHost :80>` to `<VirtualHost *:8080>`
28		26
29	3c) Restart apache	27	3c) Restart apache
30		28
31	- # invoke-rc.d apache2 restart	29	+ # invoke-rc.d apache2 restart
32		30
33	4) Varnish configuration	31	4) Varnish configuration
34		32
35	-4a) Edit /etc/default/varnish	33	+4a) Edit `/etc/default/varnish`
36		34
37	- * change the line that says "START=no" to say "START=yes"
38	- * change '-a :6081' to '-a :80'	35	+ * change the line that says `START=no` to say `START=yes`
		36	+ * change `-a :6081` to `-a :80`
39		37
40	-4b) Edit /etc/varnish/default.vcl and add the following lines at the end:	38	+4b) Edit `/etc/varnish/default.vcl` and add the following lines at the end:
41		39
42	- include "/etc/noosfero/varnish-noosfero.vcl";
43	- include "/etc/noosfero/varnish-accept-language.vcl";	40	+ include "/etc/noosfero/varnish-noosfero.vcl";
		41	+ include "/etc/noosfero/varnish-accept-language.vcl";
44		42
45	-On manual installations, change "/etc/noosfero/*" to
46	-"{Rails.root}/etc/noosfero/*"	43	+On manual installations, change `/etc/noosfero/` to `{Rails.root}/etc/noosfero/`
47		44
48	-NOTE: it is very important that the *.vcl files are included in that order,
49	-i.e. first include "varnish-noosfero.vcl", and after
50	-"noosfero-accept-language.cvl".	45	+NOTE: it is very important that the `.vcl` files are included in that order, i.e. first* include `varnish-noosfero.vcl`, and after `noosfero-accept-language.cvl`.
51		46
52	4c) Restart Varnish	47	4c) Restart Varnish
53		48
54	- # invoke-rc.d varnish restart	49	+ # invoke-rc.d varnish restart
55		50
56	5) Enable varnish logging:	51	5) Enable varnish logging:
57		52
58	-5a) Edit /etc/default/varnishncsa and uncomment the line that contains:	53	+5a) Edit `/etc/default/varnishncsa` and uncomment the line that contains:
59		54
60	-VARNISHNCSA_ENABLED=1	55	+ VARNISHNCSA_ENABLED=1
61		56
62	-The varnish log will be written to /var/log/varnish/varnishncsa.log in an
63	-apache-compatible format. You should change your statistics generation software
64	-(e.g. awstats) to use that instead of apache logs.	57	+The varnish log will be written to `/var/log/varnish/varnishncsa.log` in an apache-compatible format. You should change your statistics generation software (e.g. awstats) to use that instead of apache logs.
65		58
66	5b) Restart Varnish Logging service	59	5b) Restart Varnish Logging service
67		60
68	- # invoke-rc.d varnishncsa restart	61	+ # invoke-rc.d varnishncsa restart
69		62
70	-Thanks to Cosimo Streppone for varnish-accept-language. See
71	-http://github.com/cosimo/varnish-accept-language for more information.	63	+Thanks to Cosimo Streppone for varnish-accept-language. See http://github.com/cosimo/varnish-accept-language for more information.