From 93e9e341756bd7efe12cc2dbdfda1a718031ef12 Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@slava-pestovs-macbook-pro.local>
Date: Sun, 16 Nov 2008 06:02:13 -0600
Subject: [PATCH] Add $maybe markup element

---
 basis/alarms/alarms-docs.factor               |  2 +-
 basis/concurrency/locks/locks-docs.factor     |  6 +++---
 .../concurrency/promises/promises-docs.factor |  2 +-
 .../semaphores/semaphores-docs.factor         |  4 ++--
 basis/help/markup/markup.factor               |  9 ++++++++-
 basis/html/templates/chloe/chloe-docs.factor  |  2 +-
 basis/http/http-docs.factor                   |  2 +-
 .../servers/connection/connection-docs.factor |  4 ++--
 basis/io/timeouts/timeouts-docs.factor        |  4 ++--
 basis/math/intervals/intervals-docs.factor    | 20 +++++++++----------
 basis/threads/threads-docs.factor             |  4 ++--
 basis/ui/commands/commands-docs.factor        |  4 ++--
 basis/ui/gadgets/gadgets-docs.factor          |  4 ++--
 .../gadgets/scrollers/scrollers-docs.factor   |  2 +-
 basis/ui/gadgets/sliders/sliders-docs.factor  |  4 ++--
 basis/ui/gadgets/worlds/worlds-docs.factor    |  2 +-
 basis/ui/gestures/gestures-docs.factor        |  2 +-
 basis/ui/operations/operations-docs.factor    |  6 +++---
 basis/ui/ui-docs.factor                       |  2 +-
 basis/urls/urls-docs.factor                   |  6 +++---
 core/effects/effects-docs.factor              |  2 +-
 core/generic/generic-docs.factor              |  2 +-
 core/lexer/lexer-docs.factor                  |  6 +++---
 core/slots/slots-docs.factor                  |  2 +-
 24 files changed, 55 insertions(+), 48 deletions(-)

diff --git a/basis/alarms/alarms-docs.factor b/basis/alarms/alarms-docs.factor
index dac8b72dd5..2d494afca3 100644
--- a/basis/alarms/alarms-docs.factor
+++ b/basis/alarms/alarms-docs.factor
@@ -5,7 +5,7 @@ HELP: alarm
 { $class-description "An alarm. Can be passed to " { $link cancel-alarm } "." } ;
 
 HELP: add-alarm
-{ $values { "quot" quotation } { "time" timestamp } { "frequency" "a " { $link duration } " or " { $link f } } { "alarm" alarm } }
+{ $values { "quot" quotation } { "time" timestamp } { "frequency" { $maybe duration } } { "alarm" alarm } }
 { $description "Creates and registers an alarm. If " { $snippet "frequency" } " is " { $link f } ", this will be a one-time alarm, otherwise it will fire with the given frequency. The quotation will be called from the alarm thread." } ;
 
 HELP: later
diff --git a/basis/concurrency/locks/locks-docs.factor b/basis/concurrency/locks/locks-docs.factor
index a3cf2fc782..b74dcec384 100644
--- a/basis/concurrency/locks/locks-docs.factor
+++ b/basis/concurrency/locks/locks-docs.factor
@@ -14,7 +14,7 @@ HELP: <reentrant-lock>
 { $description "Creates a reentrant lock." } ;
 
 HELP: with-lock-timeout
-{ $values { "lock" lock } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }
+{ $values { "lock" lock } { "timeout" { $maybe duration } } { "quot" quotation } }
 { $description "Calls the quotation, ensuring that only one thread executes with the lock held at a time. If another thread is holding the lock, blocks until the thread releases the lock." }
 { $errors "Throws an error if the lock could not be acquired before the timeout expires. A timeout value of " { $link f } " means the thread is willing to wait indefinitely." } ;
 
@@ -36,7 +36,7 @@ HELP: rw-lock
 { $class-description "The class of reader/writer locks." } ;
 
 HELP: with-read-lock-timeout
-{ $values { "lock" lock } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }
+{ $values { "lock" lock } { "timeout" { $maybe duration } } { "quot" quotation } }
 { $description "Calls the quotation, ensuring that no other thread is holding a write lock at the same time. If another thread is holding a write lock, blocks until the thread releases the lock." }
 { $errors "Throws an error if the lock could not be acquired before the timeout expires. A timeout value of " { $link f } " means the thread is willing to wait indefinitely." } ;
 
@@ -45,7 +45,7 @@ HELP: with-read-lock
 { $description "Calls the quotation, ensuring that no other thread is holding a write lock at the same time. If another thread is holding a write lock, blocks until the thread releases the lock." } ;
 
 HELP: with-write-lock-timeout
-{ $values { "lock" lock } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }
+{ $values { "lock" lock } { "timeout" { $maybe duration } } { "quot" quotation } }
 { $description "Calls the quotation, ensuring that no other thread is holding a read or write lock at the same time. If another thread is holding a read or write lock, blocks until the thread releases the lock." }
 { $errors "Throws an error if the lock could not be acquired before the timeout expires. A timeout value of " { $link f } " means the thread is willing to wait indefinitely." } ;
 
diff --git a/basis/concurrency/promises/promises-docs.factor b/basis/concurrency/promises/promises-docs.factor
index 6a4a2bf8d6..be7a8cf65b 100644
--- a/basis/concurrency/promises/promises-docs.factor
+++ b/basis/concurrency/promises/promises-docs.factor
@@ -12,7 +12,7 @@ HELP: promise-fulfilled?
 { $description "Tests if " { $link fulfill } " has previously been called on the promise, in which case " { $link ?promise } " will return immediately without blocking." } ;
 
 HELP: ?promise-timeout
-{ $values { "promise" promise } { "timeout" "a " { $link duration } " or " { $link f } } { "result" object } }
+{ $values { "promise" promise } { "timeout" { $maybe duration } } { "result" object } }
 { $description "Waits for another thread to fulfill a promise, returning immediately if the promise has already been fulfilled. A timeout of " { $link f } " indicates that the thread may block indefinitely, otherwise it will wait up to " { $snippet "timeout" } " milliseconds." }
 { $errors "Throws an error if the timeout expires before the promise has been fulfilled." } ;
 
diff --git a/basis/concurrency/semaphores/semaphores-docs.factor b/basis/concurrency/semaphores/semaphores-docs.factor
index 379fd6a3a0..c86623f86f 100644
--- a/basis/concurrency/semaphores/semaphores-docs.factor
+++ b/basis/concurrency/semaphores/semaphores-docs.factor
@@ -9,7 +9,7 @@ HELP: <semaphore>
 { $description "Creates a counting semaphore with the specified initial count." } ;
 
 HELP: acquire-timeout
-{ $values { "semaphore" semaphore } { "timeout" "a " { $link duration } " or " { $link f } } }
+{ $values { "semaphore" semaphore } { "timeout" { $maybe duration } } }
 { $description "If the semaphore has a non-zero count, decrements it and returns immediately. Otherwise, if the timeout is " { $link f } ", waits indefinitely for the semaphore to be released. If the timeout is not " { $link f } ", waits a certain period of time, and if the semaphore still has not been released, throws an error." }
 { $errors "Throws an error if the timeout expires before the semaphore is released." } ;
 
@@ -22,7 +22,7 @@ HELP: release
 { $description "Increments a semaphore's count. If the count was previously zero, any threads waiting on the semaphore are woken up." } ;
 
 HELP: with-semaphore-timeout
-{ $values { "semaphore" semaphore } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }
+{ $values { "semaphore" semaphore } { "timeout" { $maybe duration } } { "quot" quotation } }
 { $description "Calls the quotation with the semaphore held." } ;
 
 HELP: with-semaphore
diff --git a/basis/help/markup/markup.factor b/basis/help/markup/markup.factor
index 1eae56cfcc..4410a6f780 100644
--- a/basis/help/markup/markup.factor
+++ b/basis/help/markup/markup.factor
@@ -234,7 +234,8 @@ ALIAS: $slot $snippet
     ] ($grid) ;
 
 : a/an ( str -- str )
-    first "aeiou" member? "an" "a" ? ;
+    [ first ] [ length ] bi 1 =
+    "afhilmnorsx" "aeiou" ? member? "an" "a" ? ;
 
 GENERIC: ($instance) ( element -- )
 
@@ -244,8 +245,14 @@ M: word ($instance)
 M: string ($instance)
     dup a/an write bl $snippet ;
 
+M: f ($instance)
+    drop { f } $link ;
+
 : $instance ( children -- ) first ($instance) ;
 
+: $maybe ( children -- )
+    $instance " or " print-element { f } $instance ;
+
 : values-row ( seq -- seq )
     unclip \ $snippet swap ?word-name 2array
     swap dup first word? [ \ $instance prefix ] when 2array ;
diff --git a/basis/html/templates/chloe/chloe-docs.factor b/basis/html/templates/chloe/chloe-docs.factor
index 402b6e68a9..a0faecd743 100644
--- a/basis/html/templates/chloe/chloe-docs.factor
+++ b/basis/html/templates/chloe/chloe-docs.factor
@@ -14,7 +14,7 @@ HELP: required-attr
 { $errors "Throws an error if the attribute is not specified." } ;
 
 HELP: optional-attr
-{ $values { "tag" tag } { "name" string } { "value" "a " { $link string } " or " { $link f } } }
+{ $values { "tag" tag } { "name" string } { "value" { $maybe string } } }
 { $description "Extracts an attribute from a tag." }
 { $notes "Outputs " { $link f } " if the attribute is not specified." } ;
 
diff --git a/basis/http/http-docs.factor b/basis/http/http-docs.factor
index 4db04f04aa..6fb5b73fad 100644
--- a/basis/http/http-docs.factor
+++ b/basis/http/http-docs.factor
@@ -81,7 +81,7 @@ HELP: delete-cookie
 { $side-effects "request/response" } ;
 
 HELP: get-cookie
-{ $values { "request/response" "a " { $link request } " or a " { $link response } } { "name" string } { "cookie/f" "a " { $link cookie } " or " { $link f } } }
+{ $values { "request/response" "a " { $link request } " or a " { $link response } } { "name" string } { "cookie/f" { $maybe cookie } } }
 { $description "Gets a named cookie from a request or response." } ;
 
 HELP: put-cookie
diff --git a/basis/io/servers/connection/connection-docs.factor b/basis/io/servers/connection/connection-docs.factor
index 22c40da3d7..b093840987 100644
--- a/basis/io/servers/connection/connection-docs.factor
+++ b/basis/io/servers/connection/connection-docs.factor
@@ -114,11 +114,11 @@ HELP: stop-this-server
 { $description "Stops the current threaded server, preventing it from accepting any more connections and returning to the caller of " { $link start-server } ". All client connections which have already been opened continue to be serviced." } ;
 
 HELP: secure-port
-{ $values { "n" "an " { $link integer } " or " { $link f } } }
+{ $values { "n" { $maybe integer } } }
 { $description "Outputs the port number on which the current threaded server accepts secure socket connections. Outputs " { $link f } " if the current threaded server does not accept secure socket connections." }
 { $notes "Can only be used from the dynamic scope of a " { $link handle-client* } " call." } ;
 
 HELP: insecure-port
-{ $values { "n" "an " { $link integer } " or " { $link f } } }
+{ $values { "n" { $maybe integer } } }
 { $description "Outputs the port number on which the current threaded server accepts ordinary socket connections. Outputs " { $link f } " if the current threaded server does not accept ordinary socket connections." }
 { $notes "Can only be used from the dynamic scope of a " { $link handle-client* } " call." } ;
diff --git a/basis/io/timeouts/timeouts-docs.factor b/basis/io/timeouts/timeouts-docs.factor
index b2927af362..fcaab80958 100644
--- a/basis/io/timeouts/timeouts-docs.factor
+++ b/basis/io/timeouts/timeouts-docs.factor
@@ -2,11 +2,11 @@ IN: io.timeouts
 USING: help.markup help.syntax math kernel calendar ;
 
 HELP: timeout
-{ $values { "obj" object } { "dt/f" "a " { $link duration } " or " { $link f } } }
+{ $values { "obj" object } { "dt/f" { $maybe duration } } }
 { $contract "Outputs an object's timeout." } ;
 
 HELP: set-timeout
-{ $values { "dt/f" "a " { $link duration } " or " { $link f } } { "obj" object } }
+{ $values { "dt/f" { $maybe duration } } { "obj" object } }
 { $contract "Sets an object's timeout." } ;
 
 HELP: cancel-operation
diff --git a/basis/math/intervals/intervals-docs.factor b/basis/math/intervals/intervals-docs.factor
index c5e5a6e7b8..5a96c7aceb 100644
--- a/basis/math/intervals/intervals-docs.factor
+++ b/basis/math/intervals/intervals-docs.factor
@@ -156,8 +156,8 @@ HELP: interval*
 { $description "Multiplies two intervals." } ;
 
 HELP: interval-shift
-{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
-{ $description "Shifts " { $snippet "i1" } " to the left by " { $snippet "i2" } " bits. Outputs " { $link f } " if the endpoints of either " { $snippet "i1" } " or " { $snippet "i2" } " are not integers." } ;
+{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
+{ $description "Shifts " { $snippet "i1" } " to the left by " { $snippet "i2" } " bits. Outputs " { $link full-interval } " if the endpoints of either " { $snippet "i1" } " or " { $snippet "i2" } " are not integers." } ;
 
 HELP: interval-max
 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
@@ -253,8 +253,8 @@ HELP: points>interval
 ;
 
 HELP: interval-shift-safe
-{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
-{ $description "Shifts " { $snippet "i1" } " to the left by " { $snippet "i2" } " bits. Outputs " { $link f } " if the endpoints of either " { $snippet "i1" } " or " { $snippet "i2" } " are not integers, or if the endpoints of " { $snippet "i2" } " are so large that the resulting interval will consume too much memory." } ;
+{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
+{ $description "Shifts " { $snippet "i1" } " to the left by " { $snippet "i2" } " bits. Outputs " { $link full-interval } " if the endpoints of either " { $snippet "i1" } " or " { $snippet "i2" } " are not integers, or if the endpoints of " { $snippet "i2" } " are so large that the resulting interval will consume too much memory." } ;
 
 HELP: incomparable
 { $description "Output value from " { $link interval<= } ", " { $link interval< } ", " { $link interval>= } " and " { $link interval> } " in the case where the result of the comparison is ambiguous." } ;
@@ -304,20 +304,20 @@ HELP: interval>points
 { $description "Outputs both endpoints of the interval." } ;
 
 HELP: assume<
-{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
-{ $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are less than all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
+{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
+{ $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are less than all points in " { $snippet "i2" } "." } ;
 
 HELP: assume<=
-{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
-{ $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are less or equal to all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
+{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
+{ $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are less or equal to all points in " { $snippet "i2" } "." } ;
 
 HELP: assume>
 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 { $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are greater than all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
 
 HELP: assume>=
-{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
-{ $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are greater than or equal to all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
+{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
+{ $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are greater than or equal to all points in " { $snippet "i2" } "." } ;
 
 HELP: integral-closure
 { $values { "i1" "an " { $link interval } " with integer end-points" } { "i2" "a closed " { $link interval } " with integer end-points" } }
diff --git a/basis/threads/threads-docs.factor b/basis/threads/threads-docs.factor
index 3c4715d3e3..f6f102c4b4 100644
--- a/basis/threads/threads-docs.factor
+++ b/basis/threads/threads-docs.factor
@@ -1,5 +1,5 @@
 USING: help.markup help.syntax kernel kernel.private io
-threads.private continuations dlists init quotations strings
+threads.private continuations init quotations strings
 assocs heaps boxes namespaces deques ;
 IN: threads
 
@@ -82,7 +82,7 @@ $nl
 { $notes "In most cases, user code should call " { $link spawn } " instead, however for control over the error handler quotation, threads can be created with " { $link <thread> } " then passed to " { $link (spawn) } "." } ;
 
 HELP: run-queue
-{ $values { "queue" dlist } }
+{ $values { "queue" deque } }
 { $var-description "Global variable holding the queue of runnable threads. Calls to " { $link yield } " switch to the thread which has been in the queue for the longest period of time."
 $nl
 "By convention, threads are queued with " { $link push-front } 
diff --git a/basis/ui/commands/commands-docs.factor b/basis/ui/commands/commands-docs.factor
index 25312ad868..5f1ff6dabd 100644
--- a/basis/ui/commands/commands-docs.factor
+++ b/basis/ui/commands/commands-docs.factor
@@ -71,7 +71,7 @@ HELP: command-word
 { $description "Outputs the word that will be executed by " { $link invoke-command } ". This is only used for documentation purposes." } ;
 
 HELP: command-map
-{ $values { "group" string } { "class" "a class word" } { "command-map" "a " { $link command-map } " or " { $link f } } }
+{ $values { "group" string } { "class" "a class word" } { "command-map" { $maybe command-map } } }
 { $description "Outputs a named command map defined on a class." }
 { $class-description "A command map stores a group of related commands. The " { $snippet "commands" } " slot stores an association list mapping gestures to commands, and the " { $snippet "blurb" } " slot stores an optional one-line description string of this command map."
 $nl
@@ -82,7 +82,7 @@ HELP: commands
 { $description "Outputs a hashtable mapping command map names to " { $link command-map } " instances." } ;
 
 HELP: define-command-map
-{ $values { "class" "a class word" } { "group" string } { "blurb" "a " { $link string } " or " { $link f } } { "pairs" "a sequence of gesture/word pairs" } }
+{ $values { "class" "a class word" } { "group" string } { "blurb" { $maybe string } } { "pairs" "a sequence of gesture/word pairs" } }
 { $description
     "Defines a command map on the specified gadget class. The " { $snippet "specs" } " parameter is a sequence of pairs " { $snippet "{ gesture word }" } ". The words must be valid commands; see " { $link define-command } "."
 }
diff --git a/basis/ui/gadgets/gadgets-docs.factor b/basis/ui/gadgets/gadgets-docs.factor
index 394841c599..5ab20364ee 100644
--- a/basis/ui/gadgets/gadgets-docs.factor
+++ b/basis/ui/gadgets/gadgets-docs.factor
@@ -34,7 +34,7 @@ HELP: children-on
 { $notes "This does not have to be an accurate intersection test, and simply returning " { $snippet "children" } " is a valid implementation. However, an accurate intersection test reduces the amount of work done when drawing this gadget if it is partially clipped and not all children are visible." } ;
 
 HELP: pick-up
-{ $values { "point" "a pair of integers" } { "gadget" gadget } { "child/f" "a " { $link gadget } " or " { $link f } } }
+{ $values { "point" "a pair of integers" } { "gadget" gadget } { "child/f" { $maybe gadget } } }
 { $description "Outputs the child at a point in the gadget's co-ordinate system. This word recursively descends the gadget hierarchy, and so outputs the deepest child." } ;
 
 HELP: max-dim
@@ -52,7 +52,7 @@ HELP: gadget-selection?
 { $contract "Outputs if the gadget has an active text selection; if so, the selected text can be obtained with a call to " { $link gadget-selection } "." } ;
 
 HELP: gadget-selection
-{ $values { "gadget" gadget } { "string/f" "a " { $link string } " or " { $link f } } }
+{ $values { "gadget" gadget } { "string/f" { $maybe string } } }
 { $contract "Outputs the gadget's text selection, or " { $link f } " if nothing is selected." } ;
 
 HELP: relayout
diff --git a/basis/ui/gadgets/scrollers/scrollers-docs.factor b/basis/ui/gadgets/scrollers/scrollers-docs.factor
index 3554c735a7..b248527c37 100644
--- a/basis/ui/gadgets/scrollers/scrollers-docs.factor
+++ b/basis/ui/gadgets/scrollers/scrollers-docs.factor
@@ -8,7 +8,7 @@ $nl
 "Scroller gadgets are created by calling " { $link <scroller> } "." } ;
 
 HELP: find-scroller
-{ $values { "gadget" gadget } { "scroller/f" "a " { $link scroller } " or " { $link f } } }
+{ $values { "gadget" gadget } { "scroller/f" { $maybe scroller } } }
 { $description "Finds the first parent of " { $snippet "gadget" } " which is a " { $link scroller } ". Outputs " { $link f } " if the gadget is not contained in a " { $link scroller } "." } ;
 
 HELP: scroller-value
diff --git a/basis/ui/gadgets/sliders/sliders-docs.factor b/basis/ui/gadgets/sliders/sliders-docs.factor
index 63284f135d..c130c724d0 100644
--- a/basis/ui/gadgets/sliders/sliders-docs.factor
+++ b/basis/ui/gadgets/sliders/sliders-docs.factor
@@ -5,7 +5,7 @@ HELP: elevator
 { $class-description "An elevator is the part of a " { $link slider } " between the up/down arrow buttons, where a " { $link thumb } " may be moved up and down." } ;
 
 HELP: find-elevator
-{ $values { "gadget" gadget } { "elevator/f" "an " { $link elevator } " or " { $link f } } }
+{ $values { "gadget" gadget } { "elevator/f" { $maybe elevator } } }
 { $description "Finds the first parent of " { $snippet "gadget" } " which is an " { $link elevator } ". Outputs " { $link f } " if the gadget is not contained in an " { $link elevator } "." } ;
 
 HELP: slider
@@ -14,7 +14,7 @@ $nl
 "Sliders are created by calling " { $link <x-slider> } " or " { $link <y-slider> } "." } ;
 
 HELP: find-slider
-{ $values { "gadget" gadget } { "slider/f" "a " { $link slider } " or " { $link f } } }
+{ $values { "gadget" gadget } { "slider/f" { $maybe slider } } }
 { $description "Finds the first parent of " { $snippet "gadget" } " which is a " { $link slider } ". Outputs " { $link f } " if the gadget is not contained in a " { $link slider } "." } ;
 
 HELP: thumb
diff --git a/basis/ui/gadgets/worlds/worlds-docs.factor b/basis/ui/gadgets/worlds/worlds-docs.factor
index 122d14eed7..9dd152885e 100644
--- a/basis/ui/gadgets/worlds/worlds-docs.factor
+++ b/basis/ui/gadgets/worlds/worlds-docs.factor
@@ -46,7 +46,7 @@ HELP: <world>
 { $description "Creates a new " { $link world } " delegating to the given gadget." } ;
 
 HELP: find-world
-{ $values { "gadget" gadget } { "world/f" "a " { $link world } " or " { $link f } } }
+{ $values { "gadget" gadget } { "world/f" { $maybe world } } }
 { $description "Finds the " { $link world } " containing the gadget, or outputs " { $link f } " if the gadget is not grafted." } ;
 
 HELP: draw-world
diff --git a/basis/ui/gestures/gestures-docs.factor b/basis/ui/gestures/gestures-docs.factor
index 0575ff17f0..3471bd2cdb 100644
--- a/basis/ui/gestures/gestures-docs.factor
+++ b/basis/ui/gestures/gestures-docs.factor
@@ -189,7 +189,7 @@ HELP: under-hand
 { $description "Outputs a sequence where the first element is the " { $link hand-world } " and the last is the " { $link hand-gadget } ", with all parents in between." } ;
 
 HELP: gesture>string
-{ $values { "gesture" "a gesture" } { "string/f" "a " { $link string } " or " { $link f } } }
+{ $values { "gesture" "a gesture" } { "string/f" { $maybe string } } }
 { $contract "Creates a human-readable string from a gesture object, returning " { $link f } " if the gesture does not have a human-readable form." }
 { $examples
     { $example "USING: io ui.gestures ;" "T{ key-down f { C+ } \"x\" } gesture>string print" "C+x" }
diff --git a/basis/ui/operations/operations-docs.factor b/basis/ui/operations/operations-docs.factor
index ebdf3eee1f..4ab17228b5 100644
--- a/basis/ui/operations/operations-docs.factor
+++ b/basis/ui/operations/operations-docs.factor
@@ -41,11 +41,11 @@ HELP: object-operations
 { $description "Outputs a sequence of operations applicable to the given object, by testing each defined operation's " { $snippet "predicate" } " quotation in turn." } ;
 
 HELP: primary-operation
-{ $values { "obj" object } { "operation" "an " { $link operation  } " or " { $link f } } }
+{ $values { "obj" object } { "operation" { $maybe operation } } }
 { $description "Outputs the operation which should be invoked when a presentation of " { $snippet "obj" } " is clicked." } ;
 
 HELP: secondary-operation
-{ $values { "obj" object } { "operation" "an " { $link operation  } " or " { $link f } } }
+{ $values { "obj" object } { "operation" { $maybe operation } } }
 { $description "Outputs the operation which should be invoked when a " { $snippet "RET" } " is pressed while a presentation of " { $snippet "obj" } " is selected in a list." } ;
 
 HELP: define-operation
@@ -61,7 +61,7 @@ HELP: define-operation
 } ;
 
 HELP: define-operation-map
-{ $values { "class" "a class word" } { "group" string } { "blurb" "a " { $link string } " or " { $link f } } { "object" object } { "hook" "a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } } { "translator" "a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } } }
+{ $values { "class" "a class word" } { "group" string } { "blurb" { $maybe string } } { "object" object } { "hook" "a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } } { "translator" "a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } } }
 { $description "Defines a command map named " { $snippet "group" } " on " { $snippet "class" } " consisting of operations applicable to " { $snippet "object" } ". The hook quotation is applied to the target gadget; the translator quotation is applied to the result of the hook. Finally the result of the translator is passed to the operation. A distinction is drawn between the hook and the translator because for listener operations, the hook runs in the event loop and the translator runs in the listener. This avoids polluting the listener output with large prettyprinted gadgets and long quotations." } ;
 
 HELP: $operations
diff --git a/basis/ui/ui-docs.factor b/basis/ui/ui-docs.factor
index d8c816d717..9dd3a712c0 100644
--- a/basis/ui/ui-docs.factor
+++ b/basis/ui/ui-docs.factor
@@ -23,7 +23,7 @@ HELP: fullscreen?
 { fullscreen? set-fullscreen? } related-words
 
 HELP: find-window
-{ $values { "quot" "a quotation with stack effect " { $snippet "( world -- ? )" } } { "world" "a " { $link world } " or " { $link f } } }
+{ $values { "quot" "a quotation with stack effect " { $snippet "( world -- ? )" } } { "world" { $maybe world } } }
 { $description "Finds a native window such that the gadget passed to " { $link open-window } " satisfies the quotation, outputting " { $link f } " if no such gadget could be found. The front-most native window is checked first." } ;
 
 HELP: register-window
diff --git a/basis/urls/urls-docs.factor b/basis/urls/urls-docs.factor
index b423e6b751..ce8a7be88c 100644
--- a/basis/urls/urls-docs.factor
+++ b/basis/urls/urls-docs.factor
@@ -77,7 +77,7 @@ HELP: ensure-port
 } ;
 
 HELP: parse-host
-{ $values { "string" string } { "host" string } { "port" "an " { $link integer } " or " { $link f } } }
+{ $values { "string" string } { "host" string } { "port" { $maybe integer } } }
 { $description "Splits a string of the form " { $snippet "host:port" } " into a host and a port number. If the port number is not specified, outputs " { $link f } "." }
 { $notes "This word is used by " { $link >url } ". It can also be used directly to parse " { $snippet "host:port" } " strings which are not full URLs." }
 { $examples
@@ -89,13 +89,13 @@ HELP: parse-host
 } ;
 
 HELP: protocol-port
-{ $values { "protocol" "a protocol string" } { "port" "an " { $link integer } " or " { $link f } } }
+{ $values { "protocol" "a protocol string" } { "port" { $maybe integer } } }
 { $description "Outputs the port number associated with a protocol, or " { $link f } " if the protocol is unknown." } ;
 
 HELP: query-param
 { $values
      { "url" url } { "key" string }
-    { "value" "a " { $link string } " or " { $link f } } }
+    { "value" { $maybe string } } }
 { $description "Outputs the URL-decoded value of a URL query parameter." }
 { $examples
     { $example
diff --git a/core/effects/effects-docs.factor b/core/effects/effects-docs.factor
index f9c18e410d..b209dcf259 100644
--- a/core/effects/effects-docs.factor
+++ b/core/effects/effects-docs.factor
@@ -68,5 +68,5 @@ HELP: effect>string
 } ;
 
 HELP: stack-effect
-{ $values { "word" word } { "effect/f" "an " { $link effect } " or " { $link f } } }
+{ $values { "word" word } { "effect/f" { $maybe effect } } }
 { $description "Outputs the stack effect of a word; either a stack effect declared with " { $link POSTPONE: ( } ", or an inferred stack effect (see " { $link "inference" } "." } ;
diff --git a/core/generic/generic-docs.factor b/core/generic/generic-docs.factor
index 396b3e8f9a..182cfbf419 100644
--- a/core/generic/generic-docs.factor
+++ b/core/generic/generic-docs.factor
@@ -127,7 +127,7 @@ HELP: method-body
 { $class-description "The class of method bodies, which are words with special word properties set." } ;
 
 HELP: method
-{ $values { "class" class } { "generic" generic } { "method/f" "a " { $link method-body } " or " { $link f } } }
+{ $values { "class" class } { "generic" generic } { "method/f" { $maybe method-body } } }
 { $description "Looks up a method definition." } ;
 
 { method create-method POSTPONE: M: } related-words
diff --git a/core/lexer/lexer-docs.factor b/core/lexer/lexer-docs.factor
index 67948cc8f9..ead3c15a37 100644
--- a/core/lexer/lexer-docs.factor
+++ b/core/lexer/lexer-docs.factor
@@ -54,11 +54,11 @@ HELP: still-parsing-line?
 { $description "Outputs " { $link f } " if the end of the current line has been reached, " { $link t } " otherwise." } ;
 
 HELP: parse-token
-{ $values { "lexer" lexer } { "str/f" "a " { $link string } " or " { $link f } } }
+{ $values { "lexer" lexer } { "str/f" { $maybe string } } }
 { $description "Reads the next token from the lexer. Tokens are delimited by whitespace, with the exception that " { $snippet "\"" } " is treated like a single token even when not followed by whitespace." } ;
 
 HELP: scan
-{ $values { "str/f" "a " { $link string } " or " { $link f } } }
+{ $values { "str/f" { $maybe string } } }
 { $description "Reads the next token from the lexer. See " { $link parse-token } " for details." }
 $parsing-note ;
 
@@ -73,7 +73,7 @@ HELP: parse-tokens
 $parsing-note ;
 
 HELP: unexpected
-{ $values { "want" "a " { $link word } " or " { $link f } } { "got" word } }
+{ $values { "want" { $maybe word } } { "got" word } }
 { $description "Throws an " { $link unexpected } " error." }
 { $error-description "Thrown by the parser if an unmatched closing delimiter is encountered." }
 { $examples
diff --git a/core/slots/slots-docs.factor b/core/slots/slots-docs.factor
index d2d7dc1102..c9ce334388 100644
--- a/core/slots/slots-docs.factor
+++ b/core/slots/slots-docs.factor
@@ -166,5 +166,5 @@ HELP: set-slot ( value obj n -- )
 { $warning "This word is in the " { $vocab-link "slots.private" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
 
 HELP: slot-named
-{ $values { "name" string } { "specs" "a sequence of " { $link slot-spec } " instances" } { "spec/f" "a " { $link slot-spec } " or " { $link f } } }
+{ $values { "name" string } { "specs" "a sequence of " { $link slot-spec } " instances" } { "spec/f" { $maybe slot-spec } } }
 { $description "Outputs the " { $link slot-spec } " with the given name." } ;