document arithmetic utilities

sh/arith

@@ -8,6 +8,13 @@
 
 arith() { ### @-
     ### perform arithmetic using the shell and display the result.
+    ### see also [`hex`](#hex) and [`bin`](#bin).
+    ###
+    ### ```
+    ### % db=6
+    ### % noglob arith 10**(db/20.)
+    ### 1.9952623149688795
+    ### ```
 #   <<<"$(($@))"
     printf "%s\n" "$(($@))"
 }

sh/bin

@@ -3,7 +3,18 @@
 # YES_BASH
 # YES_DASH
 
+# though technically compatible with other shells,
+# extra functionality is through zsh's extended arithmetic functions.
+
 bin() { ### @-
+    ### perform arithmetic using the shell and display the result as
+    ### an unsigned 8-bit integer in binary.
+    ### see also [`arith`](#arith) and [`hex`](#hex).
+    ###
+    ### ```
+    ### $ bin 123
+    ### 01111011
+    ### ```
     local a="$(($@))"
     a="$(( (((((((((((((a + 0x0FFFFF80) & 0x1000007F) + 0x00FFFFC0) & 0x1100003F) + 0x000FFFE0) & 0x1110001F) + 0x0000FFF0) & 0x1111000F) + 0x00000FF8) & 0x11111007) + 0x000000FC) & 0x11111103) + 0x0000000E) & 0x11111111 ))"
     printf "%08X\n" "$a"

sh/hex

@@ -7,7 +7,14 @@
 # extra functionality is through zsh's extended arithmetic functions.
 
 hex() { ### @-
-    ### perform arithmetic using the shell and display the result as an unsigned 32-bit integer in hexadecimal.
+    ### perform arithmetic using the shell and display the result as
+    ### an unsigned 32-bit integer in hexadecimal.
+    ### see also [`arith`](#arith) and [`bin`](#bin).
+    ###
+    ### ```
+    ### $ hex 0x221EA8-0x212020
+    ### 0000FE88
+    ### ```
     printf "%08X\n" "$(($@))"
 }