From 7fd71338dce041b352f84e7939f6966f4d379459 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Mon, 18 Apr 2022 01:41:13 +0300
Subject: [PATCH] Improve markup of boolean values nil/t

* dash.el (-flatten, dash--match-cons-1, -distinct, -unfold):
Remove `...' quoting around nil and t in docstrings and commentary,
as per (info "(elisp) Documentation Tips").
(-snoc): Make wording of docstring sound a bit more natural.
(-any?, -none?): Upcase metavariables in docstrings.

* dev/dash-defs.el (dash--booleans-to-md): New function.
(dash--docstring-to-md): Use it to mark up nil/t with backquotes.
(dash--docstring-to-texi): Mark up nil/t as @code.

* README.md:
* dash.texi: Regenerate docs.
---
 README.md        | 196 +++++++++++++++++++++++------------------------
 dash.el          |  14 ++--
 dash.texi        | 196 +++++++++++++++++++++++------------------------
 dev/dash-defs.el |  17 +++-
 4 files changed, 218 insertions(+), 205 deletions(-)

diff --git a/README.md b/README.md
index 076bd51..bfb20ea 100644
--- a/README.md
+++ b/README.md
@@ -407,7 +407,7 @@ This function's anaphoric counterpart is `--map`.
 #### -map-when `(pred rep list)`
 
 Use `pred` to conditionally apply `rep` to each item in `list`.
-Return a copy of `list` where the items for which `pred` returns nil
+Return a copy of `list` where the items for which `pred` returns `nil`
 are unchanged, and the rest are mapped through the `rep` function.
 
 Alias: `-replace-where`
@@ -424,7 +424,7 @@ See also: [`-update-at`](#-update-at-n-func-list)
 
 Use `pred` to determine the first item in `list` to call `rep` on.
 Return a copy of `list` where the first item for which `pred` returns
-non-nil is replaced with the result of calling `rep` on that item.
+non-`nil` is replaced with the result of calling `rep` on that item.
 
 See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-first`](#-replace-first-old-new-list)
 
@@ -438,7 +438,7 @@ See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-first`](#-replace-
 
 Use `pred` to determine the last item in `list` to call `rep` on.
 Return a copy of `list` where the last item for which `pred` returns
-non-nil is replaced with the result of calling `rep` on that item.
+non-`nil` is replaced with the result of calling `rep` on that item.
 
 See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-last`](#-replace-last-old-new-list)
 
@@ -531,7 +531,7 @@ Functions returning a sublist of the original list.
 
 #### -filter `(pred list)`
 
-Return a new list of the items in `list` for which `pred` returns non-nil.
+Return a new list of the items in `list` for which `pred` returns non-`nil`.
 
 Alias: `-select`.
 
@@ -547,7 +547,7 @@ For similar operations, see also [`-keep`](#-keep-fn-list) and [`-remove`](#-rem
 
 #### -remove `(pred list)`
 
-Return a new list of the items in `list` for which `pred` returns nil.
+Return a new list of the items in `list` for which `pred` returns `nil`.
 
 Alias: `-reject`.
 
@@ -563,7 +563,7 @@ For similar operations, see also [`-keep`](#-keep-fn-list) and [`-filter`](#-fil
 
 #### -remove-first `(pred list)`
 
-Remove the first item from `list` for which `pred` returns non-nil.
+Remove the first item from `list` for which `pred` returns non-`nil`.
 This is a non-destructive operation, but only the front of `list`
 leading up to the removed item is a copy; the rest is `list`'s
 original tail.  If no item is removed, then the result is a
@@ -583,7 +583,7 @@ See also [`-map-first`](#-map-first-pred-rep-list), [`-remove-item`](#-remove-it
 
 #### -remove-last `(pred list)`
 
-Remove the last item from `list` for which `pred` returns non-nil.
+Remove the last item from `list` for which `pred` returns non-`nil`.
 The result is a copy of `list` regardless of whether an element is
 removed.
 
@@ -612,7 +612,7 @@ The comparison is done with `equal`.
 
 #### -non-nil `(list)`
 
-Return a copy of `list` with all nil items removed.
+Return a copy of `list` with all `nil` items removed.
 
 ```el
 (-non-nil '(nil 1 nil 2 nil nil 3 4 nil 5 nil)) ;; => (1 2 3 4 5)
@@ -640,7 +640,7 @@ section is returned.  Defaults to 1.
 
 Return a copy of the first `n` items in `list`.
 Return a copy of `list` if it contains `n` items or fewer.
-Return nil if `n` is zero or less.
+Return `nil` if `n` is zero or less.
 
 See also: [`-take-last`](#-take-last-n-list).
 
@@ -654,7 +654,7 @@ See also: [`-take-last`](#-take-last-n-list).
 
 Return a copy of the last `n` items of `list` in order.
 Return a copy of `list` if it contains `n` items or fewer.
-Return nil if `n` is zero or less.
+Return `nil` if `n` is zero or less.
 
 See also: [`-take`](#-take-n-list).
 
@@ -667,7 +667,7 @@ See also: [`-take`](#-take-n-list).
 #### -drop `(n list)`
 
 Return the tail (not a copy) of `list` without the first `n` items.
-Return nil if `list` contains `n` items or fewer.
+Return `nil` if `list` contains `n` items or fewer.
 Return `list` if `n` is zero or less.
 
 For another variant, see also [`-drop-last`](#-drop-last-n-list).
@@ -682,7 +682,7 @@ For another variant, see also [`-drop-last`](#-drop-last-n-list).
 
 Return a copy of `list` without its last `n` items.
 Return a copy of `list` if `n` is zero or less.
-Return nil if `list` contains `n` items or fewer.
+Return `nil` if `list` contains `n` items or fewer.
 
 See also: [`-drop`](#-drop-n-list).
 
@@ -694,10 +694,10 @@ See also: [`-drop`](#-drop-n-list).
 
 #### -take-while `(pred list)`
 
-Take successive items from `list` for which `pred` returns non-nil.
+Take successive items from `list` for which `pred` returns non-`nil`.
 `pred` is a function of one argument.  Return a new list of the
 successive elements from the start of `list` for which `pred` returns
-non-nil.
+non-`nil`.
 
 This function's anaphoric counterpart is `--take-while`.
 
@@ -711,10 +711,10 @@ For another variant, see also [`-drop-while`](#-drop-while-pred-list).
 
 #### -drop-while `(pred list)`
 
-Drop successive items from `list` for which `pred` returns non-nil.
+Drop successive items from `list` for which `pred` returns non-`nil`.
 `pred` is a function of one argument.  Return the tail (not a copy)
 of `list` starting from its first element for which `pred` returns
-nil.
+`nil`.
 
 This function's anaphoric counterpart is `--drop-while`.
 
@@ -776,8 +776,8 @@ Functions returning a modified copy of the input list.
 
 #### -keep `(fn list)`
 
-Return a new list of the non-nil results of applying `fn` to each item in `list`.
-Like [`-filter`](#-filter-pred-list), but returns the non-nil results of `fn` instead of
+Return a new list of the non-`nil` results of applying `fn` to each item in `list`.
+Like [`-filter`](#-filter-pred-list), but returns the non-`nil` results of `fn` instead of
 the corresponding elements of `list`.
 
 Its anaphoric counterpart is `--keep`.
@@ -806,7 +806,7 @@ The last argument is not copied, just used as the tail of the new list.
 Take a nested list `l` and return its contents as a single, flat list.
 
 Note that because `nil` represents a list of zero elements (an
-empty list), any mention of nil in `l` will disappear after
+empty list), any mention of `nil` in `l` will disappear after
 flattening.  If you need to preserve nils, consider [`-flatten-n`](#-flatten-n-num-list)
 or map them to some unique symbol and then map them back.
 
@@ -1099,7 +1099,7 @@ For other folds, see also [`-reductions-r-from`](#-reductions-r-from-fn-init-lis
 
 #### -count `(pred list)`
 
-Counts the number of items in `list` where (`pred` item) is non-nil.
+Counts the number of items in `list` where (`pred` item) is non-`nil`.
 
 ```el
 (-count 'even? '(1 2 3 4 5)) ;; => 2
@@ -1281,7 +1281,7 @@ Reductions of one or more lists to a boolean value.
 
 #### -some `(pred list)`
 
-Return (`pred` x) for the first `list` item where (`pred` x) is non-nil, else nil.
+Return (`pred` x) for the first `list` item where (`pred` x) is non-`nil`, else `nil`.
 
 Alias: `-any`.
 
@@ -1295,13 +1295,13 @@ This function's anaphoric counterpart is `--some`.
 
 #### -every `(pred list)`
 
-Return non-nil if `pred` returns non-nil for all items in `list`.
+Return non-`nil` if `pred` returns non-`nil` for all items in `list`.
 If so, return the last such result of `pred`.  Otherwise, once an
-item is reached for which `pred` returns nil, return nil without
+item is reached for which `pred` returns `nil`, return `nil` without
 calling `pred` on any further `list` elements.
 
 This function is like `-every-p`, but on success returns the last
-non-nil result of `pred` instead of just t.
+non-`nil` result of `pred` instead of just `t`.
 
 This function's anaphoric counterpart is `--every`.
 
@@ -1313,7 +1313,7 @@ This function's anaphoric counterpart is `--every`.
 
 #### -any? `(pred list)`
 
-Return t if (`pred` x) is non-nil for any x in `list`, else nil.
+Return `t` if (`pred` `x`) is non-`nil` for any `x` in `list`, else `nil`.
 
 Alias: `-any-p`, `-some?`, `-some-p`
 
@@ -1325,12 +1325,12 @@ Alias: `-any-p`, `-some?`, `-some-p`
 
 #### -all? `(pred list)`
 
-Return t if (`pred` `x`) is non-nil for all `x` in `list`, else nil.
+Return `t` if (`pred` `x`) is non-`nil` for all `x` in `list`, else `nil`.
 In the latter case, stop after the first `x` for which (`pred` `x`) is
-nil, without calling `pred` on any subsequent elements of `list`.
+`nil`, without calling `pred` on any subsequent elements of `list`.
 
 The similar function [`-every`](#-every-pred-list) is more widely useful, since it
-returns the last non-nil result of `pred` instead of just t on
+returns the last non-`nil` result of `pred` instead of just `t` on
 success.
 
 Alias: `-all-p`, `-every-p`, `-every?`.
@@ -1345,7 +1345,7 @@ This function's anaphoric counterpart is `--all?`.
 
 #### -none? `(pred list)`
 
-Return t if (`pred` x) is nil for all x in `list`, else nil.
+Return `t` if (`pred` `x`) is `nil` for all `x` in `list`, else `nil`.
 
 Alias: `-none-p`
 
@@ -1357,9 +1357,9 @@ Alias: `-none-p`
 
 #### -only-some? `(pred list)`
 
-Return t if different `list` items both satisfy and do not satisfy `pred`.
-That is, if `pred` returns both nil for at least one item, and
-non-nil for at least one other item in `list`.  Return nil if all
+Return `t` if different `list` items both satisfy and do not satisfy `pred`.
+That is, if `pred` returns both `nil` for at least one item, and
+non-`nil` for at least one other item in `list`.  Return `nil` if all
 items satisfy the predicate or none of them do.
 
 Alias: `-only-some-p`
@@ -1372,10 +1372,10 @@ Alias: `-only-some-p`
 
 #### -contains? `(list element)`
 
-Return non-nil if `list` contains `element`.
+Return non-`nil` if `list` contains `element`.
 
 The test for equality is done with `equal`, or with `-compare-fn`
-if that's non-nil.
+if that's non-`nil`.
 
 Alias: `-contains-p`
 
@@ -1401,7 +1401,7 @@ Alias: `-same-items-p`
 
 #### -is-prefix? `(prefix list)`
 
-Return non-nil if `prefix` is a prefix of `list`.
+Return non-`nil` if `prefix` is a prefix of `list`.
 
 Alias: `-is-prefix-p`.
 
@@ -1413,7 +1413,7 @@ Alias: `-is-prefix-p`.
 
 #### -is-suffix? `(suffix list)`
 
-Return non-nil if `suffix` is a suffix of `list`.
+Return non-`nil` if `suffix` is a suffix of `list`.
 
 Alias: `-is-suffix-p`.
 
@@ -1425,7 +1425,7 @@ Alias: `-is-suffix-p`.
 
 #### -is-infix? `(infix list)`
 
-Return non-nil if `infix` is infix of `list`.
+Return non-`nil` if `infix` is infix of `list`.
 
 This operation runs in O(n^2) time
 
@@ -1439,7 +1439,7 @@ Alias: `-is-infix-p`
 
 #### -cons-pair? `(obj)`
 
-Return non-nil if `obj` is a true cons pair.
+Return non-`nil` if `obj` is a true cons pair.
 That is, a cons (`a` . `b`) where `b` is not a list.
 
 Alias: `-cons-pair-p`.
@@ -1505,7 +1505,7 @@ See also [`-split-when`](#-split-when-fn-list)
 
 #### -split-when `(fn list)`
 
-Split the `list` on each element where `fn` returns non-nil.
+Split the `list` on each element where `fn` returns non-`nil`.
 
 Unlike [`-partition-by`](#-partition-by-fn-list), the "matched" element is discarded from
 the results.  Empty lists are also removed from the result.
@@ -1606,7 +1606,7 @@ other value (the body).
 
 #### -partition-after-pred `(pred list)`
 
-Partition `list` after each element for which `pred` returns non-nil.
+Partition `list` after each element for which `pred` returns non-`nil`.
 
 This function's anaphoric counterpart is `--partition-after-pred`.
 
@@ -1665,7 +1665,7 @@ related predicates.
 #### -elem-index `(elem list)`
 
 Return the index of the first element in the given `list` which
-is equal to the query element `elem`, or nil if there is no
+is equal to the query element `elem`, or `nil` if there is no
 such element.
 
 ```el
@@ -1688,7 +1688,7 @@ element `elem`, in ascending order.
 #### -find-index `(pred list)`
 
 Take a predicate `pred` and a `list` and return the index of the
-first element in the list satisfying the predicate, or nil if
+first element in the list satisfying the predicate, or `nil` if
 there is no such element.
 
 See also [`-first`](#-first-pred-list).
@@ -1702,7 +1702,7 @@ See also [`-first`](#-first-pred-list).
 #### -find-last-index `(pred list)`
 
 Take a predicate `pred` and a `list` and return the index of the
-last element in the list satisfying the predicate, or nil if
+last element in the list satisfying the predicate, or `nil` if
 there is no such element.
 
 See also [`-last`](#-last-pred-list).
@@ -1753,7 +1753,7 @@ Operations pretending lists are sets.
 #### -union `(list list2)`
 
 Return a new list of all elements appearing in either `list1` or `list2`.
-Equality is defined by the value of `-compare-fn` if non-nil;
+Equality is defined by the value of `-compare-fn` if non-`nil`;
 otherwise `equal`.
 
 ```el
@@ -1766,7 +1766,7 @@ otherwise `equal`.
 
 Return a new list with only the members of `list` that are not in `list2`.
 The test for equality is done with `equal`,
-or with `-compare-fn` if that's non-nil.
+or with `-compare-fn` if that's non-`nil`.
 
 ```el
 (-difference () ()) ;; => ()
@@ -1777,7 +1777,7 @@ or with `-compare-fn` if that's non-nil.
 #### -intersection `(list list2)`
 
 Return a new list of the elements appearing in both `list1` and `list2`.
-Equality is defined by the value of `-compare-fn` if non-nil;
+Equality is defined by the value of `-compare-fn` if non-`nil`;
 otherwise `equal`.
 
 ```el
@@ -1809,7 +1809,7 @@ Return the permutations of `list`.
 
 Return a new list with all duplicates removed.
 The test for equality is done with `equal`,
-or with `-compare-fn` if that's non-nil.
+or with `-compare-fn` if that's non-`nil`.
 
 Alias: `-uniq`
 
@@ -1837,7 +1837,7 @@ The time complexity is O(n).
 #### -repeat `(n x)`
 
 Return a new list of length `n` with each element being `x`.
-Return nil if `n` is less than 1.
+Return `nil` if `n` is less than 1.
 
 ```el
 (-repeat 3 :a) ;; => (:a :a :a)
@@ -1850,7 +1850,7 @@ Return nil if `n` is less than 1.
 Make a new list from the elements of `args`.
 The last 2 elements of `args` are used as the final cons of the
 result, so if the final element of `args` is not a list, the result
-is a dotted list.  With no `args`, return nil.
+is a dotted list.  With no `args`, return `nil`.
 
 ```el
 (-cons* 1 2) ;; => (1 . 2)
@@ -1864,7 +1864,7 @@ Append `elem` to the end of the list.
 
 This is like `cons`, but operates on the end of list.
 
-If `elements` is non nil, append these to the list as well.
+If any `elements` are given, append them to the list as well.
 
 ```el
 (-snoc '(1 2 3) 4) ;; => (1 2 3 4)
@@ -2062,8 +2062,8 @@ See also: [`-flatten-n`](#-flatten-n-num-list), [`-table`](#-table-fn-rest-lists
 
 #### -first `(pred list)`
 
-Return the first item in `list` for which `pred` returns non-nil.
-Return nil if no such element is found.
+Return the first item in `list` for which `pred` returns non-`nil`.
+Return `nil` if no such element is found.
 To get the first item in the list no questions asked, use `car`.
 
 Alias: `-find`.
@@ -2078,7 +2078,7 @@ This function's anaphoric counterpart is `--first`.
 
 #### -last `(pred list)`
 
-Return the last x in `list` where (`pred` x) is non-nil, else nil.
+Return the last x in `list` where (`pred` x) is non-`nil`, else `nil`.
 
 ```el
 (-last 'even? '(1 2 3 4 5 6 3 3 3)) ;; => 6
@@ -2088,7 +2088,7 @@ Return the last x in `list` where (`pred` x) is non-nil, else nil.
 
 #### -first-item `(list)`
 
-Return the first item of `list`, or nil on an empty list.
+Return the first item of `list`, or `nil` on an empty list.
 
 See also: [`-second-item`](#-second-item-list), [`-last-item`](#-last-item-list).
 
@@ -2100,7 +2100,7 @@ See also: [`-second-item`](#-second-item-list), [`-last-item`](#-last-item-list)
 
 #### -second-item `(list)`
 
-Return the second item of `list`, or nil if `list` is too short.
+Return the second item of `list`, or `nil` if `list` is too short.
 
 See also: [`-third-item`](#-third-item-list).
 
@@ -2111,7 +2111,7 @@ See also: [`-third-item`](#-third-item-list).
 
 #### -third-item `(list)`
 
-Return the third item of `list`, or nil if `list` is too short.
+Return the third item of `list`, or `nil` if `list` is too short.
 
 See also: [`-fourth-item`](#-fourth-item-list).
 
@@ -2122,7 +2122,7 @@ See also: [`-fourth-item`](#-fourth-item-list).
 
 #### -fourth-item `(list)`
 
-Return the fourth item of `list`, or nil if `list` is too short.
+Return the fourth item of `list`, or `nil` if `list` is too short.
 
 See also: [`-fifth-item`](#-fifth-item-list).
 
@@ -2133,7 +2133,7 @@ See also: [`-fifth-item`](#-fifth-item-list).
 
 #### -fifth-item `(list)`
 
-Return the fifth item of `list`, or nil if `list` is too short.
+Return the fifth item of `list`, or `nil` if `list` is too short.
 
 See also: [`-last-item`](#-last-item-list).
 
@@ -2144,7 +2144,7 @@ See also: [`-last-item`](#-last-item-list).
 
 #### -last-item `(list)`
 
-Return the last item of `list`, or nil on an empty list.
+Return the last item of `list`, or `nil` on an empty list.
 
 ```el
 (-last-item '(1 2 3)) ;; => 3
@@ -2166,7 +2166,7 @@ Return a list of all items in list except for the last.
 
 Sort `list`, stably, comparing elements using `comparator`.
 Return the sorted list.  `list` is `not` modified by side effects.
-`comparator` is called with two elements of `list`, and should return non-nil
+`comparator` is called with two elements of `list`, and should return non-`nil`
 if the first element should sort before the second.
 
 ```el
@@ -2211,7 +2211,7 @@ Functions pretending lists are trees.
 
 Return a sequence of the nodes in `tree`, in depth-first search order.
 
-`branch` is a predicate of one argument that returns non-nil if the
+`branch` is a predicate of one argument that returns non-`nil` if the
 passed argument is a branch, that is, a node that can have children.
 
 `children` is a function of one argument that returns the children
@@ -2239,8 +2239,8 @@ Apply `fn` to each element of `tree` while preserving the tree structure.
 
 Call `fun` on each node of `tree` that satisfies `pred`.
 
-If `pred` returns nil, continue descending down this node.  If `pred`
-returns non-nil, apply `fun` to this node and do not descend
+If `pred` returns `nil`, continue descending down this node.  If `pred`
+returns non-`nil`, apply `fun` to this node and do not descend
 further.
 
 ```el
@@ -2388,8 +2388,8 @@ In the first form, bind `variable` to `value`.  In the second form, bind
 
 #### -some-> `(x &optional form &rest more)`
 
-When expr is non-nil, thread it through the first form (via [`->`](#--x-optional-form-rest-more)),
-and when that result is non-nil, through the next form, etc.
+When expr is non-`nil`, thread it through the first form (via [`->`](#--x-optional-form-rest-more)),
+and when that result is non-`nil`, through the next form, etc.
 
 ```el
 (-some-> '(2 3 5)) ;; => (2 3 5)
@@ -2399,8 +2399,8 @@ and when that result is non-nil, through the next form, etc.
 
 #### -some->> `(x &optional form &rest more)`
 
-When expr is non-nil, thread it through the first form (via [`->>`](#--x-optional-form-rest-more)),
-and when that result is non-nil, through the next form, etc.
+When expr is non-`nil`, thread it through the first form (via [`->>`](#--x-optional-form-rest-more)),
+and when that result is non-`nil`, through the next form, etc.
 
 ```el
 (-some->> '(1 2 3) (-map 'square)) ;; => (1 4 9)
@@ -2410,9 +2410,9 @@ and when that result is non-nil, through the next form, etc.
 
 #### -some--> `(expr &rest forms)`
 
-Thread `expr` through `forms` via [`-->`](#---x-rest-forms), while the result is non-nil.
-When `expr` evaluates to non-nil, thread the result through the
-first of `forms`, and when that result is non-nil, thread it
+Thread `expr` through `forms` via [`-->`](#---x-rest-forms), while the result is non-`nil`.
+When `expr` evaluates to non-`nil`, thread the result through the
+first of `forms`, and when that result is non-`nil`, thread it
 through the next form, etc.
 
 ```el
@@ -2440,7 +2440,7 @@ Macros that combine `let` and `let*` with destructuring and flow control.
 
 #### -when-let `((var val) &rest body)`
 
-If `val` evaluates to non-nil, bind it to `var` and execute body.
+If `val` evaluates to non-`nil`, bind it to `var` and execute body.
 
 Note: binding is done according to [`-let`](#-let-varlist-rest-body).
 
@@ -2457,7 +2457,7 @@ If all `vals` evaluate to true, bind them to their corresponding
 pairs.
 
 Note: binding is done according to [`-let*`](#-let-varlist-rest-body).  `vals` are evaluated
-sequentially, and evaluation stops after the first nil `val` is
+sequentially, and evaluation stops after the first `nil` `val` is
 encountered.
 
 ```el
@@ -2467,7 +2467,7 @@ encountered.
 
 #### -if-let `((var val) then &rest else)`
 
-If `val` evaluates to non-nil, bind it to `var` and do `then`,
+If `val` evaluates to non-`nil`, bind it to `var` and do `then`,
 otherwise do `else`.
 
 Note: binding is done according to [`-let`](#-let-varlist-rest-body).
@@ -2484,7 +2484,7 @@ If all `vals` evaluate to true, bind them to their corresponding
 of (`var` `val`) pairs.
 
 Note: binding is done according to [`-let*`](#-let-varlist-rest-body).  `vals` are evaluated
-sequentially, and evaluation stops after the first nil `val` is
+sequentially, and evaluation stops after the first `nil` `val` is
 encountered.
 
 ```el
@@ -2564,17 +2564,17 @@ Key/value stores:
 
     (&plist key0 a0 ... keyN aN) - bind value mapped by keyK in the
                                    `source` plist to aK.  If the
-                                   value is not found, aK is nil.
+                                   value is not found, aK is `nil`.
                                    Uses `plist-get` to fetch values.
 
     (&alist key0 a0 ... keyN aN) - bind value mapped by keyK in the
                                    `source` alist to aK.  If the
-                                   value is not found, aK is nil.
+                                   value is not found, aK is `nil`.
                                    Uses `assoc` to fetch values.
 
     (&hash key0 a0 ... keyN aN) - bind value mapped by keyK in the
                                   `source` hash table to aK.  If the
-                                  value is not found, aK is nil.
+                                  value is not found, aK is `nil`.
                                   Uses `gethash` to fetch values.
 
 Further, special keyword &keys supports "inline" matching of
@@ -2738,7 +2738,7 @@ Functions iterating over lists for side effect only.
 #### -each `(list fn)`
 
 Call `fn` on each element of `list`.
-Return nil; this function is intended for side effects.
+Return `nil`; this function is intended for side effects.
 
 Its anaphoric counterpart is `--each`.
 
@@ -2753,9 +2753,9 @@ For access to the current element's index in `list`, see
 
 #### -each-while `(list pred fn)`
 
-Call `fn` on each `item` in `list`, while (`pred` `item`) is non-nil.
-Once an `item` is reached for which `pred` returns nil, `fn` is no
-longer called.  Return nil; this function is intended for side
+Call `fn` on each `item` in `list`, while (`pred` `item`) is non-`nil`.
+Once an `item` is reached for which `pred` returns `nil`, `fn` is no
+longer called.  Return `nil`; this function is intended for side
 effects.
 
 Its anaphoric counterpart is `--each-while`.
@@ -2770,7 +2770,7 @@ Its anaphoric counterpart is `--each-while`.
 
 Call `fn` on each index and element of `list`.
 For each `item` at `index` in `list`, call (funcall `fn` `index` `item`).
-Return nil; this function is intended for side effects.
+Return `nil`; this function is intended for side effects.
 
 See also: [`-map-indexed`](#-map-indexed-fn-list).
 
@@ -2783,7 +2783,7 @@ See also: [`-map-indexed`](#-map-indexed-fn-list).
 #### -each-r `(list fn)`
 
 Call `fn` on each element of `list` in reversed order.
-Return nil; this function is intended for side effects.
+Return `nil`; this function is intended for side effects.
 
 Its anaphoric counterpart is `--each-r`.
 
@@ -2795,9 +2795,9 @@ Its anaphoric counterpart is `--each-r`.
 
 #### -each-r-while `(list pred fn)`
 
-Call `fn` on each `item` in reversed `list`, while (`pred` `item`) is non-nil.
-Once an `item` is reached for which `pred` returns nil, `fn` is no
-longer called.  Return nil; this function is intended for side
+Call `fn` on each `item` in reversed `list`, while (`pred` `item`) is non-`nil`.
+Once an `item` is reached for which `pred` returns `nil`, `fn` is no
+longer called.  Return `nil`; this function is intended for side
 effects.
 
 Its anaphoric counterpart is `--each-r-while`.
@@ -2998,7 +2998,7 @@ See `srfi-26` for detailed description.
 
 Return a predicate that negates the result of `pred`.
 The returned predicate passes its arguments to `pred`.  If `pred`
-returns nil, the result is non-nil; otherwise the result is nil.
+returns `nil`, the result is non-`nil`; otherwise the result is `nil`.
 
 See also: [`-andfn`](#-andfn-rest-preds) and [`-orfn`](#-orfn-rest-preds).
 
@@ -3010,12 +3010,12 @@ See also: [`-andfn`](#-andfn-rest-preds) and [`-orfn`](#-orfn-rest-preds).
 
 #### -orfn `(&rest preds)`
 
-Return a predicate that returns the first non-nil result of `preds`.
+Return a predicate that returns the first non-`nil` result of `preds`.
 The returned predicate takes a variable number of arguments,
 passes them to each predicate in `preds` in turn until one of them
-returns non-nil, and returns that non-nil result without calling
-the remaining `preds`.  If all `preds` return nil, or if no `preds` are
-given, the returned predicate returns nil.
+returns non-`nil`, and returns that non-`nil` result without calling
+the remaining `preds`.  If all `preds` return `nil`, or if no `preds` are
+given, the returned predicate returns `nil`.
 
 See also: [`-andfn`](#-andfn-rest-preds) and [`-not`](#-not-pred).
 
@@ -3027,12 +3027,12 @@ See also: [`-andfn`](#-andfn-rest-preds) and [`-not`](#-not-pred).
 
 #### -andfn `(&rest preds)`
 
-Return a predicate that returns non-nil if all `preds` do so.
+Return a predicate that returns non-`nil` if all `preds` do so.
 The returned predicate `p` takes a variable number of arguments and
 passes them to each predicate in `preds` in turn.  If any one of
-`preds` returns nil, `p` also returns nil without calling the
-remaining `preds`.  If all `preds` return non-nil, `p` returns the last
-such value.  If no `preds` are given, `p` always returns non-nil.
+`preds` returns `nil`, `p` also returns `nil` without calling the
+remaining `preds`.  If all `preds` return non-`nil`, `p` returns the last
+such value.  If no `preds` are given, `p` always returns non-`nil`.
 
 See also: [`-orfn`](#-orfn-rest-preds) and [`-not`](#-not-pred).
 
@@ -3077,11 +3077,11 @@ iteration halts when either of the following conditions is satisfied:
       numbers, it may be necessary to provide an appropriate
       approximate comparison test.
 
- 2. `halt-test` returns a non-nil value. `halt-test` defaults to a
-      simple counter that returns t after `-fixfn-max-iterations`,
+ 2. `halt-test` returns a non-`nil` value. `halt-test` defaults to a
+      simple counter that returns `t` after `-fixfn-max-iterations`,
       to guard against infinite iteration. Otherwise, `halt-test`
       must be a function that accepts a single argument, the
-      current value of `x`, and returns non-nil as long as iteration
+      current value of `x`, and returns non-`nil` as long as iteration
       should continue. In this way, a more sophisticated
       convergence test may be supplied by the caller.
 
diff --git a/dash.el b/dash.el
index 472ffa5..26e1f8b 100644
--- a/dash.el
+++ b/dash.el
@@ -720,7 +720,7 @@ N is the length of the returned list."
 (defun -flatten (l)
   "Take a nested list L and return its contents as a single, flat list.
 
-Note that because `nil' represents a list of zero elements (an
+Note that because nil represents a list of zero elements (an
 empty list), any mention of nil in L will disappear after
 flattening.  If you need to preserve nils, consider `-flatten-n'
 or map them to some unique symbol and then map them back.
@@ -803,7 +803,7 @@ is a dotted list.  With no ARGS, return nil."
 
 This is like `cons', but operates on the end of list.
 
-If ELEMENTS is non nil, append these to the list as well."
+If any ELEMENTS are given, append them to the list as well."
   (-concat list (list elem) elements))
 
 (defmacro --first (form list)
@@ -983,7 +983,7 @@ See also: `-last-item'."
   `(and (--some ,form ,list) t))
 
 (defun -any? (pred list)
-  "Return t if (PRED x) is non-nil for any x in LIST, else nil.
+  "Return t if (PRED X) is non-nil for any X in LIST, else nil.
 
 Alias: `-any-p', `-some?', `-some-p'"
   (--any? (funcall pred it) list))
@@ -1039,7 +1039,7 @@ This function's anaphoric counterpart is `--all?'."
   `(--all? (not ,form) ,list))
 
 (defun -none? (pred list)
-  "Return t if (PRED x) is nil for all x in LIST, else nil.
+  "Return t if (PRED X) is nil for all X in LIST, else nil.
 
 Alias: `-none-p'"
   (--none? (funcall pred it) list))
@@ -2012,7 +2012,7 @@ MATCH-FORM is either a symbol, which gets bound to the respective
 value in source or another match form which gets destructured
 recursively.
 
-If the cdr of last cons cell in the list is `nil', matching stops
+If the cdr of last cons cell in the list is nil, matching stops
 there.
 
 SOURCE is a proper or improper list."
@@ -2618,7 +2618,7 @@ Alias: `-uniq'"
   (let* ((len (length list))
          (lut (and (> len 32)
                    ;; Check that `-compare-fn' is a valid hash-table
-                   ;; lookup function or `nil'.
+                   ;; lookup function or nil.
                    (memq -compare-fn '(nil equal eq eql))
                    (make-hash-table :test (or -compare-fn #'equal)
                                     :size len))))
@@ -2901,7 +2901,7 @@ This is \"dual\" operation to `-reduce-r': while -reduce-r
 consumes a list to produce a single value, `-unfold' takes a
 seed value and builds a (potentially infinite!) list.
 
-FUN should return `nil' to stop the generating process, or a
+FUN should return nil to stop the generating process, or a
 cons (A . B), where A will be prepended to the result and B is
 the new seed."
   (let ((last (funcall fun seed)) r)
diff --git a/dash.texi b/dash.texi
index 9bcff91..5952cca 100644
--- a/dash.texi
+++ b/dash.texi
@@ -261,7 +261,7 @@ This function's anaphoric counterpart is @code{--map}.
 @anchor{-map-when}
 @defun -map-when (pred rep list)
 Use @var{pred} to conditionally apply @var{rep} to each item in @var{list}.
-Return a copy of @var{list} where the items for which @var{pred} returns nil
+Return a copy of @var{list} where the items for which @var{pred} returns @code{nil}
 are unchanged, and the rest are mapped through the @var{rep} function.
 
 Alias: @code{-replace-where}
@@ -288,7 +288,7 @@ See also: @code{-update-at} (@pxref{-update-at})
 @defun -map-first (pred rep list)
 Use @var{pred} to determine the first item in @var{list} to call @var{rep} on.
 Return a copy of @var{list} where the first item for which @var{pred} returns
-non-nil is replaced with the result of calling @var{rep} on that item.
+non-@code{nil} is replaced with the result of calling @var{rep} on that item.
 
 See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-replace-first})
 
@@ -312,7 +312,7 @@ See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-r
 @defun -map-last (pred rep list)
 Use @var{pred} to determine the last item in @var{list} to call @var{rep} on.
 Return a copy of @var{list} where the last item for which @var{pred} returns
-non-nil is replaced with the result of calling @var{rep} on that item.
+non-@code{nil} is replaced with the result of calling @var{rep} on that item.
 
 See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-last} (@pxref{-replace-last})
 
@@ -473,7 +473,7 @@ Functions returning a sublist of the original list.
 
 @anchor{-filter}
 @defun -filter (pred list)
-Return a new list of the items in @var{list} for which @var{pred} returns non-nil.
+Return a new list of the items in @var{list} for which @var{pred} returns non-@code{nil}.
 
 Alias: @code{-select}.
 
@@ -499,7 +499,7 @@ For similar operations, see also @code{-keep} (@pxref{-keep}) and @code{-remove}
 
 @anchor{-remove}
 @defun -remove (pred list)
-Return a new list of the items in @var{list} for which @var{pred} returns nil.
+Return a new list of the items in @var{list} for which @var{pred} returns @code{nil}.
 
 Alias: @code{-reject}.
 
@@ -525,7 +525,7 @@ For similar operations, see also @code{-keep} (@pxref{-keep}) and @code{-filter}
 
 @anchor{-remove-first}
 @defun -remove-first (pred list)
-Remove the first item from @var{list} for which @var{pred} returns non-nil.
+Remove the first item from @var{list} for which @var{pred} returns non-@code{nil}.
 This is a non-destructive operation, but only the front of @var{list}
 leading up to the removed item is a copy; the rest is @var{list}'s
 original tail.  If no item is removed, then the result is a
@@ -555,7 +555,7 @@ See also @code{-map-first} (@pxref{-map-first}), @code{-remove-item} (@pxref{-re
 
 @anchor{-remove-last}
 @defun -remove-last (pred list)
-Remove the last item from @var{list} for which @var{pred} returns non-nil.
+Remove the last item from @var{list} for which @var{pred} returns non-@code{nil}.
 The result is a copy of @var{list} regardless of whether an element is
 removed.
 
@@ -604,7 +604,7 @@ The comparison is done with @code{equal}.
 
 @anchor{-non-nil}
 @defun -non-nil (list)
-Return a copy of @var{list} with all nil items removed.
+Return a copy of @var{list} with all @code{nil} items removed.
 
 @example
 @group
@@ -652,7 +652,7 @@ section is returned.  Defaults to 1.
 @defun -take (n list)
 Return a copy of the first @var{n} items in @var{list}.
 Return a copy of @var{list} if it contains @var{n} items or fewer.
-Return nil if @var{n} is zero or less.
+Return @code{nil} if @var{n} is zero or less.
 
 See also: @code{-take-last} (@pxref{-take-last}).
 
@@ -676,7 +676,7 @@ See also: @code{-take-last} (@pxref{-take-last}).
 @defun -take-last (n list)
 Return a copy of the last @var{n} items of @var{list} in order.
 Return a copy of @var{list} if it contains @var{n} items or fewer.
-Return nil if @var{n} is zero or less.
+Return @code{nil} if @var{n} is zero or less.
 
 See also: @code{-take} (@pxref{-take}).
 
@@ -699,7 +699,7 @@ See also: @code{-take} (@pxref{-take}).
 @anchor{-drop}
 @defun -drop (n list)
 Return the tail (not a copy) of @var{list} without the first @var{n} items.
-Return nil if @var{list} contains @var{n} items or fewer.
+Return @code{nil} if @var{list} contains @var{n} items or fewer.
 Return @var{list} if @var{n} is zero or less.
 
 For another variant, see also @code{-drop-last} (@pxref{-drop-last}).
@@ -724,7 +724,7 @@ For another variant, see also @code{-drop-last} (@pxref{-drop-last}).
 @defun -drop-last (n list)
 Return a copy of @var{list} without its last @var{n} items.
 Return a copy of @var{list} if @var{n} is zero or less.
-Return nil if @var{list} contains @var{n} items or fewer.
+Return @code{nil} if @var{list} contains @var{n} items or fewer.
 
 See also: @code{-drop} (@pxref{-drop}).
 
@@ -746,10 +746,10 @@ See also: @code{-drop} (@pxref{-drop}).
 
 @anchor{-take-while}
 @defun -take-while (pred list)
-Take successive items from @var{list} for which @var{pred} returns non-nil.
+Take successive items from @var{list} for which @var{pred} returns non-@code{nil}.
 @var{pred} is a function of one argument.  Return a new list of the
 successive elements from the start of @var{list} for which @var{pred} returns
-non-nil.
+non-@code{nil}.
 
 This function's anaphoric counterpart is @code{--take-while}.
 
@@ -773,10 +773,10 @@ For another variant, see also @code{-drop-while} (@pxref{-drop-while}).
 
 @anchor{-drop-while}
 @defun -drop-while (pred list)
-Drop successive items from @var{list} for which @var{pred} returns non-nil.
+Drop successive items from @var{list} for which @var{pred} returns non-@code{nil}.
 @var{pred} is a function of one argument.  Return the tail (not a copy)
 of @var{list} starting from its first element for which @var{pred} returns
-nil.
+@code{nil}.
 
 This function's anaphoric counterpart is @code{--drop-while}.
 
@@ -873,8 +873,8 @@ Functions returning a modified copy of the input list.
 
 @anchor{-keep}
 @defun -keep (fn list)
-Return a new list of the non-nil results of applying @var{fn} to each item in @var{list}.
-Like @code{-filter} (@pxref{-filter}), but returns the non-nil results of @var{fn} instead of
+Return a new list of the non-@code{nil} results of applying @var{fn} to each item in @var{list}.
+Like @code{-filter} (@pxref{-filter}), but returns the non-@code{nil} results of @var{fn} instead of
 the corresponding elements of @var{list}.
 
 Its anaphoric counterpart is @code{--keep}.
@@ -923,7 +923,7 @@ The last argument is not copied, just used as the tail of the new list.
 Take a nested list @var{l} and return its contents as a single, flat list.
 
 Note that because @code{nil} represents a list of zero elements (an
-empty list), any mention of nil in @var{l} will disappear after
+empty list), any mention of @code{nil} in @var{l} will disappear after
 flattening.  If you need to preserve nils, consider @code{-flatten-n} (@pxref{-flatten-n})
 or map them to some unique symbol and then map them back.
 
@@ -1394,7 +1394,7 @@ For other folds, see also @code{-reductions-r-from} (@pxref{-reductions-r-from})
 
 @anchor{-count}
 @defun -count (pred list)
-Counts the number of items in @var{list} where (@var{pred} item) is non-nil.
+Counts the number of items in @var{list} where (@var{pred} item) is non-@code{nil}.
 
 @example
 @group
@@ -1725,7 +1725,7 @@ Reductions of one or more lists to a boolean value.
 
 @anchor{-some}
 @defun -some (pred list)
-Return (@var{pred} x) for the first @var{list} item where (@var{pred} x) is non-nil, else nil.
+Return (@var{pred} x) for the first @var{list} item where (@var{pred} x) is non-@code{nil}, else @code{nil}.
 
 Alias: @code{-any}.
 
@@ -1749,13 +1749,13 @@ This function's anaphoric counterpart is @code{--some}.
 
 @anchor{-every}
 @defun -every (pred list)
-Return non-nil if @var{pred} returns non-nil for all items in @var{list}.
+Return non-@code{nil} if @var{pred} returns non-@code{nil} for all items in @var{list}.
 If so, return the last such result of @var{pred}.  Otherwise, once an
-item is reached for which @var{pred} returns nil, return nil without
+item is reached for which @var{pred} returns @code{nil}, return @code{nil} without
 calling @var{pred} on any further @var{list} elements.
 
 This function is like @code{-every-p}, but on success returns the last
-non-nil result of @var{pred} instead of just t.
+non-@code{nil} result of @var{pred} instead of just @code{t}.
 
 This function's anaphoric counterpart is @code{--every}.
 
@@ -1777,7 +1777,7 @@ This function's anaphoric counterpart is @code{--every}.
 
 @anchor{-any?}
 @defun -any? (pred list)
-Return t if (@var{pred} x) is non-nil for any x in @var{list}, else nil.
+Return @code{t} if (@var{pred} @var{x}) is non-@code{nil} for any @var{x} in @var{list}, else @code{nil}.
 
 Alias: @code{-any-p}, @code{-some?}, @code{-some-p}
 
@@ -1799,12 +1799,12 @@ Alias: @code{-any-p}, @code{-some?}, @code{-some-p}
 
 @anchor{-all?}
 @defun -all? (pred list)
-Return t if (@var{pred} @var{x}) is non-nil for all @var{x} in @var{list}, else nil.
+Return @code{t} if (@var{pred} @var{x}) is non-@code{nil} for all @var{x} in @var{list}, else @code{nil}.
 In the latter case, stop after the first @var{x} for which (@var{pred} @var{x}) is
-nil, without calling @var{pred} on any subsequent elements of @var{list}.
+@code{nil}, without calling @var{pred} on any subsequent elements of @var{list}.
 
 The similar function @code{-every} (@pxref{-every}) is more widely useful, since it
-returns the last non-nil result of @var{pred} instead of just t on
+returns the last non-@code{nil} result of @var{pred} instead of just @code{t} on
 success.
 
 Alias: @code{-all-p}, @code{-every-p}, @code{-every?}.
@@ -1829,7 +1829,7 @@ This function's anaphoric counterpart is @code{--all?}.
 
 @anchor{-none?}
 @defun -none? (pred list)
-Return t if (@var{pred} x) is nil for all x in @var{list}, else nil.
+Return @code{t} if (@var{pred} @var{x}) is @code{nil} for all @var{x} in @var{list}, else @code{nil}.
 
 Alias: @code{-none-p}
 
@@ -1851,9 +1851,9 @@ Alias: @code{-none-p}
 
 @anchor{-only-some?}
 @defun -only-some? (pred list)
-Return t if different @var{list} items both satisfy and do not satisfy @var{pred}.
-That is, if @var{pred} returns both nil for at least one item, and
-non-nil for at least one other item in @var{list}.  Return nil if all
+Return @code{t} if different @var{list} items both satisfy and do not satisfy @var{pred}.
+That is, if @var{pred} returns both @code{nil} for at least one item, and
+non-@code{nil} for at least one other item in @var{list}.  Return @code{nil} if all
 items satisfy the predicate or none of them do.
 
 Alias: @code{-only-some-p}
@@ -1876,10 +1876,10 @@ Alias: @code{-only-some-p}
 
 @anchor{-contains?}
 @defun -contains? (list element)
-Return non-nil if @var{list} contains @var{element}.
+Return non-@code{nil} if @var{list} contains @var{element}.
 
 The test for equality is done with @code{equal}, or with @code{-compare-fn}
-if that's non-nil.
+if that's non-@code{nil}.
 
 Alias: @code{-contains-p}
 
@@ -1925,7 +1925,7 @@ Alias: @code{-same-items-p}
 
 @anchor{-is-prefix?}
 @defun -is-prefix? (prefix list)
-Return non-nil if @var{prefix} is a prefix of @var{list}.
+Return non-@code{nil} if @var{prefix} is a prefix of @var{list}.
 
 Alias: @code{-is-prefix-p}.
 
@@ -1947,7 +1947,7 @@ Alias: @code{-is-prefix-p}.
 
 @anchor{-is-suffix?}
 @defun -is-suffix? (suffix list)
-Return non-nil if @var{suffix} is a suffix of @var{list}.
+Return non-@code{nil} if @var{suffix} is a suffix of @var{list}.
 
 Alias: @code{-is-suffix-p}.
 
@@ -1969,7 +1969,7 @@ Alias: @code{-is-suffix-p}.
 
 @anchor{-is-infix?}
 @defun -is-infix? (infix list)
-Return non-nil if @var{infix} is infix of @var{list}.
+Return non-@code{nil} if @var{infix} is infix of @var{list}.
 
 This operation runs in @var{o}(n^2) time
 
@@ -1993,7 +1993,7 @@ Alias: @code{-is-infix-p}
 
 @anchor{-cons-pair?}
 @defun -cons-pair? (obj)
-Return non-nil if @var{obj} is a true cons pair.
+Return non-@code{nil} if @var{obj} is a true cons pair.
 That is, a cons (@var{a} . @var{b}) where @var{b} is not a list.
 
 Alias: @code{-cons-pair-p}.
@@ -2100,7 +2100,7 @@ See also @code{-split-when} (@pxref{-split-when})
 
 @anchor{-split-when}
 @defun -split-when (fn list)
-Split the @var{list} on each element where @var{fn} returns non-nil.
+Split the @var{list} on each element where @var{fn} returns non-@code{nil}.
 
 Unlike @code{-partition-by} (@pxref{-partition-by}), the "matched" element is discarded from
 the results.  Empty lists are also removed from the result.
@@ -2281,7 +2281,7 @@ other value (the body).
 
 @anchor{-partition-after-pred}
 @defun -partition-after-pred (pred list)
-Partition @var{list} after each element for which @var{pred} returns non-nil.
+Partition @var{list} after each element for which @var{pred} returns non-@code{nil}.
 
 This function's anaphoric counterpart is @code{--partition-after-pred}.
 
@@ -2391,7 +2391,7 @@ related predicates.
 @anchor{-elem-index}
 @defun -elem-index (elem list)
 Return the index of the first element in the given @var{list} which
-is equal to the query element @var{elem}, or nil if there is no
+is equal to the query element @var{elem}, or @code{nil} if there is no
 such element.
 
 @example
@@ -2434,7 +2434,7 @@ element @var{elem}, in ascending order.
 @anchor{-find-index}
 @defun -find-index (pred list)
 Take a predicate @var{pred} and a @var{list} and return the index of the
-first element in the list satisfying the predicate, or nil if
+first element in the list satisfying the predicate, or @code{nil} if
 there is no such element.
 
 See also @code{-first} (@pxref{-first}).
@@ -2458,7 +2458,7 @@ See also @code{-first} (@pxref{-first}).
 @anchor{-find-last-index}
 @defun -find-last-index (pred list)
 Take a predicate @var{pred} and a @var{list} and return the index of the
-last element in the list satisfying the predicate, or nil if
+last element in the list satisfying the predicate, or @code{nil} if
 there is no such element.
 
 See also @code{-last} (@pxref{-last}).
@@ -2544,7 +2544,7 @@ Operations pretending lists are sets.
 @anchor{-union}
 @defun -union (list list2)
 Return a new list of all elements appearing in either @var{list1} or @var{list2}.
-Equality is defined by the value of @code{-compare-fn} if non-nil;
+Equality is defined by the value of @code{-compare-fn} if non-@code{nil};
 otherwise @code{equal}.
 
 @example
@@ -2567,7 +2567,7 @@ otherwise @code{equal}.
 @defun -difference (list list2)
 Return a new list with only the members of @var{list} that are not in @var{list2}.
 The test for equality is done with @code{equal},
-or with @code{-compare-fn} if that's non-nil.
+or with @code{-compare-fn} if that's non-@code{nil}.
 
 @example
 @group
@@ -2588,7 +2588,7 @@ or with @code{-compare-fn} if that's non-nil.
 @anchor{-intersection}
 @defun -intersection (list list2)
 Return a new list of the elements appearing in both @var{list1} and @var{list2}.
-Equality is defined by the value of @code{-compare-fn} if non-nil;
+Equality is defined by the value of @code{-compare-fn} if non-@code{nil};
 otherwise @code{equal}.
 
 @example
@@ -2647,7 +2647,7 @@ Return the permutations of @var{list}.
 @defun -distinct (list)
 Return a new list with all duplicates removed.
 The test for equality is done with @code{equal},
-or with @code{-compare-fn} if that's non-nil.
+or with @code{-compare-fn} if that's non-@code{nil}.
 
 Alias: @code{-uniq}
 
@@ -2696,7 +2696,7 @@ The time complexity is @var{o}(n).
 @anchor{-repeat}
 @defun -repeat (n x)
 Return a new list of length @var{n} with each element being @var{x}.
-Return nil if @var{n} is less than 1.
+Return @code{nil} if @var{n} is less than 1.
 
 @example
 @group
@@ -2719,7 +2719,7 @@ Return nil if @var{n} is less than 1.
 Make a new list from the elements of @var{args}.
 The last 2 elements of @var{args} are used as the final cons of the
 result, so if the final element of @var{args} is not a list, the result
-is a dotted list.  With no @var{args}, return nil.
+is a dotted list.  With no @var{args}, return @code{nil}.
 
 @example
 @group
@@ -2743,7 +2743,7 @@ Append @var{elem} to the end of the list.
 
 This is like @code{cons}, but operates on the end of list.
 
-If @var{elements} is non nil, append these to the list as well.
+If any @var{elements} are given, append them to the list as well.
 
 @example
 @group
@@ -3065,8 +3065,8 @@ See also: @code{-flatten-n} (@pxref{-flatten-n}), @code{-table} (@pxref{-table})
 
 @anchor{-first}
 @defun -first (pred list)
-Return the first item in @var{list} for which @var{pred} returns non-nil.
-Return nil if no such element is found.
+Return the first item in @var{list} for which @var{pred} returns non-@code{nil}.
+Return @code{nil} if no such element is found.
 To get the first item in the list no questions asked, use @code{car}.
 
 Alias: @code{-find}.
@@ -3091,7 +3091,7 @@ This function's anaphoric counterpart is @code{--first}.
 
 @anchor{-last}
 @defun -last (pred list)
-Return the last x in @var{list} where (@var{pred} x) is non-nil, else nil.
+Return the last x in @var{list} where (@var{pred} x) is non-@code{nil}, else @code{nil}.
 
 @example
 @group
@@ -3111,7 +3111,7 @@ Return the last x in @var{list} where (@var{pred} x) is non-nil, else nil.
 
 @anchor{-first-item}
 @defun -first-item (list)
-Return the first item of @var{list}, or nil on an empty list.
+Return the first item of @var{list}, or @code{nil} on an empty list.
 
 See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} (@pxref{-last-item}).
 
@@ -3133,7 +3133,7 @@ See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} (@pxref{
 
 @anchor{-second-item}
 @defun -second-item (list)
-Return the second item of @var{list}, or nil if @var{list} is too short.
+Return the second item of @var{list}, or @code{nil} if @var{list} is too short.
 
 See also: @code{-third-item} (@pxref{-third-item}).
 
@@ -3151,7 +3151,7 @@ See also: @code{-third-item} (@pxref{-third-item}).
 
 @anchor{-third-item}
 @defun -third-item (list)
-Return the third item of @var{list}, or nil if @var{list} is too short.
+Return the third item of @var{list}, or @code{nil} if @var{list} is too short.
 
 See also: @code{-fourth-item} (@pxref{-fourth-item}).
 
@@ -3169,7 +3169,7 @@ See also: @code{-fourth-item} (@pxref{-fourth-item}).
 
 @anchor{-fourth-item}
 @defun -fourth-item (list)
-Return the fourth item of @var{list}, or nil if @var{list} is too short.
+Return the fourth item of @var{list}, or @code{nil} if @var{list} is too short.
 
 See also: @code{-fifth-item} (@pxref{-fifth-item}).
 
@@ -3187,7 +3187,7 @@ See also: @code{-fifth-item} (@pxref{-fifth-item}).
 
 @anchor{-fifth-item}
 @defun -fifth-item (list)
-Return the fifth item of @var{list}, or nil if @var{list} is too short.
+Return the fifth item of @var{list}, or @code{nil} if @var{list} is too short.
 
 See also: @code{-last-item} (@pxref{-last-item}).
 
@@ -3205,7 +3205,7 @@ See also: @code{-last-item} (@pxref{-last-item}).
 
 @anchor{-last-item}
 @defun -last-item (list)
-Return the last item of @var{list}, or nil on an empty list.
+Return the last item of @var{list}, or @code{nil} on an empty list.
 
 @example
 @group
@@ -3247,7 +3247,7 @@ Return a list of all items in list except for the last.
 @defun -sort (comparator list)
 Sort @var{list}, stably, comparing elements using @var{comparator}.
 Return the sorted list.  @var{list} is @var{not} modified by side effects.
-@var{comparator} is called with two elements of @var{list}, and should return non-nil
+@var{comparator} is called with two elements of @var{list}, and should return non-@code{nil}
 if the first element should sort before the second.
 
 @example
@@ -3320,7 +3320,7 @@ Functions pretending lists are trees.
 @defun -tree-seq (branch children tree)
 Return a sequence of the nodes in @var{tree}, in depth-first search order.
 
-@var{branch} is a predicate of one argument that returns non-nil if the
+@var{branch} is a predicate of one argument that returns non-@code{nil} if the
 passed argument is a branch, that is, a node that can have children.
 
 @var{children} is a function of one argument that returns the children
@@ -3368,8 +3368,8 @@ Apply @var{fn} to each element of @var{tree} while preserving the tree structure
 @defun -tree-map-nodes (pred fun tree)
 Call @var{fun} on each node of @var{tree} that satisfies @var{pred}.
 
-If @var{pred} returns nil, continue descending down this node.  If @var{pred}
-returns non-nil, apply @var{fun} to this node and do not descend
+If @var{pred} returns @code{nil}, continue descending down this node.  If @var{pred}
+returns non-@code{nil}, apply @var{fun} to this node and do not descend
 further.
 
 @example
@@ -3609,8 +3609,8 @@ In the first form, bind @var{variable} to @var{value}.  In the second form, bind
 
 @anchor{-some->}
 @defmac -some-> (x &optional form &rest more)
-When expr is non-nil, thread it through the first form (via @code{->} (@pxref{->})),
-and when that result is non-nil, through the next form, etc.
+When expr is non-@code{nil}, thread it through the first form (via @code{->} (@pxref{->})),
+and when that result is non-@code{nil}, through the next form, etc.
 
 @example
 @group
@@ -3630,8 +3630,8 @@ and when that result is non-nil, through the next form, etc.
 
 @anchor{-some->>}
 @defmac -some->> (x &optional form &rest more)
-When expr is non-nil, thread it through the first form (via @code{->>} (@pxref{->>})),
-and when that result is non-nil, through the next form, etc.
+When expr is non-@code{nil}, thread it through the first form (via @code{->>} (@pxref{->>})),
+and when that result is non-@code{nil}, through the next form, etc.
 
 @example
 @group
@@ -3651,9 +3651,9 @@ and when that result is non-nil, through the next form, etc.
 
 @anchor{-some-->}
 @defmac -some--> (expr &rest forms)
-Thread @var{expr} through @var{forms} via @code{-->} (@pxref{-->}), while the result is non-nil.
-When @var{expr} evaluates to non-nil, thread the result through the
-first of @var{forms}, and when that result is non-nil, thread it
+Thread @var{expr} through @var{forms} via @code{-->} (@pxref{-->}), while the result is non-@code{nil}.
+When @var{expr} evaluates to non-@code{nil}, thread the result through the
+first of @var{forms}, and when that result is non-@code{nil}, thread it
 through the next form, etc.
 
 @example
@@ -3702,7 +3702,7 @@ Macros that combine @code{let} and @code{let*} with destructuring and flow contr
 
 @anchor{-when-let}
 @defmac -when-let ((var val) &rest body)
-If @var{val} evaluates to non-nil, bind it to @var{var} and execute body.
+If @var{val} evaluates to non-@code{nil}, bind it to @var{var} and execute body.
 
 Note: binding is done according to @code{-let} (@pxref{-let}).
 
@@ -3729,7 +3729,7 @@ If all @var{vals} evaluate to true, bind them to their corresponding
 pairs.
 
 Note: binding is done according to @code{-let*} (@pxref{-let*}).  @var{vals} are evaluated
-sequentially, and evaluation stops after the first nil @var{val} is
+sequentially, and evaluation stops after the first @code{nil} @var{val} is
 encountered.
 
 @example
@@ -3746,7 +3746,7 @@ encountered.
 
 @anchor{-if-let}
 @defmac -if-let ((var val) then &rest else)
-If @var{val} evaluates to non-nil, bind it to @var{var} and do @var{then},
+If @var{val} evaluates to non-@code{nil}, bind it to @var{var} and do @var{then},
 otherwise do @var{else}.
 
 Note: binding is done according to @code{-let} (@pxref{-let}).
@@ -3770,7 +3770,7 @@ If all @var{vals} evaluate to true, bind them to their corresponding
 of (@var{var} @var{val}) pairs.
 
 Note: binding is done according to @code{-let*} (@pxref{-let*}).  @var{vals} are evaluated
-sequentially, and evaluation stops after the first nil @var{val} is
+sequentially, and evaluation stops after the first @code{nil} @var{val} is
 encountered.
 
 @example
@@ -3860,17 +3860,17 @@ Key/value stores:
 
   (&plist key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the
                                  @var{source} plist to aK.  If the
-                                 value is not found, aK is nil.
+                                 value is not found, aK is @code{nil}.
                                  Uses @code{plist-get} to fetch values.
 
   (&alist key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the
                                  @var{source} alist to aK.  If the
-                                 value is not found, aK is nil.
+                                 value is not found, aK is @code{nil}.
                                  Uses @code{assoc} to fetch values.
 
   (&hash key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the
                                 @var{source} hash table to aK.  If the
-                                value is not found, aK is nil.
+                                value is not found, aK is @code{nil}.
                                 Uses @code{gethash} to fetch values.
 
 Further, special keyword &keys supports "inline" matching of
@@ -4075,7 +4075,7 @@ Functions iterating over lists for side effect only.
 @anchor{-each}
 @defun -each (list fn)
 Call @var{fn} on each element of @var{list}.
-Return nil; this function is intended for side effects.
+Return @code{nil}; this function is intended for side effects.
 
 Its anaphoric counterpart is @code{--each}.
 
@@ -4100,9 +4100,9 @@ For access to the current element's index in @var{list}, see
 
 @anchor{-each-while}
 @defun -each-while (list pred fn)
-Call @var{fn} on each @var{item} in @var{list}, while (@var{pred} @var{item}) is non-nil.
-Once an @var{item} is reached for which @var{pred} returns nil, @var{fn} is no
-longer called.  Return nil; this function is intended for side
+Call @var{fn} on each @var{item} in @var{list}, while (@var{pred} @var{item}) is non-@code{nil}.
+Once an @var{item} is reached for which @var{pred} returns @code{nil}, @var{fn} is no
+longer called.  Return @code{nil}; this function is intended for side
 effects.
 
 Its anaphoric counterpart is @code{--each-while}.
@@ -4127,7 +4127,7 @@ Its anaphoric counterpart is @code{--each-while}.
 @defun -each-indexed (list fn)
 Call @var{fn} on each index and element of @var{list}.
 For each @var{item} at @var{index} in @var{list}, call (funcall @var{fn} @var{index} @var{item}).
-Return nil; this function is intended for side effects.
+Return @code{nil}; this function is intended for side effects.
 
 See also: @code{-map-indexed} (@pxref{-map-indexed}).
 
@@ -4150,7 +4150,7 @@ See also: @code{-map-indexed} (@pxref{-map-indexed}).
 @anchor{-each-r}
 @defun -each-r (list fn)
 Call @var{fn} on each element of @var{list} in reversed order.
-Return nil; this function is intended for side effects.
+Return @code{nil}; this function is intended for side effects.
 
 Its anaphoric counterpart is @code{--each-r}.
 
@@ -4172,9 +4172,9 @@ Its anaphoric counterpart is @code{--each-r}.
 
 @anchor{-each-r-while}
 @defun -each-r-while (list pred fn)
-Call @var{fn} on each @var{item} in reversed @var{list}, while (@var{pred} @var{item}) is non-nil.
-Once an @var{item} is reached for which @var{pred} returns nil, @var{fn} is no
-longer called.  Return nil; this function is intended for side
+Call @var{fn} on each @var{item} in reversed @var{list}, while (@var{pred} @var{item}) is non-@code{nil}.
+Once an @var{item} is reached for which @var{pred} returns @code{nil}, @var{fn} is no
+longer called.  Return @code{nil}; this function is intended for side
 effects.
 
 Its anaphoric counterpart is @code{--each-r-while}.
@@ -4511,7 +4511,7 @@ See @var{srfi-26} for detailed description.
 @defun -not (pred)
 Return a predicate that negates the result of @var{pred}.
 The returned predicate passes its arguments to @var{pred}.  If @var{pred}
-returns nil, the result is non-nil; otherwise the result is nil.
+returns @code{nil}, the result is non-@code{nil}; otherwise the result is @code{nil}.
 
 See also: @code{-andfn} (@pxref{-andfn}) and @code{-orfn} (@pxref{-orfn}).
 
@@ -4533,12 +4533,12 @@ See also: @code{-andfn} (@pxref{-andfn}) and @code{-orfn} (@pxref{-orfn}).
 
 @anchor{-orfn}
 @defun -orfn (&rest preds)
-Return a predicate that returns the first non-nil result of @var{preds}.
+Return a predicate that returns the first non-@code{nil} result of @var{preds}.
 The returned predicate takes a variable number of arguments,
 passes them to each predicate in @var{preds} in turn until one of them
-returns non-nil, and returns that non-nil result without calling
-the remaining @var{preds}.  If all @var{preds} return nil, or if no @var{preds} are
-given, the returned predicate returns nil.
+returns non-@code{nil}, and returns that non-@code{nil} result without calling
+the remaining @var{preds}.  If all @var{preds} return @code{nil}, or if no @var{preds} are
+given, the returned predicate returns @code{nil}.
 
 See also: @code{-andfn} (@pxref{-andfn}) and @code{-not} (@pxref{-not}).
 
@@ -4560,12 +4560,12 @@ See also: @code{-andfn} (@pxref{-andfn}) and @code{-not} (@pxref{-not}).
 
 @anchor{-andfn}
 @defun -andfn (&rest preds)
-Return a predicate that returns non-nil if all @var{preds} do so.
+Return a predicate that returns non-@code{nil} if all @var{preds} do so.
 The returned predicate @var{p} takes a variable number of arguments and
 passes them to each predicate in @var{preds} in turn.  If any one of
-@var{preds} returns nil, @var{p} also returns nil without calling the
-remaining @var{preds}.  If all @var{preds} return non-nil, @var{p} returns the last
-such value.  If no @var{preds} are given, @var{p} always returns non-nil.
+@var{preds} returns @code{nil}, @var{p} also returns @code{nil} without calling the
+remaining @var{preds}.  If all @var{preds} return non-@code{nil}, @var{p} returns the last
+such value.  If no @var{preds} are given, @var{p} always returns non-@code{nil}.
 
 See also: @code{-orfn} (@pxref{-orfn}) and @code{-not} (@pxref{-not}).
 
@@ -4630,11 +4630,11 @@ iteration halts when either of the following conditions is satisfied:
     numbers, it may be necessary to provide an appropriate
     approximate comparison test.
 
- 2. @var{halt-test} returns a non-nil value. @var{halt-test} defaults to a
-    simple counter that returns t after @code{-fixfn-max-iterations},
+ 2. @var{halt-test} returns a non-@code{nil} value. @var{halt-test} defaults to a
+    simple counter that returns @code{t} after @code{-fixfn-max-iterations},
     to guard against infinite iteration. Otherwise, @var{halt-test}
     must be a function that accepts a single argument, the
-    current value of @var{x}, and returns non-nil as long as iteration
+    current value of @var{x}, and returns non-@code{nil} as long as iteration
     should continue. In this way, a more sophisticated
     convergence test may be supplied by the caller.
 
diff --git a/dev/dash-defs.el b/dev/dash-defs.el
index d869af9..1c3a6e6 100644
--- a/dev/dash-defs.el
+++ b/dev/dash-defs.el
@@ -158,6 +158,13 @@ Based on `describe-function-1'."
                        (format "`%s`" fn))
                      t t))))
 
+(defun dash--booleans-to-md ()
+  "Mark up booleans (nil/t) in current buffer as Markdown."
+  (goto-char (point-min))
+  (while (re-search-forward (rx bow (| "nil" "t") eow) nil t)
+    (unless (memql (char-before (match-beginning 0)) '(?\' ?`))
+      (replace-match "`\\&`" t))))
+
 (defun dash--indent-md-blocks ()
   "Indent example blocks in current buffer for Markdown."
   (goto-char (point-min))
@@ -171,6 +178,7 @@ Based on `describe-function-1'."
     (dash--argnames-to-md)
     (dash--metavars-to-md)
     (dash--hyperlinks-to-md)
+    (dash--booleans-to-md)
     (dash--indent-md-blocks)
     (buffer-string)))
 
@@ -184,7 +192,8 @@ Based on `describe-function-1'."
     ;; TODO: Use `help-argument-name' like in `dash--argnames-to-md'?
     (while (re-search-forward
             (rx (| (group bow (in "A-Z") (* (in "A-Z" ?-)) (* num) eow)
-                   (: ?` (group (+ (not (in ?\s)))) ?\')
+                   (: ?` (group (+? (not (in ?\s)))) ?\')
+                   (group bow (| "nil" "t") eow)
                    (: "..." (? (group eol)))))
             nil t)
       (cond ((match-beginning 1)
@@ -197,8 +206,12 @@ Based on `describe-function-1'."
                                 "@code{\\2} (@pxref{\\2})"
                               "@code{\\2}")
                             t))
+            ;; nil/t.
+            ((match-beginning 3)
+             (unless (= (char-before (match-beginning 3)) ?\')
+               (replace-match "@code{\\3}" t)))
             ;; Ellipses.
-            ((match-beginning 3) (replace-match "@enddots{}" t t))
+            ((match-beginning 4) (replace-match "@enddots{}" t t))
             ((replace-match "@dots{}" t t))))
     (buffer-string)))