documentation updates

Author: JorjMcKie

docs/irect.rst

@@ -93,15 +93,15 @@ IRect is a rectangular bounding box similar to :ref:`Rect`, except that all corn
 
       :rtype: bool
 
-   .. method:: morph(point, matrix)
+   .. method:: morph(pivot, matrix)
 
       *(New in version 1.17.0)*
 
       Return a new quad after applying a matrix to it using a pivotal point.
 
-      :arg point_like point: the pivotal point.
+      :arg point_like pivot: the pivotal point.
       :arg matrix_like matrix: the matrix.
-      :returns: a new quad. 
+      :returns: a new :ref:`Quad`. This a wrapper of the same-named quad method.
 
    .. method:: norm()
 

docs/page.rst

@@ -59,7 +59,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 :meth:`Page.drawSquiggle`         PDF only: draw a squiggly line
 :meth:`Page.drawZigzag`           PDF only: draw a zig-zagged line
 :meth:`Page.getFontList`          PDF only: get list of used fonts
-:meth:`Page.getImageBbox`         PDF only: get bbox of inserted image
+:meth:`Page.getImageBbox`         PDF only: get bbox of embedded image
 :meth:`Page.getImageList`         PDF only: get list of used images
 :meth:`Page.getLinks`             get all links
 :meth:`Page.getPixmap`            create a page image in raster format
@@ -269,7 +269,7 @@ In a nutshell, this is what you can do with PyMuPDF:
            >>> quads = page.searchFor("pymupdf", hit_max=100, quads=True)
            >>> page.addHighlightAnnot(quads)
 
-      :arg rect_like,quad_like,list,tuple quads: *(Changed in v1.14.20)* the rectangles or quads containing the to-be-marked text (locations). A list or tuple must consist of :data:`rect_like` or :data:`quad_like` items (or even a mixture of either). You should prefer using quads, because this will automatically support non-horizontal text and avoid rectangle-to-quad conversion effort. *(Changed in v1.16.14)* **Set this parameter to** *None* if you want to use the following arguments.
+      :arg rect_like,quad_like,list,tuple quads: *(Changed in v1.14.20)* the location(s) -- rectangle(s) or quad(s) -- to be marked. A list or tuple must consist of :data:`rect_like` or :data:`quad_like` items (or even a mixture of either). Every item must be finite, convex and not empty (as applicable). *(Changed in v1.16.14)* **Set this parameter to** *None* if you want to use the following arguments.
       :arg point_like start: *(New in v1.16.14)* start text marking at this point. Defaults to the top-left point of *clip*.
       :arg point_like stop: *(New in v1.16.14)* stop text marking at this point. Defaults to the bottom-right point of *clip*.
       :arg rect_like clip: *(New in v1.16.14)* only consider text lines intersecting this area. Defaults to the page rectangle.
@@ -797,16 +797,16 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       *Changed in version 1.17.0:*
 
-      * The method should deliver mostly correct results now.
+      * The method should deliver correct results now.
       * The page's ``/Contents`` are no longer modified by this method.
-      * Images occurring inside embedded PDF pages (i.e. in **Form XObjects**) never correctly worked and are now ignored. Use the items of :meth:`Document.getPageXObjectList` to determine the bboxes of embedded PDF pages.
+      * Images occurring inside embedded PDF pages (i.e. in **Form XObjects**) never correctly worked and are now ignored [#f5]_. Use the items of :meth:`Document.getPageXObjectList` to determine the bboxes of embedded PDF pages.
 
-      :arg list,str item: an item of the list :meth:`Page.getImageList` with *full=True* specified, or the **name** entry of such an item, which is item[-3] (or item[7] respectively). *Changed in v1.17.0:* only images are considered where item[1] == 0. This are images **directly** referenced by the page.
+      :arg list,str item: an item of the list :meth:`Page.getImageList` with *full=True* specified, or the **name** entry of such an item, which is item[-3] (or item[7] respectively). *Changed in v1.17.0:* only images are considered where item[1] == 0 [#f5]_. This are images **directly** referenced by the page.
 
       :rtype: :ref:`Rect`
       :returns: the boundary box of the image.
          *(Changed in version 1.16.7)* If the page in fact does not display this image, an infinite rectangle is returned now. In previous versions, an exception was raised.
-         *(Changed in version 1.17.0)* Only images referenced directly by the page are considered. This means that images occurring in embedded PDF pages are ignored and an infinite rectangle is returned.
+         *(Changed in version 1.17.0)* Only images referenced directly by the page are considered. This means that images occurring in embedded PDF pages are ignored and an exception is raised.
 
       .. note::
 
@@ -1192,3 +1192,5 @@ The page number "pno"` is a 0-based integer *-inf < pno < pageCount*.
 .. [#f3] Not all PDF readers display these fonts at all. Some others do, but use a wrong character spacing, etc.
 
 .. [#f4] You are generally free to choose any of the :ref:`mupdficons` you consider adequate.
+
+.. [#f5] This restriction will be removed with the next MuPDF version again: all inserted images shown on the page will be reported correctly, whether the page itself invokes them or some of its Form XObjects.

docs/quad.rst

@@ -14,6 +14,7 @@ Quads can **be obtained** as results of text search methods (:meth:`Page.searchF
 
    * Attribute :attr:`Quad.rect` obtains the envelopping rectangle. Vice versa, rectangles now have attributes :attr:`Rect.quad`, resp. :attr:`IRect.quad` to obtain their respective tetragon versions.
 
+
 ============================= =======================================================
 **Methods / Attributes**      **Short Description**
 ============================= =======================================================
@@ -56,17 +57,19 @@ Quads can **be obtained** as results of text search methods (:meth:`Page.searchF
 
       :arg matrix_like matrix: the matrix.
 
-   .. method:: morph(point, matrix)
+   .. method:: morph(pivot, matrix)
 
       *(New in version 1.17.0)* "Morph" the quad with a matrix-like using a point-like as pivotal point.
 
-      :arg point_like point: the point.
+      :arg point_like pivot: the point.
       :arg matrix_like matrix: the matrix.
-      :returns: a new quad. The effect is achieved by using the following code snippet::
+      :returns: a new quad. The effect is achieved by using the following code::
 
-         >>> T = fitz.Matrix(1, 1).preTranslate(point.x, point.y)
+         >>> T = fitz.Matrix(1, 1).preTranslate(pivot.x, pivot.y)
          >>> result = self * ~T * matrix * T
 
+      So the quad is translated such, that pivot becomes the origin (0, 0), then the matrix is applied to it, and finally a reverse translation is done.
+
       Typical uses include rotating the quad around a desired point.
 
    .. attribute:: rect
@@ -105,19 +108,19 @@ Quads can **be obtained** as results of text search methods (:meth:`Page.searchF
 
       *(New in version 1.16.1)*
 
-      True if all lines are contained in the quad which connect two points of the quad. 
+      True if every line connecting two points of the quad is inside the quad. We in addition also make sure here, that the quad is not "degenerate", i.e. not all corners are on the same line (which would still qualify as convexity in the mathematical sense).
 
       :type: bool
 
    .. attribute:: isEmpty
 
-      True if enclosed area is zero, which means that all four points are on the same line. If this is false, the quad may still be degenerate or not look like a rectangle at all (triangles, parallelograms, trapezoids, ...).
+      True if enclosed area is zero, which means that at least three of the four corners are on the same line. If this is false, the quad may still be degenerate or not look like a tetragon at all (triangles, parallelograms, trapezoids, ...).
 
       :type: bool
 
    .. attribute:: isRectangular
 
-      True if all angles are 90 degrees. This also implies that the area is **not empty** and **convex**.
+      True if all corner angles are 90 degrees. This implies that the quad is **convex and not empty**.
 
       :type: bool
 

docs/rect.rst

@@ -153,15 +153,15 @@ Hence some useful classification:
 
       :rtype: bool
 
-   .. method:: morph(point, matrix)
+   .. method:: morph(pivot, matrix)
 
       *(New in version 1.17.0)*
 
       Return a new quad after applying a matrix to it using a pivotal point.
 
-      :arg point_like point: the pivotal point.
+      :arg point_like pivot: the pivotal point.
       :arg matrix_like matrix: the matrix.
-      :returns: a new quad. 
+      :returns: a new :ref:`Quad`. This a wrapper for the same-named quad method.
 
    .. method:: norm()
 

docs/textwriter.rst

@@ -4,21 +4,24 @@
 TextWriter
 ================
 
-*(New in v1.16.18)* This class represents a MuPDF *text* object. It can be thought of as a store of text spans -- each span having its own position, font and font size. It is an elegant alternative for writing text to PDF pages, when compared with methods :meth:`Page.insertText` and friends:
+*(New in v1.16.18)* This class represents a MuPDF *text* object. It can be thought of as a collection of text spans. Each span has its own starting position and its font and font size. It is an elegant alternative for writing text to PDF pages, when compared with methods :meth:`Page.insertText` and friends:
 
-* **Improved text positioning:** The position of the last inserted character is returned, as well as the combined rectangle of text stored so far.
-* **Automatic fallback fonts:** If a character is not represented by the chosen font, alternative fonts are automatically checked. This significantly reduces the risk of seeing unprintable symbols in the output, so-called "TOFUs". PyMuPDF now also comes with a **"universal"** font, which supports **all Latin** characters (incuding Cyrillic and Greek), and **all CJK** characters (Chinese, Japanese, Korean).
-* **Reusability:** A TextWriter exists independent from any page. The same text can be written multiple times, to the same or other pages, same or different PDFs, choosing different colors or transparency.
-* **Transparency support:** Parameter *opacity* is supported. This offers a handy way to write watermark-style text.
+* **Improved text positioning:** Choose any point where insertion of a text span should start. The position of the last inserted character is returned, as well as the combined rectangle of all spans stored so far.
+* **Free font choice:** Each text span has its own font and fontsize. This lets you easily switch between normal, bold and italic versions of either the same or a different font when composing a larger text.
+* **Automatic fallback fonts:** If a character is not represented by the chosen font, alternative fonts are automatically checked. This significantly reduces the risk of seeing unprintable symbols in the output, so-called "TOFUs". PyMuPDF now also comes with the **universal font "Droid Sans Fallback Regular"**, which supports **all Latin** characters (incuding Cyrillic and Greek), and **all CJK** characters (Chinese, Japanese, Korean).
+* **Transparency support:** Parameter *opacity* is supported. This offers a handy way to create watermark-style text.
 * **Justified text:** Supported for any font -- not just simple fonts as in :meth:`Page.insertText`.
+* **Reusability:** A TextWriter exists independent from any page. The same text can be written multiple times, either to the same or to other pages, in the same or in different PDFs, choosing different colors or transparency.
 
 Using this object entails three steps:
 
-1. When **created**, a TextWriter object requires a fixed **page rectangle** in relation to which it calculates text positions. Pages with different dimensions cannot use this TextWriter object.
-2. Store text in the TextWriter using method either :meth:`TextWriter.append` or :meth:`TextWriter.fillTextbox`.
-3. Output the stored text on any PDF page with the same rectangle. This is the only point, where pages are referenced.
+1. When **created**, a TextWriter object requires a fixed **page rectangle** in relation to which it calculates text positions. Text can be written to a page if and only if the page's size equals that of the TextWriter.
+2. Store text in the TextWriter using methods :meth:`TextWriter.append` or :meth:`TextWriter.fillTextbox` any number of times.
+3. Output the stored text on some PDF page (having the same rectangle).
 
-TextWriters do not support text rotation. But the new method :meth:`Page.writeText` is able to combine one or more TextWriters and jointly write them to **any rectangle** and with **any rotation angle** -- much like :meth:`Page.showPDFpage`.
+Starting with version 1.17.0, TextWriters **do support** text rotation via the *morph* parameter of :meth:`TextWriter.writeText`.
+
+There also exists :meth:`Page.writeText` which is able to combine one or more TextWriters and jointly write them to a given rectangle and with a given any rotation angle -- much like :meth:`Page.showPDFpage`.
 
 **Class API**
 
@@ -41,12 +44,11 @@ TextWriters do not support text rotation. But the new method :meth:`Page.writeTe
       :arg float fontsize: the fontsize, a positive number, default 11.
       :arg str language: the language to use, e.g. "en" for English. Meaningful values should be compliant with the ISO 639 standards 1, 2, 3 or 5. Reserved for future use: currently has no effect as far as we know.
 
-      :returns: :attr:`textRect` and :attr:`lastPoint` after this text has been added.
-
+      :returns: :attr:`textRect` and :attr:`lastPoint`.
 
    .. method:: fillTextbox(rect, text, font="helv", fontsize=11, align=0, warn=True)
 
-      Fill a given rectangle with text. This is a convenience method to use instead of :meth:`append` (which is internally invoked).
+      Fill a given rectangle with text. This is a convenience method to use instead of :meth:`append`.
 
       :arg rect_like rect: the area to fill. No part of the text will appear outside of this.
       :arg str,sequ text: the text. Can be specified as a (UTF-8) string or a list / tuple of strings. A string will first be converted to a list using *splitlines()*. Every list item will begin on a new line (forced line breaks).
@@ -55,23 +57,27 @@ TextWriters do not support text rotation. But the new method :meth:`Page.writeTe
       :arg int align: text alignment. Use one of TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT or TEXT_ALIGN_JUSTIFY.
       :arg bool warn: print a warning if the area is too small, or raise an exception.
 
-   .. method:: writeText(page, opacity=None, color=None, overlay=True)
+   .. note:: Use these methods as often as is required -- there is no technical limit, except memory constraints of your system. You can also mix appends and text boxes and have multiple of both. Text positioning is controlled by the insertion point. There is no need to adhere to any reading order.
+
+
+   .. method:: writeText(page, opacity=None, color=None, morph=None, overlay=True)
 
-      Write the accumulated text to the page.
+      Write the TextWriter text to a page.
 
       :arg page: write to this :ref:`Page`.
-      :arg float opacity: overwrite the value of the TextWriter for this output.
-      :arg sequ color: overwrite the value of the TextWriter for this output.
+      :arg float opacity: override the value of the TextWriter for this output.
+      :arg sequ color: override the value of the TextWriter for this output.
+      :arg sequ morph: modify the text appearance by applying a matrix to it. If provided, this must be a sequence *(pivot, matrix)* with a point-like *pivot* and a matrix-like *matrix*. A typical example is rotating the text around *pivot*.
       :arg bool overlay: put in foreground (default) or background.
 
 
    .. attribute:: textRect
 
-      The area currently occupied. This value changes when more text is added.
+      The :ref:`Rect` currently occupied. This value changes when more text is added.
 
    .. attribute:: lastPoint
 
-      The "cursor position" after the last written character.
+      The "cursor position" -- a :ref:`Point` -- after the last written character (its bottom-right).
 
    .. attribute:: opacity
 
@@ -83,11 +89,15 @@ TextWriters do not support text rotation. But the new method :meth:`Page.writeTe
 
    .. attribute:: rect
 
-      The rectangle for which this TextWriter was created. Must not be modified.
+      The page rectangle for which this TextWriter was created. Must not be modified.
+
+
+To see some demo scripts dealing with TextWriter, have a look at `this <https://github.com/pymupdf/PyMuPDF-Utilities/tree/master/textwriter>`_ rpository.
+
 
 .. note::
 
   1. Opacity and color apply to **all the text** in this object. 
-  2. If you need different colors / transpareny, you must create a separate TextWriter. Whenever you determine the color should change, simply append the text to the respective TextWriter using the previously returned :attr:`lastPoint` as position for the new text.
-  3. Appending items can occur in arbitrary order: only the position parameter controls where text appears.
+  2. If you need different colors / transpareny, you must create a separate TextWriter. Whenever you determine the color should change, simply append the text to the respective TextWriter using the previously returned :attr:`lastPoint` as position for the new text span.
+  3. Appending items or text boxes can occur in arbitrary order: only the position parameter controls where text appears.
   4. Font and fontsize can freely vary within the same TextWriter. This can be used to let text with different properties appear on the same displayed line: just specify *pos* accordingly, and e.g. set it to :attr:`lastPoint` of the previously added item.

installation/ubuntu/ubuntu_pymupdf.sh

@@ -1,7 +1,7 @@
-wget https://mupdf.com/downloads/archive/mupdf-1.16.1-source.tar.gz
-tar -zxvf mupdf-1.16.1-source.tar.gz
+wget https://mupdf.com/downloads/archive/mupdf-1.17.0-source.tar.gz
+tar -zxvf mupdf-1.17.0-source.tar.gz
 
-cd mupdf-1.16.1-source
+cd mupdf-1.17.0-source
 
 export CFLAGS="-fPIC"
 # install some prerequirement