From 612a4a6b9df18b5fbca54cf5d31e23f5abd4803e Mon Sep 17 00:00:00 2001
From: sebseb7 <sebgreenbus@gmail.com>
Date: Mon, 11 Aug 2025 17:15:43 +0200
Subject: [PATCH] Add detailed patch file format documentation to
 patch_files.js, including instructions for context and code changes.

---
 tools/patch_files.js | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/tools/patch_files.js b/tools/patch_files.js
index 87851e2..076ffc3 100644
--- a/tools/patch_files.js
+++ b/tools/patch_files.js
@@ -3,6 +3,49 @@
 /**
  * A self-contained JavaScript utility for applying human-readable
  * "pseudo-diff" patch files to a collection of text files.
+ * 
+
+
+
+
+
+*** Begin Patch
+[YOUR_PATH]
+*** End Patch
+
+
+Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
+
+*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.
+For each snippet of code that needs to be changed, repeat the following:
+[context_before] -> See below for further instructions on context.
+- [old_code] -> Precede the old code with a minus sign.
++ [new_code] -> Precede the new, replacement code with a plus sign.
+[context_after] -> See below for further instructions on context.
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
+
+ * 
+ * 
+ * 
  */
 
 // --------------------------------------------------------------------------- //