[gnome-applets/wip-readme] README: use markdown and improve documentation

[Sebastian Geiger <segeiger src gnome org>]

commit 217704db72b6884271cf86eedcdf602718d672df
Author: Sebastian Geiger <sbastig gmx net>
Date:   Sun Mar 22 12:34:30 2020 +0100

    README: use markdown and improve documentation

 README                            |  29 +-------------------
 README.md                         |  56 ++++++++++++++++++++++++++++++++++++++
 configure.ac                      |   2 +-
 docs/add-to-panel-dialog.png      | Bin 0 -> 85574 bytes
 docs/gnome-panel-context-menu.png | Bin 0 -> 15922 bytes
 5 files changed, 58 insertions(+), 29 deletions(-)
---
diff --git a/README b/README
index 1f6a02666..96dc92fbd 100644
--- a/README
+++ b/README
@@ -1,28 +1 @@
-GNOME-Applets
-=============
-
-This package contains applets for use with the GNOME panel.  Therefore, it
-requires gnome-core to be installed.  To build all applets additional
-libraries may be needed.
-
-This list is by no means definitive.
-
-
-Requirements
-------------
-
-See the section "Minimum library versions for GNOME-APPLETS" in
-https://gitlab.gnome.org/GNOME/gnome-applets/blob/master/configure.ac
-
-
-Mailing List
-------------
-
-The mailing list for GNOME-Applets is gnome-flashback-list gnome org
-
-
-Reporting Bugs
---------------
-
-Bugs should be reported in the GNOME issue tracker:
-<https://gitlab.gnome.org/GNOME/gnome-applets/issues>
+See README.md
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..58ccfa29f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# About
+
+GNOME Applets is part of the GNOME Flashback project and contains applets for use with
+GNOME Panel. This includes applets for various tasks such as viewing the battery status,
+viewing the cpu frequency or memory consumption, a weather applet and many more.
+
+Please note that GNOME Panel also includes built-in applets such as the task list,
+the application menu or the notification area, that are maintained directly in the
+GNOME Panel source code.
+
+Applets can be loaded by `gnome-panel` from a well-known system path and
+can be added to a panel from the "Add to Panel..." dialog that can be accessed
+from any panel's context menu by pressing `<Alt>+<Right Click>`
+on an empty area of the panel:
+
+![Gnome Panel Context Menu](docs/gnome-panel-context-menu.png)
+
+Installed applets appear in the panel's "Add to Panel" dialog:
+
+![Add-to-panel dialog of a Gnome Panel](docs/add-to-panel-dialog.png)
+
+# Development
+
+Applets should be written with the `libgnome-panel` library available since
+gnome-panel 3.36 (for details see the
+[libgnome-panel documentation](https://developer.gnome.org/libgnome-panel/)).
+
+Older applets are still written with the `libpanel-applet` library that
+is deprecated and will be removed from gnome-panel in the future (for details
+see the [libpanel-applet documentation](https://developer.gnome.org/libpanel-applet)).
+
+# Releases
+
+You may download GNOME Applets releases and updates from the
+[release server](http://download.gnome.org/sources/gnome-applets/).
+
+# Requirements
+
+See the section "Minimum library versions for GNOME Applets" in
+[configure.ac](https://gitlab.gnome.org/GNOME/gnome-applets/blob/master/configure.ac).
+
+# Discussions
+
+To discuss gnome-panel, you may use the
+[gnome-flashback-list](http://mail.gnome.org/mailman/listinfo/gnome-flashback-list) mailing list.
+
+# Installation
+
+See the INSTALL file. If you are not using a released version of
+GNOME Panel (for example, if you checked out the code from git), you
+first need to run './autogen.sh'.
+
+# Reporting Bugs
+
+Bug reports should be reported on the
+[issue section](https://gitlab.gnome.org/GNOME/gnome-applets/issues) on GNOME's Gitlab server.
diff --git a/configure.ac b/configure.ac
index 70c4d7cd3..86acae497 100644
--- a/configure.ac
+++ b/configure.ac
@@ -57,7 +57,7 @@ LT_INIT([dlopen disable-static])
 LT_LIB_M
 
 dnl ***************************************************************************
-dnl *** Minimum library versions for GNOME-APPLETS                          ***
+dnl *** Minimum library versions for GNOME Applets                          ***
 dnl ***************************************************************************
 GTK_REQUIRED=3.20.0
 GLIB_REQUIRED=2.44.0
diff --git a/docs/add-to-panel-dialog.png b/docs/add-to-panel-dialog.png
new file mode 100644
index 000000000..93a8066cb
Binary files /dev/null and b/docs/add-to-panel-dialog.png differ
diff --git a/docs/gnome-panel-context-menu.png b/docs/gnome-panel-context-menu.png
new file mode 100644
index 000000000..c14c28be2
Binary files /dev/null and b/docs/gnome-panel-context-menu.png differ