From ab309f1ae917ea5a6ca4468dfb17cb0407977107 Mon Sep 17 00:00:00 2001
From: Cyrus Rahman <crahman@gmail.com>
Date: Tue, 21 Jun 2022 18:57:45 -0600
Subject: [PATCH] Add to and improve documentation.

---
 acpi_hidd.4    | 26 ++++++++++++++++++++++++--
 port/pkg-descr | 12 ++++++------
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/acpi_hidd.4 b/acpi_hidd.4
index fc4e93b..f5807b7 100644
--- a/acpi_hidd.4
+++ b/acpi_hidd.4
@@ -88,7 +88,7 @@ Notifications are passed to userland via
 and
 .Xr devd.conf 5
 for examples.
-The
+When an ACPI key is pressed, the
 .Nm
 driver sends events with the following attributes:
 .Pp
@@ -122,6 +122,27 @@ An integer corresponding to the new value of
 .Em hw.acpi.hidd.brightness .
 .El
 .Sh BUGS
+.Nm
+only manages the ACPI BIOS's primary monitor's brightness.  Use
+.Xr acpi_video 4
+and the
+.Xr evdev 4
+or
+.Xr devd 8
+interfaces to manage other displays.
+.Pp
+The
+.Xr acpi_video 4
+driver assumes that nothing else changes the ACPI BIOS brightness, and uses a
+cached value instead of asking the ACPI BIOS before reporting it through its
+.Xr sysctl 8 .
+To avoid confusion, when a system such as a window manager is managing the screen
+brightness, set
+\fIhw.acpi.hidd.brightness_keycontrol\fP=0,
+and do not write directly to
+.Em hw.acpi.hidd.brightness
+to adjust the brightness.
+.Pp
 The collection of key codes is very small at this time, comprising only the two that are
 present on the GPD MicroPC.  This does not prevent use of the driver with
 .Xr devd 8 ,
@@ -129,7 +150,8 @@ but contributions from users will make the
 .Xr  evdev 4
 interface more useful.
 Submit your computer's key/code pairs and its make and model as an issue at
-https://github.com/signetica/acpi_hidd.
+\fIhttps://github.com/signetica/acpi_hidd\fP.
+More detailed instructions are in the repository.
 .Pp
 For example:
 .Bd -literal -offset indent
diff --git a/port/pkg-descr b/port/pkg-descr
index 61180c9..36b0285 100644
--- a/port/pkg-descr
+++ b/port/pkg-descr
@@ -1,10 +1,10 @@
 The acpi_hidd kernel module provides driver services for ACPI HIDD
 hardware, in particular brightness and media control keyboard support.
 
-The driver has devd(8), evdev(4), and sysctl(8) interfaces; the sysctl(8) interface
-allows inspection and control of the screen brightness, the evdev(4) interface
-allows applications to directly receive keystrokes corresponding to ACPI events, and
-the devd(8) interface provides a way to have userland programs run when ACPI
-keys are pressed.
+The driver has devd(8), evdev(4), and sysctl(8) interfaces; the sysctl(8)
+interface allows inspection and control of the screen brightness, the evdev(4)
+interface allows applications to directly receive keystrokes corresponding to
+ACPI events, and the devd(8) interface provides a way to have userland
+programs run when ACPI keys are pressed.
 
-WWW: www.github.com/signetica/acpi_hidd
+WWW: https://www.github.com/signetica/acpi_hidd