From c68b1a1b5abcb440216a8d1e7f0f20c40e0398a6 Mon Sep 17 00:00:00 2001
From: kisnner <s46jbhqzxq@privaterelay.appleid.com>
Date: Tue, 6 Oct 2026 00:17:28 -0600
Subject: [PATCH] document the hex2bin conversion function

---
 docs/manual/part2-5.txt | 33 +++++++++++++++++++++++++++++++++
 docs/manual/part3-1.txt |  2 +-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/manual/part2-5.txt b/docs/manual/part2-5.txt
index 6b5dd7d..3f1f6bb 100644
--- a/docs/manual/part2-5.txt
+++ b/docs/manual/part2-5.txt
@@ -70,3 +70,36 @@ you're creating Eeprom/Flash IC programmer or bootloader.
       BLOCK_SIZE = 128    # 128 bytes
       for addr in range(0, EEPROM_SIZE, BLOCK_SIZE):
           eeprom.i2c_write(addr, ih.tobinarray(start=addr, size=BLOCK_SIZE))
+
+
+hex-to-binary conversion helper
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. py:function:: intelhex.hex2bin(fin, fout, start=None, end=None, size=None, pad=None)
+
+   convert an intel hex file directly to binary output without creating an
+   ``IntelHex`` object yourself.
+
+   :param fin: input filename or a file-like object containing hex text.
+   :param fout: output filename or a file-like object accepting binary data.
+   :param start: first address to write; defaults to the lowest input address.
+   :param end: last address to write, inclusive; defaults to the highest input address.
+   :param size: when nonzero, derive the range from this byte count. if ``end``
+               is supplied, use ``max(0, end + 1 - size)`` as ``start``;
+               otherwise use ``start + size - 1`` as ``end``.
+   :param pad: byte used for addresses without input data; defaults to ``0xff``.
+   :return: ``0`` on success, or ``1`` after printing an error for invalid hex
+            input or an output io error. other exceptions may propagate.
+
+   for example, convert two bytes from an in-memory hex file::
+
+       >>> from io import BytesIO, StringIO
+       >>> from intelhex import hex2bin
+       >>> source = StringIO(":04000000102030405C\n:00000001FF\n")
+       >>> output = BytesIO()
+       >>> hex2bin(source, output, start=1, size=2)
+       0
+       >>> output.getvalue().hex()
+       '2030'
+
+   ``end=2`` instead of ``size=2`` selects the same inclusive range.
diff --git a/docs/manual/part3-1.txt b/docs/manual/part3-1.txt
index 8b29f9d..4abfe67 100644
--- a/docs/manual/part3-1.txt
+++ b/docs/manual/part3-1.txt
@@ -1,7 +1,7 @@
 Script ``hex2bin.py``
 *********************
 You can use ``hex2bin.py`` as handy hex-to-bin converter. 
-This script is just a frontend for function ``hex2bin`` from intelhex package.
+This script is just a frontend for :func:`intelhex.hex2bin` from intelhex package.
 ::
 
         Usage: