Update README file

AUTHORS

@@ -1 +1 @@
-Damien Goutte-Gattat
+Damien Goutte-Gattat <dgouttegattat@incenp.org>

README.md

@@ -2,26 +2,52 @@ Scdtools - Tools for Scdaemon and OpenPGP smartcards
 ====================================================
 
 Scdtools is a set of utility tools to work with Scdaemon, the smartcard
-daemon of the GnuPG project, and OpenPGP smartcards.
+daemon of the [GnuPG project](http://www.gnupg.org/), and [OpenPGP
+smartcards](http://g10code.com/docs/openpgp-card-2.0.pdf).
 
 
 Scdrand - Extract random numbers from a smartcard
 -------------------------------------------------
-Scdrand obtains up to 256 bytes of random data from a ISO7816-compliant
+_Scdrand_ obtains up to 256 bytes of random data from a ISO7816-compliant
 smartcard and adds them to the kernel entropy pool.
 
 It uses Scdaemon to send a `GET CHALLENGE` to the smartcard. As per
-ISO 7816-4, the smartcard replies with random bytes, which Scdrand then
+ISO 7816-4, the smartcard replies with random bytes, which _scdrand_ then
 sends to the Linux kernel entropy pool through the RNDADDENTROPY ioctl
 call on `/dev/random`.
 
-Since that call requires root privileges, scdrand is installed with the
-setuid bit set. To mitigate risks associated with running as root, the
-program forks itself at startup and only the child retains the root
+Since that call requires root privileges, _scdrand_ is installed with
+the setuid bit set. To mitigate risks associated with running as root,
+the program forks itself at startup and only the child retains the root
 privileges needed to write to `/dev/random`. The parent process, in
 charge of communicating with the smartcard, then runs with the
 privileges on the calling user.
 
+### Usage
+The most basic usage of _scdrand_ is as follows:
+
+```sh
+$ scdrand 32
+```
+
+The program will request 32 random bytes from the card, feed them to the
+entropy pool, then quits. You can request from 1 to 256 bytes.
+
+With the `-l, --loop` option, _scdrand_ will not quit, but will
+periodically request random bytes from the card and feed them to the
+pool. With the `-t, --threshold` option, _scdrand_ will attempt to feed
+the pool only if the available entropy in the pool falls below a
+specified threshold. So in the following example:
+
+```sh
+$ scdrand -l -i 1 -t 512 256
+```
+
+_scdrand_ will check the state of the entropy pool every second; if
+there is less than 512 bits of entropy available, it will feed the pool
+with 256 random bytes. The program will quit upon receiving a `^C`
+signal.
+
 
 Scdtotp - Generate time-based OTP from an OpenPGP smartcard
 -----------------------------------------------------------
@@ -31,20 +57,21 @@ generator token. It generates time-based one-time password (TOTP) as per
 expects to find in the private data object of the inserted OpenPGP
 smartcard.
 
-Note that contrary to a true password generator token, the key cannot
-remain only on the smartcard, it has to be sent to the computer so
-that scdtotp can derive the password from it. Thus it cannot provide
-the same level of security.
+> Contrary to a true password generator token, the key cannot remain
+> only on the smartcard, it has to be sent to the computer so that
+> scdtotp can derive the password from it. Thus it cannot provide the
+> same level of security.
 
 The key must be stored as an `otpauth://` URI as specified in [Google
 Authenticator’s wiki](https://code.google.com/p/google-authenticator/wiki/KeyUriFormat),
 e.g.:
 
-    otpauth://totp/alice@example.org?secret=KIMEFUAW4SRW
+```
+otpauth://totp/alice@example.org?secret=KIMEFUAW4SRW
+```
 
-where the _secret_ parameter is the Base32-encoded key. This format
-allows to specify also the non-secret parameters of the TOTP
-algorithm:
+where the _secret_ parameter is the Base32-encoded key.  This format
+allows to specify also the non-secret parameters of the TOTP algorithm:
 
 - the HMAC algorithm to use: `&algorithm=mac`, where _mac_ can be `sha1`
   (default), `sha256`, or `sha512`;
@@ -52,7 +79,13 @@ algorithm:
   seconds by default);
 - the number of digits to output: `&digits=N` (defaults to 6).
 
-All of these parameters may be overridden by command line options.
+> The (undocumented) `privatedo N` command of the GnuPG’s card editor
+> may be used to store the URI into the Nth private DO of the OpenPGP
+> smartcard.
+
+Once the URI is on the card and the card is inserted in the card reader,
+simply calling _scdtotp_ will print the one-time password for the
+current time window on standard output.
 
 
 Copying
@@ -62,12 +95,9 @@ License, version 3 or higher. The full license is included in the
 [COPYING file](COPYING) of the source distribution.
 
 
-Homepage and contact
---------------------
+Homepage and repository
+-----------------------
 The project is located at <http://www.incenp.org/dvlpt/scdrand.html>.
 The latest source code is available in a Git repository at
 <git://git.incenp.org/scdrand.git> and may also be browsed at
 <http://www.incenp.org/gitweb/?p=scdrand.git;a=summary>.
-
-The author may be contact at the following address:
-Damien Goutte-Gattat <dgouttegattat@incenp.org>