Merge branch 'feature/upstream' into develop

1 files changed, 30 insertions, 26 deletions

diff --git a/README.md b/README.md
index ac6b51c..478300d 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,62 @@
 [![Build Status](https://gitlab.gnome.org/GNOME/simple-scan/badges/master/build.svg)](https://gitlab.gnome.org/GNOME/simple-scan/pipelines)
+[![License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://gitlab.gnome.org/GNOME/simple-scan/blob/master/COPYING)
 
-# SIMPLE SCAN
+# Introduction
 
-This is the source code to "Simple Scan" a simple GNOME scanning application,
-using the [SANE](http://sane-project.org/) scanning libraries.
+This is the source code to *Simple Scan* — a [GNOME](https://www.gnome.org/)
+document scanning application. Simple Scan allows you to capture images using
+[image scanners](https://en.wikipedia.org/wiki/Image_scanner) (e.g. flatbed
+scanners) that have suitable [SANE drivers](http://sane-project.org/) installed.
 
-## BUILDING
+# Building from source
 
-Install the dependencies (on Ubuntu/Debian):
+Install the dependencies (first line is Ubuntu/Debian, second is Fedora):
 ```
 $ sudo apt install git meson valac libgtk-3-dev libgusb-dev libcolord-dev libpackagekit-glib2-dev libwebp-dev libsane-dev gettext itstool
 ```
+```
+$ sudo dnf install -y meson vala gettext itstool gtk3-devel libgusb-devel colord-devel PackageKit-glib-devel libwebp-devel sane-backends-devel
+```
 
 Get the source:
 ```
 $ git clone https://gitlab.gnome.org/GNOME/simple-scan.git
+$ cd simple-scan
 ```
 
-Build locally with:
+Build and run:
 ```
 $ meson --prefix $PWD/install build/
 $ ninja -C build/ all install
 $ XDG_DATA_DIRS=install/share:$XDG_DATA_DIRS ./install/bin/simple-scan
 ```
 
-## DEBUGGING
+# Debugging
 
 There is a --debug command line switch to enable more verbose logging:
 ```
-./install/bin/simple-scan --debug
+$ simple-scan --debug
 ```
 
-Log messages can also be found in the $HOME/.cache/simple-scan folder.
+Log messages can also be found in the `$HOME/.cache/simple-scan` folder.
 
 If you don't have a scanner ready, you can use a virtual "test" scanner:
 ```
-./install/bin/simple-scan --debug test
+$ simple-scan --debug test
 ```
 
-When debugging hardware issues always check xsane and especially scanimage.
-
-* http://xsane.org/
-* http://www.sane-project.org/man/scanimage.1.html
-
-## CONTRIBUTING
-
-The preferred way to contribute code to Simple Scan is
-to create a merge request on gitlab.gnome.org.
-
-## CONTACT
+Simple Scan works by using the [SANE API](http://sane-project.org/html/) to
+capture images. It chooses the settings it thinks are appropriate for what you
+are trying to do. Drivers have many options and are of differring quality - it
+is useful to work out if any issues are caused by Simple Scan or the drivers. To
+rule out Simple Scan you can use the graphical tool (XSane) or the
+command line
+[scanimage](http://www.sane-project.org/man/scanimage.1.html) provided
+by the SANE project - these allow to to easily see and control all the
+settings your driver provides.
 
-### Websites
-* https://gitlab.gnome.org/GNOME/simple-scan
-* https://gitlab.gnome.org/GNOME/simple-scan/issues
+# Contributing
 
-### IRC
-* Freenode (irc.ubuntu.com): #simple-scan
+To contribute code to Simple Scan make merge requests on
+[gitlab.gnome.org](https://gitlab.gnome.org/GNOME/simple-scan). If you
+find issues please [report them](https://gitlab.gnome.org/GNOME/simple-scan/issues).