bug#49452: Confusing behavior with (include) used in file in GUILE_LOAD_PATH

[Vijay Marupudi]

Hello all,

It is unclear to me what the intended behavior for (include
"filename.scm") is, so I'm sending an email about this potential bug.

The Local Inclusion docs
<https://www.gnu.org/software/guile/manual/html_node/Local-Inclusion.html>
seem to state that relative paths are found relative to the file that
included them.

> If file-name is a relative path, it is searched for relative to the
> path that contains the file that the include form appears in.

So if I have a file "/libraries/libname/main.scm" than has (include
"./helpers.scm"), then the file "/libraries/libname/helpers.scm"
*should* (I think) be imported.

But this does not seem to work if "/libraries" is in the GUILE_LOAD_PATH
and my current working directory is somewhere else, say "/home/user" and
I'm running "/home/user/program.scm" that imports the (libname main)
library from "/libraries". Then Guile seems to try to include the
"libname/helpers.scm" file from the current directory, which does not
exist.

Conversations with leoprikler in IRC have revealed to me that
call-with-include-port is the function responsible for this behavior
<https://git.savannah.gnu.org/cgit/guile.git/tree/module/ice-9/psyntax.scm#n3231>.
`syntax-source` returns a file path relative to the load path, and
include tries to use that path to open a file relative to the current
working directory.

In Guile's bug guidelines
<https://www.gnu.org/software/guile/docs/docs-2.2/guile-ref/Reporting-Bugs.html>,
to me this fits

* Whenever documentation and actual behavior differ, you have certainly
  found a bug, either in the documentation or in the program.

and potentially

* When some part of the documentation is not clear and does not make
  sense to you even after re-reading the section, it is a bug.

I believe this is a bug, but I may be wrong, so emailing to clarify.
Thank you!

Vijay Marupudi
PhD Student in Human Centered-Computing
Georgia Institute of Technology