Clarifications

Several clarifications.

Author: JorjMcKie

docs/page.rst

@@ -300,30 +300,17 @@ In a nutshell, this is what you can do with PyMuPDF:
 
    .. method:: add_redact_annot(quad, text=None, fontname=None, fontsize=11, align=TEXT_ALIGN_LEFT, fill=(1, 1, 1), text_color=(0, 0, 0), cross_out=True)
 
-      **PDF only**: Add a redaction annotation. A redaction annotation identifies content to be removed from the document. Adding such an annotation is the first of two steps. It makes visible what will be removed in the subsequent step, :meth:`Page.apply_redactions`.
+      **PDF only**: Add a redaction annotation. A redaction annotation identifies an area whose content should be removed from the document. Adding such an annotation is the first of two steps. It makes visible what will be removed in the subsequent step, :meth:`Page.apply_redactions`.
 
       :arg quad_like,rect_like quad: specifies the (rectangular) area to be removed which is always equal to the annotation rectangle. This may be a :data:`rect_like` or :data:`quad_like` object. If a quad is specified, then the enveloping rectangle is taken.
 
       :arg str text: text to be placed in the rectangle after applying the redaction (and thus removing old content). (New in v1.16.12)
 
-      :arg str fontname: the font to use when *text* is given, otherwise ignored. The same rules apply as for :meth:`Page.insert_textbox` -- which is the method :meth:`Page.apply_redactions` internally invokes. The replacement text will be **vertically centered**, if this is one of the CJK or :ref:`Base-14-Fonts`. (New in v1.16.12)
-
-         .. note::
-
-            * For an **existing** font of the page, use its reference name as *fontname* (this is *item[4]* of its entry in :meth:`Page.get_fonts`).
-            * For a **new, non-builtin** font, proceed as follows::
-
-               page.insert_text(point,  # anywhere, but outside all redaction rectangles
-                   "something",  # some non-empty string
-                   fontname="newname",  # new, unused reference name
-                   fontfile="...",  # desired font file
-                   render_mode=3,  # makes the text invisible
-               )
-               page.add_redact_annot(..., fontname="newname")
+      :arg str fontname: the font to use when ``text`` is given, otherwise ignored. Only CJK and the :ref:`Base-14-Fonts` are supported. Apart from this, the same rules apply as for :meth:`Page.insert_textbox` -- which is what the method :meth:`Page.apply_redactions` internally invokes. 
 
       :arg float fontsize: the :data:`fontsize` to use for the replacing text. If the text is too large to fit, several insertion attempts will be made, gradually reducing the :data:`fontsize` to no less than 4. If then the text will still not fit, no text insertion will take place at all. (New in v1.16.12)
 
-      :arg int align: the horizontal alignment for the replacing text. See :meth:`insert_textbox` for available values. The vertical alignment is (approximately) centered if a PDF built-in font is used (CJK or :ref:`Base-14-Fonts`). (New in v1.16.12)
+      :arg int align: the horizontal alignment for the replacing text. See :meth:`insert_textbox` for available values. The vertical alignment is (approximately) centered.
 
       :arg sequence fill: the fill color of the rectangle **after applying** the redaction. The default is *white = (1, 1, 1)*, which is also taken if ``None`` is specified. To suppress a fill color altogether, specify ``False``. In this cases the rectangle remains transparent. (New in v1.16.12)
 

docs/rect.rst

@@ -104,11 +104,11 @@ The following remarks are also valid for :ref:`IRect` objects:
 
       If "rect" is specified, the constructor creates a **new copy** of it.
 
-      Without parameters, the empty rectangle *Rect(0.0, 0.0, 0.0, 0.0)* is created.
+      Without parameters, the empty rectangle ``Rect(0.0, 0.0, 0.0, 0.0)`` is created.
 
    .. method:: round()
 
-      Creates the smallest containing :ref:`IRect`. This is **not** the same as simply rounding the rectangle's edges: The top left corner is rounded upwards and to the left while the bottom right corner is rounded downwards and to the right.
+      Creates the smallest containing :ref:`IRect`. This is **not the same** as simply rounding the rectangle's edges: The top left corner is rounded upwards and to the left while the bottom right corner is rounded downwards and to the right.
 
       >>> pymupdf.Rect(0.5, -0.01, 123.88, 455.123456).round()
       IRect(0, -1, 124, 456)
@@ -131,7 +131,7 @@ The following remarks are also valid for :ref:`IRect` objects:
       Transforms the rectangle with a matrix and **replaces the original**. If the rectangle is empty or infinite, this is a no-operation.
 
       :arg m: The matrix for the transformation.
-      :type m: :ref:`Matrix`
+      :type m: :data:`matrix_like`
 
       :rtype: *Rect*
       :returns: the smallest rectangle that contains the transformed original.
@@ -141,21 +141,21 @@ The following remarks are also valid for :ref:`IRect` objects:
       The intersection (common rectangular area, largest rectangle contained in both) of the current rectangle and *r* is calculated and **replaces the current** rectangle. If either rectangle is empty, the result is also empty. If *r* is infinite, this is a no-operation. If the rectangles are (mathematically) disjoint sets, then the result is invalid. If the result is valid but empty, then the rectangles touch each other in a corner or (part of) a side.
 
       :arg r: Second rectangle
-      :type r: :ref:`Rect`
+      :type r: :data:`rect_like`
 
    .. method:: include_rect(r)
 
-      The smallest rectangle containing the current one and *r* is calculated and **replaces the current** one. If either rectangle is infinite, the result is also infinite. If one is empty, the other one will be taken as the result.
+      The smallest rectangle containing the current one and ``r`` is calculated and **replaces the current** one. If either rectangle is infinite, the result is also infinite. If ``r`` is empty, the current rectangle remains unchanged. Else if the current rectangle is empty, it is replaced by ``r``.
 
       :arg r: Second rectangle
-      :type r: :ref:`Rect`
+      :type r: :data:`rect_like`
 
    .. method:: include_point(p)
 
-      The smallest rectangle containing the current one and point *p* is calculated and **replaces the current** one. **The infinite rectangle remains unchanged.** To create a rectangle containing a series of points, start with (the empty) *pymupdf.Rect(p1, p1)* and successively include the remaining points.
+      The smallest rectangle containing the current one and :data:`point_like` ``p`` is calculated and **replaces the current** one. **The infinite rectangle remains unchanged.** To create the rectangle that wraps a sequence of points, start with :meth:`EMPTY_RECT` and successively include the members of the sequence.
 
       :arg p: Point to include.
-      :type p: :ref:`Point`
+      :type p: :data:`point_like`
 
 
    .. method:: get_area([unit])