Updated README, use Markdown syntax

1 files changed, 107 insertions, 81 deletions

diff --git a/README b/README.md
index 85fe9b4..2caba48 100644
--- a/README
+++ b/README.md
@@ -1,70 +1,98 @@
-Twinkle is a SIP based VoIP client.
+# Twinkle
 
-Release 0.5 notes
------------------
-In this release the SIP UDP port and RTP port settings have been
-moved from the user profile to the system settings. If you made
-any changes to the default port values in your user profiles, then
-these changes will be lost.
+Twinkle is a SIP-based VoIP client.
+
+## Dependencies
 
-Library requirements
---------------------
 To compile Twinkle you need the following libraries:
 
-libccext2 (version >= 1.4.2) [GNU Common C++]
-libccgnu2 (version >= 1.4.2) [GNU Common C++]
-	http://www.gnu.org/software/commoncpp/
+* commoncpp2 and ucommon (version >= 1.4.2) - [GNU Common C++](http://www.gnu.org/software/commoncpp/)
+* ccRTP (version >= 1.5.0) [GNU RTP Stack](http://www.gnu.org/software/ccrtp/)
+* libxml2
+* Boost regex
+* libsndfile
+* Qt 4 or Qt 5
+
+### Optional dependencies
+
+* alsa-lib
+* libzrtpcpp (version >= 0.9.0) [ZRTP library, ccRTP support must be enabled](http://www.gnutelephony.org/index.php/GNU_ZRTP)
+* bcg729 [G.729A codec library](http://www.linphone.org/technical-corner/bcg729/overview)
+* speex [Speex codec library](http://www.speex.org/)
+* iLBC [iLBC codec library](http://www.ilbcfreeware.org/)
+
+## Build
+
+First of all, choose which options you want to have enabled.
+As a very minimum, you should choose Qt 4 (`-DWITH_QT4=On`) or
+Qt 5 (`-DWITH_QT5=On`). These two options are mutually exclusive.
+
+All possible options are:
+
+* Qt 5 GUI: `-DWITH_QT5=On`
+* Qt 4 GUI: `-DWITH_QT4=On`
+* ALSA support: `-DWITH_ALSA=On` (on by default)
+* ZRTP support: `-DWITH_ZRTP=On`
+* G.729A codec support: `-DWITH_G729=On`
+* Speex codec support: `-DWITH_SPEEX=On`
+* iLBC codec support: `-DWITH_ILBC=On`
+* Diamondcard support: `-DWITH_DIAMONDCARD=On`
+
+### Build instructions
+
+	# Create a subdirectory for the build an enter it
+	mkdir build && cd build
+
+	# Run cmake with a list of build options
+	cmake .. -Dexample_option=On
+
+	# Build Twinkle
+	make
 
-libccrtp1 (version >= 1.5.0) [GNU RTP Stack]
-libzrtpcpp (version >= 0.9.0) [Extension library of GNU ccRTP]
-	http://www.gnu.org/software/ccrtp/
+	# Install Twinkle
+	make install
 
-libqt-mt (version >= 3.3.0) [Qt library with threading support]
-	http://www.trolltech.com/
-	For the Qt environment the $QTDIR variable must be set
-	correctly
+## Shared user data
 
-Shared user data
-----------------
 Installation will create the following directory for shared user data
 on your system:
 
-	$(pkgdatadir)/twinkle
+	${CMAKE_INSTALL_PREFIX}/share/twinkle
 
-Typical value for pkgdatadir is: /usr/local/share or /opt/kde3/share
+The typical default value for `CMAKE_INSTALL_PREFIX` is `/usr/local`.
+
+## Application icon
 
-Application icon
-----------------
 If you want to create an application link on your desktop you
 can find an application icon in the shared user data directory:
 
-	twinkle16.png	16x16 icon
-	twinkle32.png	32x32 icon
-	twinkle48.png	48x48 icon
+*	twinkle16.png	(16x16 icon)
+*	twinkle32.png	(32x32 icon)
+*	twinkle48.png	(48x48 icon)
+
+## User data
 
-User data
----------
-On first run Twinkle will create the directory ".twinkle" in your home
+On first run Twinkle will create the `.twinkle` directory in your home
 directory. In this directory all user data will be put:
 
-	user profiles (.cfg)
-	log files (.log)
-	system settings (twinkle.sys)
-	call history (twinkle.ch)
-	lock file (twinkle.lck)
+* user profiles (.cfg)
+* log files (.log)
+* system settings (twinkle.sys)
+* call history (twinkle.ch)
+* lock file (twinkle.lck)
+
+## Starting Twinkle
 
-Starting Twinkle
-----------------
 Give the command: twinkle
 
-'twinkle -h' will show you some command line options you may use.
+`twinkle -h` will show you some command line options you may use.
 
 NOTE: the CLI option is not fool proof. A command given at a wrong
       time may crash the program. It is recommended to use the GUI.
   
-If you do not specify a configuration file (-f <profile>) on the command
+If you do not specify a configuration file (`-f <profile>`) on the command
 line, then Twinkle will look for configuration files in your 
-.twinkle directory. 
+`.twinkle` directory. 
 
 If you do not have any configuration file, the configuration file
 editor will startup so you can create one. If you have
@@ -85,14 +113,14 @@ NOTE: the configuration file editor only exists in the GUI.
       If you run the CLI mode and you do not specify a file name
       on the command line, then Twinkle will use twinkle.cfg
 
-NAT
----
+## NAT
+
 If there is a NAT between you and your SIP server then you have
 3 options to make things work:
 
-1) Your SIP provider uses a Session Border Controller
-2) Your SIP provider offers a STUN server
-3) Make static address mappings in your NAT for SIP and RTP
+1. Your SIP provider uses a Session Border Controller
+2. Your SIP provider offers a STUN server
+3. Make static address mappings in your NAT for SIP and RTP
 
 STUN can be enabled in the NAT section of the user profile.
 
@@ -101,32 +129,32 @@ the NAT section of the user profile:
 
       Use statically configured public IP address inside SIP messages
 
-   And fill in the public IP address of your NAT.
+And fill in the public IP address of your NAT.
 
-   Twinkle will then use this IP address inside SIP headers and
-   SDP bodies instead of the private IP address of your machine.
+Twinkle will then use this IP address inside SIP headers and
+SDP bodies instead of the private IP address of your machine.
 
-   In addition you have to add the following port forwardings for UDP
-   on your NAT
+In addition you have to add the following port forwardings for UDP
+on your NAT
 
 	public:5060 --> private:5060 (for SIP signaling)
 	public:8000 --> private:8000 (for RTP on line 1)
 	public:8001 --> private:8001 (for RTCP on line 1)
 	public:8002 --> private:8002 (for RTP on line 2)
 	public:8003 --> private:8003 (for RTCP on line 2)
-        public:8004 --> private:8004 (for RTP for call transfer)
-        public:8005 --> private:8005 (for RTCP for call transfer)
+    public:8004 --> private:8004 (for RTP for call transfer)
+    public:8005 --> private:8005 (for RTCP for call transfer)
+
+If you have changed the SIP/RTP ports in your profile you have
+to change the port forwarding rules likewise.
 
-   If you have changed the SIP/RTP ports in your profile you have
-   to change the port forwarding rules likewise.
+## Log files
 
-Log files
----------
 During execution Twinkle will create the following log files in
 your .twinkle directory:
 
-	twinkle.log	This is the latest log file
-	twinkle.log.old	This is the previous log file
+* twinkle.log (latest log file)
+* twinkle.log.old (previous log file)
 
 When twinkle.log is full (default is 5 MB) then it is moved to 
 twinkle.log.old and a new twinkle.log is created.
@@ -134,8 +162,8 @@ twinkle.log.old and a new twinkle.log is created.
 On startup an existing twinkle.log is moved to twinkle.log.old and a
 new twinkle.log is created.
 
-User profile configuration
---------------------------
+## User profile configuration
+
 A user profile contains information about your user account,
 SIP proxy, and several SIP protocol options. If you use Twinkle
 with different user accounts you may create multiple user
@@ -151,10 +179,10 @@ profile.
 The user profile is stored as '<name>.cfg' in the .twinkle
 directory where <name> is the name you gave to the profile.
 
-At a minumimum you have to specify the following:
+At a minimum you have to specify the following:
 
-  User name: this is your SIP user name (eg. phone number)
-  Domain:    the domain of your provider (eg. fwd.pulver.com)
+* User name: this is your SIP user name (eg. phone number)
+* Domain:    the domain of your provider (eg. fwd.pulver.com)
              this could also be the IP address of your SIP proxy
 	     if you want to do IP-to-IP dialing (without proxy) then
 	     fill in the IP address or FQDN of your computer.
@@ -164,14 +192,12 @@ filled in for 'Domain' can be resolved to an IP address by Twinkle,
 eg. it is an IP address or an FQDN that is in an A-record of the
 DNS, then you are ready now.
 
-NOTE: Twinkle does not support DNS SRV records yet.
+## Authentication
 
-Authentication
---------------
 If your proxy needs authentication, then specify the following fields
 in the SIP authentication box:
 
-  Realm:	the realm for authentication
+* Realm:	the realm for authentication
 	 	you might leave the realm empty. If you do so, then
 		Twinkle will use the name and password regardless of
 		the realm put in the challenge by the proxy. For most
@@ -180,15 +206,15 @@ in the SIP authentication box:
 		you have to access multiple realms. Then for the realms
 		not known to Twinkle you will be requested for a login
 		when needed.
-  Name:		your authentication name
-  Password:	your authentication password
+* Name:		your authentication name
+* Password:	your authentication password
 
 If authentication fails during registration or any other SIP request
 because you filled in wrong values, then Twinkle will at that time
 interactively request your login and cache it.
 
-Outbound proxy
---------------
+## Outbound proxy
+
 An outbound proxy is only needed if the domain value cannot be resolved
 to an IP address by Twinkle or because your provider demands you to
 use an outbound proxy that is at a different IP address.
@@ -214,8 +240,8 @@ the 'in-dialog' option, then an in-dialog request will
 never go to the proxy. If its destination cannot be resolved, then
 the request will simply fail.
 
-Registrar
----------
+## Registrar
+
 By default a REGISTER will be send to the IP address resolved from
 the domain value or to the outbound proxy if specified.
 
@@ -230,12 +256,12 @@ registration. The expiry time may be overruled by the registrar.
 The 'registrar at startup option' will make Twinkle automatically 
 send a REGISTER on startup of the profile.  
 
-Addressing
-----------
+## Addressing
+
 When you invite someone to a call you have to enter an an address.
 A SIP address has the following form:
 
-   sip:<user>@<host-part>
+	sip:<user>@<host-part>
 
 Where 'user' is a user name or a phone number
 and 'host-part' is a domain name, FQDN or IP address
@@ -245,9 +271,9 @@ will fill in the other parts if you do not provide them.
 For the host-part, Twinkle will fill in the value you configured
 as your 'domain'.
 
-Currently "sip:" is the only addressing scheme supported by Twinkle.
+Currently `sip:` is the only addressing scheme supported by Twinkle.
+
+Michel de Boer [michel@twinklephone.com]
 
-January 2006
+Lubos Dolezel [lubos@dolezel.info]
 
-Michel de Boer
-michel@twinklephone.com