(feat,fix) save/export scrapper buffers

README.md

@@ -564,6 +564,9 @@ in putting each reference onto a separate line.
 After you are finished with editing the text data, press `C-c C-c` to
 proceed to the second step.
 
+Press `C-x C-s` to save your progress or `C-x C-w` to write the text references
+into a file.
+
 Press `C-c C-k` anytime to abort the ORB PDF Scrapper process.
 
 #### <a name="orb-pdf-scrapper-bibtex-mode"></a>BibTeX mode
@@ -587,10 +590,16 @@ generation.  During key generation, it is also possible to automatically set
 the values of BibTeX fields: see `orb-pdf-scrapper-set-fields` docstring for
 more details.
 
+Press `C-x C-s` to save your progress or `C-x C-w` to write the BibTeX entries
+into a file.
+
 Press `C-c C-r` to return to the text-editing mode in its last state.  Note
 that all the progress in BibTeX mode will be lost.
 
-Press `C-c C-c` to proceed to the third step.
+Press `C-c C-c` to proceed to the third step.  If the BibTeX buffer was edited
+and the changes were not saved, e.g. by pressing `C-x C-s`, you will be
+prompted to generated BibTeX keys by default. The variable
+`orb-pdf-prompt-to-generate-keys` more finely controls this behaviour.
 
 #### <a name="orb-pdf-scrapper-org-mode"></a>Org mode
 In the third step, the BibTeX records are processed internally by ORB PDF
@@ -621,17 +630,60 @@ Review and edit the generated Org-mode data, or press `C-c C-c` to
 insert the references into the note's buffer and finish the ORB PDF
 Scrapper.
 
+Press `C-x C-s` to save your progress or `C-x C-w` to write the Org data
+into a file.
+
 Press `C-c C-r` to return to BibTeX editing mode in its last state.
 Note that all the progress in current mode will be lost.
 
 The following user variables control the appearance of the generated Org-mode
 data: `orb-pdf-scrapper-group-references`, `orb-pdf-scrapper-grouped-export`,
 `orb-pdf-scrapper-ungrouped-export`, `orb-pdf-scrapper-table-export-fields`,
-`orb-pdf-scrapper-list-style`, `orb-pdf-scrapper-citation-numbers`,
+`orb-pdf-scrapper-list-style`, `orb-pdf-scrapper-reference-numbers`,
 `orb-pdf-scrapper-citekey-format`.  These variables can be set through the
 Customize interface or with `setq`.  Refer to their respective docstrings in
 Emacs for more information.
 
+#### <a name="orb-pdf-scrapper-export-options"></a>Exporting data generated by ORB PDF Scrapper
+The different types of data generated by ORB PDF Scrapper – text, BibTeX and
+Org - can be exported to the buffer of origin or an external file.  By default,
+only the Org data is exported to the buffer of origin. Different export options
+can be set in `orb-pdf-scrapper-export-options`.  Consult its docstring for a
+detailed explanation.  The following example demonstrates various
+possibilities.
+
+``` el
+(setq orb-pdf-scrapper-export-options
+      '((org  ;; <= TYPE
+         ;;  Export to a heading in the buffer of origin
+         (heading "References (extracted by ORB PDF Scrapper)"
+         ;; ^             ^
+         ;; TARGET     LOCATION
+                     ;; PROPERTIES
+                     ;;    v
+                     :property-drawer ("PDF_SCRAPPER_TYPE"
+                                       "PDF_SCRAPPER_SOURCE"
+                                       "PDF_SCRAPPER_DATE")))
+        (txt
+         ;; Export to a file "references.org"
+         (path "references.org"
+               ;; under a heading "New references"
+               :placement
+               (heading "New references"
+                        :property-drawer ("PDF_SCRAPPER_TYPE"
+                                          "PDF_SCRAPPER_SOURCE"
+                                          "PDF_SCRAPPER_DATE")
+                        ;; Put the new heading in front of other headings
+                        :placement prepend)))
+        (bib
+         ;; Export to a file in an existing directory.  The file name will be CITEKEY.bib
+         (path "/path/to/references-dir/"
+               :placement prepend
+              ;; Include only the references that are not in the target file
+              ;; *and* the file(s) specified in bibtex-completion-bibliography
+               :filter-bib-entries bibtex-completion-bibliography))))
+```
+
 #### Training a Parser model
 ##### <a name="parser-model-prerequisites"></a>Prerequisites
 Currently, the core data set (explained below) must be installed manually by the user as follows: