From: Eshel Yaron <me@eshelyaron.com>
Date: Sun, 22 Jan 2023 20:04:15 +0000 (+0200)
Subject: Document sweeprolog-file-at-point, file-name-at-point-functions
X-Git-Tag: V9.1.3-sweep-0.14.0~1
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a4d496e96ca808c5ab343b5505689d07d89d8e73;p=dict.git

Document sweeprolog-file-at-point, file-name-at-point-functions
---

diff --git a/README.org b/README.org
index a93aa30..b5f1070 100644
--- a/README.org
+++ b/README.org
@@ -1094,19 +1094,32 @@ library directories.
 
 - Key: C-c C-o (sweeprolog-find-file-at-point) :: Resolve file
   specification at point and visit the specified file.
+- Function: sweeprolog-file-at-point &optional point :: Return the
+  file name specified by the Prolog file specification at POINT.
 
-You can follow file specifications that occur in =sweeprolog-mode=
-buffers with =C-c C-o= (or =M-x sweeprolog-find-file-at-point=) whenever
+You can follow file specifications that occur in ~sweeprolog-mode~
+buffers with ~C-c C-o~ (or ~M-x sweeprolog-find-file-at-point~) whenever
 point is over a valid file specification.  For example, consider a
-Prolog file buffer with the common directive =use_module/1=:
+Prolog file buffer with the common directive ~use_module/1~:
 
 #+begin_src prolog
   :- use_module(library(lists)).
 #+end_src
 
-With point in any position inside =library(lists)=, typing =C-c C-o= will
+With point in any position inside ~library(lists)~, typing ~C-c C-o~ will
 open the =lists.pl= file in the Prolog library.
 
+Sweep also extends Emacs's ~file-name-at-point-functions~ hook with the
+function ~sweeprolog-file-at-point~ that returns the resolved Prolog
+file specification at point, if any.  Emacs uses this hook to populate
+the "future history" of minibuffer prompts that read file names, such
+as the one you get when you type ~C-x C-f~ (~find-file~).  In particular
+this means that if point is in a Prolog file specification, you can
+type ~M-n~ after ~C-x C-f~ to populate the minibuffer with the
+corresponding file name.  You can then go ahead and visit the file by
+typing ~RET~, or you can edit the minibuffer contents and visit a nearby
+file instead.
+
 For more information about file specifications in SWI-Prolog, see
 [[https://www.swi-prolog.org/pldoc/doc_for?object=absolute_file_name/3][absolute_file_name/3]] in the SWI-Prolog manual.
 
@@ -1909,7 +1922,7 @@ loaded or auto-loadable Prolog predicate.
 :ALT_TITLE: File Spec Expansion
 :END:
 
-Sweep defines a handler for the Emacs function =expand-file-file= that
+Sweep defines a handler for the Emacs function =expand-file-name= that
 recognizes Prolog file specifications, such as =library(lists)=, and
 expands them to their corresponding absolute paths.  This means that
 one can use Prolog file specifications with Emacs's standard =find-file=
diff --git a/sweeprolog.el b/sweeprolog.el
index 3876bfd..a3502f8 100644
--- a/sweeprolog.el
+++ b/sweeprolog.el
@@ -2953,6 +2953,7 @@ buffer to load."
                    #'sweeprolog-file-name-handler))
 
 (defun sweeprolog-file-at-point (&optional point)
+  "Return the file name specified by the Prolog file spec at POINT."
   (setq point (or point (point)))
   (let ((fap nil))
     (sweeprolog-analyze-term-at-point