some docu updates

Author: JorjMcKie

docs/document.rst

@@ -404,16 +404,16 @@ For details on **embedded files** refer to Appendix 3.
 
     .. method:: getPageImageList(pno, full=False)
 
-      PDF only: Return a list of all images referenced by the page.
+      PDF only: Return a list of all images (directly or indirectly) referenced by the page.
 
       :arg int pno: page number, 0-based, *-inf < pno < pageCount*.
-      :arg bool full: whether to also include the invoker's :data:`xref` (which is zero if this is the page).
+      :arg bool full: whether to also include the referencer's :data:`xref` (which is zero if this is the page).
 
       :rtype: list
 
       :returns: a list of images shown on this page. Each item looks like
 
-      **(xref, smask, width, height, bpc, colorspace, alt. colorspace, name, filter, invoker)**
+      **(xref, smask, width, height, bpc, colorspace, alt. colorspace, name, filter, referencer)**
 
       Where
 
@@ -425,7 +425,7 @@ For details on **embedded files** refer to Appendix 3.
         * **alt. colorspace** (*str*) is any alternate colorspace depending on the value of **colorspace**
         * **name** (*str*) is the symbolic name by which the image is referenced
         * **filter** (*str*) is the decode filter of the image (:ref:`AdobeManual`, pp. 65).
-        * **invoker** (*int*) the :data:`xref` of the invoker. Zero if directly referenced by the page. Only present if *full=True*.
+        * **referencer** (*int*) the :data:`xref` of the referencer. Zero if directly referenced by the page. Only present if *full=True*.
 
       See below how this information can be used to extract PDF images as separate files. Another demonstration::
 
@@ -438,16 +438,16 @@ For details on **embedded files** refer to Appendix 3.
 
     .. method:: getPageFontList(pno, full=False)
 
-      PDF only: Return a list of all fonts referenced by the page.
+      PDF only: Return a list of all fonts (directly or indirectly) referenced by the page.
 
       :arg int pno: page number, 0-based, -inf < pno < pageCount.
-      :arg bool full: whether to also include the invoker's :data:`xref` (which is zero if directly referenced by the page).
+      :arg bool full: whether to also include the referencer's :data:`xref`. If *True*, the returned items are one entry longer. Use this option if you need to know, whether the page directly references the font. In this case the last entry is 0. If the font is referenced by an ``/XObject`` of the page, you will find its :data:`xref` here.
 
       :rtype: list
 
       :returns: a list of fonts referenced by this page. Each entry looks like
-        
-      **(xref, ext, type, basefont, name, encoding, invoker)**,
+
+      **(xref, ext, type, basefont, name, encoding, referencer)**,
 
       where
 
@@ -457,7 +457,7 @@ For details on **embedded files** refer to Appendix 3.
           * **basefont** (*str*) is the base font name,
           * **name** (*str*) is the symbolic name, by which the font is referenced
           * **encoding** (*str*) the font's character encoding if different from its built-in encoding (:ref:`AdobeManual`, p. 414):
-          * **invoker** (*int* optional) the :data:`xref` of the invoker. Zero if directly referenced by the page. Only present if *full=True*.
+          * **referencer** (*int* optional) the :data:`xref` of the referencer. Zero if directly referenced by the page, otherwise the xref of an XObject. Only present if *full=True*.
 
       Example::
 
@@ -469,7 +469,7 @@ For details on **embedded files** refer to Appendix 3.
           [28, 'ttf', 'TrueType', 'NOHSJV+Calibri-Light', 'R12', '']
           [8, 'ttf', 'Type0', 'ECPLRU+Calibri', 'R23', 'Identity-H']
 
-      .. note:: This list has no duplicate entries: the combination of :data:`xref` and *name* is unique. But by themselves, each of the two may occur multiple times. Duplicate *name* entries indicate the presence of "Form XObjects" on the page, e.g. generated by :meth:`Page.showPDFpage`.
+      .. note:: This list has no duplicate entries: the combination of :data:`xref`, *name* and *referencer* is unique.
 
     .. method:: getPageText(pno, output="text")
 

docs/faq.rst

@@ -560,7 +560,7 @@ This script will take a document filename and generate a text file from all of i
 
 The document can be any supported type like PDF, XPS, etc.
 
-The script works as a command line tool which expects the document filename supplied as a parameter. It generates one text file named "filename.txt" in the script directory. Text of pages is separated by a line "-----"::
+The script works as a command line tool which expects the document filename supplied as a parameter. It generates one text file named "filename.txt" in the script directory. Text of pages is separated by a form feed character::
 
     import sys, fitz
     fname = sys.argv[1]  # get document filename
@@ -588,50 +588,7 @@ See the following two section for examples and further explanations.
 
 How to Extract Text from within a Rectangle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Please refer to the script `textboxtract.py <https://github.com/pymupdf/PyMuPDF-Utilities/blob/master/examples/textboxtract.py>`_.
-
-It demonstrates ways to extract text contained in the following red rectangle,
-
-.. image:: images/img-textboxtract.png
-   :scale: 75
-
-.. highlight:: text
-
-by using more or less restrictive conditions to find the relevant words::
-
-    Select the words strictly contained in rectangle
-    ------------------------------------------------
-    Die Altersübereinstimmung deutete darauf hin,
-    engen, nur 50 Millionen Jahre großen
-    Gesteinshagel auf den Mond traf und dabei
-    hinterließ – einige größer als Frankreich.
-    es sich um eine letzte, infernalische Welle
-    Geburt des Sonnensystems. Daher tauften die
-    das Ereignis »lunare Katastrophe«. Später
-    die Bezeichnung Großes Bombardement durch.
-
-Or, more forgiving, respectively::
-
-    Select the words intersecting the rectangle
-    -------------------------------------------
-    Die Altersübereinstimmung deutete darauf hin, dass
-    einem engen, nur 50 Millionen Jahre großen Zeitfenster
-    ein Gesteinshagel auf den Mond traf und dabei unzählige
-    Krater hinterließ – einige größer als Frankreich. Offenbar
-    handelte es sich um eine letzte, infernalische Welle nach
-    der Geburt des Sonnensystems. Daher tauften die Caltech-
-    Forscher das Ereignis »lunare Katastrophe«. Später setzte
-    sich die Bezeichnung Großes Bombardement durch.
-
-The latter output also includes words *intersecting* the rectangle.
-
-.. highlight:: python
-
-What if your **rectangle spans across more than one page**? Follow this recipe:
-
-* Create a common list of all words of all pages which your rectangle intersects.
-* When adding word items to this common list, increase their **y-coordinates** by the accumulated height of all previous pages.
-
+There is now (v1.18.0) more than one way to achieve this. We therefore have created a `folder <https://github.com/pymupdf/PyMuPDF-Utilities/tree/master/textbox-extraction>`_ in the PyMuPDF-Utilities repository specifically dealing with this topic.
 
 ----------