.svnignore

@@ -1,2 +0,0 @@
-build
-locale

Makefile

@@ -22,6 +22,13 @@ Checking
 - check_structure      to check the structure of all .rst files.
 - check_syntax         to check the syntax of all .rst files.
 - check_spelling       to check spelling for text in RST files.
+
+Utilities
+---------
+
+- update               to update the repository to the most recent version.
+- format_py            to auto-format Python scripts.
+
 endef
 # HELP_TEXT (end)
 
@@ -117,6 +124,12 @@ report_po_progress:
 	@python3 tools_report/report_translation_progress.py --quiet \
 	         `find locale/ -maxdepth 1 -mindepth 1 -type d -not -iwholename '*.git*' -printf 'locale/%f\n' | sort`
 
+update:
+	@git pull --rebase
+
+format_py:
+	@autopep8 --in-place --recursive .
+
 # ----------------------
 # Help for build targets
 

make.bat

@@ -63,6 +63,11 @@ if "%1" == "help" (
 	echo - check_structure      to check the structure of all .rst files
 	echo - check_syntax         to check the syntax of all .rst files
 	echo - check_spelling       to check spelling for text in RST files
+	echo.
+	echo Utilities
+	echo ---------
+	echo.
+	echo - update               to update the repository to the most recent version.
 	goto EOF
 )
 
@@ -109,6 +114,10 @@ if "%1" == "check_structure" (
 	python tools_rst\rst_check_images.py
 	goto EOF
 
+if "%1" == "update" (
+	git pull --rebase
+	goto EOF
+
 ) else (
 	%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS% %O%
 	goto EOF

manual/addons/3d_view/precision_drawing_tools/download.rst

@@ -8,9 +8,10 @@ In this case you need only enable the Add-on in the Add-on Preferences.
 
 However, the latest releases can be found on our GitHub.
 
-Downloads should only be taken the from the official releases page:
+Downloads should only be taken the from the
+`official releases page <https://github.com/Clockmender/Precision-Drawing-Tools/releases>`__.
+
 
-https://github.com/Clockmender/Precision-Drawing-Tools/releases
 
 Patches and Commits, that may add new features and/or bug fixes may be downloaded
 from the Commits to the Master branch, no development code should be used
@@ -55,6 +56,6 @@ again only edit the message section in quotes, not the PDT assignments.
 Issues
 ======
 
-Please report any issues, or feature request, etc. using the Issues section
+Please report any issues, or feature request, etc. using the Issues section of the
-of the PDT Repository (https://github.com/Clockmender/Precision-Drawing-Tools/issues),
+`PDT Repository <https://github.com/Clockmender/Precision-Drawing-Tools/issues>`__,
 that way they can be properly tracked, actioned and incorporated into the add-on.

manual/addons/baking/index.rst

@@ -0,0 +1,11 @@
+
+#############
+  Baking
+#############
+
+These add-ons add UI elements for faster baking access.
+
+.. toctree::
+   :maxdepth: 1
+
+   vdm_brush_baker.rst

manual/addons/baking/vdm_brush_baker.rst

@@ -0,0 +1,36 @@
+*******
+VDM Brush Baker
+*******
+
+This is a small add-on that makes it easy to create vector displacement map (aka VDM) brushes in Blender.
+Sculpting setups and the brushes can be created with one click.
+
+Activation
+==========
+
+- Open Blender and go to Preferences then the Add-ons tab.
+- Switch the category to "Baking"
+- Enable the "VDM Brush Baker" addon.
+
+Interface
+=========
+
+Located in the :menuselection:`3D Viewport --> Sidebar --> Tools`.
+
+Usage
+=====
+
+Use the "Create Sculpting Plane" button for an optimal startign setup for sculpting your own VDM brush.
+
+Use the "Render and Create VDM Brush" button to covnert bake the plane into a new brush.
+The brush will be added with all relevant options and a vector displacement map
+is saved near the blender file as an Open EXR file (or a 'tmp' folder if the blender file wasn't saved).
+New brushes can be found as Draw brushes in sculpt mode.
+The add-on won't create any preview images for these brushes.
+
+Tips
+----
+
+- While Sculpting make sure to mask the borders of the plane for a better result.
+- If your VDM brush gets cut off at the corners, you can increase the size inside the texture panel of the brush settings to 1.1 or 1.2 for each axis.
+- A vdm-resolution of 512 px or lower is usually enough. Unless you have extremely detailed sculptings

manual/addons/import_export/mesh_atomic.rst

@@ -42,14 +42,15 @@ See `Examples`_ at the end of this page.
    - A list of software that deals with PDB in different ways can be found on
      the `RCSB site <https://www.rcsb.org/docs/additional-resources/molecular-graphics-software>`__. There also is
      `Vesta <https://jp-minerals.org/vesta/en/>`__, `ASE <https://wiki.fysik.dtu.dk/ase/>`__ and all the
-     `quantum chemical calculators <https://en.wikipedia.org/wiki/List_of_quantum_chemistry_and_solid-state_physics_
+     `quantum chemical calculators
-     software>`__ used in research, which can create or even calculate atomic structures and store them in PDB/XYZ
+     <https://en.wikipedia.org/wiki/List_of_quantum_chemistry_and_solid-state_physics_software>`__
-     files.
+     used in research, which can create or even calculate atomic structures and store them in PDB/XYZ files.
 
 .. seealso:: **Forum**
 
-   - Please, use the `Blender Artists forum <https://blenderartists.org/t/atomic-blender-pdb-xyz-for-blender-2-8-and-
+   - Please, use the `Blender Artists forum
-     higher/1197801>`__ for comments and questions or directly the `Blender chat <https://blender.chat/home>`__.
+     <https://blenderartists.org/t/atomic-blender-pdb-xyz-for-blender-2-8-and-higher/1197801>`__
+     for comments and questions or directly the `Blender chat <https://blender.chat/home>`__.
    - There also is the possibility to ask questions on `Stack Exchange <https://blender.stackexchange.com/>`__.
      However, note that some of the developers like Blendphys don't have enough credits, which are, however, needed to
      have the permission for giving answers on Stack Exchange.

manual/addons/import_export/scene_3ds.rst

@@ -7,7 +7,7 @@ Autodesk 3DS
 
    :Category: Import-Export
    :Menu: :menuselection:`File --> Import/Export --> 3D Studio (.3ds)`
-   :Version: 2.3.4
+   :Version: 2.4.1
    :Blender: 3.6
    :Authors: Bob Holcomb, Campbell Barton, Sebastian Schrand
    :Maintainer: Sebastian Sille (NRGSille)
@@ -36,7 +36,7 @@ Image Search
    This enables a recursive file search if an image file can't be found.
 
 Read Keyframe
-   Reads the keyframe tracks from a 3ds file and transforms the objects to the data wich was found.
+   Reads the keyframe tracks from a 3ds file and transforms the objects to the data which was found.
    Usually only one frame is found in static scenes, it will be imported to the timeline.
    If the 3ds scene is animated, the complete animation will be imported to the timeline.
 
@@ -60,7 +60,7 @@ Apply Transform
 
 World Space
    Use world matrix instead of local matrix to transform the objects.
-   This is useful for older 3ds files from 3D Studio DOS wich only used world space to transform the objects.
+   This is useful for older 3ds files from 3D Studio DOS which only used world space to transform the objects.
    It is also useful if the object was exported without apply transform.
 
 
@@ -73,6 +73,10 @@ Include
 Selection Only
    When checked, only selected objects are exported. Otherwise export all objects in the scene.
 
+Write Keyframe
+   Writes the keyframe section of a 3ds file and exports the animation if an action was found.
+   The animation can be imported the same way, un-check if any importer crashes,
+   not every application can handle the keyframe section.
 
 Transform
 ^^^^^^^^^
@@ -88,11 +92,11 @@ Forward / Up
 Materials
 =========
 
-Materials in 3ds are defined in various color and percent chunks wich can include
+Materials in 3ds are defined in various color and percent chunks which can include
 either integer percent and 24bit color values or float color and percent values,
 both can be read by the importer and will be converted to blender values.
 The exporter uses the integer values, since this is used from 3ds version 3 and above.
-The material definitions wich Blender can use are the following:
+The material definitions which Blender can use are the following:
 
 - 3ds Diffuse Color <-> blender Base Color
 - 3ds Specular Color <-> blender Specular Color
@@ -101,8 +105,8 @@ The material definitions wich Blender can use are the following:
 - 3ds Mat Shin2 <-> blender Specular Intensity
 - 3ds Mat Shin3 <-> blender Metallic
 - 3ds Mat Opacity <-> blender Alpha inverted
-- 3ds Mat Bump PCT <-> blender Normalmap Strength
+- 3ds Mat Bump PCT <-> blender Normal-map Strength
-- 3ds Self Illum PCT <-> blender Emission Strength
+- 3ds Self Illumination PCT <-> blender Emission Strength
 
 
 Textures
@@ -111,8 +115,8 @@ Textures
 Each 3ds material can include different texture mappings,
 which are all imported to Blender material nodes including texture coordinates.
 The 3ds exporter basically takes the images and coordinates,
-wich are directly connected to the Principled BSDF shader,
+which are directly connected to the Principled BSDF shader,
-if an image is connected to a colormix shader, it will exported as secondary texture.
+if an image is connected to a color-mix shader, it will exported as secondary texture.
 Shininess maps to roughness and opacity to the alpha channel,
 they must be color inverted afterwards to match with Blender definition.
 The material mappings are defined as following:
@@ -122,9 +126,9 @@ The material mappings are defined as following:
 - 3ds Shininess Map <-> blender Roughness Texture
 - 3ds Reflection Map <-> blender Metallic Texture
 - 3ds Opacity Map <-> blender Alpha Texture
-- 3ds Self Illum Map <-> blender Emission Texture
+- 3ds Self Illumination Map <-> blender Emission Texture
 - 3ds Bump Map <-> blender Normal Map (tangent space)
-- 3ds Tex2 Map <-> blender Color Texture (connect to mixshader)
+- 3ds Tex2 Map <-> blender Color Texture (connect to mix-shader)
 
 .. figure:: /images/addons_io_3ds_material-nodes.jpg
 
@@ -140,12 +144,12 @@ Meshes
 ======
 
 Meshes are made of triangles only, no quads are supported,
-3ds Studio uses edge visibilty flags to hide and show edges, many 3ds files use them to mark the quads.
+3ds Studio uses edge visibility flags to hide and show edges, many 3ds files use them to mark the quads.
 The Blender 3ds importer and exporter will use those flags to mark edges sharp,
 this can be used to convert the triangles back to quads.
-The importer can read the smoothchunk and shades a face smooth if it belongs to a smoothgroup,
+The importer can read the smooth-chunk and shades a face smooth if it belongs to a smooth-group,
 the exporter creates a smooth chunk if the mesh contains any smooth faces.
-3ds only supports one pair of UV coordinates per vertex. If any vertex has more UVs, it will be dublicated.
+3ds only supports one pair of UV coordinates per vertex. If any vertex has more UVs, it will be duplicated.
 
 
 Ambient
@@ -178,3 +182,4 @@ Keyframes
 The importer can read the keyframes, they will be added to the timeline.
 Most animations will play, but the transformations may not be correct,
 some axes or rotations can be inverted. It depends on how it was exported from other applications.
+The exporter can write the keyframes of the timeline to an animated 3ds file.

manual/addons/import_export/scene_dxf.rst

@@ -6,7 +6,7 @@ AutoCAD DXF
 .. reference::
 
    :Category:  Import-Export
-   :Menu:      :menuselection:`File --> Import/Export --> AutoCAD DXF`
+   :Menu:      :menuselection:`File --> Import/Export --> AutoCAD DXF (.dxf)`
 
 
 .. _dxf-import:

manual/addons/index.rst

@@ -27,6 +27,7 @@ Add-ons Category Listings
    add_curve/index.rst
    add_mesh/index.rst
    animation/index.rst
+   baking/index.rst
    camera/index.rst
    development/index.rst
    import_export/index.rst

manual/addons/interface/amaranth.rst

@@ -330,7 +330,7 @@ Timeline Extra Info
 
 Display amount of frames left until Frame End, very handy especially when rendering an animation or OpenGL preview.
 
-Display current/end time in `SMPTE <https://en.wikipedia.org/wiki/SMPTE_timecode>`_.
+Display current/end time in `SMPTE <https://en.wikipedia.org/wiki/SMPTE_timecode>`__.
 
 Usage: Find it in the Timeline Editor's header.
 
@@ -381,7 +381,7 @@ Sequencer: Display Image File Name
 When seeking through an image sequence, display the active strips'
 file name for the current frame, and its playhead (in square brackets).
 
-Usage: Find it in the VSE header.
+Usage: Find it in the sequencer header.
 
 
 EXR Render: Warn when Z not connected

manual/addons/mesh/tissue.rst

@@ -414,8 +414,8 @@ that generate the various patterns of many living organisms.
 See `this video <https://youtu.be/J-0NzU1TmIY>`__ for an example of the Reaction-Diffusion simulation with Tissue.
 
 
-Radom Materials
+Random Materials
----------------
+----------------
 
 (To Do)
 

manual/addons/object/greasepencil_tools.rst

@@ -76,7 +76,7 @@ Timeline Scrub
 Call a timeline popup at mouse position to scrub without leaving the 3D viewport.
 
 Default shortcut to call the timeline is :kbd:`Alt-MMB`.
-The shortcut enable the scrubbing when hovering timeline editors as well (dopesheet, sequencer, etc).
+The shortcut enable the scrubbing when hovering timeline editors as well (dope-sheet, sequencer, etc).
 
 Scene start/end and keyframes are represented with symbols on the timeline.
 

manual/addons/render/copy_settings.rst

@@ -43,7 +43,7 @@ Presets
    *This will work even without the UI template list patch.*
 
    Set Scale/Clear Scale
-      Copy the render scale setting (below resolution controls, in *Dimensions* panel).
+      Copy the render scale setting (below resolution controls, in *Format* panel).
       Highly useful to do preview renders!
 
    Set Resolution/Clear Resolution

manual/advanced/command_line/arguments.rst

@@ -1,6 +1,5 @@
 .. DO NOT EDIT THIS FILE, GENERATED BY 'blender_help_extract.py'
 
-
    CHANGES TO THIS FILE MUST BE MADE IN BLENDER'S SOURCE CODE, SEE:
    https://projects.blender.org/blender/blender/src/branch/main/source/creator/creator_args.c
 
@@ -10,10 +9,8 @@
 Command Line Arguments
 **********************
 
-
+| Blender |BLENDER_VERSION|
-Blender |BLENDER_VERSION|
+| Usage: ``blender [args ...] [file] [args ...]``
-Usage: blender [args ...] [file] [args ...]
-
 
 .. _command-line-args-render-options:
 
@@ -22,10 +19,13 @@ Render Options
 
 ``-b``, ``--background``
    Run in background (often used for UI-less rendering).
+
 ``-a``, ``--render-anim``
    Render frames from start to end (inclusive).
+
 ``-S``, ``--scene`` ``<name>``
    Set the active scene ``<name>`` for rendering.
+
 ``-f``, ``--render-frame`` ``<frame>``
    Render frame ``<frame>`` and save it.
 
@@ -33,12 +33,16 @@ Render Options
    * A comma separated list of frames can also be used (no spaces).
    * A range of frames can be expressed using ``..`` separator between the first and last frames (inclusive).
 
+
 ``-s``, ``--frame-start`` ``<frame>``
    Set start to frame ``<frame>``, supports +/- for relative frames too.
+
 ``-e``, ``--frame-end`` ``<frame>``
    Set end to frame ``<frame>``, supports +/- for relative frames too.
+
 ``-j``, ``--frame-jump`` ``<frames>``
    Set number of frames to step forward after each rendered frame.
+
 ``-o``, ``--render-output`` ``<path>``
    Set the render path and file name.
    Use ``//`` at the start of the path to render relative to the blend-file.
@@ -57,13 +61,36 @@ Render Options
       blender -b animation.blend -o //render_ -F PNG -x 1 -a
 
    ``//render_`` becomes ``//render_####``, writing frames as ``//render_0001.png``
+
 ``-E``, ``--engine`` ``<engine>``
    Specify the render engine.
    Use ``-E help`` to list available engines.
+
 ``-t``, ``--threads`` ``<threads>``
    Use amount of ``<threads>`` for rendering and other operations
    [1-1024], 0 for systems processor count.
 
+.. _command-line-args-cycles-render-options:
+
+Cycles Render Options
+=====================
+
+Cycles add-on options must be specified following a double dash.
+
+``--cycles-device`` ``<device>``
+   Set the device used for rendering.
+   Valid options are: ``CPU`` ``CUDA`` ``OPTIX`` ``HIP`` ``ONEAPI`` ``METAL``.
+
+   Append +CPU to a GPU device to render on both CPU and GPU.
+
+   Example:
+
+   .. code-block:: sh
+
+      blender -b file.blend -f 20 -- --cycles-device OPTIX
+
+``--cycles-print-stats``
+   Log statistics about render memory and time usage.
 
 .. _command-line-args-format-options:
 
@@ -73,10 +100,11 @@ Format Options
 ``-F``, ``--render-format`` ``<format>``
    Set the render format.
    Valid options are:
-   ``TGA`` ``RAWTGA`` ``JPEG`` ``IRIS`` ``IRIZ`` ``AVIRAW`` ``AVIJPEG`` ``PNG`` ``BMP``
+   ``TGA`` ``RAWTGA`` ``JPEG`` ``IRIS`` ``IRIZ`` ``AVIRAW`` ``AVIJPEG`` ``PNG`` ``BMP``.
 
    Formats that can be compiled into Blender, not available on all systems:
-   ``HDR`` ``TIFF`` ``OPEN_EXR`` ``OPEN_EXR_MULTILAYER`` ``MPEG`` ``CINEON`` ``DPX`` ``DDS`` ``JP2`` ``WEBP``
+   ``HDR`` ``TIFF`` ``OPEN_EXR`` ``OPEN_EXR_MULTILAYER`` ``MPEG`` ``CINEON`` ``DPX`` ``DDS`` ``JP2`` ``WEBP``.
+
 ``-x``, ``--use-extension`` ``<bool>``
    Set option to add the file extension to the end of the file.
 
@@ -96,7 +124,7 @@ Animation Playback Options
       Open with lower left corner at ``<sx>``, ``<sy>``.
    ``-m``
       Read from disk (Do not buffer).
-   ``-f`` ``<fps>`` ``<fps-base>``
+   ``-f`` ``<fps>`` ``<fps_base>``
       Specify FPS to start with.
    ``-j`` ``<frame>``
       Set frame step to ``<frame>``.
@@ -116,16 +144,22 @@ Window Options
 
 ``-w``, ``--window-border``
    Force opening with borders.
+
 ``-W``, ``--window-fullscreen``
    Force opening in fullscreen mode.
+
 ``-p``, ``--window-geometry`` ``<sx>`` ``<sy>`` ``<w>`` ``<h>``
    Open with lower left corner at ``<sx>``, ``<sy>`` and width and height as ``<w>``, ``<h>``.
+
 ``-M``, ``--window-maximized``
    Force opening maximized.
+
 ``-con``, ``--start-console``
    Start with the console window open (ignored if ``-b`` is set), (Windows only).
+
 ``--no-native-pixels``
    Do not use native pixel size, for high resolution displays (MacBook ``Retina``).
+
 ``--no-window-focus``
    Open behind other windows and without taking focus.
 
@@ -136,23 +170,31 @@ Python Options
 ==============
 
 ``-y``, ``--enable-autoexec``
-   Enable automatic Python script execution (default).
+   Enable automatic Python script execution.
+
 ``-Y``, ``--disable-autoexec``
-   Disable automatic Python script execution (pydrivers & startup scripts).
+   Disable automatic Python script execution (pydrivers & startup scripts), (default).
+
 
 ``-P``, ``--python`` ``<filepath>``
    Run the given Python script file.
+
 ``--python-text`` ``<name>``
    Run the given Python script text block.
+
 ``--python-expr`` ``<expression>``
    Run the given expression as a Python script.
+
 ``--python-console``
    Run Blender with an interactive console.
+
 ``--python-exit-code`` ``<code>``
    Set the exit-code in [0..255] to exit if a Python exception is raised
    (only for scripts executed from the command line), zero disables.
+
 ``--python-use-system-env``
    Allow Python to use system environment variables such as ``PYTHONPATH`` and the user site-packages directory.
+
 ``--addons`` ``<addon(s)>``
    Comma separated list (no spaces) of add-ons to enable in addition to any default add-ons.
 
@@ -170,15 +212,20 @@ Logging Options
    so ``--log "*undo*"`` logs every kind of undo-related message.
    Use "^" prefix to ignore, so ``--log "*,^wm.operator.*"`` logs all except for ``wm.operators.*``
    Use "*" to log everything.
+
 ``--log-level`` ``<level>``
    Set the logging verbosity level (higher for more details) defaults to 1,
    use -1 to log all levels.
+
 ``--log-show-basename``
    Only show file name in output (not the leading path).
+
 ``--log-show-backtrace``
    Show a back trace for each log message (debug builds only).
+
 ``--log-show-timestamp``
    Show a timestamp for each log message in seconds since start.
+
 ``--log-file`` ``<filepath>``
    Set a file to output the log to.
 
@@ -194,73 +241,109 @@ Debug Options
    * Enables memory error detection
    * Disables mouse grab (to interact with a debugger in some cases)
    * Keeps Python's ``sys.stdin`` rather than setting it to None
+
 ``--debug-value`` ``<value>``
    Set debug value of ``<value>`` on startup.
 
+
 ``--debug-events``
    Enable debug messages for the event system.
+
 ``--debug-ffmpeg``
    Enable debug messages from FFmpeg library.
+
 ``--debug-handlers``
    Enable debug messages for event handling.
+
 ``--debug-libmv``
    Enable debug messages from libmv library.
+
 ``--debug-cycles``
    Enable debug messages from Cycles.
+
 ``--debug-memory``
    Enable fully guarded memory allocation and debugging.
+
 ``--debug-jobs``
    Enable time profiling for background jobs.
+
 ``--debug-python``
    Enable debug messages for Python.
+
 ``--debug-depsgraph``
    Enable all debug messages from dependency graph.
+
 ``--debug-depsgraph-eval``
    Enable debug messages from dependency graph related on evaluation.
+
 ``--debug-depsgraph-build``
    Enable debug messages from dependency graph related on graph construction.
+
 ``--debug-depsgraph-tag``
    Enable debug messages from dependency graph related on tagging.
+
 ``--debug-depsgraph-no-threads``
    Switch dependency graph to a single threaded evaluation.
+
 ``--debug-depsgraph-time``
    Enable debug messages from dependency graph related on timing.
+
 ``--debug-depsgraph-pretty``
    Enable colors for dependency graph debug messages.
+
 ``--debug-depsgraph-uuid``
    Verify validness of session-wide identifiers assigned to ID datablocks.
+
 ``--debug-ghost``
    Enable debug messages for Ghost (Linux only).
+
 ``--debug-wintab``
    Enable debug messages for Wintab.
+
 ``--debug-gpu``
    Enable GPU debug context and information for OpenGL 4.3+.
+
 ``--debug-gpu-force-workarounds``
    Enable workarounds for typical GPU issues and disable all GPU extensions.
+
 ``--debug-gpu-disable-ssbo``
    Disable usage of shader storage buffer objects.
+
 ``--debug-gpu-renderdoc``
    Enable Renderdoc integration for GPU frame grabbing and debugging.
+
 ``--debug-wm``
    Enable debug messages for the window manager, shows all operators in search, shows keymap errors.
+
 ``--debug-xr``
    Enable debug messages for virtual reality contexts.
    Enables the OpenXR API validation layer, (OpenXR) debug messages and general information prints.
+
 ``--debug-xr-time``
    Enable debug messages for virtual reality frame rendering times.
+
 ``--debug-all``
    Enable all debug messages.
+
 ``--debug-io``
    Enable debug messages for I/O (Collada, ...).
 
+
 ``--debug-fpe``
    Enable floating-point exceptions.
+
 ``--debug-exit-on-error``
    Immediately exit when internal errors are detected.
+
+``--debug-freestyle``
+   Enable debug messages for Freestyle.
+
 ``--disable-crash-handler``
    Disable the crash handler.
+
 ``--disable-abort-handler``
    Disable the abort handler.
+
 ``--verbose`` ``<verbose>``
    Set the logging verbosity level for debug messages that support it.
 
@@ -281,49 +364,60 @@ Misc Options
 
 ``--open-last``
    Open the most recently opened blend file, instead of the default startup file.
+
 ``--app-template`` ``<template>``
    Set the application template (matching the directory name), use ``default`` for none.
+
 ``--factory-startup``
-   Skip reading the startup.blend in the users home directory.
+   Skip reading the ``startup.blend`` in the users home directory.
+
 ``--enable-event-simulate``
    Enable event simulation testing feature ``bpy.types.Window.event_simulate``.
 
+
 ``--env-system-datafiles``
    Set the ``BLENDER_SYSTEM_DATAFILES`` environment variable.
+
 ``--env-system-scripts``
    Set the ``BLENDER_SYSTEM_SCRIPTS`` environment variable.
+
 ``--env-system-python``
    Set the ``BLENDER_SYSTEM_PYTHON`` environment variable.
 
+
 ``-noaudio``
    Force sound system to None.
+
 ``-setaudio``
    Force sound system to a specific device.
    ``None`` ``SDL`` ``OpenAL`` ``CoreAudio`` ``JACK`` ``PulseAudio`` ``WASAPI``.
 
+
 ``-h``, ``--help``
    Print this help text and exit.
+
 ``/?``
    Print this help text and exit (Windows only).
-``-R``
+
-   Register blend-file extension, then exit (Windows only).
+``-r``, ``--register``
-``-r``
+   Register blend-file extension for current user, then exit (Windows only).
-   Silently register blend-file extension, then exit (Windows only).
+
+``--register-allusers``
+   Register blend-file extension for all users, then exit (Windows only).
+
+``--unregister``
+   Unregister blend-file extension for current user, then exit (Windows only).
+
+``--unregister-allusers``
+   Unregister blend-file extension for all users, then exit (Windows only).
+
 ``-v``, ``--version``
    Print Blender version and exit.
+
 ``--``
    End option processing, following arguments passed unchanged. Access via Python's ``sys.argv``.
 
 
-.. _command-line-args-other-options:
-
-Other Options
-=============
-
-``--debug-freestyle``
-   Enable debug messages for Freestyle.
-
-
 .. _command-line-args-argument-parsing:
 
 Argument Parsing
@@ -337,7 +431,6 @@ Arguments must be separated by white space, eg:
 
 ...will exit since ``-ba`` is an unknown argument.
 
-
 .. _command-line-args-argument-order:
 
 Argument Order
@@ -347,7 +440,7 @@ Arguments are executed in the order they are given. eg:
 
 .. code-block:: sh
 
-   blender --background test.blend --render-frame 1 --render-output '/tmp'
+   blender --background test.blend --render-frame 1 --render-output "/tmp"
 
 ...will not render to ``/tmp`` because ``--render-frame 1`` renders before the output path is set.
 
@@ -363,7 +456,6 @@ Arguments are executed in the order they are given. eg:
 
 ...works as expected.
 
-
 .. _command-line-args-environment-variables:
 
 Environment Variables
@@ -381,5 +473,5 @@ Environment Variables
 :BLENDER_SYSTEM_DATAFILES:  Directory for system wide data files.
 :BLENDER_SYSTEM_PYTHON:     Directory for system Python libraries.
 :OCIO:                     Path to override the OpenColorIO config file.
-:TEMP:                     Store temporary files here.
+:TEMP:                     Store temporary files here (MS-Windows).
-:TMP: or $TMPDIR           Store temporary files here.
+:TMP: or $TMPDIR           Store temporary files here (UNIX Systems).

manual/advanced/command_line/render.rst

@@ -14,13 +14,14 @@ and consequently we can render via a remote shell (typically SSH).
 - See :doc:`Command Line Arguments </advanced/command_line/arguments>`
   for a full list of arguments
   (for example to specify which scene to render, the end frame number, etc.), or simply run:
-- See :ref:`Command Line Launching <command_line-launch-index>`
-  for specific instructions on launching Blender from the command line.
 
 .. code-block:: sh
 
    blender --help
 
+- See :ref:`Command Line Launching <command_line-launch-index>`
+  for specific instructions on launching Blender from the command line.
+
 .. note::
 
    Arguments are executed in the order they are given!
@@ -98,20 +99,4 @@ Cycles
 
 In addition to the options above, which apply to all render engines,
 Cycles has additional options to further control its behavior. 
-
+See :ref:`Cycles Render Options <command-line-args-cycles-render-options>`
-.. code-block:: sh
-
-   blender -b file.blend -f 20 -- --cycles-device CPU
-
-.. note::
-
-   Unlike the generic options, the Cycles-specific ones must be passed on
-   the end of the command line, following a double dash.
-
-``--cycles-device CPU``
-   Override the device that is used to render frames.
-   Currently supported options are ``CPU``, ``CUDA``, ``OPTIX``, ``HIP``, ``ONEAPI``, and ``METAL``.
-   Additionally, you can append ``+CPU`` to any GPU type for hybrid rendering.
-
-``--cycles-print-stats``
-   Show detailed statistics about memory and time usage for Cycles renders on the console.

manual/animation/armatures/posing/editing/pose_library.rst

@@ -1,3 +1,4 @@
+
 .. _bpy.ops.poselib:
 
 ************
@@ -70,13 +71,9 @@ True to its name, the *Create Pose Asset* button automatically marks the Action
 Not only does this make it available in the pose library, it will also act as a *fake user*
 to ensure the Action isn't lost after you unassign it from the armature.
 
-The *Create Pose Asset* button is also available in the 3D Viewport sidebar.
+The pose asset can be renamed in the Asset Browser. There you can also right
-This button acts almost the same as the one in the Action Editor, except for one thing:
+click on the thumbnail, then choose Assign Action to assign the Action to the
-it will not assign the newly created Action. Doing so would be invisible,
+active Object (see description above).
-as the pose doesn't change and the name of the current Action is not shown in the viewport.
-The pose asset can still be renamed in the Asset Browser.
-There you can also click the *Assign Action* button to explicitly assign
-the selected pose asset as the armature's active Action.
 
 .. note::
 
@@ -127,8 +124,7 @@ data to the currently open blend-file. To copy a pose from some other file into
 a pose library file, see the following steps:
 
 - Pose the character and select the relevant bones.
-- Click the **Copy Pose as Asset button**, which is available in the Action Editor
+- Click the **Copy Pose as Asset button**, which is available in the Action Editor. This will create the pose asset
-  as well as the 3D Viewport Sidebar. This will create the pose asset
   (including its thumbnail) and store it in a temporary file somewhere.
 - Choose an existing pose asset, and open its context menu. Click the **Open Blend File** option.
 - A new Blender process will start, and automatically open the asset library
@@ -213,14 +209,6 @@ The **Pose Library panels will appear** when the active object is an armature
 and in Pose Mode. The :doc:`catalog system </files/asset_libraries/catalogs>`
 and the filter bar at the top can be used to search for specific poses.
 
-.. _bpy.types.WindowManager.poselib_flipped:
-
-Flip Pose
-   Will mirror the pose from left to right and vice versa.
-   This makes it possible, for example, to apply a left-hand pose to the right hand,
-   reducing the number of poses you have to put into the library.
-   This can of course also be applied for asymmetrical facial expressions
-   that depend on the camera angle.
 
 The following operators can be accessed by :kbd:`RMB` on a pose:
 
@@ -233,13 +221,23 @@ Apply Pose
    and then an "open hand" pose for only the index finger and thumb.
    Double-clicking a pose will also apply it.
 
+Apply Pose Flipped
+   Will mirror the pose from left to right and vice versa. This makes it
+   possible, for example, to apply a left-hand pose to the right hand, reducing
+   the number of poses you have to put into the library. This can of course also
+   be applied for asymmetrical facial expressions that depend on the camera
+   angle. While blending (see below), keep :kbd:`Ctrl` pressed to blend the flipped pose.
+
 .. _bpy.ops.poselib.blend_pose_asset:
 
 Blend Pose
    Allows you to gradually blend a pose from the library into the character's pose.
    Click the button, then move the mouse left/right to determine the desired blend.
-   While blending, you can use the Tab key to toggle between the original and the blended pose.
+   A pose asset can be "subtracted" while blending. Drag to the right to blend as usual, drag to the left to subtract
-   As usual in Blender, left-click or press Enter to confirm; right-click or press Escape to cancel the operator.
+   the pose. While blending, you can use :kbd:`Tab` to toggle between the original and the blended pose.
+   As usual in Blender, :kbd:`LMB` or press :kbd:`Return` to confirm; :kbd:`RMB` or press :kbd:`Esc` to cancel the
+   operator. Blending can also exaggerate a pose, by pressing :kbd:`E` (for Extrapolate) and applying a pose for more
+   than 100%.
 
 .. _bpy.ops.poselib.pose_asset_select_bones:
 
@@ -266,8 +264,6 @@ This means that it can allow faster interaction.
 You can also select and apply a pose via the cursor keys.
 This allows for fast exploration of the poses,
 to directly see the result on the active character.
-Of course the *Flip Pose* checkbox is available here as well --
-it works the same as described in the previous section.
 
 **Drag the pose thumbnail left to right to blend it** into the character's current pose.
 Just release the mouse button to confirm.

manual/compositing/introduction.rst

@@ -85,7 +85,7 @@ When nodes receive inputs with differently sized Images, these rules apply:
 
 So each node in a composite can operate on different sized images as defined by its inputs.
 Only the *Composite* output node has a fixed size,
-as defined by the settings in Properties :menuselection:`Render --> Dimensions`.
+as defined by the settings in :menuselection:`Output Properties --> Render --> Format`.
 The *Viewer* node always shows the size from its input, but when not linked
 (or linked to a value) it shows a small 320×256 pixel image.
 

manual/compositing/realtime_compositor.rst

@@ -184,9 +184,9 @@ If an input image to a node is not perfectly aligned with the operation domain o
 different size in pixels, the node would typically need to do a process called Interpolation, where
 the input image is read at the exact positions of the pixels of the operation domain. This can be
 done using different interpolation methods, including Nearest-Neighbor, Bilinear, and Bicubic
-interpolations. Those interpolation methods are demonstrated in the following `Wikipedia gallery
+interpolations. Those interpolation methods are demonstrated in the following
-<https://en.wikipedia.org/wiki/Comparison_gallery_of_image_scaling_algorithms>`_. Transformation
+`Wikipedia gallery <https://en.wikipedia.org/wiki/Comparison_gallery_of_image_scaling_algorithms>`__.
-nodes like the :ref:`Transform <bpy.types.CompositorNodeTransform>` and :ref:`Rotate
+Transformation nodes like the :ref:`Transform <bpy.types.CompositorNodeTransform>` and :ref:`Rotate
 <bpy.types.CompositorNodeRotate>` nodes include an interpolation option to set how they prefer their
 output image to be read and interpolated.
 

manual/compositing/types/color/hue_saturation.rst

@@ -1,4 +1,4 @@
-.. index:: Compositor Nodes; Hue Saturation Value
+.. index:: Compositor Nodes; Hue/Saturation/Value
 .. _bpy.types.CompositorNodeHueSat:
 .. Editor's Note: This page gets copied into:
 .. - :doc:`</render/cycles/nodes/types/color/hue_saturation>`
@@ -6,14 +6,14 @@
 .. --- copy below this line ---
 
 *************************
-Hue Saturation Value Node
+Hue/Saturation/Value Node
 *************************
 
 .. figure:: /images/compositing_node-types_CompositorNodeHueSat.webp
    :align: right
-   :alt: Hue Saturation Node.
+   :alt: Hue/Saturation/Value Node.
 
-The *Hue Saturation Value Node* applies a color transformation in the HSV :term:`Color Model`.
+The *Hue/Saturation/Value Node* applies a color transformation in the HSV :term:`Color Model`.
 
 
 Inputs

manual/compositing/types/color/index.rst

@@ -18,7 +18,7 @@ overlaying another image, etc.
    gamma.rst
    hue_correct.rst
    hue_saturation.rst
-   invert.rst
+   invert_color.rst
    mix.rst
    posterize.rst
    rgb_curves.rst

manual/compositing/types/color/invert_color.rst

@@ -1,19 +1,19 @@
-.. index:: Compositor Nodes; Invert
+.. index:: Compositor Nodes; Invert Color
 .. _bpy.types.CompositorNodeInvert:
 .. Editor's Note: This page gets copied into:
 .. - :doc:`</render/cycles/nodes/types/color/invert>`
 
 .. --- copy below this line ---
 
-***********
+*****************
-Invert Node
+Invert Color Node
-***********
+*****************
 
 .. figure:: /images/compositing_node-types_CompositorNodeInvert.webp
    :align: right
-   :alt: Invert Node.
+   :alt: Invert Color Node.
 
-The *Invert Node* inverts the colors in the input image, producing a negative.
+The *Invert Color Node* inverts the colors in the input image, producing a negative.
 
 
 Inputs

manual/compositing/types/converter/color_space.rst

@@ -9,8 +9,6 @@ Color Space Node
    :align: right
    :alt: Color Space Node.
 
-:guilabel:`CPU Compositor Only`
-
 The *Color Space Node* converts images from one :term:`color spaces <Color Space>`.
 
 .. note::

manual/compositing/types/converter/id_mask.rst

@@ -9,8 +9,6 @@ ID Mask Node
    :align: right
    :alt: ID Mask Node.
 
-:guilabel:`CPU Compositor Only`
-
 The *ID Mask Node* can be used to access an alpha mask per object or per material.
 
 .. seealso::

manual/compositing/types/distort/plane_track_deform.rst

@@ -9,8 +9,6 @@ Plane Track Deform Node
    :align: right
    :alt: Plane Track Deform Node.
 
-:guilabel:`CPU Compositor Only`
-
 The Plane Track Deform Node is used to incorporate the special "plane track" in your composite by checking areas
 which are planes, and replacing their footage with some other image.
 

manual/compositing/types/filter/denoise.rst

@@ -9,8 +9,6 @@ Denoise Node
    :align: right
    :alt: Denoise Node.
 
-:guilabel:`CPU Compositor Only`
-
 The Denoise node is used to denoise renders from :doc:`Cycles </render/cycles/index>`
 and other ray tracing renderers. This helps to significantly reduce render time by
 rendering with fewer samples.

manual/contribute/editing.rst

@@ -18,7 +18,7 @@ Update
 
 Firstly, make sure that your local copy of the manual is up to date with the online repository using::
 
-   git pull --rebase
+   make update
 
 
 Writing
@@ -40,7 +40,7 @@ Bigger Changes
 If you are going to add or overhaul a section, be sure to check carefully that it does not already exist.
 In some places, the docs are so disorganized that sections may be duplicated or in a strange location.
 In the case that you find a duplicate or out of place section,
-`create a task <https://projects.blender.org/blender/documentation/issues/new>`__
+`create an issue <https://projects.blender.org/blender/documentation/issues/new>`__
 explaining the issue, and optionally include a revision (actual changes).
 
 Before you make any edits that are not simple and plainly justified (for example, moving folders around),

manual/contribute/guides/commit_guide.rst

@@ -20,7 +20,7 @@ If you leave out ``-m "message"``, you will be prompted to type the message in a
    You should make sure you are always on the latest revision before committing.
    You may not be able to commit directly if there are conflicting changes in the latest revision.
 
-   To avoid this run ``git pull --rebase`` before committing.
+   To avoid this update your local repository before committing (run ``make update``).
 
 .. seealso::
 

manual/contribute/install/windows.rst

@@ -52,7 +52,7 @@ Setting up the Build Environment
 ================================
 
 - Open a Command Prompt. (Run as Administrator)
-- Enter the ``blender-manual`` folder which was just added by the SVN checkout::
+- Enter the ``blender-manual`` folder which was just added by `git clone`::
 
      cd C:\blender-manual
 

manual/contribute/pull_requests.rst

@@ -73,8 +73,7 @@ Guidelines for Reviewers
   ``WIP:`` prefix in the title, indicating the author considers the pull request not ready to be merged.
   No review is expected unless the author specifically asks for it.
 - Writers are expected to reply to pull requests in 3 working days.
-- Add relevant modules/projects to tags.
+- Add relevant modules/projects to the labels.
-- Assign individuals (instead of modules/projects) for reviewers, to avoid too much noise.
 - Encourage new writes to do review, it's a good way to learn and important to grow the project.
 
 

manual/contribute/translations/add_language.rst

@@ -24,7 +24,7 @@ This will give you a foundation environment for:
 Below examples show the process to create a new set of files for French, language code ``fr``, on Linux platform.
 Other platforms might vary slightly but should be mainly the same.
 
-#. `Create a Blender ID <https://id.blender.org/register/>` if you have not done so already
+#. `Create a Blender ID <https://id.blender.org/register/>`__ if you have not done so already
 #. Log into `projects.blender.org <https://projects.blender.org/>`__ and
    `Create an Issue <https://projects.blender.org/blender/documentation/issues/new>`__
    requesting for commit access in order to transfer changes to the central repository of the translation team.

manual/editors/3dview/display/overlays.rst

@@ -84,8 +84,13 @@ Annotations
 Objects
 -------
 
-Extra
+Extras
    Show objects that don't have geometry (such as empties, cameras and lights).
+
+.. _bpy.types.View3DOverlay.show_light_colors:
+
+Light Colors
+   Shades the outline of light objects to the color the light produces.
 Relationship Lines
    Show dashed lines indicating parent or constraint relationships.
 Outline Selected
@@ -183,27 +188,31 @@ Seams
 Shading
 -------
 
-Hidden Wire
+.. _bpy.types.View3DOverlay.show_retopology:
-   Show only front-facing wireframes.
-   This is useful for a retopology workflow.
 
-   .. tip::
+Retopology
+   Hide the solid mesh and offset the overlay towards the view.
+   Selection is occluded by inactive geometry, unless X-Ray is enabled
 
-      Optimally this could be combined with the *X-Ray* display setting.
+   .. _bpy.types.View3DOverlay.retopology_offset:
+
+   Offset
+      Amount to offset edit mesh in front of other geometry.
+
+.. _bpy.types.View3DOverlay.show_weight:
 
 Vertex Groups Weights
    Display weights in Edit Mode.
 
+   .. _bpy.types.ToolSettings.vertex_group_user:
+
    Zero Weights
       Display unreferenced and zero-weighted areas in black.
       This helps to identify areas with very low weights that have been painted onto.
 
-      None
+      :None: Vertices are displayed in the usual way.
-         Vertices are displayed in the usual way.
+      :Active: Vertices are shown in black if they have no weight in the active vertex group.
-      Active
+      :All: Vertices are shown in black if they have no weight in any vertex group.
-         Vertices are shown in black if they have no weight in the active vertex group.
-      All
-         Vertices are shown in black if they have no weight in any vertex group.
 
 
 Mesh Analysis

manual/editors/graph_editor/channels/introduction.rst

@@ -54,7 +54,8 @@ Selecting
 ---------
 
 - Select channel (text in white/black): :kbd:`LMB`
-- Multi Select/Deselect: :kbd:`Shift-LMB`
+- Multi Select/Deselect: :kbd:`Ctrl-LMB`
+- Range Select: :kbd:`Shift-LMB`
 - Select All: :kbd:`A`
 - Deselect All: :kbd:`Alt-A`
 - Box Select: (:kbd:`LMB` drag) or :kbd:`B` (:kbd:`LMB` drag)

manual/editors/graph_editor/fcurves/editing.rst

@@ -150,14 +150,14 @@ Copy/Paste
 
 .. admonition:: Reference
 
-   :Menu:      :menuselection:`Key --> Copy Keyframes`, :menuselection:`Key --> Paste Keyframes`
+   :Menu:      :menuselection:`Key --> Copy`, :menuselection:`Key --> Paste`
    :Shortcut:  :kbd:`Ctrl-C`, :kbd:`Ctrl-V`
 
 Use :kbd:`Ctrl-C` to copy selected keyframes and :kbd:`Ctrl-V` to paste the previously copied keyframes.
 During the paste action, the :ref:`bpy.ops.screen.redo_last` panel provides some options in
 how the paste is applied.
 
-Offset
+Frame Offset
    :No Offset:
       Pastes the keyframes in the location they were copied from.
    :Frame Relative:
@@ -167,6 +167,19 @@ Offset
       Pastes the keyframes with the first keyframe of the copied set placed at the current frame.
    :Frame End:
       Pastes the keyframes with the last keyframe of the copied set placed at the current frame.
+
+Value Offset
+   :No Offset:
+      Pastes the keyframes with the value they were copied from.
+   :Cursor Value:
+      Paste the keyframes at the 2D cursor as a starting point.
+   :Current Frame Value:
+      Paste keyframes relative to the value of the curve under the cursor.
+   :Right Key:
+      Paste keyframes such that the last frame matches the key value right of the cursor.
+   :Left Key:
+      Paste keyframes such that the first key matches the key value left of the cursor.
+
 Type
    :Mix:
       Integrates the pasted keyframes in with existing keyframes only overwriting keyframes that share a frame.
@@ -442,3 +455,31 @@ seem to be never modified by this tool.
      - .. figure:: /images/editors_graph-editor_fcurves_editing_smooth.png
 
           F-Curve after smoothing.
+
+
+.. _bpy.ops.graph.gaussian_smooth:
+
+Smooth (Gaussian)
+-----------------
+
+.. reference::
+
+   :Menu:      :menuselection:`Key --> Smooth --> Smooth (Gaussian)`
+
+Smooths the selected keyframes using a Gaussian kernel. It can handle gaps in the keyframe data.
+The operator is modal with a blend factor, making it possible to tweak the strength of the filter.
+
+Factor
+   A blend factor from original to filtered curve.
+
+Sigma
+   The shape of the gaussian distribution. Lower values mean a sharper curve, giving keys that are close to each
+   other more weight. A high value behaves like a simple average filter.
+
+Filter Width
+   A wider filter looks at more keyframes, producing a smoother result.
+   At a size of 1 the filter only looks at the keyframes to the immediate left and right for a weighted average.
+
+.. figure:: /images/editors_graph-editor_gaussian_smooth.jpg
+
+   F-Curve after applying the Gaussian Smooth with the original curve overlayed.

manual/editors/graph_editor/fcurves/properties.rst

@@ -163,8 +163,9 @@ Interpolation
 
    .. seealso::
 
-      For more info and a few live demos, see https://easings.net and
+      For more info and a few live demos,
-      http://robertpenner.com/easing/
+      see `easings.net <https://easings.net>`__ and
+      `Robert Penner's Easing Functions <http://robertpenner.com/easing>`__.
 
 
    .. rubric:: Dynamic Effects

manual/editors/image/editing.rst

@@ -14,7 +14,7 @@ New
    :Menu:      :menuselection:`Image --> New`
    :Shortcut:  :kbd:`Alt-N`
 
-Creates a new :ref:`image-generated` Image.
+Create a new :ref:`image-generated` Image.
 
 
 .. _bpy.ops.image.open:
@@ -28,7 +28,7 @@ Open
    :Menu:      :menuselection:`Image --> Open`
    :Shortcut:  :kbd:`Alt-O`
 
-Load image from a file.
+Load an image from a file.
 
 
 .. _bpy.ops.image.read_viewlayers:

manual/editors/image/sidebar.rst

@@ -43,7 +43,7 @@ You can set the editor's display options in this panel.
 Aspect Ratio
    Display aspect for this image. Does not affect rendering.
 Repeat Image
-   Tiles the image so it completely fills the editor.
+   Tile the image so it completely fills the editor.
 
 
 Annotations
@@ -78,7 +78,7 @@ A predominantly dark image would have the highest values toward the left side of
 Use this mode to balance out the tonal range in an image.
 A well-balanced image should have a nice smooth distribution of color values.
 
-You can drag the mouse in the histogram to adjust its vertical zoom.
+You can drag :kbd:`LMB` in the histogram to adjust its vertical zoom.
 
 Luma
    Shows a luminosity histogram.

manual/editors/nla/tracks.rst

@@ -12,9 +12,6 @@ the bottom layer first, to the top, last.
 
    NLA Tracks and Strips.
 
-Solo (star icon)
-   Toggling *Solo Track* causes only the selected tracks effects to be visible when animating.
-   This is very useful for debugging complex animations.
 Mute (checkbox)
    Keeps the track from having an effect on the animation. (Mute only applies when *Solo* is not used.)
    All strips in that track are shown as being muted (dashed outline).
@@ -22,6 +19,9 @@ Lock (padlock icon)
    Prevents changes from being made to this layer.
    This is useful, for example, if you want to select several strips and move them;
    but you want to keep a few tracks excluded from the change.
+Solo (star icon)
+   Toggling *Solo Track* causes only the selected tracks effects to be visible when animating.
+   This is very useful for debugging complex animations.
 
 
 Action Track

manual/editors/outliner/interface.rst

@@ -34,10 +34,10 @@ Data API
 Library Overrides
    Display library override data in the current blend-file. Separated further into two view modes:
 
-   Properties:
+   :Properties:
       Display data-blocks with overridden properties. The overridden properties are listed together with widgets to
       modify the value of the properties.
-   Hierarchies:
+   :Hierarchies:
       Visualize the hierarchical dependencies between data-blocks with library overrides. For example, to create a
       library override of a mesh used by an object inside of a linked collection, Blender automatically creates
       (disabled) library overrides for the object and the collection, resulting in a collection > object > mesh
@@ -137,19 +137,19 @@ Object State
    List the objects based on their state or restrictions.
    The results can be inverted using the *Invert* button.
 
-   All
+   :All:
       The default option, no restrictions.
-   Visible
+   :Visible:
       List only the objects visible in the viewports.
       The global and temporary visibility settings are taken into consideration.
-   Invisible
+   :Invisible:
       List only the objects not visible in the viewports.
-   Selected
+   :Selected:
       Lists the object(s) that are currently selected in the 3D Viewport.
       See :doc:`selecting in the 3D Viewport </scene_layout/object/selecting>` for more information.
-   Active
+   :Active:
       Lists only the active (often last selected) object.
-   Selectable
+   :Selectable:
       List all objects whose :ref:`Selectability <bpy.types.Collection.hide_select>` option is enabled.
 
 .. _bpy.types.SpaceOutliner.use_filter_object_content:
@@ -167,6 +167,7 @@ Object Children
 .. _bpy.types.SpaceOutliner.use_filter_object_mesh:
 .. _bpy.types.SpaceOutliner.use_filter_object_light:
 .. _bpy.types.SpaceOutliner.use_filter_object_camera:
+.. _bpy.types.SpaceOutliner.use_filter_object_grease_pencil:
 .. _bpy.types.SpaceOutliner.use_filter_object_empty:
 .. _bpy.types.SpaceOutliner.use_filter_object_others:
 

manual/editors/preferences/system.rst

@@ -46,10 +46,10 @@ Distribute Memory Across Devices
 
    Currently only NVLink on Nvidia GPUs is supported.
 
-MetalRT (Experimental)
+Embree on GPU
-   MetalRT for ray tracing uses less memory for scenes which use curves extensively,
+   Enables the use of hardware ray tracing on Intel GPUs, providing better overall performance.
-   and can give better performance in specific cases.
+
-   This feature is experimental and some scenes may render incorrectly.
+   Only supported with oneAPI rendering devices..
 
 HIP RT (Experimental)
    Speeds up rendering by enabling AMD hardware ray tracing on RDNA2 and above, with shader fallback on older cards.
@@ -57,6 +57,11 @@ HIP RT (Experimental)
 
    This feature is only available when using a *HIP* render device.
 
+MetalRT (Experimental)
+   MetalRT for ray tracing uses less memory for scenes which use curves extensively,
+   and can give better performance in specific cases.
+   This feature is experimental and some scenes may render incorrectly.
+
 
 Operating System Settings
 =========================

manual/editors/texture_node/types/color/index.rst

@@ -7,7 +7,7 @@
    :maxdepth: 1
 
    combine_color.rst
-   invert.rst
+   invert_color.rst
    mix_rgb.rst
    rgb_curves.rst
    hue_saturation.rst

manual/editors/texture_node/types/color/invert_color.rst

@@ -1,4 +1,4 @@
 .. _bpy.types.TextureNodeInvert:
 .. DO NOT EDIT FILE. This is simply a stub which copies everything from the link below.
-.. include:: /compositing/types/color/invert.rst
+.. include:: /compositing/types/color/invert_color.rst
    :start-after: .. --- copy below this line ---

manual/editors/timeline.rst

@@ -302,7 +302,7 @@ Cache
    Show Cache
       Show all enabled types.
 
-      Soft Body, Particles, Cloth, Smoke, Dynamic Paint, Rigid Body.
+      Soft Body, Particles, Cloth, Simulation Nodes, Smoke, Dynamic Paint, Rigid Body.
 
    .. figure:: /images/editors_timeline_cache.png
 

manual/editors/uv/controls/snapping.rst

@@ -3,6 +3,13 @@
 Snapping
 ********
 
+Snapping lets you easily align UV elements to others.
+It can be toggled by clicking the magnet icon in the UV Editor's header,
+or more temporarily by holding :kbd:`Ctrl`.
+
+This page is about the Snap header button; for the Snap menu,
+see :ref:`UV Editing <bpy.ops.uv.snap_selected>`.
+
 .. _bpy.types.ToolSettings.snap_uv_element:
 
 Snap To
@@ -14,23 +21,20 @@ Snap To
    :Shortcut:  :kbd:`Shift-Ctrl-Tab`
 
 Increment
-   Snap elements along points on a fixed scale.
+   Snaps to grid points.
-   These points are defined by the intersection points of the grid
-   and the scale of the increments depending on zoom level,
-   unless using :ref:`Fixed Subdivisions <bpy.types.SpaceUVEditor.custom_grid_subdivisions>`.
-
-   The Custom Grid can also be used to define a set distance of the scale.
 
    .. note::
 
-      In this context the grid does not mean the visual grid cue displayed.
+      By default, this option won't snap to the grid that's displayed in the editor,
-      Snapping will use the resolution of the displayed grid,
+      but an imaginary grid with the same resolution that starts at the selection's
-      but all transformations are relative to the initial position (before the snap operation).
+      original location. In other words, it lets you move the selection in "increments" of the
+      grid cell size.
 
-      Note, the behavior can be disabled by using *Absolute Grid Snap*.
+      If you want to snap to the viewport grid instead, you can enable *Absolute Grid Snap*
+      (see below).
 
 Vertex
-   Snap to UV vertices.
+   Snaps to the vertex that's closest to the mouse cursor.
 
 
 Additional Options
@@ -38,15 +42,16 @@ Additional Options
 
 .. _bpy.types.ToolSettings.use_snap_uv_grid_absolute:
 
-Absolute Grid Snap
+Absolute Grid Snap :guilabel:`Increment`
-   Available only for the *Increment* option.
+   Snaps to the grid, instead of snapping in increments relative to the current location.
-   Snap to the visual grid, instead of snapping in increments relative to the current location.
 
-Target
+Target :guilabel:`Vertex`
    See :ref:`3D Viewport Snapping <bpy.types.ToolSettings.snap_target>` for more information.
 
 
 Affect
 ======
 
-Limits the effect of the snap to the transformation type.
+Specifies which transformations are affected by snapping.
+By default, snapping only happens while moving something,
+but you can also enable it for rotating and scaling.

manual/editors/uv/introduction.rst

@@ -4,41 +4,42 @@
 Introduction
 ************
 
-The UV Editor is used to map 2D assets like images/textures
+The UV Editor is used for editing UV maps, which describe how a 2D image should be mapped
-onto 3D objects and edit what are called UVs.
+onto a 3D object.
 
 .. figure:: /images/editors_uv_introduction_main.png
 
    UV Editor with a UV map and a test grid texture.
 
-The most flexible way of mapping a 2D texture over a 3D object is a process called "UV mapping".
+Image textures are typically needed when the desired look is hard to achieve with procedural textures,
-In this process, you take your three-dimensional (X, Y & Z) mesh and unwrap it to a flat two-dimensional
+or if the texture is not uniform. For example, a car would only have scratches in a few places where they make sense,
-(X & Y ... or rather, as we shall soon see, "U & V") image. Colors in the image are thus mapped to your mesh,
+not in random places all over its body.
-and show up as the color of the faces of the mesh. Use UV texturing to provide realism to your objects that
+
-procedural materials and textures cannot do, and better details than Vertex Painting can provide.
+Blender offers a number of projections (Box, Sphere...) that automatically apply a 2D image to a 3D object,
+but these tend to only work for simple meshes. For more complex ones, you need to create a UV map instead.
+This is a flat area where each face of the 3D object is laid out on the 2D image, specifying which part of the
+image it should be textured with. This gives you complete control over the mapping process.
+
+The name "UV" refers to the axes of the map: U for horizontal, V for vertical. These letters were chosen to
+avoid confusion with "X" and "Y", which refer to axes in 3D space instead.
 
 
 UVs Explained
 =============
 
-The best analogy to understanding UV mapping is cutting up a cardboard box.
+The best analogy to understand UV mapping is cutting up a cardboard box.
-The box is a three-dimensional (3D) object, just like the mesh cube you add to your scene.
+If you were to take a pair of scissors and cut along its edges,
-
+you would be able to spread it out flat on a tabletop. As you are looking down at the table,
-If you were to take a pair of scissors and cut a seam or fold of the box,
-you would be able to lay it flat on a tabletop. As you are looking down at the box on the table,
 we could say that U is the left-right direction, and V is the up-down direction.
-This image is thus in two dimensions (2D). We use U and V to refer to these
-"texture-space coordinates" instead of the normal X and Y, which are always used
-(along with Z) to refer to the three-dimensional space (3D).
 
-When the box is reassembled, a certain UV location on the paper is transferred to an (X, Y, Z)
+As a next step, you could put the spread-out box on top of a poster, cut the poster
-location on the box. This is what the computer does with a 2D image in wrapping it around a 3D object.
+to match its shape, glue the poster to the box, and finally reassemble the box.
+You now have a 3D box textured with a 2D image.
 
-During the UV unwrapping process, you tell Blender exactly how to map the faces of your object (in this case, a box)
+A UV map describes how the box is cut up, and how it's laid out on the poster.
-to a flat image in the UV Editor. You have complete freedom in how to do this.
+You have complete freedom in how to do this: if you wanted to, you could cut each individual
-(Continuing our previous example, imagine that, having initially laid the box flat on the tabletop,
+side of the box and position, rotate, scale, and even skew it on the poster
-you now cut it into smaller pieces, somehow stretch and/or shrink those pieces,
+independently of the other sides.
-and then arrange them in some way upon a photograph that is also lying on that tabletop.)
 
 
 Example
@@ -49,46 +50,19 @@ Example
 
    3D space (XYZ) versus UV space.
 
-In this image you can easily see that the shape and
+In the above image, a dome in 3D space is flattened into a disc in UV space.
-size of the marked face in 3D space is different in UV space.
+Each 3D face is then textured with the part of the image it covers in the UV map.
-This difference is caused by the "stretching" (technically called mapping)
-of the 3D part (XYZ) onto a 2D plane (i.e. the UV map).
 
-If a 3D object has a UV map, then, in addition to the 3D coordinates X, Y, and Z,
+The image also demonstrates a common problem in UV maps: distortion. Notice how,
-each point on the object will have corresponding U and V coordinates.
+even though the checkered squares in the 2D texture are all the same size,
+they get different sizes when applied to the 3D dome (they're smaller at the base
+than at the top). This is because the faces in the UV map have different relative
+sizes than in 3D space, which is a result of the flattening process.
 
-.. note::
+You'll typically want to minimize this distortion by manually guiding and tweaking
+the flattening, using :doc:`seams </modeling/meshes/uv/unwrapping/seams>` for example.
+However, it's not always possible to eliminate it completely.
 
-   On more complex models (like seen in the sphere above)
-   there pops up an issue where the faces cannot be cut,
-   but instead they are stretched in order to make them flat.
-   This helps making easier UV maps, but sometimes adds distortion to the final mapped texture.
-
-
-Advantages of UVs
-=================
-
-While procedural textures are useful -- they never repeat themselves and always "fit" 3D objects
--- they are not sufficient for more complex or natural objects.
-For instance, the skin on a human head will never look quite right when procedurally generated.
-Wrinkles on a human head, or scratches on a car do not occur in random places,
-but depend on the shape of the model and its usage. Manually-painted images,
-or images captured from the real world gives more control and realism.
-For details such as book covers, tapestry, rugs, stains, and detailed props,
-artists are able to control every pixel on the surface using a UV texture.
-
-A UV map describes what part of the texture should be attached to each polygon in the model.
-Each polygon's vertex gets assigned to 2D coordinates that define which part of the image gets mapped.
-These 2D coordinates are called UVs (compare this to the XYZ coordinates in 3D).
-The operation of generating these UV maps is also called "unwrap",
-since it is as if the mesh were unfolded onto a 2D plane.
-
-For most simple 3D models, Blender has an automatic set of unwrapping algorithms that you can easily apply.
-For more complex 3D models, regular Cubic, Cylindrical or Spherical mapping, is usually not sufficient.
-For even and accurate projection, use :doc:`seams </modeling/meshes/uv/unwrapping/seams>` to guide the UV mapping.
-This can be used to apply textures to arbitrary and complex shapes,
-like human heads or animals. Often these textures are painted images,
-created in applications like the Gimp, Krita, or your favorite painting application.
 
 
 Interface
@@ -104,7 +78,7 @@ Header
 The header contains several menus and options for working with UVs.
 
 Sync Selection
-   Syncs selection between the UV Editor and the 3D Viewport.
+   Synchronizes the selection between the UV Editor and the 3D Viewport.
    See :ref:`Sync Selection <bpy.types.ToolSettings.use_uv_select_sync>` for more details.
 
 Selection Mode
@@ -112,7 +86,7 @@ Selection Mode
    See :ref:`Selection Mode <bpy.types.ToolSettings.uv_select_mode>` for more details.
 
 Sticky Selection Mode
-   Option to automatically expand selection.
+   Which other vertices to select automatically.
    See :ref:`Sticky Selection Mode <bpy.types.ToolSettings.uv_sticky_select_mode>` for more details.
 
 View
@@ -120,59 +94,62 @@ View
    See :doc:`/editors/uv/navigating`.
 
 Select
-   Tools for :doc:`Selecting UVs </editors/uv/selecting>`.
+   Tools for :doc:`selecting UVs </editors/uv/selecting>`.
 
 Image
    Tools for opening and manipulating images.
    See :doc:`/editors/image/editing`.
 
 UV
-   Contains tools for :doc:`Unwrapping Meshes </modeling/meshes/uv/unwrapping/index>`
+   Contains tools for :doc:`Unwrapping Meshes </modeling/meshes/uv/unwrapping/introduction>`
    and :doc:`Editing UVs </modeling/meshes/uv/editing>`.
 
+Pivot :kbd:`Period`
+   See :doc:`/editors/3dview/controls/pivot_point/index`.
+
+Snap :kbd:`Shift-Tab`
+   See :doc:`/editors/uv/controls/snapping`.
+
+Proportional Editing :kbd:`O`
+   See :doc:`Proportional Editing </editors/3dview/controls/proportional_editing>`.
+
 Image
    A :ref:`data-block menu <ui-data-block>` used for selecting images.
-   When an image has been loaded or created in the Image editor,
+   When an image has been loaded or created in the UV Editor,
-   the Image panel appears in the *Sidebar region*.
+   the :doc:`Image panel </editors/image/image_settings>` appears in the Sidebar region.
-   See :doc:`/editors/image/image_settings`.
 
 Image Pin
-   Todo.
+   When enabled the current image remains visible regardless of the object selection.
+   This switching only happens if the 3D Viewport is in Edit Mode or Texture Paint Mode.
+
+   This can be useful to enable when an image is used as a reference.
+
+Show Gizmo
+   Lets you show/hide all gizmos using the toggle button, or specific gizmos using
+   the drop-down arrow.
+
+   Navigate
+      Enable/disable the gizmos used to pan or zoom the 2D viewport.
+      See :ref:`Navigation Gizmos <editors-uv-navigate-gizmos>` for more information.
+
+Show Overlays
+   Lets you show/hide all overlays using the toggle button, or specific overlays
+   using the drop-down arrow. See :doc:`/editors/uv/overlays`.
 
 Active UV Loop Layer
    Select which UV map to use.
 
-Viewport Gizmos
-   Selectively show or hide specific gizmo controls that are displayed in the 2D viewport.
-	All gizmos can be hidden or shown at once with the toggle next to the pop-over arrow.
-
-   Navigate
-      Enable/disable the gizmos used to pan or zoom the 2D viewport,
-      see :ref:`Navigation Gizmos <editors-uv-navigate-gizmos>` for more information.
-
 Display Channels
    Select what color channels are displayed.
 
    :Color & Alpha:
-      Replaces transparent pixels with background checkerboard, denoting the alpha channel.
+      Enables transparency and shows a checkerboard behind the image.
    :Color:
-      Display the colored image, without alpha channel.
+      Displays the colored image, without alpha channel.
    :Alpha:
-      Displays the Alpha channel a grayscale image.
+      Displays the alpha channel as a grayscale image. White areas are opaque, black areas are transparent.
-      White areas are opaque, black areas have an alpha of 0.
    :Z-Buffer:
-      Display the depth from the camera, from Clip Start to Clip End,
+      Displays the depth from the camera, from Clip Start to Clip End,
       as specified in the :doc:`Camera settings </render/cameras>`.
    :Red, Green, Blue:
-      Single Color Channel visualized as a grayscale image.
+      Single color channel visualized as a grayscale image.
-
-
-Tool Settings
--------------
-
-Pivot
-   Similar to working with pivot points in the 3D Viewport.
-:doc:`UV Snapping </editors/uv/controls/snapping>`
-   Controls to snap UV points, similar to snapping in the 3D Viewport.
-Proportional Editing
-   See :doc:`Proportional Editing </editors/3dview/controls/proportional_editing>`.

manual/editors/uv/navigating.rst

@@ -3,20 +3,12 @@
 Navigating
 **********
 
-The UV Editor has a 2D cursor. Its position can be changed by :kbd:`LMB` clicking in the UV editor
-while the cursor tool is active. You can also manually adjust its position in the Sidebar region.
-The range by default is from 0.0 to 1.0 starting from the lower left corner.
-By enabling :ref:`Pixel Coordinates <bpy.types.SpaceUVEditor.show_pixel_coords>`,
-the coordinates match the pixels in your image with XY(0, 0) located in the lower left corner.
-
-
 2D Viewport
 ===========
 
-Panning can be done by clicking the :kbd:`MMB` and dragging.
+Panning can be done by dragging with :kbd:`MMB`.
 
-Zooming can be done by scrolling :kbd:`Wheel` up or down.
+Zooming can be done using :kbd:`Wheel` or :kbd:`NumpadPlus`/:kbd:`NumpadMinus`.
-Also, as in the 3D Viewport, you can use :kbd:`NumpadPlus` or :kbd:`NumpadMinus` to zoom.
 
 
 .. _editors-uv-navigate-gizmos:
@@ -31,7 +23,24 @@ and zooming more comfortably when e.g. no mouse wheel is available.
 View Menu
 =========
 
-Also see :doc:`/editors/image/navigating` in the Image editor.
+Also see :doc:`/editors/image/navigating` in the Image Editor.
 
 Frame Selected :kbd:`NumpadPeriod`
-   Change view so that all selected UV vertices are visible.
+   Change the view so that all selected UV vertices are visible.
+
+
+2D Cursor
+=========
+
+Just like the :doc:`3D Viewport </editors/3dview/3d_cursor>`, the UV Editor has a Cursor
+that you can jump to (:menuselection:`View --> Center View to Cursor`). It can also serve as
+a :doc:`pivot point </editors/3dview/controls/pivot_point/index>` and a
+:ref:`snapping target <bpy.ops.uv.snap_selected>`.
+
+To change the Cursor's position, either press :kbd:`LMB` with the Cursor tool selected,
+or :kbd:`Shift-RMB` with any tool selected. You can also change the "Location X/Y" fields
+in the *View* tab of the Sidebar, in either relative coordinates (0 to 1) or
+:ref:`pixel coordinates <bpy.types.SpaceUVEditor.show_pixel_coords>`.
+In both cases, the lower left corner of the image serves as the origin (0, 0).
+
+You can press :kbd:`Shift-C` to move the Cursor to the center.

manual/editors/uv/overlays.rst

@@ -3,14 +3,17 @@
 Overlays
 ********
 
-The Overlays popover configures the overlays that are displayed on top of images.
+.. figure:: /images/editors_uv_overlays.png
+   :align: right
+   
+   The Overlays pop-over.
+
 In the header, there is a button to turn off all overlays for the UV Editor.
-This option also toggles the visibility of :doc:`/modeling/meshes/uv/workflows/udims` tile information.
+This option also toggles the visibility of :doc:`UDIM </modeling/meshes/uv/workflows/udims>`
-The options that are visible in the pop-over depend on the UV Editor mode.
+tile information.
 
-.. seealso::
+The drop-down button opens a pop-over with more detailed settings.
-
+The following categories are available:
-   Additional :doc:`View Properties </editors/uv/sidebar>` can be configured in the Sidebar.
 
 
 Guides
@@ -19,26 +22,26 @@ Guides
 .. _bpy.types.SpaceImageOverlay.show_grid_background:
 
 Grid
-   Show the grid background and borders.
+   Show the grid.
 
 .. _bpy.types.SpaceUVEditor.show_grid_over_image:
 
 Over Image
-   Allows the grid overlay to be shown on top of the image rather than behind it.
+   Show the grid on top of the image rather than behind it.
 
 .. _bpy.types.SpaceUVEditor.grid_shape_source:
 
 Grid Shape Source
-   How the size/subdivisions of grid cells are determined.
+   How the row and column counts are determined.
 
-   :Dynamic: The grid subdivisions changes based on the zoom level.
+   :Dynamic: The grid starts at 8×8 cells that are automatically subdivided further as you zoom in.
-   :Fixed: The grid subdivisions stays consistent based off the *Fixed Subdivisions* property.
+   :Fixed: The row and column counts are fixed and can be configured manually.
-   :Pixel: The grid aligns with pixels from image so each grid cell represents one pixel.
+   :Pixel: Each grid cell matches one image pixel.
 
 .. _bpy.types.SpaceUVEditor.custom_grid_subdivisions:
 
 Fixed Subdivisions X, Y
-   Number of grid units in UV space that make one UV Unit.
+   Number of columns/rows in the grid.
 
 .. _bpy.types.SpaceUVEditor.tile_grid_shape:
 
@@ -54,9 +57,9 @@ UV Editing
 .. _bpy.types.SpaceUVEditor.show_stretch:
 
 Display Stretch
-   Shows how much of a difference there is between UV coordinates and 3D coordinates.
+   Show how much of a shape difference there is between UV space and 3D space.
-   Blue means low distortion, while Red means high distortion.
+   Blue means low distortion, red means high.
-   Choose to display the distortion of *Angles* or the *Area*.
+   You can choose whether to display the distortion based on *Angle* or *Area*.
 
 
 Geometry
@@ -65,22 +68,22 @@ Geometry
 .. _bpy.types.SpaceUVEditor.uv_opacity:
 
 UV Opacity
-   Opacity of the above UV overlays.
+   Opacity of edges and faces.
 
 .. _bpy.types.SpaceUVEditor.edge_display_type:
 
 Display As
-   Controls how edges are shown.
+   Control how edges are shown.
 
-   :Outline: Display white edges with black outline.
+   :Outline: Display edges in gray with a black outline.
-   :Dash: Display dashed black-white edges.
+   :Dash: Display edges as dashed black-gray lines.
-   :Black: Display black edges.
+   :Black: Display edges in black.
-   :White: Display white edges.
+   :White: Display edges in white.
 
 .. _bpy.types.SpaceUVEditor.show_modified_edges:
 
 Modified Edges
-   Show results of modifiers in the UV display.
+   Additionally show the edges as they look after applying modifiers (in gray).
 
 .. _bpy.types.SpaceUVEditor.show_faces:
 
@@ -92,4 +95,5 @@ Image
 =====
 
 Show Metadata
-   Displays the metadata if they were set in the render tab's :doc:`/render/output/properties/metadata` panel.
+   Display metadata about the selected Render Result. See the Output tab's
+   :doc:`/render/output/properties/metadata` panel to change what metadata to include.

manual/editors/uv/selecting.rst

@@ -4,52 +4,39 @@
 Selecting
 *********
 
-Selection tools are available in the *Select Menu* in the header,
+Much like the 3D Viewport, the UV Editor has selection mode buttons in the header,
-and the shortcuts listed below.
+as well as a *Select* menu.
-
 
 .. _bpy.types.ToolSettings.use_uv_select_sync:
 
 Sync Selection
 ==============
 
-Turning on the *Sync Selection* button causes selection of components
+If turned off (the default), the UV Editor only shows the faces that are selected in the
-in the 3D Viewport to sync with their corresponding elements in the UV editor.
+3D Viewport. Selecting an item in one editor does not automatically select it in the other.
-If off only the selected faces are displayed in the UV editor.
+If one 3D vertex/edge corresponds to multiple UV vertices/edges, you can select each
-These two modes have very different results when transforming components in the UV editor.
+of those individually.
-
-.. seealso::
-
-   :doc:`Selecting in the 3D Viewport </editors/3dview/selecting>`.
 
+If turned on, the UV Editor always shows all faces. Selecting an item in one editor also
+selects it in the other. If one 3D vertex/edge corresponds to multiple UV vertices/edges,
+you can't select those individually (you can only select all of them).
 
 .. _bpy.ops.uv.select_mode:
 .. _bpy.types.ToolSettings.uv_select_mode:
 
-Selection Modes
+Selection Mode
-===============
+==============
 
-Select Modes dependent on the Sync Selection.
+:Vertex: :kbd:`1` Select vertices.
+:Edge: :kbd:`2` Select edges.
+:Face: :kbd:`3` Select faces.
+:Island: :kbd:`4` Select contiguous groups of faces. Only available if *Sync Selection* is disabled.
 
+If *Sync Selection* is enabled, you can hold :kbd:`Shift` while clicking a selection mode to
+activate multiple ones at the same time, or :kbd:`Ctrl` to expand/contract the selection.
 
-Sync Selection Off
+.. seealso::
-------------------
+   :doc:`Mesh Selection </modeling/meshes/selecting/introduction>`
-
-:Vertex: Select individual vertices.
-:Edge: Select edges.
-:Face: Select faces.
-:Island: Select contiguous groups of faces.
-
-
-Sync Selection On
------------------
-
-When selecting UVs or Edges, it behaves like the *Shared Vertex* option of the *Sticky Selection Mode*.
-When selecting Faces, it behaves like the *Disabled* option of the *Sticky Selection Mode*.
-
-:Vertex: Select individual vertices.
-:Edge: Select edges.
-:Face: Select faces.
 
 
 .. _bpy.types.ToolSettings.uv_sticky_select_mode:
@@ -57,98 +44,100 @@ When selecting Faces, it behaves like the *Disabled* option of the *Sticky Selec
 Sticky Selection Mode
 =====================
 
-This selector lets you enable automatic additional selection.
+Options for automatically selecting additional UV vertices. Only available if *Sync Selection* is disabled.
 
-:Shared Vertex:
+Disabled
-   Selects UVs that share a mesh vertex, even if they are in different UV locations.
+   Each UV vertex can be selected independently of the others.
-:Shared Location:
+Shared Location
-   Selects UVs that are in the same UV location and share a mesh vertex.
+   Automatically select UV vertices that correspond to the same mesh vertex and have the same UV coordinates.
-:Disabled:
+   This is the default and gives the illusion that multiple faces in a UV map can share the same vertex;
-   Disables Sticky Selection.
+   in reality, they have separate vertices that overlap.
-   When you move a UV in this mode, each face owns its own UVs, allowing them to be separated.
+Shared Vertex
+   Automatically select UV vertices that correspond to the same mesh vertex,
+   even if they have different UV coordinates.
+   This is also the behavior when *Sync Selection* is enabled.
 
+Select Menu
+===========
 
-Menu
+All :kbd:`A`
-====
+   Selects all UV elements.
-
+None :kbd:`Alt-A`
-Box Select :kbd:`B`
+   Deselects all UV elements.
-   Click and drag to box select UV coordinates.
+Invert :kbd:`Ctrl-I`
-   Alternatively, use :kbd:`B` to start :ref:`box selection <tool-select-box>`.
-Box Select Pinned :kbd:`Ctrl-B`
-   Use the box lasso to select only pinned UV coordinates.
-Circle Select
-   See :ref:`tool-select-circle`.
-Select All :kbd:`A`
-   Selects all UV coordinates.
-Select None :kbd:`Alt-A`
-   Deselects all UV coordinate.
-Inverse :kbd:`Ctrl-I`
    Inverts the current selection.
+Box Select :kbd:`B`
+   See :ref:`Box Select <bpy.ops.*.select_box>`.
+Box Select Pinned :kbd:`Ctrl-B`
+   Like *Box Select*, but only selects :ref:`pinned <bpy.ops.uv.pin>` UV vertices.
+Circle Select
+   See :ref:`Circle Select <bpy.ops.*.select_circle>`.
 More/Less :kbd:`Ctrl-NumpadPlus`, :kbd:`Ctrl-NumpadMinus`
-   Expands/Contracts the selection to/from the adjacent elements of the selection type.
+   Expands/contracts the selection to/from the adjacent elements.
 Select Pinned :kbd:`Shift-P`
-   Selects all :ref:`pinned <bpy.ops.uv.pin>` UVs.
+   Selects all pinned UVs.
 Select Linked
    Linked :kbd:`Ctrl-L`
-      This operator selects all UVs that are connected to currently selected UVs.
+      Selects all elements that are connected to the currently selected ones.
-      This works similarly to the tools in 3D Viewport.
    Shortest Path
-      Path between two selected elements.
+      Selects the path between two selected elements. (See below)
 
 .. _bpy.ops.uv.select_similar:
 
 Select Similar :kbd:`Shift-G`
-   Selects UV vertices that have certain similar properties to the :term:`Active` vertex.
+   Selects UV elements that are similar to the :term:`active` one in some way.
-   The :ref:`bpy.ops.screen.redo_last` panel provides several selection options:
+   The :ref:`bpy.ops.screen.redo_last` panel provides several options:
 
    Type
-      The property to compare against the active vertex.
+      The property to compare. Which properties are available depends on the
-      The properties that are shown depend on the :ref:`Selection Mode <bpy.types.ToolSettings.uv_select_mode>`.
+      :ref:`Selection Mode <bpy.types.ToolSettings.uv_select_mode>`.
 
-      Vertex Selection Mode:
+      Vertex Selection Mode
+         :Pinned: Selects vertices with the same :ref:`pinned <bpy.ops.uv.pin>` state.
 
-      :Pinned: Selects vertices with the same :ref:`pinned <bpy.ops.uv.pin>` state as the active vertex.
+      Edge Selection Mode
+         :Length: Selects edges with a similar length in the UV map.
+         :Length 3D: Selects edges with a similar length in the 3D mesh.
+         :Pinned: Selects edges with the same pinned state.
 
-      Edge Selection Mode:
+      Face Selection Mode
-
+         :Area: Selects faces with a similar area in the UV map.
-      :Length: Selects edges with a similar length.
+         :Area 3D: Selects faces with a similar area in the 3D mesh.
-      :Length 3D: Selects edges with a similar length in world space coordinates.
-      :Pinned:
-         Selects edges whose both vertices have the same
-         :ref:`pinned <bpy.ops.uv.pin>` state as the active vertex.
-
-      Face Selection Mode:
-
-      :Area: Selects faces with a similar area.
-      :Area 3D: Selects faces with a similar area in world space coordinates.
          :Material: Selects faces that have the same :doc:`Material </render/materials/index>`.
          :Object:
-         Selects faces which have the same object. This is useful when multiple objects are in Edit mode at once.
+            Selects faces that belong to the same object.
-      :Polygon Sides: Selects faces with the same number of edges per face.
+            This is useful when multiple objects are in Edit mode at once.
-      :Winding: Select faces which are facing the same as the current face i.e. upwards or downwards.
+         :Polygon Sides: Selects faces with a similar number of edges.
+         :Winding: Select faces that have the same orientation (facing upwards or downwards in the UV map).
 
-      Island Selection Mode:
+      Island Selection Mode
-
+         :Area: Selects islands with a similar area in the UV map.
-      :Area: Selects islands with a similar area.
+         :Area 3D: Selects islands with a similar area in the 3D mesh.
-      :Area 3D: Selects islands with a similar area in world space coordinates.
+         :Amount of Faces in Island: Selects islands with a similar number of faces.
-      :Amount of Face in Island: Selects islands with a similar number of faces per each island.
 
    Compare
-      For quantitative properties, this property selects the type of comparison to between the two numerical values.
+      The comparison operator.
 
-      :Equal: Select items with the same value as the active item's chosen property.
+      :Equal: Select elements whose value is equal.
-      :Greater: Select items with a larger value as the active item's chosen property.
+      :Greater: Select elements whose value is greater or equal.
-      :Less: Select items with a smaller value as the active item's chosen property.
+      :Less: Select elements whose value is less or equal.
    Threshold
-      For quantitative properties, this property controls how
+      Tolerance for values that are almost, but not quite the same. A higher threshold will select more elements.
-      close the property's values have to be in the comparison.
 
 Select Split :kbd:`Y`
-   Cuts apart the selected UVs from the map. Only those UVs which belong to
+   "Detaches" the selected faces so they can be moved elsewhere without affecting their neighbors.
-   fully selected faces remain selected. As the name implies, this is particularly useful to
+
-   unlink faces and move them elsewhere. The hotkey is analogous to the mesh Split tool.
+   .. hint::
+
+      Unlike :doc:`Split Selection </modeling/meshes/editing/mesh/split>` for meshes, which physically disconnects
+      faces, this is a pure selection operator. In UV space, the faces were never connected to begin with;
+      it only seemed that way because *Sticky Selection* automatically selected the vertices of the neighboring faces.
+      *Select Split* deselects those vertices again.
+
+      As an alternative to *Select Split*, you can set the *Sticky Selection Mode* to *Disabled*.
+
 Select Overlap
-   Selects any UVs that are extended over other UVs while also selecting any underlying UVs.
+   Selects all UV faces that overlap each other.
 
 
 .. _bpy.ops.uv.shortest_path_select:
@@ -163,46 +152,73 @@ Shortest Path
    :Menu:      :menuselection:`Select --> Select Linked --> Shortest Path`
    :Shortcut:  :kbd:`Ctrl-LMB`
 
-Selects all UV components along the shortest path from
+Selects all the UV elements along the shortest path between two elements: the two selected elements when
-the active component to the one which was selected.
+activated using the menu, or the active one and the clicked one when activated using the shortcut.
 
 Face Stepping
-   Supports diagonal paths for vertices and faces, and
+   For vertices: allows the path to step across faces, following their diagonal rather than
-   selects edge rings with edges.
+   their edges.
+
+   For edges: selects disconnected edges that are perpendicular to the path (edge ring),
+   rather than connected edges along the path (edge loop).
+
+   For faces: allows the path to go through faces that only share a vertex, rather than an edge.
 Topological Distance
-   Only takes into account the number of edges of the path and
+   Calculates the distance by simply counting edges rather than measuring their lengths.
-   not the length of the edges to calculate the distances.
 Fill Region :kbd:`Shift-Ctrl-LMB`
-   Selects all elements in the shortest paths from the active selection to the clicked area.
+   Selects all shortest paths (rather than just one).
-Checker Deselect Options
+Dashed Line Options
-   Allows to quickly select alternate elements in a path.
+   Allows to only select elements at regular intervals, creating a "dashed line" rather
+   than a continuous one.
 
    Deselected
       The number of deselected elements in the repetitive sequence.
    Selected
       The number of selected elements in the repetitive sequence.
    Offset
-      Offset from the starting point.
+      The number of elements to offset the sequence by.
 
 .. seealso::
 
    Mesh edit :ref:`Select Shortest Path <bpy.ops.mesh.shortest_path_select>`.
 
+.. _bpy.ops.uv.select_edge_loop:
 
-.. _bpy.ops.uv.select_edge_ring:
+Select Edge Loop
-
+================
-Select Edge Loops
-=================
 
 .. reference::
 
    :Mode:      Edit Mode
-   :Shortcut:  :kbd:`Ctrl-Alt-LMB`, or :kbd:`Shift-Ctrl-Alt-LMB` for modifying existing selection.
+   :Shortcut:  :kbd:`Alt-LMB`, or :kbd:`Shift-Alt-LMB` for extending the existing selection.
 
-Holding :kbd:`Ctrl-Alt` while selecting a UV component selects a loop of edges that are connected in
+Holding :kbd:`Alt` while clicking an edge selects that edge and then expands the selection as far as
-a line end-to-end, passing through the edge under the mouse pointer.
+possible in the two directions parallel to it. (While this of course works for selecting edge "loops"
-Holding :kbd:`Shift-Ctrl-Alt` while clicking adds to the current selection.
+that go all the way around a mesh, it also works if there's no loop.)
+
+You can additionally hold :kbd:`Shift` to extend the current selection rather than replacing it.
 
 .. seealso::
 
-   Mesh edit :ref:`Select Edge Loops <bpy.ops.mesh.loop_multi_select>`.
+   Mesh edit :ref:`Select Edge Loops <bpy.ops.mesh.loop_select>`.
+
+
+.. _bpy.ops.uv.select_edge_ring:
+
+Select Edge Ring
+================
+
+.. reference::
+
+   :Mode:      Edit Mode
+   :Shortcut:  :kbd:`Ctrl-Alt-LMB`, or :kbd:`Shift-Ctrl-Alt-LMB` for extending the existing selection.
+
+Holding :kbd:`Ctrl-Alt` while clicking an edge selects that edge and then expands the selection
+as far as possible in the two directions perpendicular to it. (While this of course works for selecting
+edge "rings" that go all the way around a mesh, it also works if there's no ring.)
+
+You can additionally hold :kbd:`Shift` to extend the current selection rather than replacing it.
+
+.. seealso::
+
+   Mesh edit :ref:`Select Edge Rings <bpy.ops.mesh.select_edge_ring>`.

manual/editors/uv/sidebar.rst

@@ -9,7 +9,7 @@ Image Tab
 UV Vertex
 ---------
 
-Transform Properties :doc:`Selecting UVs </modeling/meshes/uv/editing>`.
+The averaged-out position of the selected UV vertices.
 
 
 Image
@@ -21,7 +21,7 @@ See :doc:`/editors/image/image_settings`.
 UDIM Tiles
 ----------
 
-Allows you to manage :doc:`UDIM Tiles </modeling/meshes/uv/workflows/udims>`.
+See :doc:`UDIM Tiles </modeling/meshes/uv/workflows/udims>`.
 
 
 Tool Tab
@@ -36,40 +36,34 @@ View Tab
 Display
 -------
 
-You can set the editors display options in this panel.
+You can set the editor's display options in this panel.
 
-.. figure:: /images/editors_uv_sidebar_display-panel.png
+Aspect Ratio X, Y
-   :align: right
+   Display aspect for this image. Does not affect rendering.
-
-   Display panel: With both an image and UVs selected.
-
-Aspect Ratio
-   Display Aspect for this image. Does not affect rendering.
 
 Repeat Image
-   Duplicate the image until it is repeated to fill the main view.
+   Tile the image so it completely fills the editor.
 
 .. _bpy.types.SpaceUVEditor.show_pixel_coords:
 
 Pixel Coordinates
-   Display UV coordinates in pixels rather than from 0.0 to 1.0
+   Use pixel coordinates rather than relative coordinates (0 to 1) for the UV Vertex
+   and 2D Cursor Location fields.
 
 
 2D Cursor
 ---------
 
 Location X, Y
-   Control 2D cursor location.
+   View and change the location of the 2D Cursor.
 
 
 Annotations
 -----------
 
-Options for the :doc:`annotation tool </interface/annotate_tool>`.
+Options for the :doc:`Annotate tool </interface/annotate_tool>`.
 
 
-.. (TODO add) images per type
-
 Scopes
 ======
 

manual/editors/video_sequencer/preview/introduction.rst

@@ -23,7 +23,7 @@ The gizmos however are unique for the Preview.
 .. figure:: /images/editors_vse_type.svg
    :alt: Preview window
 
-   Figure 1: Preview window of VSE.
+   Figure 1: Preview window of Video Sequencer.
 
 Sequencer preview is used to display result of rendering Sequencer timeline.
 This can be further configured to display output from certain channel, overlay or image analyzer (scope).

manual/files/import_export/usd.rst

@@ -89,6 +89,9 @@ Materials
    See `USD issue #542 <https://github.com/PixarAnimationStudios/USD/issues/542>`__
    for more information.
 
+Root Prim
+   If set, add a transform primitive with the given path to the stage as the parent of all exported data.
+
 Use Settings for
    Determines the whether to use *Viewport* or *Render* visibility of collection, modifiers,
    or any other property that can be set for both the *Viewport* and *Render*.

manual/getting_started/installing/linux_windowing_environment.rst

@@ -61,6 +61,13 @@ Disable Wayland (forcing X11)
 
       WAYLAND_DISPLAY="" blender
 
+Disable ``libdecor`` (forcing borderless windows under Gnome-Shell)
+   Uninstall ``libdecor``, then run Blender with an empty X11 display variable.
+
+   .. code-block:: sh
+
+      DISPLAY="" blender
+
 
 Environment Variables
 ---------------------
@@ -75,14 +82,11 @@ Environment Variables
 Known Limitations
 -----------------
 
-Gnome Shell's Fractional Scaling
+Gnome Shell's Fractional Scaling (before version 44)
-   While Blender supports fractional scaling on KDE & WLROOT's based compositors,
+   Versions of Gnome-Shell prior to 44 don't fully support fractional scaling.
-   gnome-shell-43 has an experimental fractional scaling which is enabled by default on Ubuntu
-   internally this renders a larger buffer then down-scales it and may cause minor glitches such as a
-   `small cursor size <https://projects.blender.org/blender/blender/issues/105895>`__.
 
-   Wayland now has an API handle fractional scaling (``wp-fractional-scale-v1``),
+   Using fractional under older versions of Gnome-Shell may result in glitches such as a
-   which should eventually resolve this issue.
+   `small cursor size <https://projects.blender.org/blender/blender/issues/105895>`__.
 
 NVidia GPU
    Currently NVidia drivers don't fully support features needed for Wayland. Graphical glitches and flickering are
@@ -127,17 +131,11 @@ Feature Comparison
      - |cross| :sup:`*2`
      - | Needed for dragging between windows and
        | restoring window positions on file load.
-   * - Window Raise/Lower
-     - |tick|
-     - |cross| :sup:`*2`
-     - | Used to bring the render window
-       | to the foreground.
 
 Other features which both systems support such as Hi-DPI, 3D-mouse, tablet input, ... etc.
 have been left out of this list.
 
 | :sup:`*1` In X11 fast cursor motion may exit the window bounds while the cursor is grabbed (transforming for e.g.).
-| :sup:`*2` Wayland doesn't support setting the window position & depth,
+| :sup:`*2` Wayland doesn't support setting the window position,
-  as this is a design decision it's unlikely to be supported (see issues for
+  as this is a design decision it's unlikely to be supported
-  `position <https://projects.blender.org/blender/blender/issues/98928>`__ and
+  (see issues for `position <https://projects.blender.org/blender/blender/issues/98928>`__).
-  `depth <https://projects.blender.org/blender/blender/issues/102985>`__).

manual/grease_pencil/modes/vertex_paint/editing.rst

@@ -58,13 +58,13 @@ Adjust the levels of Color Attributes.
 
 .. _bpy.ops.gpencil.vertex_color_hsv:
 
-Hue Saturation Value
+Hue/Saturation/Value
 ====================
 
 .. reference::
 
    :Mode:      Vertex Paint Mode
-   :Menu:      :menuselection:`Paint --> Hue Saturation Value`
+   :Menu:      :menuselection:`Paint --> Hue/Saturation/Value`
 
 Adjust the color's HSV values.
 

manual/grease_pencil/modes/weight_paint/index.rst

@@ -8,5 +8,5 @@
 
    introduction.rst
    tools.rst
-   tool_settings/brush.rst
+   tool_settings/index.rst
    weights_menu.rst

manual/grease_pencil/modes/weight_paint/tool_settings/brush.rst

@@ -1,8 +1,8 @@
 .. _tool-grease-pencil-weight-paint-weight:
 
-*****
+**************
-Brush
+Brush Settings
-*****
+**************
 
 Painting needs paint brushes and Blender provides a Brush panel within the Toolbar
 when in *Weight Paint Mode*.
@@ -11,12 +11,17 @@ Brush
    In the :ref:`Data-Block menu <ui-data-block>` you find predefined Brush presets.
    And you can create your own custom presets as needed.
 
-Radius
+Radius :kbd:`F`
    The radius defines the area of influence of the brush.
 Strength
    This is the amount of paint to be applied per brush stroke.
 Use Falloff
    When enabled, use Strength falloff for the brush.
    Brush Strength decays with the distance from the center of the brush.
-Weight
+Weight :kbd:`Ctrl-F`
    The weight (visualized as a color) to be used by the brush.
+
+   Using :kbd:`Ctrl-RMB` you can set the weight to the value thats under the cursor.
+Direction :kbd:`D`
+   Brush direction toggle, *Add* adds weight value while *Subtract* removes weight value.
+   This setting can be toggled with :kbd:`D`.

manual/grease_pencil/modes/weight_paint/tool_settings/index.rst

@@ -0,0 +1,10 @@
+
+#################
+  Tool Settings
+#################
+
+.. toctree::
+   :maxdepth: 2
+
+   brush.rst
+   options.rst

manual/grease_pencil/modes/weight_paint/tool_settings/options.rst

@@ -0,0 +1,16 @@
+
+*******
+Options
+*******
+
+Auto Normalize
+   Ensures that all deforming vertex groups add up to one while painting.
+   When this option is turned off, then all weights of a point can have any value between 0 and 1.
+   However, when vertex groups are used as deform groups for character animation
+   then Blender always interprets the weight values relative to each other.
+   That is, Blender always does a normalization over all deform bones.
+   Hence in practice it is not necessary to maintain a strict normalization and
+   further normalizing weights should not affect animation at all.
+
+   This option works most intuitively when used to maintain normalization while
+   painting on top of weights that are already normalized with another tool.

manual/grease_pencil/modes/weight_paint/tools.rst

@@ -14,6 +14,17 @@ See :doc:`Brush </grease_pencil/modes/weight_paint/tool_settings/brush>` for mor
 Draw
    Paints a specified weight over the strokes.
 
+Blur
+   Smooths out the weighting of adjacent points. In this mode the Weight
+   Value is ignored. The strength defines how much the smoothing is applied.
+
+Average
+   Smooths weights by painting the average resulting weight from all weights under the brush.
+
+Smear
+   Smudges weights by grabbing the weights under the brush and "dragging" them.
+   This can be imagined as a finger painting tool.
+
 :ref:`Annotate <tool-annotate-freehand>`
    Draw free-hand annotation.
 

manual/grease_pencil/modifiers/generate/line_art.rst

@@ -92,12 +92,9 @@ Contour
    Where the edge becomes the separation line of front/backfacing faces.
    The silhouette can also be inverted by clicking the invert button.
 
-    :None: Not filtering any lines based on illumination region.
+    :Contour: Generate lines from contour.
-    :Illuminated: Only selecting lines from illuminated regions.
+    :Silhouette: Only generate lines from the silhouette of the source objects as a whole.
-    :Shaded: Only selecting lines from shaded regions.
+    :Individual Silhouette: Generate lines from the individual silhouettes of the source objects.
-    :Illuminated (Enclosed Shapes):
-      Selecting lines from lit regions, and make the combination of contour,
-      light contour and shadow lines into enclosed shapes.
 
 .. _bpy.types.LineartGpencilModifier.use_crease:
 
@@ -145,7 +142,7 @@ Cast Shadow
 
 .. _bpy.types.LineartGpencilModifier.use_overlap_edge_type_support:
 
-Allow Overlap
+Allow Overlapping Types
    Allow an edge to have multiple overlapping types.
    This will create a separate stroke for each overlapping type.
 

manual/modeling/geometry_nodes/geometry/operations/separate_components.rst

@@ -32,12 +32,12 @@ Outputs
 Mesh
    Mesh component of the input geometry.
 
-Point Cloud
-   Point cloud component of the input geometry.
-
 Curve
    Curve component of the input geometry.
 
+Point Cloud
+   Point cloud component of the input geometry.
+
 Volume
    Volume component of the input geometry.
 

manual/modeling/geometry_nodes/hair/deformation/smooth_hair_curves.rst

@@ -4,7 +4,7 @@
 Smooth Hair Curves
 ******************
 
-Smoothes the shape of  hair curves.
+Smooths the shape of  hair curves.
 
 .. peertube:: 7fpUB2eRT6zjMyHRzJ2ZoJ
 

manual/modeling/meshes/editing/uv.rst

@@ -193,10 +193,8 @@ Follow Active Quads
    :Menu:      :menuselection:`UV --> Follow Active Quads`
    :Shortcut:  :kbd:`U`
 
-The Follow Active Quads tool takes the selected faces and lays them out
+Extrapolate UV's based on the active quad by following continuous face loops,
-by following continuous face loops, even if the mesh face is irregularly-shaped.
+even if the mesh face is irregularly-shaped.
-Note that it does not respect the image size,
-so you may have to scale them all down a bit to fit the image area.
 
 
 Options
@@ -205,16 +203,27 @@ Options
 Edge Length Mode
    Method to space UV edge loops.
 
-   :Even: Space all UVs evenly.
+   :Even:
-   :Length: Todo.
+      Space all UVs evenly, where the shape of the quad in the 3D viewport is ignored.
-   :Length Average: Average space UVs edge length of each loop.
+   :Length:
+      Each face's UV's are calculated based on the edge length.
+
+      While this minimizes distortion, adjacent loops may become disconnected.
+   :Length Average:
+      Average space UVs edge length of each loop.
+
+      This has the benefit of minimizing distortion, while keeping UV's connected.
 
 .. note::
 
-   Please note that it is the shape of the active quad in UV space that is being followed,
+   For a clean 90-degree unwrap it's typically best to first make sure the quad a rectangle in UV space.
-   not its shape in 3D space. To get a clean 90-degree unwrap make sure the active quad is
-   a rectangle in UV space before using "Follow active quad".
 
+   Otherwise any distortion in the active UV is extended which doesn't result in a useful grid-layout.
+
+.. note::
+
+   The resulting unwrap is not clamped within the UV bounds,
+   you may wish to scale down the active quad's UV's so the result is in a usable range.
 
 .. _bpy.ops.uv.cube_project:
 

manual/modeling/modifiers/deform/volume_displace.rst

@@ -5,6 +5,10 @@
 Volume Displace Modifier
 ************************
 
+.. reference::
+
+   This modifier is only available for :doc:`Volume Objects </modeling/volumes/index>`.
+
 The *Volume Displace* modifier displaces existing volume grids based on a 3D texture.
 It uses the RGB color channels of the texture to displace the volume into the X, Y and Z direction.
 

manual/modeling/modifiers/generate/mesh_to_volume.rst

@@ -5,6 +5,10 @@
 Mesh to Volume Modifier
 ***********************
 
+.. reference::
+
+   This modifier is only available for :doc:`Volume Objects </modeling/volumes/index>`.
+
 The *Mesh to Volume* modifier uses a mesh to create a new volume grid.
 All previously existing volume grids on the volume object are discarded.
 So this modifier is usually added to an empty volume object.

manual/modeling/modifiers/physics/explode.rst

@@ -15,9 +15,12 @@ That particle system will control how the mesh is exploded.
 Both the number of emitted particles and number of faces determine how granular the *Explode* modifier is.
 More of each faces and particles will mean more individual pieces.
 
-Here is a `demo video <https://archive.blender.org/wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_-_
+Here is a
-2.5.ogg/>`__ showing a cube with a particle system and *Explode* modifier. (`blend-file <https://archive.blender.org/
+`demo video <https://archive.blender.org/wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_
-wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_-_2.5.blend>`__).
+-_2.5.ogg/>`__
+showing a cube with a particle system and *Explode* modifier.
+(`blend-file <https://archive.blender.org/wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_
+-_2.5.blend>`__).
 
 .. note::
 

manual/modeling/texts/properties.rst

@@ -15,6 +15,8 @@ Most of the settings in the *Shape* panel are shared with those of
 :doc:`Curves </modeling/curves/properties/shape>`
 data-blocks, please refer to those for details.
 
+.. _bpy.types.TextCurve.use_fast_edit:
+
 Fast Editing
    Does not fill the letters in Edit Mode, only show their outline.
 
@@ -101,18 +103,39 @@ but you have to choose between different styles of a same font, or different fon
 Blender has a number of typographic controls for changing the style and layout of text,
 found in the *Font* panel.
 
+.. _bpy.types.TextCharacterFormat.use_bold:
+
 Bold
-   Toggled with the *Bold* button before typing. Text can also be set to
+   With no text selected, toggles new text to be **bold**.
-   **bold** by selecting it then using the *Bold* entry in the *Text* menu of
+   With text selected, toggles the selected text to be **bold**.
-   the 3D Viewport.
+   Text can also be set to bold by selecting it then using the *Bold*
-Italics
+   entry in the *Text* menu of the 3D Viewport.
-   Toggled with the *Italic* button before typing. Text can also be set to
+
-   *italic* by selecting it then using the *Italic* entry in the *Text* menu of
+.. _bpy.types.TextCharacterFormat.use_italic:
-   the 3D Viewport.
+
+Italic
+   With no text selected, toggles new text to be *italic*.
+   With text selected, toggles the selected text to be *italic*.
+   Text can also be set to italic by selecting it then using the *Bold*
+   entry in the *Text* menu of the 3D Viewport.
+
+.. _bpy.types.TextCharacterFormat.use_underline:
+
 Underline
-   Enables underlining, as controlled by the :ref:`underline settings <modeling-text-character-underline>` below.
+   With no text selected, toggles new text to be underline.
+   With text selected, toggles the selected text to be underline.
+   Text can also be set to underline by selecting it then using the *Underline*
+   entry in the *Text* menu of the 3D Viewport.
+
+   See also :ref:`underline settings <modeling-text-character-underline>` below.
+
+.. _bpy.types.TextCharacterFormat.use_small_caps:
+
 Small Caps
-   Enable this option to type characters as small caps.
+   With no text selected, toggles new text to be small capitals.
+   With text selected, toggles the selected text to be small capitals.
+   Text can also be set to small caps by selecting it then using the *Small Caps*
+   entry in the *Text* menu of the 3D Viewport.
 
    The size of the *Small Caps* can be changed with
    the :ref:`Small Caps Scale setting <modeling-text-character-underline>`.
@@ -121,9 +144,14 @@ Small Caps
 Transform
 ---------
 
+.. _bpy.types.TextCurve.size:
+
 Size
    Controls the size of the whole text (no way to control each char size independently).
    Note however, that chars with different fonts (different styles, see below) might have different visible sizes.
+
+.. _bpy.types.TextCurve.shear:
+
 Shear
    Controls the inclination of the whole text.
    As similar as it may seem, this is not the same thing as italics style.
@@ -133,6 +161,8 @@ Shear
 
       Shear example.
 
+.. _bpy.types.TextCurve.family:
+
 Object Font
    Allows individual objects to be used to render fonts, you can create/model your own complex font inside Blender!
    This field is used to select the objects prefix name (object "family") to be used
@@ -153,6 +183,8 @@ Object Font
       The objects are duplicated so that their center is positioned at
       the *lower right corner* of the corresponding characters.
 
+.. _bpy.types.TextCurve.follow_curve:
+
 Text on Curve
    Select a curve object for the text object to follow.
 
@@ -167,15 +199,18 @@ Text on Curve
       which offers more control, and is the standard way to achieve such effects in modern Blender.
 
 .. _modeling-text-character-underline:
+.. _bpy.types.TextCurve.underline_position:
 
-Underline
-   Toggled with the *Underline* button before typing.
-   Text can also be set to Underlined by selecting it
-   then using the *Underline* entry in the *Text* menu of the 3D Viewport.
 Underline Position
    This allows you to shift vertically the position of the underline.
+
+.. _py.types.TextCurve.underline_height:
+
 Underline Thickness
    This controls the thickness of the underline.
+
+.. _bpy.types.TextCurve.small_caps_scale:
+
 Small Caps Scale
    The scaling applied to capital letters to turn them into small caps.
 
@@ -198,6 +233,8 @@ The *Paragraph* Panel has settings for the alignment and spacing of text.
 Alignment
 ---------
 
+.. _bpy.types.TextCurve.align_x:
+
 Horizontal
    :Left:
       Aligns text to the left of the frames when using them,
@@ -218,6 +255,8 @@ Horizontal
 
    .. note:: Both *Justify* and *Flush* only work within frames.
 
+.. _bpy.types.TextCurve.align_y:
+
 Vertical
    :Top:
       - With text boxes, aligns the top of the text to the top of the frames.
@@ -247,16 +286,27 @@ Vertical
 Spacing
 -------
 
+.. _bpy.types.TextCurve.space_character:
+
 Character Spacing
    A factor by which space between each character (kerning) is scaled in width.
 
    In Edit Mode in the 3D Viewport, you can also control individual kerning
    at text cursor position by pressing :kbd:`Alt-Left` / :kbd:`Alt-Right` to decrease/increase it.
+
+.. _bpy.types.TextCurve.space_word:
+
 Word Spacing
    A factor by which whitespace between words is scaled in width.
+
+.. _bpy.types.TextCurve.space_line:
+
 Line Spacing
    A factor by which the vertical space between lines is scaled.
 
+.. _bpy.types.TextCurve.offset_x:
+.. _bpy.types.TextCurve.offset_y:
+
 Offset X, Y
    These settings control the X and Y offset of the text position within the object.
    This applies relatively to the object's origin, either to the whole text or, when using text boxes, to each frame.
@@ -284,13 +334,19 @@ If the last frame is reached, text overflows out of it (by default, see options
 
    Text Boxes panel.
 
+.. _bpy.ops.font.textbox_add:
+
 Add Textbox
    Inserts a new frame, just after the current one (in text flow order).
    The new frame will have the same size and position as the selected one.
 
+.._bpy.ops.font.textbox_remove:
+
 Delete ``X``
    Delete the current frame.
 
+.. _bpy.types.TextCurve.overflow:
+
 Overflow
    How to handle text overflowing available space in the defined boxes.
 
@@ -306,10 +362,15 @@ Overflow
          It will only truncate in *Object Mode*,
          in *Edit Mode* the whole text remains visible (and overflows as needed).
 
+.. _bpy.types.TextBox.width:
+
 Size X, Y
    Specifies the width and height of the text box, if set to **zero** no word wrapping happens
    (it is ignored, and the whole text box system is disabled if all are set to a null size).
 
+.. _bpy.types.TextBox.x:
+.. _bpy.types.TextBox.y:
+
 Offset X, Y
    Controls the *X* and *Y* offset of the frame, i.e. its position.
 

manual/modeling/texts/selecting.rst

@@ -15,6 +15,8 @@ it determines where new chars will be inserted.
 
 Select All :kbd:`Ctrl-A`
    Selects the full text.
+Top/Bottom :kbd:`Shift-Ctrl-Home`/ :kbd:`Shift-Ctrl-End`
+   Moves the cursor to the start or end of the text object.
 Next/Previous Character :kbd:`Left`/ :kbd:`Right`
    You can move the cursor with the arrow keys.
 Next/Previous Word :kbd:`Ctrl-Left`/ :kbd:`Ctrl-Right`

manual/physics/soft_body/introduction.rst

@@ -49,8 +49,8 @@ Soft bodies are well suited for:
 
 The following videos may give you some more ideas:
 
-- https://www.youtube.com/watch?v=hLnY-OFUBzM
+- `New Penguoen <https://www.youtube.com/watch?v=hLnY-OFUBzM>`__.
-- https://www.youtube.com/watch?v=qdusMZlBbQ4
+- `Blender Softbody Simulations <https://www.youtube.com/watch?v=qdusMZlBbQ4>`__.
 
 
 Creating a Soft Body

manual/render/cycles/gpu_rendering.rst

@@ -246,8 +246,7 @@ but the only real solution is to use separate graphics cards for display and ren
 
 Another solution can be to increase the time-out,
 although this will make the user interface less responsive when rendering heavy scenes.
-`Learn More Here <https://learn.microsoft.com/en-us/windows-hardware/drivers/display/timeout-detection-and-
+`Learn More Here <https://learn.microsoft.com/en-us/windows-hardware/drivers/display/timeout-detection-and-recovery>`__.
-recovery>`__.
 
 
 CUDA error: Unknown error in cuCtxSynchronize()

manual/render/cycles/render_settings/sampling.rst

@@ -175,7 +175,7 @@ Training Samples
 .. _bpy.types.CyclesRenderSettings.use_surface_guiding:
 
 Surface
-   Enable path guiding for the diffuse component of surfaces.
+   Enable path guiding for the diffuse and glossy components of surfaces.
 
 .. _bpy.types.CyclesRenderSettings.use_volume_guiding:
 

manual/render/cycles/world_settings.rst

@@ -53,8 +53,8 @@ Falloff
 
 .. figure:: /images/render_cycles_world-settings_mist-example1-BI.jpg
 
-   Mist example (`blend-file <https://archive.blender.org/wiki/index.php/File:25-Manual-World-Mist-
+   Mist example
-   Example1.blend>`__).
+   (`blend-file <https://archive.blender.org/wiki/index.php/File:25-Manual-World-Mist-Example1.blend>`__).
 
 
 .. _bpy.types.CyclesVisibilitySettings.camera:

manual/render/output/animation.rst

@@ -91,7 +91,7 @@ Frame Sequence Workflow
 =======================
 
 #. First prepare your animation.
-#. In the *Dimensions* panel, choose the render size, Pixel Aspect Ratio, and the Range of Frames to use,
+#. In the *Format* panel, choose the render size, Pixel Aspect Ratio, and the Range of Frames to use,
    as well as the frame rate, which should already be set.
 #. In the Output panel set up your animation to be rendered out as images,
    generally using a format that does not compromise any quality.

manual/render/shader_nodes/color/index.rst

@@ -9,7 +9,7 @@
    bright_contrast.rst
    gamma.rst
    hue_saturation.rst
-   invert.rst
+   invert_color.rst
    light_falloff.rst
    mix.rst
    rgb_curves.rst

manual/render/shader_nodes/color/invert_color.rst

@@ -1,4 +1,4 @@
 .. _bpy.types.ShaderNodeInvert:
 .. DO NOT EDIT FILE. This is simply a stub which copies everything from the link below.
-.. include:: /compositing/types/color/invert.rst
+.. include:: /compositing/types/color/invert_color.rst
    :start-after: .. --- copy below this line ---

manual/render/shader_nodes/osl.rst

@@ -157,14 +157,19 @@ Other
 Attributes
 ==========
 
-Some object, particle and mesh attributes are available to the built-in ``getattribute()`` function.
+Geometry attributes can be read through the ``getattribute()`` function.
-UV maps and Color Attributes can be retrieved using their name.
+This includes UV maps, color attributes and any attributes output from geometry nodes.
-Other attributes are listed below:
+
+The following built-in attributes are available through ``getattribute()`` as well.
 
 ``geom:generated``
-   Generated texture coordinates.
+   Automatically generated texture coordinates, from undeformed mesh.
 ``geom:uv``
    Default render UV map.
+``geom:tangent``
+   Default tangent vector along surface, in object space.
+``geom:undisplaced``
+   Position before displacement, in object space.
 ``geom:dupli_generated``
    For instances, generated coordinate from instancer object.
 ``geom:dupli_uv``
@@ -177,26 +182,38 @@ Other attributes are listed below:
    Vertex coordinates array of the polygon (always three vertices currently).
 ``geom:name``
    Name of the object.
+``geom:is_smooth``
+   Is mesh face smooth or flat shaded.
 ``geom:is_curve``
-   Is object a strand or not.
+   Is object a curve or not.
 ``geom:curve_intercept``
-   Point along the strand, from root to tip.
+   0..1 coordinate for point along the curve, from root to tip.
 ``geom:curve_thickness``
-   Thickness of the strand.
+   Thickness of the curve in object space.
+``geom:curve_length``
+   Length of the curve in object space.
 ``geom:curve_tangent_normal``
    Tangent Normal of the strand.
+``geom:is_point``
+   Is point in a point cloud or not.
+``geom:point_radius``
+   Radius of point in point cloud.
+``geom:point_position``
+   Center position of point in point cloud.
+``geom:point_random``
+   Random number, different for every point in point cloud.
 ``path:ray_length``
    Ray distance since last hit.
+``object:random``
+   Random number, different for every object instance.
+``object:index``
+   Object unique instance index.
 ``object:location``
    Object location.
-``object:index``
-   Object index number.
-``object:random``
-   Per object random number generated from object index and name.
 ``material:index``
-   Material index number.
+   Material unique index number.
 ``particle:index``
-   Particle instance number.
+   Particle unique instance number.
 ``particle:age``
    Particle age in frames.
 ``particle:lifetime``
@@ -226,3 +243,16 @@ This function cannot be used instead of lighting;
 the main purpose is to allow shaders to "probe" nearby geometry,
 for example to apply a projected texture that can be blocked by geometry,
 apply more "wear" to exposed geometry, or make other ambient occlusion-like effects.
+
+Metadata
+========
+
+Metadata on parameters controls their display in the user interface. The following
+metadata is supported:
+
+``[[ string label = "My Label" ]]``
+  Name of parameter in in the user interface
+``[[ string widget = "null" ]]``
+  Hide parameter in the user interface.
+``[[ string widget = "boolean" ]]`` and ``[[ string widget = "checkbox" ]]``
+  Display integer parameter as a boolean checkbox.

manual/render/shader_nodes/textures/image.rst

@@ -63,7 +63,7 @@ Projection
       this origin onto this sphere. This projection is, of course, perfect for spherical objects
       such as planets, and is also useful for organic objects.
    :Tube:
-      Wrap the image around a cylinder with origin (0.5, 0.5, 0) and height 1, and project the
+      Wrap the image around a cylinder with base (0.5, 0.5, 0) and height 1, and project the
       *Vector* horizontally from the central axis onto this cylinder. This projection is useful for
       a label on a bottle, for example. However, it's not suited for the top or bottom side of objects.
 

manual/sculpt_paint/brush/texture.rst

@@ -135,7 +135,7 @@ Size X, Y, Z
 
 Sample Bias :guilabel:`Sculpt Mode`
    Value added to texture samples.
-   This can be used if the midlevel of a height map is not correct.
+   This can be used if the mid-level of a height map is not correct.
 
 .. _bpy.types.Brush.use_color_as_displacement:
 

manual/sculpt_paint/sculpting/editing/expand.rst

@@ -12,7 +12,7 @@ When executed, it uniformly expand outwards a pattern from the vertex under the
 
    These operators are meant to be used interactively through the shortcut.
 
-There is also a `full showcase of the Expand features and use cases <https://www.youtube.com/watch?v=XT7h6lmE5bc>`_.
+There is also a `full showcase of the Expand features and use cases <https://www.youtube.com/watch?v=XT7h6lmE5bc>`__.
 
 .. figure:: /images/sculpt-paint_sculpting_expand_example.png
 

manual/sculpt_paint/sculpting/introduction/cloth_sculpting.rst

@@ -27,4 +27,4 @@ but other transform brushes like :doc:`Pose </sculpt_paint/sculpting/tools/pose>
 :doc:`Boundary </sculpt_paint/sculpting/tools/boundary>` also support cloth sculpting in the brush settings.
 
 A demo file for trying out the various brushes and tools is available
-`here <https://www.blender.org/download/demo-files/#sculpting>`_.
+`here <https://www.blender.org/download/demo-files/#sculpting>`__.

manual/sculpt_paint/sculpting/tools/draw.rst

@@ -34,10 +34,11 @@ to displace geometry in three directions instead of just one.
 .. figure:: /images/sculpt-paint_sculpt_vdm_example.png
    :width: 580px
 
-   An example of various VDM brushes used on a smooth head from the offical demo file.
+   An example of various VDM brushes used on a smooth head from the official demo file.
 
-`Download the demo file <https://www.blender.org/download/demo-files/#sculpting>`_ for more information and to try
+For easy creation of VDM brushes, enable the :doc:`VDM Brush Baker </addons/baking/vdm_brush_baker>` addon.
-the feature out.
+`Download the demo file <https://www.blender.org/download/demo-files/#sculpting>`__
+for more information and to try the feature out.
 
 To use this feature, enable :ref:`Vector Displacement <bpy.types.Brush.use_color_as_displacement>` in the texture
 panel. All :ref:`stroke methods <bpy.types.Brush.stroke_method>` are supported, but the recommended behavior is

manual/sculpt_paint/vertex_paint/editing.rst

@@ -58,7 +58,7 @@ Levels
 
 .. _bpy.ops.paint.vertex_color_hsv:
 
-Hue Saturation Value
+Hue/Saturation/Value
    Adjust the HSV values of the selected vertices.
 
 .. _bpy.ops.paint.vertex_color_brightness_contrast:

manual/video_editing/edit/montage/editing.rst

@@ -28,7 +28,7 @@ Expand
 Snapping
 ^^^^^^^^
 
-It is possible to enable snapping in the header of the VSE.
+It is possible to enable snapping in the header of the Video Sequencer.
 The snapping behavior can be configured as follows:
 
 .. _bpy.types.SequencerToolSettings.snap_to_current_frame:

pyproject.toml

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+[tool.autopep8]
+# Configuration for `autopep8`, allowing the command: autopep8 .
+# to reformat all source files.
+#
+# NOTE: the settings defined here map directly to command line arguments
+# which will override these settings when passed in to autopep8.
+
+max_line_length = 120
+
+ignore = [
+    # Info: Use `isinstance()` instead of comparing types directly.
+    # Why disable? Changes code logic, in rare cases we want to compare exact types.
+    "E721",
+    # Info: Fix bare except.
+    # Why disable? Disruptive, leave our exceptions alone.
+    "E722",
+    # Info: Fix module level import not at top of file.
+    # Why disable? Re-ordering imports is disruptive and breaks some scripts
+    # that need to check if a module has already been loaded in the case of reloading.
+    "E402",
+    # Info: Fix various deprecated code (via lib2to3)
+    # Why disable? Does nothing besides incorrectly adding a duplicate import,
+    # could be reported as a bug except this is likely to be removed soon, see:
+    # https://github.com/python/cpython/issues/84540.
+    "W690",
+]
+
+# Use aggressive as many useful edits are disabled unless it's enabled.
+# Any edits which are overly disruptive or risky can be removed in the `ignore` list.
+aggressive = 2
+
+# Exclude:
+# - `./tools/svn_rev_map` because it's a large data-file.
+exclude = """
+./tools/svn_rev_map/sha1_to_rev.py,
+"""
+
+# Omit settings such as `jobs`, `in_place` & `recursive` as they can cause editor utilities that auto-format on save
+# to fail if the STDIN/STDOUT is used for formatting (which isn't compatible with these options).

resources/.htaccess

@@ -144,3 +144,7 @@ RedirectMatch "^/manual/{lang}/{version}/modeling/geometry_nodes/utilities/align
 RedirectMatch "^/manual/{lang}/{version}/modeling/geometry_nodes/utilities/rotate_euler.html" "/manual/{lang}/{version}/modeling/geometry_nodes/utilities/rotation/rotate_euler.html"
 
 RedirectMatch "^/manual/{lang}/{version}/editors/graph_editor/channels.html" "/manual/{lang}/{version}/editors/graph_editor/channels/index.html"
+
+RedirectMatch "^/manual/{lang}/{version}/compositing/types/color/invert.html" "^/manual/{lang}/{version}/compositing/types/color/invert_color.html"
+RedirectMatch "^/manual/{lang}/{version}/editors/texture_node/types/color/invert.html" "^/manual/{lang}/{version}/editors/texture_node/types/color/invert_color.html"
+RedirectMatch "^/manual/{lang}/{version}/render/shader_nodes/color/invert.html" "^/manual/{lang}/{version}/render/shader_nodes/color/invert_color.html"

tools_maintenance/blender_help_extract.py

@@ -1,325 +1,188 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
-# <pep8 compliant>
+
+"""
+This script extracts RST fro Blender's "--help",
+using simple conventions & REGEX parsing.
+
+Example:
+   python tools_maintenance/blender_help_extract.py /path/to/blender manual/advanced/command_line/arguments.rst
+"""
+
+# Conversion from There are some cases which aren't handled (and aren't needed at the moment),
+# noting for completeness.
+#
+# - Multi-line code-blocks as each block is currently only a single line.
+# - Skip parsing text inside comment blocks (literal quoting single brackets for e.g.).
 
 import os
 import re
-
+import subprocess
-# This script extracts the '--help' message from Blender's source code,
-# using primitive regex parsing.
-#
-# e.g:
-# python tools_maintenance/blender_help_extract.py \
-#        ../blender/source/creator/creator_args.c \
-#        manual/advanced/command_line/arguments.rst
 
 
-def text_remove_comments(text):
+def help_text_make_version_and_usage_substitution(text: str) -> str:
-    def replacer(match):
+    text = re.sub(
-        s = match.group(0)
+        re.compile(r"^(Blender) +\d.*\n(Usage:) +(.*)$", flags=re.MULTILINE),
-        if s.startswith('/'):
+        lambda x: (
-            return " "
+            "| {:s} |BLENDER_VERSION|\n"
-        else:
+            "| {:s} ``{:s}``"
-            return s
+        ).format(x.group(1), x.group(2), x.group(3)),
-    pattern = re.compile(
+        text,
-        r'//.*?$|/\*.*?\*/|\'(?:\\.|[^\\\'])*\'|"(?:\\.|[^\\"])*"',
-        re.DOTALL | re.MULTILINE
-    )
-    return re.sub(pattern, replacer, text)
-
-
-def text_remove_preprocess(text):
-    lines = text.split("\n")
-    non_comment_lines = [line for line in lines if not line.strip().startswith("#")]
-    return "\n".join(non_comment_lines)
-
-def text_join_lines(text):
-    lines = text.split("\n")
-    lines_out = [[]]
-    for l in lines:
-        lines_out[-1].append(l)
-        if l.endswith((";", "{", ")", "}")) or l.lstrip().startswith("#"):
-            lines_out.append([])
-    text = "\n".join(
-        [
-            " ".join(l.lstrip() if i != 0 else l for i, l in enumerate(l_group))
-            for l_group in lines_out
-        ]
     )
     return text
 
 
-def text_expand_macros(text):
+def help_text_make_args_literal(text: str) -> str:
-    # CB() macro
-    def replacer_CB(match):
-        return match.group(2) + "_doc, " + match.group(2)
 
-    pattern_CB = re.compile(
+    re_content_table = (
-        r'\b(CB)\s*\(([^\,]+)\)',
+        (
-        re.DOTALL | re.MULTILINE
+            re.compile(r"(\-+[A-Za-z\-]+)"),
+            lambda x: "``" + x.group(1) + "``",
+        ),
     )
 
-    # CB_EX() macro
+    re_argument_line = re.compile(r"^(\s*)(\-+[A-Za-z\-]+.*)$", flags=re.MULTILINE)
-    def replacer_CB_EX(match):
-        return match.group(2) + "_doc_" + match.group(3) + ", " + match.group(2)
 
-    pattern_CB_EX = re.compile(
+    def re_argument_line_fn(x: re.Match[str]) -> str:
-        r'\b(CB_EX)\s*\(([^\,]+),\s*([^\)]+)\)',
+        indent = x.group(1)
-        re.DOTALL | re.MULTILINE
+        content = x.group(2)
+
+        for re_expr, re_fn in re_content_table:
+            content = re.sub(re_expr, re_fn, content)
+
+        # Weak but works to replace or's with commas.
+        content = content.replace("`` or ``-", "``, ``-", 1)
+        return indent + content
+
+    text = re.sub(re_argument_line, re_argument_line_fn, text)
+    return text
+
+
+def help_text_make_single_quotes_literal(text: str) -> str:
+    re_table = (
+        (
+            re.compile(r"(\s+)'([^\']+)'"),
+            lambda x: x.group(1) + "``" + x.group(2) + "``",
+        ),
+        (
+            re.compile(r"([-+]?<[A-Za-z_0-9\(\)]+>)"),
+            lambda x: "``" + x.group(1) + "``",
+        ),
     )
 
-    # STRINGIFY_ARG() macro
+    for re_expr, re_fn in re_table:
-    def replacer_STRINGIFY_ARG(match):
+        text = re.sub(re_expr, re_fn, text)
-        return "\"``" + match.group(2) + "``\""
-
-    pattern_STRINGIFY_ARG = re.compile(
-        r'\b(STRINGIFY_ARG)\s*\(([^\)]+)\)',
-        re.DOTALL | re.MULTILINE
-    )
-
-    text = re.sub(pattern_CB, replacer_CB, text)
-    text = re.sub(pattern_CB_EX, replacer_CB_EX, text)
-    text = re.sub(pattern_STRINGIFY_ARG, replacer_STRINGIFY_ARG, text)
 
     return text
 
 
-def text_extract_args(text):
+def help_text_make_title_and_dedent(text: str) -> str:
+    re_title = re.compile(r"\n\n([A-Z][^:]+):$", flags=re.MULTILINE)
+    title_char = "="
 
-    args = {}
+    def re_title_fn(x: re.Match[str]) -> str:
-    # use replace to scan (misuse!)
+        heading = x.group(1)
-
+        return (
-    def replacer(match):
-        fn = match.group(1)
-        s = match.group(2)
-
-        # remove first 2 args
-        s = s.split(',', 1)[-1]
-        # remove last 2 args
-        s = s.rsplit(',', 2)[0]
-
-        if fn == "BLI_args_add":
-            # get first 2 args
-            arg_short, arg_long, s = [w.strip() for w in s.split(",", 2)]
-        elif fn == "BLI_args_add_case":
-            # get first 2 args
-            arg_short, _, arg_long, _, s = [w.strip() for w in s.split(",", 4)]
-            del _
-        else:
-            # should never happen
-            raise Exception("Bad function call %r" % fn)
-
-        if arg_short == "NULL":
-            arg_short = None
-        else:
-            arg_short = eval(arg_short, {})
-        if arg_long == "NULL":
-            arg_long = None
-        else:
-            arg_long = eval(arg_long, {})
-        args[arg_short, arg_long] = s
-
-        # print(arg_short, arg_long, s)
-
-    pattern = re.compile(
-        r'\b(BLI_args_add[_case]*)\s*\(((?:(?!\)\s*;).)*?)\)\s*;',
-        re.DOTALL | re.MULTILINE
-    )
-
-    re.sub(pattern, replacer, text)
-    return args
-
-
-def text_extract_strings(text):
-    strings = {}
-    # use replace to scan (misuse!)
-
-    text = (
-        text
-    ).replace(
-        "PY_ENABLE_AUTO", " \" (default)\""
-    ).replace(
-        "PY_DISABLE_AUTO", " \"\""
-    ).replace(
-        "STRINGIFY(BLENDER_STARTUP_FILE)", "\"startup.blend\""
-    ).replace(
-        "STRINGIFY(BLENDER_MAX_THREADS)", "\"1024\""
-    )
-
-    def replacer(match):
-        var = match.group(1).strip()
-        s = match.group(2)
-        s = " ".join([w.strip() for w in s.split("\n")])
-        s = eval(s, {})
-        strings[var] = s
-
-    pattern = re.compile(
-        r'\bstatic\s+const\s+char\s+([A-Za-z0-9_]+)\[\]\s*=\s*((?:(?!"\s*;).)*?")\s*;',
-        re.DOTALL | re.MULTILINE
-    )
-
-    re.sub(pattern, replacer, text)
-    return strings
-
-
-def text_extract_help(text, args, static_strings):
-    func_id = 'static int arg_handle_print_help(int UNUSED(argc), const char **UNUSED(argv), void *data)\n'
-    index_start = text.find(func_id)
-    assert(index_start != -1)
-    index_end = text.find("exit(0);", index_start)
-    # print(index_start, index_end)
-    body = text[index_start + len(func_id):index_end]
-    body = [l for l in body.split("\n") if not l.strip().startswith("#")]
-    body = [l.strip() for l in body]
-    body = [l for l in body if l]
-
-    # args dicts
-    args_short = {}
-    args_long = {}
-    args_used = set()
-
-    for (arg_short, arg_long), value in args.items():
-        if arg_short is not None:
-            args_short[arg_short] = (arg_short, arg_long), value
-        if arg_long is not None:
-            args_long[arg_long] = (arg_short, arg_long), value
-    # there is some overlap in short/long args, second pass to fix
-    # by assigning long-only
-    for (arg_short, arg_long), value in args.items():
-        if arg_short is not None:
-            if arg_long is None:
-                args_short[arg_short] = (arg_short, arg_long), value
-
-    def args_get(arg):
-        value = args_long.get(arg)
-        if value is None:
-            value = args_short.get(arg)
-            if value is None:
-                raise Exception("Can't find %r" % arg)
-        return value
-
-    text_rst = []
-
-    # execute the code!
-    other_vars = {
-        "BKE_blender_version_string": lambda: "|BLENDER_VERSION|",
-    }
-
-    def write_arg(arg):
-        (arg_short, arg_long), arg_text = args_get(arg)
-        args_used.add((arg_short, arg_long))
-
-        # replacement table
-        arg_text = re.sub(r"\"\s*STRINGIFY_ARG\s*\(([a-zA-Z0-9_]+)\)\"", r"``\1``", arg_text)
-        arg_text = arg_text.replace('" STRINGIFY(BLENDER_MAX_THREADS) "', "64")
-        arg_text = arg_text.replace('" STRINGIFY(BLENDER_STARTUP_FILE) "', "startup.blend")
-        arg_text = arg_text.replace('" PY_ENABLE_AUTO', '\"')
-        arg_text = arg_text.replace('" PY_DISABLE_AUTO', ', (default).\"')
-
-        # print(arg_text)
-        arg_text = eval(arg_text, static_strings)
-        arg_text = arg_text.replace("\t", "   ")
-
-        text_rst.append("``" + "``, ``".join([w for w in (arg_short, arg_long) if w is not None]) + "`` ")
-        text_rst.append(arg_text + "\n")
-
-    ind_re = None
-    for l in body:
-        if l.startswith("printf"):
-            l = eval(l.replace("printf(", "").replace(");", ""), other_vars)
-            if type(l) is tuple:
-                # Run the C-style string format.
-                l = l[0] % l[1:]
-            if l.lstrip() == l and l.strip("\n").endswith(":"):
-                # Create RST heading & unique reference target.
-                l = l.strip(":\n")
-                l = (
             "\n"
             "\n"
-                    ".. _command-line-args-%s:\n"
+            ".. _command-line-args-{:s}:\n"
             "\n"
-                    "%s\n"
+            "{:s}\n"
-                    "%s\n"
+            "{:s}\n"
-                    "\n"
+        ).format(
-                ) % (
+            "".join([(c if c.isalpha() else "-") for c in heading.lower()]),
-                    # Create reference so each heading can be linked to.
+            heading,
-                    "".join([(c if c.isalpha() else "-") for c in l.lower()]),
+            (title_char * len(heading)),
-                    # The heading.
-                    l,
-                    # Heading underline.
-                    len(l) * "=",
         )
-                ind_re = None
+
+    text = re.sub(re_title, re_title_fn, text)
+
+    # Un-indent entirely indented blocks (directly after the title).
+    lines = text.splitlines(keepends=False)
+    i = 0
+    while i < len(lines):
+        if not (lines[i].startswith(title_char) and lines[i].strip(title_char) == ""):
+            # Not a title, continue.
+            i += 1
+            continue
+
+        # We have a title, check the next non-blank line.
+        i_next = i + 1
+        while lines[i_next] == "":
+            i_next += 1
+        if not lines[i_next].startswith(" "):
+            # No indentation, continue.
+            i = i_next
+            continue
+
+        # Measure indent and de-dent until indentation not met.
+        indent_len = len(lines[i_next]) - len(lines[i_next].lstrip())
+        indent = " " * indent_len
+        while i_next < len(lines):
+            if lines[i_next].startswith(indent):
+                lines[i_next] = lines[i_next][indent_len:]
+            elif lines[i_next] == "":
+                pass
             else:
-                # unindent to the previous min indent
-                for _ in range(2):
-                    if ind_re is None:
-                        ind_re = r"\A\t{0,}"
-                    ind_m = re.match(ind_re, l)
-                    if ind_m:
-                        ind_re = r"\A\t{" + str(ind_m.end(0)) + r"}"
-                        l = re.sub(ind_re, '', l)
                 break
-                    else:
+            i_next += 1
-                        # indent is less than before
-                        ind_re = None
 
-                l = l.replace("\t", "   ")
+        i = i_next
 
-            text_rst.append(l)
+    text = "\n".join(lines)
-        elif l.startswith("BLI_args_print_arg_doc("):
-            arg = l.split(",")[-1].strip(");\n")
-            arg = eval(arg, {})
-            write_arg(arg)
-        elif l.startswith("BLI_args_print_other_doc("):
-            items = list(args.items())
-            # sort as strings since we can't order (None <> str)
-            items.sort(key=lambda i: str(i[0]))
-            for key, value in items:
-                if key not in args_used:
-                    write_arg(key[0] or key[1])
 
-    text_rst = "".join(text_rst)
+    return text
 
-    # not essential, but nice to have <word> as ``<word>``
-    text_rst = re.sub(r"([\+\-]*<[a-zA-Z0-9\(\)_\-]+>)", r"``\1``", text_rst)
 
-    # ------
+def help_text_make_environment_variables(text: str) -> str:
-    # Post process (formatting)
+    env_vars = []
-    # text_rst = re.split(r"\\n|[()]", text_rst)
-    text_rst = text_rst.splitlines()
 
-    for i, l in enumerate(text_rst):
+    # Single lines.
-        # detect env var list
+    re_env = re.compile(r"^(\s*)\$([A-Z][A-Z0-9_]*)(\s+)", flags=re.MULTILINE)
-        l_strip = l.lstrip()
-        if l_strip.startswith("$"):
-            l_strip, l_tail = l_strip.lstrip("$").split(" ", 1)
-            if l_strip.isupper():
-                l = ":%s: %s" % (l_strip, l_tail)
-            del l_tail
-        elif l_strip.startswith("#"):
-            indent = l[:len(l) - len(l_strip)]
-            l = "\n" + indent + ".. code-block:: sh\n\n" + indent + "   " + l.lstrip("# ") + "\n"
-        else:
-            # use "'" as "``", except when used as plural, e.g. "Python's"
-            l = re.sub("(?<![a-z])'|'(?![st])", "``", l)
-        del l_strip
 
-        text_rst[i] = l.rstrip(" ")
+    def re_env_fn(x: re.Match[str]) -> str:
+        env_var = x.group(2)
+        env_vars.append(env_var)
+        return x.group(1) + ":" + env_var + ":" + x.group(3)
 
-    # finally, make switches literal if they proceed literal args
+    text = re.sub(re_env, re_env_fn, text)
-    # or have their own line.
-    # -a ``<b>`` ... --> ``-a`` ``<b>``
-    # and...
-    # -a --> ``-a``
-    for i, l in enumerate(text_rst):
-        if l.lstrip().startswith("-"):
-            l = re.sub(r"(\s+)(\-[a-z])(\s+``)", r"\1``\2``\3", l)
-            l = re.sub(r"^(\s+)(\-[a-z])$", r"\1``\2``", l)
-            text_rst[i] = l
 
-    text_rst = [
+    def re_env_var_quote_fn(x: re.Match[str]) -> str:
-        ".. DO NOT EDIT THIS FILE, GENERATED BY %r\n" % os.path.basename(__file__),
+        beg, end = x.span(1)
+        # Ignore environment variables that were just converted into field definitions.
+        if x.string[beg - 1] == ":" and x.string[end] == ":":
+            # Do nothing.
+            return x.group(1)
+
+        return "``" + x.group(1) + "``"
+
+    # Now literal quote all environment variables.
+    re_env_var_quote = re.compile(r"\b({:s}\b)".format("|".join(env_vars)))
+    text = re.sub(re_env_var_quote, re_env_var_quote_fn, text)
+    return text
+
+
+def help_text_make_code_blocks(text: str) -> str:
+    re_code_block = re.compile(r"^(\s*)(# .*)$", flags=re.MULTILINE)
+
+    def re_code_block_fn(x: re.Match[str]) -> str:
+        indent = x.group(1)
+        content = x.group(2)
+        return (
+            "\n"
+            "{:s}.. code-block:: sh\n"
+            "\n"
+            "{:s}   {:s}\n"
+        ).format(indent, indent, content[1:].lstrip())
+
+    text = re.sub(re_code_block, re_code_block_fn, text)
+
+    return text
+
+
+def help_text_as_rst(text: str) -> str:
+    text_header = (
+        ".. DO NOT EDIT THIS FILE, GENERATED BY '{:s}'\n"
         "\n"
         "   CHANGES TO THIS FILE MUST BE MADE IN BLENDER'S SOURCE CODE, SEE:\n"
         "   https://projects.blender.org/blender/blender/src/branch/main/source/creator/creator_args.c\n"
@@ -330,46 +193,69 @@ def text_extract_help(text, args, static_strings):
         "Command Line Arguments\n"
         "**********************\n"
         "\n"
-    ] + text_rst
+    ).format(os.path.basename(__file__))
 
-    text_rst = "\n".join(text_rst)
+    # Expand tabs & strip trailing space.
-    text_rst = text_rst + "\n"
+    text = text.expandtabs(3)
-    text_rst = text_rst.replace("\n\n\n\n", "\n\n\n")
+    text = "\n".join([line.rstrip() for line in text.splitlines()]) + "\n"
 
-    return text_rst
+    text = help_text_make_version_and_usage_substitution(text)
+    text = help_text_make_args_literal(text)
+    text = help_text_make_single_quotes_literal(text)
+    text = help_text_make_title_and_dedent(text)
+    text = help_text_make_environment_variables(text)
+    text = help_text_make_code_blocks(text)
+
+    # Hack: `/?` is a special case.
+    text = text.replace("\n/?\n", "\n``/?``\n", 1)
+
+    # Apply the header last (no need for it to be parsed).
+    return text_header + text
 
 
-def main():
+def main() -> None:
     import sys
-    source_file = sys.argv[-2]
+    blender_bin = sys.argv[-2]
     output_file = sys.argv[-1]
 
-    if not source_file.endswith("creator_args.c"):
-        print("Expected 'creator_args.c' to be passed as the second last argument")
-        return
     if not output_file.endswith(".rst"):
         print("Expected an '.rst' file to be passed as the last argument")
         return
 
-    with open(source_file, 'r') as f:
+    env = os.environ.copy()
-        text = f.read()
+    env["ASAN_OPTIONS"] = (
+        env.get("ASAN_OPTIONS", "") +
+        ":exitcode=0:check_initialization_order=0:strict_init_order=0:detect_leaks=0"
+    )
 
-    text = text_remove_comments(text)
+    text_beg = "BEGIN_BLOCK"
-    text = text_remove_preprocess(text)
+    text_end = "END_BLOCK"
-    # join ',\n' - function args split across lines.
+    text = subprocess.check_output(
-    text = text_join_lines(text)
+        [
-    # expand CB macros
+            blender_bin,
-    text = text_expand_macros(text)
+            "--factory-startup",
-    # first pass, extract 'BLI_args_add'
+            "--background",
+            "--python-exit-code", "1",
+            "--python-expr",
+            # Code begin/end text because of Blender's chatty reporting of version and that it quit.
+            (
+                "print("
+                "'{:s}\\n' + "
+                "__import__('bpy').app.help_text(all=True) + "
+                "'\\n{:s}'"
+                ")"
+            ).format(text_beg, text_end),
+        ],
+        env=env,
+    ).decode("utf-8")
 
-    args = text_extract_args(text)
+    # Extract between begin/end markers.
+    text = text[text.find(text_beg) + len(text_beg) + 1: text.find(text_end)]
 
-    static_strings = text_extract_strings(text)
+    text_rst = help_text_as_rst(text)
 
-    text_rst = text_extract_help(text, args, static_strings)
+    with open(output_file, "w", encoding="utf-8") as fh:
-
+        fh.write(text_rst)
-    with open(output_file, 'w') as f:
-        f.write(text_rst)
 
 
 if __name__ == "__main__":

tools_maintenance/change_placeholders.sh

@@ -6,7 +6,7 @@
 # when updating PO files, automatically inserting name of author and revision time,
 # which should save you some times.
 # Recommend to copy this to your $HOME/bin directory and add executable flag (chmod u+x),
-# then use it with the directory of your local repository (svn or git), ie.
+# then use it with the directory of your local repository, ie.
 # 		$HOME/bin/change_placeholders.sh $BLENDER_MAN_EN
 # Windows users can try to install Linux on Windows following this guide (https://docs.microsoft.com/en-us/windows/wsl/install-win10)
 # Author: Hoang Duy Tran <hoangduytran1960@googlemail.com>

tools_maintenance/update_po.py

@@ -6,20 +6,6 @@
 # It looks more complex then it really is, since we do multi-processing
 # to update the PO files, to save some time.
 
-# Subversion Checkout Location
-# ============================
-#
-# Note: this script supports subversion repositories at these locations:
-#
-# ./local/(.svn)          All languages in one checkout.
-# ./local/{LANG}/(.svn)   Each language in it's own checkout.
-#
-# All commands run from the project root, passing in paths
-# without changing directories.
-#
-# This works since subversion will detect the parent directories ".svn"
-# path without us having to change directories.
-
 import os
 import sys
 import shutil
@@ -33,8 +19,8 @@ VERBOSE = False
 USE_MULTI_PROCESS = True
 
 
-def run_svn(args, with_output=False):
+def run_git(args, with_output=False):
-    cmd = ["svn", *args]
+    cmd = ["git", *args]
     if VERBOSE:
         print(">>> ", cmd)
 
@@ -84,7 +70,8 @@ def run_multiprocess__multi(arg_list, job_total=1):
         sys.stdout.flush()
         sys.stderr.flush()
 
-        processes.append((args_index, subprocess.Popen(["sphinx-intl", *args])))
+        processes.append(
+            (args_index, subprocess.Popen(["sphinx-intl", *args])))
 
     while processes:
         processes_clear_finished()
@@ -122,42 +109,21 @@ LOCALE_DIR = os.path.join(ROOT_DIR, "locale")
 
 POT_FILE = os.path.join(LOCALE_DIR, "blender_manual.pot")
 
-# When we cannot use portable API's.
-IS_WIN32 = (os.name == "nt")
-
 
 # -----------------------------------------------------------------------------
 # Main Function
 
 def main():
 
-    # True when all languages are checked out under "locale/".
-    has_complete_locale_checkout = os.path.exists(os.path.join(LOCALE_DIR, ".svn"))
-
-    # All directories containing '.svn' (the parent directory).
-    svn_dirs_all = []
-    for svn_dir in os.listdir(LOCALE_DIR):
-        if not svn_dir.startswith((".", "_")):
-            svn_dir = os.path.join(LOCALE_DIR, svn_dir)
-            if os.path.isdir(svn_dir):
-                svn_dirs_all.append(svn_dir)
-    # Only for reproducible execution.
-    svn_dirs_all.sort()
-
     # ---------------------
     # Update the Locale Dir
-    #
+    status = run_git(["-C", LOCALE_DIR, "status"], True)
-    # It's easy to accidentally have a repository in an invalid state,
-    # and it's not always obvious that this is the cause of failure to commit.
-    # Play it safe and cleanup every time.
 
-    if has_complete_locale_checkout:
+    if b"nothing to commit, working tree clean" not in status:
-        run_svn(["cleanup", LOCALE_DIR])
+        sys.exit(
-        run_svn(["up", LOCALE_DIR])
+            "Locale directory has uncommitted changes, please stash or comment them")
-    else:
+
-        for svn_dir in svn_dirs_all:
+    run_git(["-C", LOCALE_DIR, "pull", "--rebase"])
-            run_svn(["cleanup", svn_dir])
-            run_svn(["up", svn_dir])
 
     # ---------------
     # Create PO Files
@@ -214,58 +180,23 @@ def main():
         print("Warning, the following commands returned non-zero exit codes:")
         for returncode, arg in zip(sphinx_intl_return_codes, sphinx_intl_arg_list):
             if returncode != 0:
-                print("returncode:", returncode, "from command:", "sphinx-intl", arg)
+                print("returncode:", returncode,
+                      "from command:", "sphinx-intl", arg)
         print("Some manual corrections might need to be done.")
     del sphinx_intl_return_codes, sphinx_intl_arg_list
 
-    # ----------
-    # Handle SVN
-
-    # Add newly created PO files:
-    for svn_dir in svn_dirs_all:
-        # Multiple args, don't quote.
-        svn_files_new = []
-        svn_dirs_new = []
-        for line in run_svn(("status", svn_dir), True).decode("utf-8").splitlines():
-            if line.startswith("?"):
-                line = line.strip()
-                line = line.split()[-1]
-                if line.endswith(".po"):
-                    svn_files_new.append(line)
-                elif os.path.isdir(line):
-                    svn_dirs_new.append(line)
-
-        if svn_files_new:
-            run_svn(["add", *svn_files_new, *svn_dirs_new])
-        del svn_files_new, svn_dirs_new
-
     # ---------------------
     # Print Commit Messages
     #
     # Use space prefix as shell's (bash/zsh/fish) uses this as a hint not to store in the users history.
-    revision = re.findall(
+    revision = run_git(["-C", ROOT_DIR, "rev-parse",
-        r"^Revision:\s([\d]+)",
+                       "--short", "HEAD"], True).decode('utf8').strip()
-        run_svn(["info", ROOT_DIR], True).decode('utf8'),
+    revision = revision if revision else "Unknown"
-        flags=re.MULTILINE,
+    print("\nPo files updated, commit files using the following commands:")
-    )
+    print("cd locale")
-    revision = revision[0] if revision else "Unknown"
+    print("git add -A")
-
+    print(
-    # Note that when 'has_complete_locale_checkout == True' we _could_ commit all languages at once,
+        "git commit -m \"Update po-files ({:s})\"".format(revision))
-    # however this can cause commits that are so large, they take a long time and risk hanging.
-    # So commit every language on it's own.
-
-    for svn_dir in svn_dirs_all:
-        # 'shlex.quote' causes path separator to be converted to forward slashes,
-        # causing the command to fail.
-        if IS_WIN32:
-            print("  " + subprocess.list2cmdline(["svn", "ci", svn_dir, "-m", "Update r" + revision]))
-        else:
-            print("  svn ci {:s} -m \"Update r{:s}\"".format(quote(svn_dir), revision))
-
-    if IS_WIN32:
-        print("  " + subprocess.list2cmdline(["svn", "ci", POT_FILE, "-m", "Update r" + revision]))
-    else:
-        print("  svn ci {:s} -m \"Update r{:s}\"".format(quote(POT_FILE), revision))
 
 
 if __name__ == "__main__":

tools_report/file_translation_progress.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
 # Copyright 2015 Anton Felix Lorenzen <anfelor@web.de>
-# <pep8 compliant>
 
 '''
 Module of Translation Tracker: report the number of complete strings in a file.

tools_report/report_translation_progress.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
 # Copyright 2015 Anton Felix Lorenzen <anfelor@web.de>
-# <pep8 compliant>
 
 '''
 Translation Tracker: report the number of complete translations.

tools_rst/rst_batch_edit.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
-# <pep8 compliant>
 
 # DEVELOPER NOTE:
 #

tools_rst/rst_check_image_names.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
-# <pep8 compliant>
 
 """
 This utility checks naming conventions (Blender specific).

tools_rst/rst_check_images.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
-# <pep8 compliant>
 
 """
 This utility checks image paths:

tools_rst/rst_check_spelling.py

@@ -49,39 +49,74 @@ def check_word(w):
     return dict_spelling.check(w)
 
 
+def regex_key_raise(x):
+    raise Exception("Unknown role! " + "".join(x.groups()))
+
+
+# A table of regex and their replacement functions.
+#
+# This is used to clean up text from `docutils.nodes.NodeVisitor.visit_Text` which doesn't remove inline markup.
+# Note that in some cases the order matters, especially with include/excluding roles.
+
+RE_TEXT_REPLACE_ROLES_INCLUDE = ("menuselection", "guilabel")
+RE_TEXT_REPLACE_ROLES_EXCLUDE = ("kbd", "ref", "doc", "abbr")
+
+RE_TEXT_REPLACE_TABLE = (
+    # Match HTML link: `Text <url>`__
+    # A URL may span multiple lines.
+    (
+        re.compile(r"(`)([^`<]+)(<[^`>]+>)(`)(__)", re.MULTILINE),
+        lambda x: x.groups()[1].strip(),
+    ),
+    # Roles with plain-text: :some_role:`Text <ref>`
+    (
+        re.compile(r"(:[A-Za-z_]+:)(`)([^`<]+)(<[^`>]+>)(`)", flags=re.MULTILINE),
+        lambda x: x.groups()[2].strip(),
+    ),
+    # Roles to always include.
+    (
+        re.compile(r"(:(" + ("|".join(RE_TEXT_REPLACE_ROLES_INCLUDE)) + r"):)(`)([^`]+)(`)", flags=re.MULTILINE),
+        lambda x: x.groups()[3].strip(),
+    ),
+    # Roles to always exclude.
+    (
+        re.compile(r"(:(" + ("|".join(RE_TEXT_REPLACE_ROLES_EXCLUDE)) + r"):)(`)([^`]+)(`)", flags=re.MULTILINE),
+        lambda _: " ",
+    ),
+    # Ensure all roles are handled.
+    (
+        re.compile(r"(:[A-Za-z_]+:)(`)([^`]+)(`)", flags=re.MULTILINE),
+        regex_key_raise,
+    ),
+    # Match substitution for removal: `|identifier|`
+    (
+        re.compile(r"\|[a-zA-Z0-9_]+\|"),
+        lambda _: " ",
+    ),
+)
+
+RE_WORDS = re.compile(
+    r"\b("
+    # Capital words, with optional '-' and "'".
+    r"[A-Z]+[\-'A-Z]*[A-Z]|"
+    # Lowercase words, with optional '-' and "'".
+    r"[A-Za-z][\-'a-z]*[a-z]+"
+    r")\b"
+)
+
+
 def check_spelling_body(text):
-    for w in text.split():
-        # skip directive args (e.g. figure target), could do differently?
-        if w.startswith(":") and w.endswith(":"):
-            continue
-        if w.startswith("<") and w.endswith(">"):
-            continue
 
-        w = w.strip("{}[](),.!?;\"'1234567890-_*")
+    # Wash text or inline RST.
+    for re_expr, re_replace_fn in RE_TEXT_REPLACE_TABLE:
+        text = re.sub(re_expr, re_replace_fn, text)
 
-        if w.startswith(":") and w.endswith(":"):
+    for re_match in RE_WORDS.finditer(text):
-            continue
+        w = re_match.group(0)
-        if w.startswith("<") and w.endswith(">"):
-            continue
 
-        # skip character and name entities
+        # Skip entirely uppercase words.
-        if w.startswith("\\") or w.startswith("|"):
+        # These are typically used for acronyms: XYZ, UDIM, API ... etc.
-            continue
+        if w.isupper():
-
-        # now we've gotten rid of typical roles, strip other chars
-        w = w.strip(":`()<>{}")
-
-        # skip python references
-        if w.startswith("bpy."):
-            continue
-
-        # skip document references and keyboard shortcuts
-        if w.startswith("doc:") or w.startswith("kbd:") or w.startswith("menuselection:") or w.startswith("ref:"):
-            continue
-
-        w_ = w
-        for w in w_.split("/"):
-            if not w:
             continue
 
         w_lower = w.lower()
@@ -192,6 +227,7 @@ directives.register_directive('highlight', directive_ignore_recursive)
 directives.register_directive('parsed-literal', directive_ignore_recursive)
 # Custom directives from extensions
 directives.register_directive('youtube', directive_ignore_recursive)
+directives.register_directive('peertube', directive_ignore_recursive)
 directives.register_directive('vimeo', directive_ignore_recursive)
 directives.register_directive('todolist', directive_ignore_recursive)
 
@@ -223,7 +259,7 @@ def role_ignore_recursive(
         name, rawtext, text, lineno, inliner,
         options={}, content=[],
 ):
-    return [RoleIgnore("", '', *(), **{})], []
+    return [RoleIgnoreRecursive("", '', *(), **{})], []
 
 
 roles.register_canonical_role('abbr', role_ignore)
@@ -306,13 +342,21 @@ def check_spelling(filename):
     doc.walkabout(visitor)
 
 
+RST_CONTEXT_FLAG_LITERAL = 1 << 0
+RST_CONTEXT_FLAG_LITERAL_BLOCK = 1 << 1
+RST_CONTEXT_FLAG_MATH = 1 << 2
+RST_CONTEXT_FLAG_COMMENT = 1 << 3
+
+
 class RstSpellingVisitor(docutils.nodes.NodeVisitor):
     __slots__ = (
         "document",
+        "skip_context",
     )
 
     def __init__(self, doc):
         self.document = doc
+        self.skip_context = 0
 
     # -----------------------------
     # Visitors (docutils callbacks)
@@ -400,8 +444,10 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
         # check_spelling_body(text)
 
     def visit_Text(self, node):
+        # Visiting text in a sipped context (literal for example).
+        if self.skip_context:
+            return
         text = node.astext()
-        # print(text)
         check_spelling_body(text)
 
     def depart_Text(self, node):
@@ -420,37 +466,48 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
         self.is_emphasis = False
 
     def visit_math(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_MATH
         raise docutils.nodes.SkipNode
 
     def depart_math(self, node):
-        pass
+        self.skip_context &= ~RST_CONTEXT_FLAG_MATH
 
     def visit_literal(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_LITERAL
         raise docutils.nodes.SkipNode
 
     def depart_literal(self, node):
-        pass
+        self.skip_context &= ~RST_CONTEXT_FLAG_LITERAL
 
     def visit_literal_block(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_LITERAL_BLOCK
         raise docutils.nodes.SkipNode
 
     def depart_literal_block(self, node):
+        self.skip_context &= ~RST_CONTEXT_FLAG_LITERAL_BLOCK
         pass
 
     def visit_code_block(self, node):
+        # No need to flag.
         raise docutils.nodes.SkipNode
 
     def depart_code_block(self, node):
         pass
 
     def visit_reference(self, node):
-        raise docutils.nodes.SkipNode
+        pass
 
     def depart_reference(self, node):
         pass
 
+    def visit_title_reference(self, node):
+        pass
+
+    def depart_title_reference(self, node):
+        pass
+
     def visit_download_reference(self, node):
-        raise docutils.nodes.SkipNode
+        pass
 
     def depart_download_reference(self, node):
         pass
@@ -466,10 +523,11 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
     #    # metadata['searchable_text'] = node.astext()
 
     def visit_comment(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_COMMENT
         raise docutils.nodes.SkipNode
 
     def depart_comment(self, node):
-        pass
+        self.skip_context &= ~RST_CONTEXT_FLAG_COMMENT
 
     def visit_raw(self, node):
         raise docutils.nodes.SkipNode

tools_rst/rst_check_spelling_config.py

@@ -180,7 +180,6 @@ dict_custom = {
     "redhat",
     "renderman",
     "sgi",
-    "tortoisesvn",
     "unix",
     "xinerama",
 

tools_rst/rst_check_syntax.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
-# <pep8 compliant>
 
 import os
 import sys

tools_rst/rst_fix_internal_links.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
-# <pep8 compliant>
 
 import os
 import io