From 23c77b4bdf11a4c69d737faef85aa6bc430a754b Mon Sep 17 00:00:00 2001
From: Peter Ludemann <peter.ludemann@gmail.com>
Date: Sun, 1 Sep 2024 16:22:16 -0700
Subject: [PATCH] Minor clarifications to documentation of absolute_file_name
 and PL_get_file_name()

---
 man/builtin.doc | 16 +++++++++++-----
 man/foreign.doc |  6 ++++--
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/man/builtin.doc b/man/builtin.doc
index a1f9fd319e..15a84bff69 100644
--- a/man/builtin.doc
+++ b/man/builtin.doc
@@ -855,18 +855,18 @@ following keys are defined:
 \hline
 \bf Key               & \bf Description \\
 \hline
-\const{directory}     & Directory in which \const{source} lives \\
+\const{directory}     & Directory in which \const{source} lives (absolute path) \\
 \const{dialect}	      & Compatibility mode.  See expects_dialect/1. \\
 \const{file}          & Similar to \const{source}, but returns the file
 			being included when called while an include file
-			is being processed \\
+			is being processed (absolute path) \\
 \const{module}        & Module into which file is loaded \\
 \const{reload}	      & \const{true} if the file is being
 			\textbf{re}loaded.  Not present on first load \\
 \const{script}	      & Boolean that indicates whether the file is
 			loaded as a script file (see
 			\cmdlineoption{-s}) \\
-\const{source}        & File being loaded.  If the system is processing an
+\const{source}        & File being loaded (absolute path).  If the system is processing an
 			included file, the value is the \emph{main} file.
 			Returns the original Prolog file when loading a
 			\fileext{qlf} file. \\
@@ -10935,6 +10935,8 @@ addressed. Notably, if a file appears in multiple directories due to
 symbolic or hard links absolute_file_name/2 returns the same absolute
 filename. SWI-Prolog uses absolute filenames to register source files
 independent of the current working directory.
+The directory separators are always \chr{/}; prolog_to_os_filename/2
+can be used to obtain the the operating system's preferred form.
 
 This predicate has a different history than absolute_file_name/3 and
 should primarily be used to get an absolute canonical name from a
@@ -10964,8 +10966,12 @@ filename or an absolute filename. The primary intention of this
 predicate is to resolve files specified as Alias(Relative), which use
 file_search_path/2 to look up the possibilities for Alias. This
 predicate \emph{only returns non-directories}, unless the option
-\term{file_type}{directory} is specified or the requested access
-is \const{none}.  Supported \arg{Options} are:
+\term{file_type}{directory} is specified or the requested access is
+\const{none}. The result always uses the directory separator \chr{/};
+if the operating system uses something different, SWI-Prolog converts
+the file name before it makes an OS call. If you need the filename in
+the OS's preferred form, use prolog_to_os_filename/2.
+Supported \arg{Options} are:
 
 \begin{description}
     \termitem{extensions}{ListOfExtensions}
diff --git a/man/foreign.doc b/man/foreign.doc
index 85e317d56b..e3f11b138e 100644
--- a/man/foreign.doc
+++ b/man/foreign.doc
@@ -4079,10 +4079,12 @@ file properties, search, naming conventions, etc., from foreign code.
 \begin{description}
     \cfunction{int}{PL_get_file_name}{term_t spec, char **name, int flags}
 Translate a Prolog term into a file name. The name is stored in the
-buffer stack described with the PL_get_chars() option \const{BUF_STACK}.
+buffer stack described with the PL_get_chars() option \const{BUF_STACK},
+which is popped upon return from the foreign predicate to Prolog.
 Conversion from the internal UNICODE encoding is done using standard C
 library functions. \arg{flags} is a bit-mask controlling the conversion
-process. Options are:
+process. On failure, \const{PL_FILE_NOERRORS} controls whether an
+exception is raised. Options are:
 
 \begin{description}
     \definition{\const{PL_FILE_ABSOLUTE}}