From 5d6ac8a02041788f62c1ca17c777f3eb84fc8afa Mon Sep 17 00:00:00 2001
From: Fabio Hernandez <fairnandez@gmail.com>
Date: Mon, 1 Jun 2020 19:38:32 +0200
Subject: [PATCH] Improve documentation: add more examples, including examples
 on how to use IPv6 addresses

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 38 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index a7f4276..684b7e8 100644
--- a/README.md
+++ b/README.md
@@ -3,26 +3,52 @@
 ## Overview
 `tlsping` is a command line tool to measure the time required to perform [Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) connections with a network server.
 
-It concurrently establishes several network connections, performs the TLS handshake on every one of them, measures the time spent and reports a summary on the observed results.
+It concurrently establishes several network connections, performs the TLS handshake on every one of them, measures the time spent handshaking and reports a summary on the observed results.
 
 ## How to use
-Example of usage:
 
-```bash
-$ tlsping mail.google.com:443
-tlsping: TLS connection to server mail.google.com:443 (10 connections)
-tlsping: min/avg/max/stddev = 92.90ms/94.65ms/96.77ms/913.94µs
-```
+#### Examples of usage:
+
+* Measure the time to establish a TCP connection to host `mail.google.com` port `443` and perform the TLS handshaking:
+ 
+	```bash
+	# The hostname 'mail.google.com' resolves to an IPv4 address
+	$ tlsping mail.google.com:443      
+	tlsping: TLS connection to mail.google.com:443 (216.58.204.133) (10 connections)
+	tlsping: min/avg/max/stddev = 95.95ms/96.31ms/96.63ms/218.19µs
+	```
+
+* Same measurement as above but connect to host `www.cloudflare.com` when it resolves to to IPv6 address `2606:4700::6811:d209`:
+
+	```bash
+	# The hostname 'www.cloudflare.com' resolves to an IPv6 address
+	$ tlsping www.cloudflare.com:443 
+	tlsping: TLS connection to www.cloudflare.com:443 (2606:4700::6811:d209) (10 connections)
+	tlsping: min/avg/max/stddev = 85.36ms/86.63ms/88.98ms/1.14ms
+	```
+	
+*	Measure only the time to establish the TCP connection (i.e. do not perform TLS handshaking) to remote server at IPv6 address `2a00:1450:400a:800::2005` port `443`:
+
+	```bash
+	# To specify an IPv6 address and port enclose the IP address in '[' and ']'
+	$ tlsping -tcponly [2a00:1450:400a:800::2005]:443
+	tlsping: TCP connection to [2a00:1450:400a:800::2005]:443 (2a00:1450:400a:800::2005) (10 connections)
+	tlsping: min/avg/max/stddev = 5.85ms/5.97ms/6.08ms/61.55µs
+	```
+
+#### Synopsis
 
-This is the synopsis of the command:
-
-```
+```bash
 tlsping [-c count] [-tcponly] [-json] [-ca=<file>] [-insecure] <server address>
 tlsping -help
 tlsping -version
 ```
 
-For getting details on options do `tlsping -help`.
+#### Getting help
+
+```bahs
+tlsping -help
+```
 
 ## Installation
 Download a **binary release** for your target operating system from the [releases page](https://github.com/airnandez/tlsping/releases).
@@ -38,7 +64,7 @@ go get -u github.com/airnandez/tlsping/...
 This tool was developed and is maintained by Fabio Hernandez at [IN2P3 / CNRS computing center](http://cc.in2p3.fr) (Lyon, France).
 
 ## License
-Copyright 2016 Fabio Hernandez
+Copyright 2016-2020 Fabio Hernandez
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.