From a772a437249f4b792aa5c343783fa05f53955de3 Mon Sep 17 00:00:00 2001
From: MarcFontaine <Marc.Fontaine@gmx.de>
Date: Thu, 19 Oct 2017 10:44:33 +0200
Subject: [PATCH] extend README

---
 README.md      | 38 ++++++++++++++++++++++++++++++++++++--
 si-clock.cabal |  8 +++-----
 2 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index cf5a1ed..6522028 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,36 @@
-# si-clock
-An interface to the Silicon Labs Si5351 clock chip
+# An interface to the Silicon Labs Si5351 clock chip
+
+![Si5351 Board](https://i.imgur.com/5DI1b1l.jpg)
+
+The Si5351 is Silicon Labs I2C-programmable any-frequency CMOS clock generator and VCXO.
+It can generate any frequency from ca 8kHz to 160MHz.
+The Si5351 uses a programmable rational clock divider.
+
+## Why yet an other SI5351 library ?
+
+First of all it is hackable in Haskell.
+And second, almost all of the other open source Si5351 libraries
+use a fixed denominator for the clock divider.
+In other words, 20 of the 58 bits, that set the clock divider, are hard-coded in
+library.
+As the IC always uses a combination of two rational divider stages,
+a total of 2*20 bits = 40 bits, that the carefully designed hardware provides
+are lost by the software design.
+That means 40 bits less resolution and more jitter.
+
+Instead of a fixed denominator, this library uses
+[continued fractions](https://en.wikipedia.org/wiki/Continued_fraction)
+to compute the (theoretically best)
+numerator-denominator pair for the clock divider.
+(TO DO investigate if this makes any difference in practice.)
+
+## Examples
+The library contains examples for:
+
+* Frequency synthesis
+* Hopping frequencies
+* CW generation (Morse code)
+* Transmitting JT65
+* RTTY / FSK
+
+## [Haddock documentation](http://hackage.haskell.org/package/si-clock)
diff --git a/si-clock.cabal b/si-clock.cabal
index 9973184..19c59d0 100644
--- a/si-clock.cabal
+++ b/si-clock.cabal
@@ -17,6 +17,7 @@ license-file:  LICENSE
 
 cabal-version: >= 1.22
 build-type:    Simple
+extra-source-files: README.md
                
 source-repository head
   type:     git
@@ -24,8 +25,8 @@ source-repository head
 
 library
   default-language: Haskell2010
-
   hs-source-dirs: src
+  ghc-options: -Wall
 
   exposed-modules:
       Hardware.SiClock
@@ -42,7 +43,4 @@ library
     , bytestring
     , transformers
     , time
-    , hsI2C >= 0.1.3
-    
-  ghc-options: -Wall -O2
-
+    , hsI2C >= 0.1.3
\ No newline at end of file