Make include docs available at REPL again + be explicit about globa…

…l scope (#27089)

base/loading.jl

@@ -1078,20 +1078,38 @@ function include_relative(mod::Module, _path::String)
 end
 
 """
-    include(m::Module, path::AbstractString)
+    Base.include([m::Module,] path::AbstractString)
+
+Evaluate the contents of the input source file in the global scope of module `m`, or,
+for the one argument call, in the global scope of the `Base` module.
+Note that every `Module` (except those defined with `baremodule`) has its own 1-argument
+definition of `include`, which evaluates the file in that module.
+Returns the result of the last evaluated expression of the input file. During including,
+a task-local include path is set to the directory containing the file. Nested calls to
+`include` will search relative to that path. This function is typically used to load source
+interactively, or to combine files in packages that are broken into multiple source files.
+"""
+Base.include # defined in sysimg.jl
 
-Evaluate the contents of the input source file into module `m`. Returns the result
-of the last evaluated expression of the input file. During including, a task-local include
+"""
+    include(path::AbstractString)
+
+Evaluate the contents of the input source file into the global scope of the containing module.
+Every `Module` (except those defined with `baremodule`) has its own 1-argument
+definition of `include`, which evaluates the file in that module.
+Returns the result of the last evaluated expression of the input file. During including, a task-local include
 path is set to the directory containing the file. Nested calls to `include` will search
 relative to that path. This function is typically used to load source
 interactively, or to combine files in packages that are broken into multiple source files.
+
+Use [`Base.include`](@ref) to evaluate a file into another module.
 """
-include # defined in sysimg.jl
+MainInclude.include # defined in sysimg.jl
 
 """
     evalfile(path::AbstractString, args::Vector{String}=String[])
 
-Load the file using [`include`](@ref), evaluate all expressions,
+Load the file using [`Base.include`](@ref), evaluate all expressions,
 and return the value of the last one.
 """
 function evalfile(path::AbstractString, args::Vector{String}=String[])

doc/src/base/base.md

@@ -28,6 +28,7 @@ Base.require
 Base.compilecache
 Base.__precompile__
 Base.include
+Base.MainInclude.include
 Base.include_string
 Base.include_dependency
 Base.which(::Any, ::Any)

doc/src/manual/code-loading.md

@@ -2,7 +2,7 @@
 
 Julia has two mechanisms for loading code:
 
-1. **Code inclusion:** e.g. `include("source.jl")`. Inclusion allows you to split a single program across multiple source files. The expression `include("source.jl")` causes the contents of the file `source.jl` to be evaluated inside of the module where the `include` call occurs. If `include("source.jl")` is called multiple times, `source.jl` is evaluated multiple times. The included path, `source.jl`, is interpreted relative to the file where the `include` call occurs. This makes it simple to relocate a subtree of source files. In the REPL, included paths are interpreted relative to the current working directory, `pwd()`.
+1. **Code inclusion:** e.g. `include("source.jl")`. Inclusion allows you to split a single program across multiple source files. The expression `include("source.jl")` causes the contents of the file `source.jl` to be evaluated in the global scope of the module where the `include` call occurs. If `include("source.jl")` is called multiple times, `source.jl` is evaluated multiple times. The included path, `source.jl`, is interpreted relative to the file where the `include` call occurs. This makes it simple to relocate a subtree of source files. In the REPL, included paths are interpreted relative to the current working directory, `pwd()`.
 2. **Package loading:** e.g. `import X` or `using X`. The import mechanism allows you to load a package—i.e. an independent, reusable collection of Julia code, wrapped in a module—and makes the resulting module available by the name `X` inside of the importing module. If the same `X` package is imported multiple times in the same Julia session, it is only loaded the first time—on subsequent imports, the importing module gets a reference to the same module. It should be noted, however, that `import X` can load different packages in different contexts: `X` can refer to one package named `X` in the main project but potentially different packages named `X` in each dependency. More on this below.
 
 Code inclusion is quite straightforward: it simply parses and evaluates a source file in the context of the caller. Package loading is built on top of code inclusion and is quite a bit more complex. The rest of this chapter, therefore, focuses on the behavior and mechanics of package loading.

doc/src/manual/modules.md

@@ -131,8 +131,9 @@ since this is needed in the vast majority of cases.
 
 ### Default top-level definitions and bare modules
 
-In addition to `using Base`, modules also automatically contain a definition of the `eval` function,
-which evaluates expressions within the context of that module.
+In addition to `using Base`, modules also automatically contain
+definitions of the `eval` and `include` functions,
+which evaluate expressions/files within the global scope of that module.
 
 If these default definitions are not wanted, modules can be defined using the keyword `baremodule`
 instead (note: `Core` is still imported, as per above). In terms of `baremodule`, a standard
@@ -145,6 +146,7 @@ using Base
 
 eval(x) = Core.eval(Mod, x)
 eval(m,x) = Core.eval(m, x)
+include(p) = Base.include(Mod, p)
 
 ...