docs/: improve description of conflict with fitz package.

Also provide links to updated description from the intro and tutorial pages.

docs/installation.rst

@@ -60,10 +60,14 @@ source using a Python sdist.
 The build will automatically download and build MuPDF.
 
 
+.. _problems-after-installation:
+
 Problems after installation
 ---------------------------------------------------------
 
-* On Windows `ImportError: DLL load failed while importing _fitz`.
+* On Windows, Python error::
+
+      ImportError: DLL load failed while importing _fitz
 
   This has been occasionally seen if `MSVCP140.dll` is missing, and appears
   to be caused by a bug in some versions (2015-2017) of `Microsoft Visual C++
@@ -77,8 +81,37 @@ Problems after installation
   See https://github.com/pymupdf/PyMuPDF/issues/2678 for more details.
 
 *
-  Problems have been reported when using PyMuPDF with Jupyter labs on Apple
-  Silicon (arm64); see https://github.com/pymupdf/PyMuPDF/issues/3643.
+  Python error::
+
+      ModuleNotFoundError: No module named 'frontend'
+  
+  This can happen if PyMuPDF's legacy name `fitz` is used (for example `import
+  fitz` instead of `import pymupdf`), and an unrelated Python package called
+  `fitz` (https://pypi.org/project/fitz/) is installed.
+
+  The fitz package appears to be no longer maintained (the latest release is
+  from 2017), but unfortunately it does not seem possible to remove it from
+  pypi.org. It does not even work on its own, as well as breaking the use of
+  PyMuPDF's legacy name.
+
+  There are a few ways to avoid this problem:
+
+  *
+    Use `import pymupdf` instead of `import fitz`, and update one's code to
+    match.
+
+  * Or uninstall the `fitz` package and reinstall PyMuPDF::
+  
+        pip uninstall fitz
+        pip install --force-reinstall pymupdf
+
+  * Or use `import pymupdf as fitz`. However this has not been well tested.
+
+* With Jupyter labs on Apple Silicon (arm64), Python error::
+
+      ImportError: /opt/conda/lib/python3.11/site-packages/pymupdf/libmupdf.so.24.4: undefined symbol: fz_pclm_write_options_usage
+
+  See https://github.com/pymupdf/PyMuPDF/issues/3643#issuecomment-2210588778.
 
 
 Notes

docs/intro.rst

@@ -40,7 +40,12 @@ The original rendering library for MuPDF was called *Libart*.
 
 *"After Artifex Software acquired the MuPDF project, the development focus shifted on writing a new modern graphics library called "Fitz". Fitz was originally intended as an R&D project to replace the aging Ghostscript graphics library, but has instead become the rendering engine powering MuPDF."* (Quoted from `Wikipedia <https://en.wikipedia.org/wiki/MuPDF>`_).
 
-`import fitz` is still supported for backwards compatibility, but this usage **cannot coexist** with packages named "fitz" in the same Python environment.
+`import fitz` is still supported for backwards compatibility.
+
+.. note::
+
+  Use of legacy name `fitz` can fail if defunct package pypi.org `fitz` is installed; see :ref:`problems-after-installation`.
+
 
 License and Copyright
 ----------------------

docs/tutorial.rst

@@ -35,10 +35,9 @@ The original rendering library for MuPDF was called *Libart*.
 
 *"After Artifex Software acquired the MuPDF project, the development focus shifted on writing a new modern graphics library called "Fitz". Fitz was originally intended as an R&D project to replace the aging Ghostscript graphics library, but has instead become the rendering engine powering MuPDF."* (Quoted from `Wikipedia <https://en.wikipedia.org/wiki/MuPDF>`_).
 
-
 .. note::
 
-    Importing |PyMuPDF| as `fitz` still works however |PyMuPDF| **cannot coexist** with other packages named "fitz" in the same Python environment.
+  Use of legacy name `fitz` can fail if defunct pypi.org package `fitz` is installed; see :ref:`problems-after-installation`.
 
 
 .. _Tutorial_Opening_a_Document: