From 7e75118956e85c9d7def3dc23173113b72333d3c Mon Sep 17 00:00:00 2001
From: Fabian Boehm <FHomborg@gmail.com>
Date: Tue, 23 Aug 2022 19:54:10 +0200
Subject: [PATCH] Document math's lack of bitnot

Fixes #9148
---
 doc_src/cmds/math.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc_src/cmds/math.rst b/doc_src/cmds/math.rst
index b4b0a18fd..d7882d3f4 100644
--- a/doc_src/cmds/math.rst
+++ b/doc_src/cmds/math.rst
@@ -121,6 +121,20 @@ Functions
 ``bitand``, ``bitor`` and ``bitxor``
     perform bitwise operations.
     These will throw away any non-integer parts and interpret the rest as an int.
+
+    Note: ``bitnot`` and ``bitnand`` don't exist. This is because numbers in math don't really have a *width* in terms of bits,
+    and tehse operations necessarily care about leading zeroes.
+
+    If you need to negate a specific number you can do it with an xor with a mask, e.g.::
+
+      > math --base=hex bitxor 0x0F, 0xFF
+      0xF0
+
+      > math --base=hex bitxor 0x2, 0x3
+      # Here we mask with 0x3 == 0b111, so our number is 3 bits wide
+      # Only the 1 bit isn't set.
+      0x1
+
 ``ceil``
     round number up to nearest integer
 ``cos``