diff --git a/TODO b/TODO
index 603b87e36c..62263ceae0 100644
--- a/TODO
+++ b/TODO
@@ -649,7 +649,6 @@ Features:
- document systemd-journal-flush.service properly
- documentation: recommend to connect the timer units of a service to the service via Also= in [Install]
- man: document the very specific env the shutdown drop-in tools live in
- - man: extend runlevel(8) to mention that runlevels suck, and are dead. Maybe add runlevel(7) with a note about that too
- man: add more examples to man pages
- man: maybe sort directives in man pages, and take sections from --help and apply them to man too
diff --git a/man/runlevel.xml b/man/runlevel.xml
index fc1f523855..ca29c7c22c 100644
--- a/man/runlevel.xml
+++ b/man/runlevel.xml
@@ -51,10 +51,61 @@
- runlevel options
+ runlevel
+ options
+
+ Overview
+
+ "Runlevels" are an obsolete way to start and stop groups of
+ services used in SysV init. systemd provides a compatibility layer
+ that maps runlevels to targets, and associated binaries like
+ runlevel. Nevertheless, only one runlevel can
+ be "active" at a given time, while systemd can activate multiple
+ targets concurrently, so the mapping to runlevels is confusing
+ and only approximate. Runlevels should not be used in new code,
+ and are mostly useful as a shorthand way to refer the matching
+ systemd targets in kernel boot parameters.
+
+
+ Mapping between runlevels and systemd targets
+
+
+
+
+
+ Runlevel
+ Target
+
+
+
+
+ 0
+ poweroff.target
+
+
+ 1
+ rescue.target
+
+
+ 2, 3, 4
+ multi-user.target
+
+
+ 5
+ graphical.target
+
+
+ 6
+ reboot.target
+
+
+
+
+
+
Description
@@ -129,18 +180,11 @@
-
- Notes
-
- This is a legacy command available for compatibility only.
- It should not be used anymore, as the concept of runlevels is
- obsolete.
-
-
See Also
systemd1,
+ systemd.target5,
systemctl1