Documentation: More syntax updates

jamie-lemon · JorjMcKie · commit e6134118d7bc · 2024-11-17T03:58:21.000-04:00
diff --git a/docs/annot.rst b/docs/annot.rst
@@ -537,7 +537,7 @@ There is a parent-child relationship between an annotation and its page. If the
 
       * *style* -- 1-byte border style: **"S"** (Solid) = solid line surrounding the annotation, **"D"** (Dashed) = dashed line surrounding the annotation, the dash pattern is specified by the *dashes* entry, **"B"** (Beveled) = a simulated embossed rectangle that appears to be raised above the surface of the page, **"I"** (Inset) = a simulated engraved rectangle that appears to be recessed below the surface of the page, **"U"** (Underline) = a single line along the bottom of the annotation rectangle.
 
-      * *clouds* -- an integer indicating a "cloudy" border, where `n` is an integer `-1 <= n <= 2`. A value `n = 0` indicates a straight line (no clouds), 1 means small and 2 means large semi-circles, mimicking the cloudy appearance. If -1, then no specification is present.
+      * *clouds* -- an integer indicating a "cloudy" border, where ``n`` is an integer `-1 <= n <= 2`. A value `n = 0` indicates a straight line (no clouds), 1 means small and 2 means large semi-circles, mimicking the cloudy appearance. If -1, then no specification is present.
 
       :rtype: dict
 
diff --git a/docs/app3.rst b/docs/app3.rst
@@ -331,7 +331,7 @@ MuPDF generates text errors and warnings.
     `mupdf_display_warnings()`.
   
   *
-    These messages are prefixed with `MuPDF error: ` and `MuPDF warning: `
+    These messages are prefixed with `MuPDF error:` and `MuPDF warning:`
     respectively.
   
 Some MuPDF errors may lead to Python exceptions.
diff --git a/docs/archive-class.rst b/docs/archive-class.rst
@@ -42,7 +42,7 @@ In PyMuPDF, archives are currently only used by :ref:`Story` objects to specify
 
       * a Python binary object (`bytes`, `bytearray`, `io.BytesIO`): this will add a single-member sub-archive. In this case, the `path` parameter is **mandatory** and should be the member name under which this item can be found / retrieved.
 
-      * a tuple `(data, name)`: This will add a single-member sub-archive with the member name `name`. `data` may be a Python binary object or a local file name (in which case its binary file content is used). Use this format if you need to specify `path`.
+      * a tuple `(data, name)`: This will add a single-member sub-archive with the member name ``name``. ``data`` may be a Python binary object or a local file name (in which case its binary file content is used). Use this format if you need to specify `path`.
 
       * a Python sequence: This is a convenience format to specify any combination of the above.
 
diff --git a/docs/document.rst b/docs/document.rst
@@ -1088,7 +1088,7 @@ For details on **embedded files** refer to Appendix 3.
 
     PDF only: Return the :data:`xref` of the outline item. This is mainly used for internal purposes.
 
-    arg int idx: index of the item in list :meth:`Document.get_toc`.
+    :arg int idx: index of the item in list :meth:`Document.get_toc`.
 
     :returns: :data:`xref`.
 
diff --git a/docs/functions.rst b/docs/functions.rst
@@ -618,7 +618,7 @@ Yet others are handy, general-purpose utilities.
 
       1. Information above tagged with "(1)" has the same meaning and value as explained in :ref:`TextPage`.
 
-         - Please note that the font `flags` value will never contain a *superscript* flag bit: the detection of superscripts is done within MuPDF :ref:`TextPage` code -- it is not a property of any font.
+         - Please note that the font ``flags`` value will never contain a *superscript* flag bit: the detection of superscripts is done within MuPDF :ref:`TextPage` code -- it is not a property of any font.
          - Also note, that the text *color* is encoded as the usual tuple of floats 0 <= f <= 1 -- not in sRGB format. Depending on `span["type"]`, interpret this as fill color or stroke color.
 
       2. There are 3 text span types:
diff --git a/docs/link.rst b/docs/link.rst
@@ -104,9 +104,9 @@ There is a parent-child relationship between a link and its page. If the page ob
       
       *
         `is_external` is true: `uri` points to some target outside the current
-        PDF, which may be an internet resource (`uri` starts with "http://" or
+        PDF, which may be an internet resource (`uri` starts with ``http://`` or
         similar), another file (`uri` starts with "file:" or "file://") or some
-        other service like an e-mail address (`uri` starts with "mailto:").
+        other service like an e-mail address (`uri` starts with ``mailto:``).
 
       *
         `is_external` is false: `uri` will be `None` or point to an
diff --git a/docs/module.rst b/docs/module.rst
@@ -479,7 +479,7 @@ Command::
 * **noligatures:** (bool) corresponds to **not** :data:`TEXT_PRESERVE_LIGATURES`. If specified, ligatures (present in advanced fonts: glyphs combining multiple characters like "fi") are split up into their components (i.e. "f", "i"). Default is passing them through.
 * **convert-white:** corresponds to **not** :data:`TEXT_PRESERVE_WHITESPACE`. If specified, all white space characters (like tabs) are replaced with one or more spaces. Default is passing them through.
 * **extra-spaces:**  (bool) corresponds to **not** :data:`TEXT_INHIBIT_SPACES`. If specified, large gaps between adjacent characters will be filled with one or more spaces. Default is off.
-* **noformfeed:**  (bool) instead of `hex(12)` (formfeed), write linebreaks `\n` at end of output pages.
+* **noformfeed:**  (bool) instead of `hex(12)` (formfeed), write linebreaks ``\n`` at end of output pages.
 * **skip-empty:**  (bool) skip pages with no text.
 * **grid:** lines with a vertical coordinate difference of no more than this value (in points) will be merged into the same output line. Only relevant for "layout" mode. **Use with care:** 3 or the default 2 should be adequate in most cases. If **too large**, lines that are *intended* to be different in the original may be merged and will result in garbled and / or incomplete output. If **too low**, artifact separate output lines may be generated for some spans in the input line, just because they are coded in a different font with slightly deviating properties.
 * **fontsize:** include text with :data:`fontsize` larger than this value only (default 3). Only relevant for "layout" option.
diff --git a/docs/outline.rst b/docs/outline.rst
@@ -67,13 +67,13 @@ Outline
       be evaluated in conjunction with property `is_external`:
       
       *
-        `is_external` is true: `uri` points to some target outside the current
-        PDF, which may be an internet resource (`uri` starts with "http://" or
-        similar), another file (`uri` starts with "file:" or "file://") or some
-        other service like an e-mail address (`uri` starts with "mailto:").
+        `is_external` is true: ``uri`` points to some target outside the current
+        PDF, which may be an internet resource (``uri`` starts with ``http://`` or
+        similar), another file (``uri`` starts with ``file:`` or ``file://``) or some
+        other service like an e-mail address (``uri`` starts with ``mailto:``).
 
       *
-        `is_external` is false: `uri` will be `None` or point to an
+        `is_external` is false: ``uri`` will be `None` or point to an
         internal location. In case of PDF documents, this should either be
         *#nnnn* to indicate a 1-based (!) page number *nnnn*, or a named
         location. The format varies for other document types, for example
diff --git a/docs/page.rst b/docs/page.rst
@@ -784,7 +784,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       * Parameter ``text`` may be a string as in the other methods. But it will be **interpreted as HTML source** and may therefore also contain HTML language elements -- including styling. The `css` parameter may be used to pass in additional styling instructions.
 
-      * Automatic line breaks are generated at word boundaries. The "soft hyphen" character `"&#173;"` (or `&shy;`) can be used to cause hyphenation and thus may also cause line breaks. **Forced** line breaks however are only achievable via the HTML tag `<br>` - `"\\n"` is ignored and will be treated like a space.
+      * Automatic line breaks are generated at word boundaries. The "soft hyphen" character `"&#173;"` (or `&shy;`) can be used to cause hyphenation and thus may also cause line breaks. **Forced** line breaks however are only achievable via the HTML tag ``<br>`` - ``\n`` is ignored and will be treated like a space.
 
       * With this method the following can be achieved:
 
@@ -1500,7 +1500,7 @@ In a nutshell, this is what you can do with PyMuPDF:
          
             **OCRed text is only available** to PyMuPDF's text extractions and searches if their `textpage` parameter specifies the output of this method.
 
-            `This <https://github.com/pymupdf/PyMuPDF-Utilities/blob/master/jupyter-notebooks/partial-ocr.ipynb>`_ Jupyter notebook walks through an example for using OCR textpages.
+            `This Jupyter notebook <https://github.com/pymupdf/PyMuPDF-Utilities/blob/master/jupyter-notebooks/partial-ocr.ipynb>`_ walks through an example for using OCR textpages.
 
       |history_begin|
 
@@ -1557,7 +1557,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       .. note::, quads and rectangles are more reliably recognized as such. (Starting with v1.19.2)
 
-      Using class :ref:`Shape`, you should be able to recreate the original drawings on a separate (PDF) page with high fidelity under normal, not too sophisticated circumstances. Please see the following comments on restrictions. A coding draft can be found in section "Extractings Drawings" of chapter :ref:`FAQ`.
+      Using class :ref:`Shape`, you should be able to recreate the original drawings on a separate (PDF) page with high fidelity under normal, not too sophisticated circumstances. Please see the following comments on restrictions. A coding draft can be found in :ref:`How to Extract Drawings <RecipesDrawingAndGraphics_Extract_Drawings>`.
 
       Specifying `extended=True` significantly alters the output. Most importantly, new dictionary types are present: "clip" and "group". All paths will now be organized in a hierarchic structure which is encoded by the new integer key "level", the hierarchy level. Each group or clip establishes a new hierarchy, which applies to all subsequent paths having a *larger* level value. (New in v1.22.0)
 
diff --git a/docs/recipes-common-issues-and-their-solutions.rst b/docs/recipes-common-issues-and-their-solutions.rst
@@ -165,7 +165,7 @@ Unfortunately there is not much you can do in most of these cases.
   * :meth:`Annot.set_flags` (annotation behaviour)
   * :meth:`Annot.set_info` (meta information, except changes to *content*)
   * :meth:`Annot.set_popup` (create popup or change its rect)
-  * :meth:`Annot.set_optional_content` (add / remove reference to optional content information)
+  * :meth:`Annot.set_oc` (add / remove reference to optional content information)
   * :meth:`Annot.set_open`
   * :meth:`Annot.update_file` (file attachment changes)
 
diff --git a/docs/shape.rst b/docs/shape.rst
@@ -133,7 +133,7 @@ Several draw methods can be executed in a row and each one of them will contribu
 
       Draw a standard cubic Bézier curve from *p1* to *p4*, using *p2* and *p3* as control points.
 
-      All arguments are :data:`point_like` \s.
+      All arguments are :data:`point_like` objects.
 
       :rtype: :ref:`Point`
       :returns: the end point, *p4*.
@@ -300,7 +300,7 @@ Several draw methods can be executed in a row and each one of them will contribu
          .. image:: images/img-inserttext.*
             :scale: 33
 
-      :arg str/sequence text: the text to be inserted. May be specified as either a string type or as a sequence type. For sequences, or strings containing line breaks *\n*, several lines will be inserted. No care will be taken if lines are too wide, but the number of inserted lines will be limited by "vertical" space on the page (in the sense of reading direction as established by the *rotate* parameter). Any rest of *text* is discarded -- the return code however contains the number of inserted lines.
+      :arg str/sequence text: the text to be inserted. May be specified as either a string type or as a sequence type. For sequences, or strings containing line breaks ``\n``, several lines will be inserted. No care will be taken if lines are too wide, but the number of inserted lines will be limited by "vertical" space on the page (in the sense of reading direction as established by the *rotate* parameter). Any rest of *text* is discarded -- the return code however contains the number of inserted lines.
 
       :arg float lineheight: a factor to override the line height calculated from font properties. If not `None`, a line height of `fontsize * lineheight` will be used.
       :arg float stroke_opacity: *(new in v1.18.1)* set transparency for stroke colors (the **border line** of a character). Only  `0 <= value <= 1` will be considered. Default is 1 (intransparent).
@@ -555,7 +555,7 @@ Common Parameters
 
 **dashes** (*str*)
 
-  Causes lines to be drawn dashed. The general format is `"[n m] p"` of (up to) 3 floats denoting pixel lengths. `n` is the dash length, `m` (optional) is the subsequent gap length, and `p` (the "phase" - **required**, even if 0!) specifies how many pixels should be skipped before the dashing starts. If `m` is omitted, it defaults to `n`.
+  Causes lines to be drawn dashed. The general format is `"[n m] p"` of (up to) 3 floats denoting pixel lengths. ``n`` is the dash length, ``m`` (optional) is the subsequent gap length, and ``p`` (the "phase" - **required**, even if 0!) specifies how many pixels should be skipped before the dashing starts. If ``m`` is omitted, it defaults to ``n``.
   
   A continuous line (no dashes) is drawn with `"[] 0"` or *None* or `""`. Examples:
   
@@ -583,7 +583,7 @@ Common Parameters
   The stroke ("border") width of the elements in a shape (if applicable). The default value is 1. The values width, color and fill have the following relationship / dependency:
 
   * If `fill=None` shape elements will always be drawn with a border - even if `color=None` (in which case black is taken) or `width=0` (in which case 1 is taken).
-  * Shapes without border can only be achieved if a fill color is specified (which may be white of course). To achieve this, specify `width=0`. In this case, the `color` parameter is ignored.
+  * Shapes without border can only be achieved if a fill color is specified (which may be white of course). To achieve this, specify `width=0`. In this case, the ``color`` parameter is ignored.
 
 ----
 
diff --git a/docs/vars.rst b/docs/vars.rst
@@ -191,7 +191,7 @@ Text Extraction Flags
 ---------------------
 Option bits controlling the amount of data, that are parsed into a :ref:`TextPage` -- this class is mainly used only internally in PyMuPDF.
 
-For the PyMuPDF programmer, some combination (using Python's `|` operator, or simply use `+`) of these values are aggregated in the `flags` integer, a parameter of all text search and text extraction methods. Depending on the individual method, different default combinations of the values are used. Please use a value that meets your situation. Especially make sure to switch off image extraction unless you really need them. The impact on performance and memory is significant!
+For the PyMuPDF programmer, some combination (using Python's `|` operator, or simply use `+`) of these values are aggregated in the ``flags`` integer, a parameter of all text search and text extraction methods. Depending on the individual method, different default combinations of the values are used. Please use a value that meets your situation. Especially make sure to switch off image extraction unless you really need them. The impact on performance and memory is significant!
 
 .. py:data:: TEXT_PRESERVE_LIGATURES
 
diff --git a/docs/xml-class.rst b/docs/xml-class.rst
@@ -35,7 +35,7 @@ There is no need to ever directly construct an :ref:`Xml` object: after creating
 :meth:`~.add_var`                Add code text (:htmlTag:`code` tag) - inline element, treated like text.
 :meth:`~.add_samp`               Add code text (:htmlTag:`code` tag) - inline element, treated like text.
 :meth:`~.add_kbd`                Add code text (:htmlTag:`code` tag) - inline element, treated like text.
-:meth:`~.add_text`               Add a text string. Line breaks `\n` are honored as :htmlTag:`br` tags.
+:meth:`~.add_text`               Add a text string. Line breaks ``\n`` are honored as :htmlTag:`br` tags.
 :meth:`~.append_child`           Append a child node.
 :meth:`~.clone`                  Make a copy if this node.
 :meth:`~.create_element`         Make a new node with a given tag name.
@@ -159,7 +159,7 @@ There is no need to ever directly construct an :ref:`Xml` object: after creating
 
     .. method:: add_text(text)
 
-       Add a text string. Line breaks `\n` are honored as :htmlTag:`br` tags.
+       Add a text string. Line breaks ``\n`` are honored as :htmlTag:`br` tags.
 
     .. method:: set_align(value)
 

Original file line number	Diff line number	Diff line change
`@@ -331,7 +331,7 @@ MuPDF generates text errors and warnings.`
`331`	`331`	`mupdf_display_warnings()`.
`332`	`332`
`333`	`333`	`*`
`334`		- These messages are prefixed with `MuPDF error: ` and `MuPDF warning: `
	`334`	+ These messages are prefixed with `MuPDF error:` and `MuPDF warning:`
`335`	`335`	`respectively.`
`336`	`336`
`337`	`337`	`Some MuPDF errors may lead to Python exceptions.`
Original file line number	Diff line number	Diff line change
`@@ -104,9 +104,9 @@ There is a parent-child relationship between a link and its page. If the page ob`
`104`	`104`
`105`	`105`	`*`
`106`	`106`	`is_external` is true: `uri` points to some target outside the current
`107`		- PDF, which may be an internet resource (`uri` starts with "http://" or
	`107`	+ PDF, which may be an internet resource (`uri` starts with ``http://`` or
`108`	`108`	similar), another file (`uri` starts with "file:" or "file://") or some
`109`		- other service like an e-mail address (`uri` starts with "mailto:").
	`109`	+ other service like an e-mail address (`uri` starts with ``mailto:``).
`110`	`110`
`111`	`111`	`*`
`112`	`112`	`is_external` is false: `uri` will be `None` or point to an