From 466ec662e7643bbbd378b23bc99b27fb7d44b32b Mon Sep 17 00:00:00 2001
From: prql-bot <107324867+prql-bot@users.noreply.github.com>
Date: Wed, 15 May 2024 11:04:43 -0700
Subject: [PATCH] chore: Backport #4473 to `web` (#4476)

Co-authored-by: Rich Brown <richb.hanover@gmail.com>
---
 web/book/src/reference/spec/modules.md | 35 +++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/web/book/src/reference/spec/modules.md b/web/book/src/reference/spec/modules.md
index 51360413fd55..c1b41d2fd3a2 100644
--- a/web/book/src/reference/spec/modules.md
+++ b/web/book/src/reference/spec/modules.md
@@ -1,9 +1,19 @@
 # Modules
 
-> This is a technical document. For a "how to use" or a TLDR; skip to the
-> [Example](#example) section.
+```admonish warning
+The `module` facility is in discussion.
+This page documents our understanding of the way
+the final PRQL compiler will likely work.
+The PRQL compiler currently uses these techniques to compile
+the `std`, `date`, `text`, and `math` modules into the language.
 
-Design goals:
+However, at this time (Spring 2024), the `module` facility does not work
+within a PRQL query itself.
+That is, a `module` statement in a query cannot import files
+from the local file system.
+```
+
+Design goals for **modules**:
 
 1. Allow importing declarations from other files.
 
@@ -113,8 +123,13 @@ let album_titles = my_playlists
 
 ## File importing
 
-> This section is under discussion. Current implementation plans do not include
-> `module` declarations, but loading of all files under the compilation path.
+```admonish warning
+The examples below do **not** work.
+At this time (Spring 2024), the `module` facility does not work
+within a PRQL query itself.
+That is, a `module` statement in a query cannot import files
+from the local file system.
+```
 
 To include PRQL source code from other files, we can use the following syntax:
 
@@ -241,7 +256,7 @@ connector (i.e. JDBC) where no other files can be loaded.
 
 ## Built-in module structure
 
-> Work In Progress
+> As noted above, this facility is in discussion.
 
 ```
 # root module of every project
@@ -264,6 +279,14 @@ module project {
 
 ## Example
 
+```admonish warning
+The examples below do **not** work.
+At this time (Spring 2024), the `module` facility does not work
+within a PRQL query itself.
+That is, a `module` statement in a query cannot import files
+from the local file system.
+```
+
 This is an example project, where each of code block is a separate file.
 
 ```