Clarify memory allocation setting JM_MEMORY.

We default to malloc()/free(). While one can force the use of
PyMem_Malloc()/PyMem_Free(), this is no longer explicitly recommended.

This addresses pymupdf#1789.

Author: julian-smith-artifex-com

docs/tools.rst

@@ -207,7 +207,7 @@ This class is a collection of utility methods and attributes, mainly around memo
         'tofu-symbol': False,
         'tofu-sil': False,
         'icc': True,
-        'py-memory': True, # (False if Python 2)
+        'py-memory': False,
         'base14': True}
 
       :rtype: dict
@@ -265,4 +265,4 @@ Example Session
 
 .. [#f1] This memory area is internally used by MuPDF, and it serves as a cache for objects that have already been read and interpreted, thus improving performance. The most bulky object types are images and also fonts. When an application starts up the MuPDF library (in our case this happens as part of *import fitz*), it must specify a maximum size for this area. PyMuPDF's uses the default value (256 MB) to limit memory consumption. Use the methods here to control or investigate store usage. For example: even after a document has been closed and all related objects have been deleted, the store usage may still not drop down to zero. So you might want to enforce that before opening another document.
 
-.. [#f2] Optionally, all dynamic management of memory can be done using Python C-level calls. MuPDF offers a hook to insert user-preferred memory managers. We are using option this for Python version 3 since PyMuPDF v1.13.19. At the same time, all memory allocation in PyMuPDF itself is also routed to Python (i.e. no more direct *malloc()* calls in the code). We have seen improved memory usage and slightly reduced runtimes with this option set. If you want to change this, you can set *#define JM_MEMORY 0* (uses standard C malloc, or 1 for Python allocation )in file *fitz.i* and then generate PyMuPDF.
+.. [#f2] By default PyMuPDF and MuPDF use ``malloc()``/``free()`` for dynamic memory management. One can instead force them to use the Python allocation functions ``PyMem_New()``/``PyMem_Del()``, by modifying *fitz/fitz.i* to do ``#define JM_MEMORY 1`` and rebuilding PyMuPDF.

fitz/fitz.i

@@ -81,7 +81,15 @@ EnsureOwnership(self)%}
 #define SWIG_FILE_WITH_INIT
 #define SWIG_PYTHON_2_UNICODE
 
-// memory allocation macros
+// JM_MEMORY controls what allocators we tell MuPDF to use when we call
+// fz_new_context():
+//
+//  JM_MEMORY=0: MuPDF uses malloc()/free().
+//  JM_MEMORY=1: MuPDF uses PyMem_Malloc()/PyMem_Free().
+//
+// There are also a small number of places where we call malloc() or
+// PyMem_Malloc() ourselves, depending on JM_MEMORY.
+//
 #define JM_MEMORY 0
 
 #if JM_MEMORY == 1