[Backport release_3.40] Update label engine options and labels export option

docs/user_manual/map_views/map_view.rst

@@ -1291,24 +1291,15 @@ In the dialog that opens:
        https://north-road.com/2019/09/03/qgis-3-10-loves-geospatialpdf/.
 
    * :guilabel:`Rasterize map`
-   * |checkbox| :guilabel:`Simplify geometries to reduce output file
-     size`:
+   * |checkbox| :guilabel:`Simplify geometries to reduce output file size`:
      Geometries will be simplified while exporting the map by removing
      vertices that are not discernibly different at the export
      resolution (e.g. if the export resolution is ``300 dpi``, vertices
      that are less than ``1/600 inch`` apart will be removed).
      This can reduce the size and complexity of the export file (very
      large files can fail to load in other applications).
-   * Set the :guilabel:`Text export`: controls whether text labels are
-     exported as proper text objects (:guilabel:`Always export texts
-     as text objects`) or as paths only (:guilabel:`Always export texts
-     as paths`).
-     If they are exported as text objects then they can be edited in
-     external applications (e.g. Inkscape) as normal text.
-     BUT the side effect is that the rendering quality is decreased,
-     AND there are issues with rendering when certain text settings
-     like buffers are in place.
-     That’s why exporting as paths is recommended.
+   * Set the :guilabel:`Text export`: controls whether text labels are always
+     or preferably exported as :ref:`text or outline objects <render_labels_text>`.
 
 #. Click :guilabel:`Save` to select file location, name and format.
 

docs/user_manual/print_composer/create_output.rst

@@ -175,14 +175,8 @@ To export a layout as SVG:
      any redundant vertices which are not discernably different at the export
      resolution (e.g. if the export resolution is ``300 dpi``, vertices that are
      less than ``1/600 inch`` apart will be removed).
-   * Set the :guilabel:`Text export`: controls whether text labels are exported
-     as proper text objects (:guilabel:`Always export texts as text
-     objects`) or as paths only (:guilabel:`Always export texts as paths`).
-     If they are exported as text objects, they can be edited in external
-     applications (e.g. Inkscape) as normal text. BUT the side effect is that
-     the rendering quality is reduced, AND there are issues with rendering when
-     certain text settings like buffers are in place. That’s why exporting as
-     paths is recommended.
+   * Set the :guilabel:`Text export`: controls whether text labels are always
+     or preferably exported as :ref:`text or outline objects <render_labels_text>`.
    * Apply |checkbox| :guilabel:`Crop to content` :ref:`option <crop_to_content>`
    * |unchecked| :guilabel:`Disable tiled raster layer exports`: When exporting
      files, QGIS uses a built-in raster layer tiled rendering that saves memory.
@@ -237,14 +231,8 @@ To export a layout as PDF:
      is on the first page.
    * |checkbox| :guilabel:`Export RDF metadata` of the document such as the
      title, author, date, description...
-   * Set the :guilabel:`Text export`: controls whether text labels are exported
-     as proper text objects (:guilabel:`Always export texts as text
-     objects`) or as paths only (:guilabel:`Always export texts as paths`).
-     If they are exported as text objects then they can be edited in external
-     applications (e.g. Inkscape) as normal text. BUT the side effect is that
-     the rendering quality is decreased, AND there are issues with rendering when
-     certain text settings like buffers are in place. That’s why exporting as
-     paths is recommended.
+   * Set the :guilabel:`Text export`: controls whether text labels are always
+     or preferably exported as :ref:`text or outline objects <render_labels_text>`.
    * Control the PDF :guilabel:`Image compression` using:
 
      * :guilabel:`Lossy (JPEG)`, which is the default compression mode

docs/user_manual/working_with_vector/vector_properties.rst

@@ -1447,15 +1447,27 @@ options:
   polygon features the number of possible labels placement based on their size.
   The longer or wider a feature is, the more candidates it has, and its labels
   can be better placed with less risk of collision.
+
+.. _render_labels_text:
+
 * :guilabel:`Text rendering`: sets the default value for label rendering
   widgets when :ref:`exporting a map canvas <exportingmapcanvas>` or
   :ref:`a layout <create-output>` to PDF or SVG.
   If :guilabel:`Always render labels as text` is selected then labels can be
   edited in external applications (e.g. Inkscape) as normal text. BUT the side
   effect is that the rendering quality is decreased, and there are issues with
-  rendering when certain text settings like buffers are in place. That's why
-  :guilabel:`Always render labels as paths (recommended)` which exports labels
-  as outlines, is recommended.
+  rendering when certain text settings like buffers are in place.
+  That's why :guilabel:`Always render labels as paths (recommended)`
+  which exports labels as outlines but guarantees complete compatibility
+  with the full range of formatting options available, is recommended.
+  With :guilabel:`Prefer rendering labels as text` option, labels are rendered as text objects,
+  unless doing so results in rendering artifacts or poor quality rendering (depending on text format settings).
+
+  .. note:: When rendering labels as text to a vector based device (e.g. PDF or SVG),
+    care must be taken to ensure that the required fonts are available to users
+    when opening the created files, or default fallback fonts will be used to display the output instead.
+    (Although PDF exports MAY automatically embed some fonts when possible, depending on the user’s platform).
+
 * |checkbox| :guilabel:`Allow truncated labels on edges of map`: controls
   whether labels which fall partially outside of the map extent should be
   rendered. If checked, these labels will be shown (when there's no way to
@@ -1473,6 +1485,8 @@ options:
   Like the label says, it's useful only for debugging and testing the effect different
   labeling settings have. This could be handy for a better manual placement with
   tools from the :ref:`label toolbar <label_toolbar>`.
+* |unchecked| :guilabel:`Show label metrics (for debugging)`:
+  displays the text bounds of the label in red and baselines in blue
 * :guilabel:`Project labeling version`: QGIS supports two different versions of
   label automatic placement: