From 0ff4099a608e58970d6ad38cef5b27c53fd3bbf4 Mon Sep 17 00:00:00 2001
From: Ori Bernstein <ori@eigenstate.org>
Date: Wed, 20 Nov 2019 16:05:52 -0800
Subject: [PATCH] improve language in delay(9)

give the reader enough context to know when to use and not
use the delay family of functions.
---
 sys/man/9/delay | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/sys/man/9/delay b/sys/man/9/delay
index b17f743f3..1a41c85b8 100644
--- a/sys/man/9/delay
+++ b/sys/man/9/delay
@@ -15,18 +15,22 @@ Timer*	addclock0link(void(*clockf)(void), int ms)
 .I Delay
 busy waits for
 .I ms
-milliseconds, forced to be at least one millisecond on some architectures.
+milliseconds. The minimum value of
+.I ms
+is one on most architectures.
 .PP
 .I Microdelay
 works exactly the same as
 .I delay
 but using microseconds instead.
 .PP
-For delays on the order of clock ticks,
-.I tsleep
-(see
-.IR sleep (9))
-provides a better alternative to the busy waiting of these routines.
+These routines are intended for use in interrupt contexts,
+device reset and shutdown functions, and other places where
+the scheduler is unavailable.
+When you have a process context, and can sleep, consider
+.IR tsleep (9).
+.I Tsleep
+does not busy wait.
 .PP
 .I Addclock0link
 adds a new periodic timer to the current processor's timer list, with