Improve README.md with features, installation and usage sections

1 files changed, 129 insertions, 35 deletions

diff --git a/README.md b/README.md
index 294c7f0..89dea3c 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,86 @@
 # libimobiledevice
 
-## About
-
-A library to communicate with services of Apple iOS devices using native
-protocols.
-
-## Requirements
-
-Development Packages of:
-* OpenSSL or GnuTLS
-* libplist
-* libusbmuxd
-
-Software:
-* usbmuxd (OSS or Apple's version)
-* make
-* autoheader
-* automake
-* autoconf
-* libtool
-* pkg-config
-* gcc or clang
+*A library to communicate with services on iOS devices using native protocols.*
+
+## Features
+
+libimobiledevice is a cross-platform software library that talks the protocols
+to interact with iOS devices.
+
+Unlike other projects, it does not depend on using any existing proprietary
+libraries and does not require jailbreaking.
+
+Some key features are:
+
+- **Interface**: Implements many high-level interfaces for device services
+- **Implementation**: Object oriented architecture and service abstraction layer
+- **Cross-Platform:** Tested on Linux, macOS, Windows and Android platforms
+- **Utilities**: Provides various command-line utilities for device services
+- **SSL**: Allows choosing between OpenSSL or GnuTLS to handle SSL communication
+- **Network**: Supports network connections with "WiFi sync" enabled devices
+- **Python:** Provides Cython based bindings for Python
+
+The implemented interfaces of many device service protocols allow applications
+to:
+
+* Access filesystem of a device
+* Access documents of file sharing apps
+* Retrieve information about a device and modify various settings
+* Backup and restore the device in a native way compatible with iTunes
+* Manage app icons arrangement on the device
+* Install, remove, list and basically manage apps
+* Activate a device using official serviers
+* Manage contacts, calendars, notes and bookmarks
+* Retrieve and remove crashreports
+* Retrieve various diagnostics information
+* Establish a debug connection for app debugging
+* Mount filesystem images
+* Forward device notifications
+* Manage device provisioning
+* Take screenshots from the device screen (requires mounted developer image)
+* Simulate changed geolocation of the device (requires mounted developer image)
+* Relay the syslog of the device
+* Expose a connection for WebKit remote debugging
+
+... and much more.
+
+The library is in development since August 2007 with the goal to bring support
+for these devices to the Linux Desktop.
+
+## Installation / Getting started
+
+### Debian / Ubuntu Linux
+
+First install all required dependencies and build tools:
+```shell
+sudo apt-get install \
+	build-essential \
+	checkinstall \
+	git \
+	autoconf \
+	automake \
+	libtool-bin \
+	libplist-dev \
+	libusbmuxd-dev \
+	libssl-dev \
+	usbmuxd
+```
 
-Optional:
-* cython (Python bindings)
-* doxygen (Documentation)
+If you want to optionally build the documentation or Python bindings use:
+```shell
+sudo apt-get install \
+	doxygen \
+	cython
+```
 
-## Installation
+Then clone the actual project repository:
+```shell
+git clone https://github.com/libimobiledevice/libimobiledevice.git
+cd libimobiledevice
+```
 
-To compile run:
-```bash
+Now you can build and install it:
+```shell
 ./autogen.sh
 make
 sudo make install
@@ -49,20 +100,63 @@ By default, OpenSSL will be used. If you prefer GnuTLS, configure with
 ./autogen.sh --disable-openssl
 ```
 
-## Who/What/Where?
+## Usage
+
+Documentation about using the library in your application is not available yet.
+The "hacker way" for now is to look at the implementation of the included
+utilities.
+
+### Utilities
+
+The library bundles the following command-line utilities in the tools directory:
+
+| Utility                    | Description                                                        |
+| -------------------------- | ------------------------------------------------------------------ |
+| `idevice_id`               | List attached devices or print device name of given device         |
+| `idevicebackup`            | Create or restore backup for devices (legacy)                      |
+| `idevicebackup2`           | Create or restore backups for devices running iOS 4 or later       |
+| `idevicecrashreport`       | Retrieve crash reports from a device                               |
+| `idevicedate`              | Display the current date or set it on a device                     |
+| `idevicedebug`             | Interact with the debugserver service of a device                  |
+| `idevicedebugserverproxy`  | Proxy a debugserver connection from a device for remote debugging  |
+| `idevicediagnostics`       | Interact with the diagnostics interface of a device                |
+| `ideviceenterrecovery`     | Make a device enter recovery mode                                  |
+| `ideviceimagemounter`      | Mount disk images on the device                                    |
+| `ideviceinfo`              | Show information about a connected device                          |
+| `idevicename`              | Display or set the device name                                     |
+| `idevicenotificationproxy` | Post or observe notifications on a device                          |
+| `idevicepair`              | Manage host pairings with devices and usbmuxd                      |
+| `ideviceprovision`         | Manage provisioning profiles on a device                           |
+| `idevicescreenshot`        | Gets a screenshot from the connected device                        |
+| `idevicesetlocation`       | Simulate location on device                                        |
+| `idevicesyslog`            | Relay syslog of a connected device                                 |
+
+Please consult the usage information or manual pages of each utility for a
+documentation of available command line options and usage examples like this:
+```shell
+ideviceinfo --help
+man ideviceinfo
+```
+
+## Links
 
-* Home: https://libimobiledevice.org/
-* Code: `git clone https://git.libimobiledevice.org/libimobiledevice.git`
-* Code (Mirror): `git clone https://github.com/libimobiledevice/libimobiledevice.git`
-* Tickets: https://github.com/libimobiledevice/libimobiledevice/issues
+* Homepage: https://libimobiledevice.org/
+* Repository: https://git.libimobiledevice.org/libimobiledevice.git
+* Repository (Mirror): https://github.com/libimobiledevice/libimobiledevice.git
+* Issue Tracker: https://github.com/libimobiledevice/libimobiledevice/issues
 * Mailing List: https://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel
 * Twitter: https://twitter.com/libimobiledev
 
+## License
+
+This library and utilities are licensed under the [GNU Lesser General Public License v2.1](https://www.gnu.org/licenses/lgpl-2.1.en.html),
+also included in the repository in the `COPYING` file.
+
 ## Credits
 
 Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc.
 
-libimobiledevice is an independent software library and has not been
-authorized, sponsored, or otherwise approved by Apple Inc.
+This project is an independent software and has not been authorized, sponsored,
+or otherwise approved by Apple Inc.
 
-README Updated on: 2020-06-08
+README Updated on: 2020-06-12