update mupdf to 1.25.x

Author: kjk

mupdf/docs/src/README.md

@@ -34,6 +34,13 @@ https://github.com/pradyunsg/furo/blob/main/LICENSE
 This then creates the HTML documentation within the folder "build" in the root of "docs".
 
 
+- Alternatively you can also use [Sphinx Autobuild](https://pypi.org/project/sphinx-autobuild/) and do:
+
+`sphinx-autobuild src _build/html`
+
+This will ensure that the documentation runs in a localhost and will also hot-reload changes.
+
+
 ## Building PDF documentation
 
 

mupdf/docs/src/conf.py

@@ -19,7 +19,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 # extensions = ["sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.ifconfig"]
-extensions = []
+extensions = ["sphinx_copybutton"]
 if hasattr(os, "uname") and os.uname()[0] in ("OpenBSD", "Darwin"):
     # rst2pdf is not available on OpenBSD or MacOS.
     pass

mupdf/docs/src/coordinate-system.rst

@@ -0,0 +1,91 @@
+.. Copyright (C) 2001-2024 Artifex Software, Inc.
+.. All Rights Reserved.
+
+.. include:: header.rst
+
+.. meta::
+   :description: MuPDF documentation
+   :keywords: MuPDF, pdf, epub
+
+
+.. _How_To_Guide_Coordinate_System:
+
+The **MuPDF** Coordinate System
+=================================
+
+Origin Point, Point Size and Y-Axis
+----------------------------------------------
+
+In **PDF**, the origin (for example: `(0, 0)`) of a page is located at its **bottom-left point**. In **MuPDF**, the origin of a page is located at its **top-left point**.
+
+
+
+.. image:: images/img-coordinate-space.png
+
+
+.. note::
+
+    The exact x,y coordinate space for origin may not be `0,0` and is defined by "CropBox" - thus "bottom left" is derived from what is defined there.
+
+.. important::
+
+    The rotation of the page affects the PDF coordinate space orientation.
+
+
+Point Size
+~~~~~~~~~~~~~
+
+
+Coordinates are float numbers and measured in **points**, where:
+
+- **The default is one point equals 1/72 inches**.
+- **Is defined by the "UserUnit" property**.
+
+
+Positioning objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When working with positioning objects, we should appreciate this coordinate system.
+
+For example:
+
+.. code-block:: javascript
+
+    let rectangle = [0,0,200,200]
+
+Results in:
+
+.. image:: images/200x200-rect.png
+
+
+
+.. _How_To_Guide_Coordinate_System_PDF:
+
+Coordinate space and `PDFObject`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In exception to using the **MuPDF** coordinate space, if we are dealing *directly* with `PDFObject` streams then we are using the **PDF** coordinate space.
+
+Therefore if we doing something low-level like adding a content stream to a `PDFObject`, for example:
+
+.. code-block:: javascript
+
+    var extra_contents = document.addStream("q 200 0 0 200 10 10 cm /Image1 Do Q", null)
+
+Then in this case we are working in the **PDF** coordinate space with the origin Y-axis at the bottom left.
+
+.. note::
+
+    To explain the syntax behind `"q 200 0 0 200 10 10 cm /Image1 Do Q"` this is **Adobe PDF** syntax for referencing, sizing and positioning an image and can be explained as follows:
+
+    .. code-block:: postscript
+
+        q                               % Save graphics state
+            200 0 0 200 10 10 cm        % Translate
+            /Image1 Do                  % Paintimage
+        Q                               % Restore graphics state
+
+    For more see `page 337 of the Adobe PDF Reference Guide <https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.7old.pdf>`_.
+
+
+.. include:: footer.rst

mupdf/docs/src/images/200x200-rect.png

@@ -25,14 +25,14 @@ Welcome to :title:`MuPDF`
 ----
 
 
-
 .. toctree::
    :caption: User Guide
    :maxdepth: 2
 
    quick-start-guide.rst
    using-mupdf.rst
    mupdf-wasm.rst
+   coordinate-system.rst
 
 
 .. toctree::

mupdf/docs/src/images/callout-annot.png

@@ -108,7 +108,7 @@ The `clean` command pretty prints and rewrites the syntax of a :title:`PDF` file
 ----
 
 `[pages]`
-   Comma separated list of page numbers and ranges. If no pages are supplied then all document pages will be considered for the output file.
+   Comma separated list of page numbers and ranges (for example: 1,5,10-15,20-N), where the character N denotes the last page. If no pages are specified, then all pages will be included.
 
 
 .. include:: footer.rst