Improve pickle docs

py5_docs/Reference/api_en/Py5Functions_get_current_sketch.txt

@@ -10,7 +10,7 @@ get_current_sketch() -> Sketch
 @@ description
 Get the py5 module's current `Sketch` instance.
 
-When coding py5 in module mode, a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "current sketch." Use this method to access that Sketch instance directly.
+When coding py5 in [module mode](content-py5-modes-module-mode), a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "current sketch." Use this method to access that Sketch instance directly.
 
 @@ example
 sketch = py5.get_current_sketch()

py5_docs/Reference/api_en/Py5Functions_reset_py5.txt

@@ -13,7 +13,7 @@ jclassname: str = None - canonical name of class to instantiate when using py5 i
 @@ description
 Reset the py5 module's current `Sketch` instance.
 
-When coding py5 in module mode, a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "Current Sketch." If the current Sketch exits, it will be in a dead state and cannot be re-run. `reset_py5()` will discard that exited Sketch instance and replace it with a new one in the ready state.
+When coding py5 in [module mode](content-py5-modes-module-mode), a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "Current Sketch." If the current Sketch exits, it will be in a dead state and cannot be re-run. `reset_py5()` will discard that exited Sketch instance and replace it with a new one in the ready state.
 
 If `reset_py5()` is called when the current Sketch is in the ready or running states, it will do nothing and return `False`. If `reset_py5()` is called when the current Sketch is in the dead state, `reset_py5()` will replace it and return `True`.
 

py5_docs/Reference/api_en/Py5Magics_py5bot.txt

@@ -18,7 +18,7 @@ This cell magic uses the same rendering mechanism as the py5bot kernel. For user
 
 This magic is similar to [](py5magics_py5draw) in that both can be used to create a static Sketch. One key difference is that `%%py5bot` requires the user to begin the code with a call to [](sketch_size), while [](py5magics_py5draw) calls [](sketch_size) for you based on the magic's arguments. 
 
-This magic supports the default renderer and the `P2D` and `P3D` renderers. Note that both of the OpenGL renderers will briefly open a window on your screen. This magic is only available when using the py5 kernel and coding in imported mode. The `P2D` and `P3D` renderers are not available when the py5 kernel is hosted on a macOS computer.
+This magic supports the default renderer and the `P2D` and `P3D` renderers. Note that both of the OpenGL renderers will briefly open a window on your screen. This magic is only available when using the py5 kernel and coding in [imported mode](content-py5-modes-imported-mode). The `P2D` and `P3D` renderers are not available when the py5 kernel is hosted on a macOS computer.
 
 Code used in this cell can reference functions and variables defined in other cells because a copy of the user namespace is provided during execution. Variables and functions created in this cell will be local to only this cell because to do otherwise would be unsafe. Mutable objects in the user namespace, however, can be altered and those changes will persist elsewhere in the notebook. Be aware that using py5 objects in a different notebook cell or reusing them in another Sketch can result in nasty errors and bizzare consequences.
 

py5_docs/Reference/api_en/Py5Tools.txt

@@ -4,7 +4,7 @@ type = pseudoclass
 provides_description = functions
 
 @@ description
-The py5 Tools are extra utility functions not directly related to creating Sketches that help faciliate the use of py5. For example, you can use these to add jar files to the Java classpath before importing py5. All of the py5 Tools are in the Python package `py5_tools`, which are installed alongside py5 but must be explicitly imported before using them. The `py5_tools` package is imported for you when coding in imported mode such as with the py5 Jupyter Notebook kernel.
+The py5 Tools are extra utility functions not directly related to creating Sketches that help faciliate the use of py5. For example, you can use these to add jar files to the Java classpath before importing py5. All of the py5 Tools are in the Python package `py5_tools`, which are installed alongside py5 but must be explicitly imported before using them. The `py5_tools` package is imported for you when coding in [imported mode](content-py5-modes-imported-mode) such as with the py5 Jupyter Notebook kernel.
 
 @@ example
 import py5_tools

py5_docs/Reference/api_en/Py5Tools_animated_gif.txt

@@ -28,7 +28,7 @@ Bottom line, you must use either the `count` parameter or the `frame_numbers` pa
 
 By default this function will return right away and construct the animated gif in the background while the Sketch is running. The completed gif will be saved to the location specified by the `filename` parameter when it is ready. Set the `block` parameter to `True` to instruct the function to not return until the gif construction is complete. This blocking feature is not available on macOS when the Sketch is executed through an IPython kernel. If the Sketch terminates prematurely, no gif will be created.
 
-By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode.
+By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode).
 
 If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness.
 

py5_docs/Reference/api_en/Py5Tools_capture_frames.txt

@@ -24,7 +24,7 @@ Bottom line, you must use either the `count` parameter or the `frame_numbers` pa
 
 By default this function will return right away and will capture frames in the background while the Sketch is running. The returned list of PIL Image objects (`list[PIL.Image]`) will initially be empty, and will be populated all at once when the complete set of frames has been captured. Set the `block` parameter to `True` to instruct this function to capture the frames in the foreground and to not return until the complete list of frames is ready to be returned. To get access to the captured frames as they become available, use the [](py5tools_offline_frame_processing) function instead. If the Sketch is terminated prematurely, the returned list will be empty.
 
-By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode.
+By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode).
 
 If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness.
 

py5_docs/Reference/api_en/Py5Tools_offline_frame_processing.txt

@@ -33,7 +33,7 @@ By default this function will return right away and will process frames in the b
 
 By default this function will report its progress as frames are processed. If you are using a Jupyter Notebook and happen to be processing tens of thousands of frames, this might cause Jupyter to crash. To avoid that fate, set the `display_progress` parameter to `False`.
 
-Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness.
+Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness.
 
 @@ example
 import skvideo.io

py5_docs/Reference/api_en/Py5Tools_save_frames.txt

@@ -23,7 +23,7 @@ Save a running Sketch's frames to a directory.
 
 By default this function will return right away and save frames in the background while the Sketch is running. The frames will be saved in the directory specified by the `dirname` parameter. Set the `block` parameter to `True` to instruct the method to not return until the number of frames saved reaches the number specified by the `limit` parameter. This blocking feature is not available on macOS when the Sketch is executed through an IPython kernel.
 
-By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode.
+By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode).
 
 If the `limit` parameter is used, this function will wait to return a list of the filenames. If not, it will return right away as the frames are saved in the background. It will keep doing so as long as the Sketch continues to run.
 

py5_docs/Reference/api_en/Py5Tools_screenshot.txt

@@ -16,7 +16,7 @@ Take a screenshot of a running Sketch.
 
 The returned image is a `PIL.Image` object. It can be assigned to a variable or embedded in the notebook.
 
-By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode.
+By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode).
 
 This function will not work on a Sketch with no `draw()` function that uses an OpenGL renderer such as `P2D` or `P3D`. Either add a token `draw()` function or switch to the default `JAVA2D` renderer.
 

py5_docs/Reference/api_en/Py5Tools_sketch_portal.txt

@@ -21,7 +21,7 @@ Creates a portal widget to continuously stream frames from a running Sketch into
 
 **Unfortunately, the Sketch Portal feature had to be removed from py5 in release 0.10.0. Changes to Jupyter Lab and Jupyter Widgets somehow broke the code and it was too difficult to figure out why. Rather than fix the code, the Sketch Portal will be re-implemented using the Python library anywidget. This new approach will hopefully be simpler to implement and easier to maintain.**
 
-By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode.
+By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode).
 
 The Sketch Portal is a custom Jupyter Widget and can handle keyboard or mouse events just like a native window. You will need to click on the portal for it to gain focus and capture keyboard events. Mouse and keyboard events will be observed by the browser and simulated events will be created for the Sketch. Every effort has been made to make the simulated events identical to real events but some small differences remain. You can also use the Jupyter-provided Widgets such as sliders and text boxes for user input.
 

py5_docs/Reference/api_en/Sketch.txt

@@ -26,6 +26,6 @@ The core functions to be implemented by the py5 coder are `setup` and `draw`. Th
 * `post_draw`
 * `pre_draw`
 
-When coding in class mode, all of the above functions should be instance methods. When coding in module mode or imported mode, the above functions should be stand-alone functions available in the local namespace in which [](sketch_run_sketch) was called.
+When coding in [class mode](content-py5-modes-class-mode), all of the above functions should be instance methods. When coding in [module mode](content-py5-modes-module-mode) or [imported mode](content-py5-modes-imported-mode), the above functions should be stand-alone functions available in the local namespace in which [](sketch_run_sketch) was called.
 
 For more information, look at the online ["User Functions"](/content/user_functions) documentation.

py5_docs/Reference/api_en/Sketch_full_screen.txt

@@ -19,7 +19,7 @@ renderer: str - the renderer to use, e.g. P2D, P3D, JAVA2D (default)
 @@ description
 Open a Sketch using the full size of the computer's display. This is intended to be called from the `settings()` function. The [](sketch_size) and `full_screen()` functions cannot both be used in the same program.
 
-When programming in module mode and imported mode, py5 will allow calls to `full_screen()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `full_screen()`, or calls to [](sketch_size), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode.
+When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `full_screen()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `full_screen()`, or calls to [](sketch_size), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode).
 
 When `full_screen()` is used without a parameter on a computer with multiple monitors, it will (probably) draw the Sketch to the primary display. When it is used with a single parameter, this number defines the screen to display to program on (e.g. 1, 2, 3...). When used with two parameters, the first defines the renderer to use (e.g. P2D) and the second defines the screen. The `SPAN` parameter can be used in place of a screen number to draw the Sketch as a full-screen window across all of the attached displays if there are more than one.
 

py5_docs/Reference/api_en/Sketch_load_pickle.txt

@@ -17,6 +17,8 @@ Load a pickled Python object from a file. The path can be in the data directory,
 
 There are security risks associated with Python pickle files. A pickle file can contain malicious code, so never load a pickle file from an untrusted source.
 
+When using py5 in [imported mode](content-py5-modes-imported-mode), pickling will not work on objects instantiated from new classes you have defined yourself on the main sketch file. This applies to py5's [](sketch_save_pickle) and `load_pickle()` methods, as well as the Python's standard library pickle module methods they depend upon. If you need to pickle objects from classes you defined, move the class definitions to a different .py file that you import as a module or import the classes from. Otherwise, you could also try using [module mode](content-py5-modes-module-mode) if you want to use pickle with your classes and keep all the sketch code in a single file.
+
 @@ example
 def setup():
     global mouse_x_positions, mouse_y_positions

py5_docs/Reference/api_en/Sketch_no_smooth.txt

@@ -14,7 +14,7 @@ Draws all geometry and fonts with jagged (aliased) edges and images with hard ed
 
 The `no_smooth()` function can only be called once within a Sketch. It is intended to be called from the `settings()` function. The [](sketch_smooth) function follows the same rules.
 
-When programming in module mode and imported mode, py5 will allow calls to `no_smooth()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `no_smooth()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode.
+When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `no_smooth()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `no_smooth()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode).
 
 @@ example
 def setup():