From 69441360a49c42faeb01629e50d7357854f028d2 Mon Sep 17 00:00:00 2001
From: Christian Hesse <mail@eworm.de>
Date: Wed, 26 Jul 2023 23:36:24 +0200
Subject: README: add documentation

Fixes GH-3
---
 Makefile  |  8 +++++++-
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index b670cff..eea54d4 100644
--- a/Makefile
+++ b/Makefile
@@ -15,7 +15,9 @@ all: README.html
 	$(MD) $< > $@
 	$(SED) -i 's/\(README[-[:alnum:]]*\).md/\1.html/g' $@
 
-install:
+install: install-bin install-doc
+
+install-bin:
 	$(INSTALL) -D -m0755 bin/pacman-offline $(DESTDIR)/usr/bin/pacman-offline
 	$(INSTALL) -D -m0644 config/offline.conf $(DESTDIR)/etc/pacman.d/offline.conf
 	$(INSTALL) -D -m0644 hook/99-pacman-offline.hook $(DESTDIR)/usr/share/libalpm/hooks/99-pacman-offline.hook
@@ -28,6 +30,10 @@ install:
 	$(INSTALL) -d -m0755 $(DESTDIR)/usr/lib/systemd/system/system-update.target.wants/
 	$(LN) -s ../pacman-offline.service $(DESTDIR)/usr/lib/systemd/system/system-update.target.wants/pacman-offline.service
 
+install-doc: README.html
+	$(INSTALL) -D -m0644 README.md $(DESTDIR)/usr/share/doc/pacman-offline/README.md
+	$(INSTALL) -D -m0644 README.html $(DESTDIR)/usr/share/doc/pacman-offline/README.html
+
 clean:
 	$(RM) -f README.html
 
diff --git a/README.md b/README.md
index f4440aa..28d565b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,57 @@
 pacman-offline
 ==============
 
-Run offline system update with pacman.
+**Run offline system update with pacman.**
+
+The offline system update with pacman is achieved by integrating into
+[offline updates in systemd](https://www.freedesktop.org/software/systemd/man/systemd.offline-updates.html#/etc/system-update).
+In fact only two scripts and a number of systemd unit files are used to
+glue `systemd` and `pacman`.
+
+Requirements
+------------
+
+There are the runtime dependencies:
+
+* [pacman](https://archlinux.org/pacman/)
+* [systemd](https://www.github.com/systemd/systemd)
+
+Optional basic support for
+[plymouth](https://www.freedesktop.org/wiki/Software/Plymouth/) is
+integrated.
+
+Usage
+-----
+
+A single command `pacman-offline` is used to prepare the offline update.
+It accepts some arguments:
+
+* *-c*: clean before download
+* *-f*: force if other system-update is pending
+* *-h*: show help
+* *-r*: reboot and install immediately
+* *-t*: start timer for nightly reboot
+* *-y*: update sync databases
+
+Configuration
+-------------
+
+A sinppet for inclusion in `/etc/pacman.conf` is shipped. To make use of
+it add this line:
+
+    Include = /etc/pacman.d/offline.conf
+
+It will cause `pacman` to ignore linux packages and prevent breaking module
+loading. These packages are not ignored on offline update.
+
+Modify `/etc/pacman.d/offline.conf` to your needs by changing or adding
+packages.
+
+### Upstream
+
+URL:
+[GitHub.com](https://github.com/eworm-de/pacman-offline#pacman-offline)
+
+Mirror:
+[eworm.de](https://git.eworm.de/cgit.cgi/pacman-offline/)
+[GitLab.com](https://gitlab.com/eworm-de/pacman-offline#pacman-offline)
-- 
cgit v1.2.3-54-g00ecf