doc: even more lazy documentation

README.md

@@ -79,6 +79,7 @@ try to run any Fennel code.
 
 ```lua
 -- ~/.config/nvim/init.lua
+
 local function ensure_installed(plugin, branch)
   local user, repo = string.match(plugin, "(.+)/(.+)")
   local repo_path = vim.fn.stdpath("data") .. "/lazy/" .. repo
@@ -108,21 +109,23 @@ end
 
 local lazy_path = ensure_installed("folke/lazy.nvim", "stable")
 local hotpot_path = ensure_installed("rktjmp/hotpot.nvim", "v0.13.1")
--- As per lazy's install instructions, but insert hotpots path at the front
+
+-- As per Lazy's install instructions, but also include hotpot
 vim.opt.runtimepath:prepend({hotpot_path, lazy_path})
 
-require("hotpot") -- Optionally you may call require("hotpot").setup(...) here
+-- You must call vim.loader.enable() before requiring hotpot unless you are
+-- passing {performance = {cache = false}} to Lazy.
+vim.loader.enable()
 
--- If you want to use lazy's "structured" style, you will need 
--- a `.hotpot.lua` file containing `return {build=true,clean=true}`
--- so a `lua/` dir is generated for lazy to scan.
--- See further down in the readme for details.
+require("hotpot") -- Optionally you may call require("hotpot").setup(...) here
 
--- Include hotpot as a plugin so lazy will update it
+-- You must include Hotpot in your plugin list for it to function correctly.
+-- If you want to use Lazy's "structured" style, see the next code sample.
 local plugins = {"rktjmp/hotpot.nvim"}
 require("lazy").setup(plugins)
 
--- Include the rest of your config
+-- Include the rest of your config.
+-- Note your call to Lazy.setup does not have to be done in init.lua.
 require("say-hello")
 ```
 
@@ -133,6 +136,58 @@ The `say-hello` module would be put in `~/.config/nvim/fnl/say-hello.fnl`:
 (print :hello!)
 ```
 
+**"Structured Setup"**
+
+Lazy.nvim allows you to separate your plugin specs into individual files and
+folders, but to support this it must be able to find the raw lua files.
+
+We can instruct Hotpot to compile your Fennel code ahead of time, into a
+directory Lazy can find (eg: `lua/`).
+
+First we must define a `.hotpot.lua` file at the root of `~/.config/nvim`.
+
+```lua
+-- ~/.config/nvim/.hotpot.lua
+
+-- By default, the Fennel compiler wont complain if unknown variables are
+-- referenced, we can force a compiler error so we don't try to run faulty code.
+local allowed_globals = {}
+for key, _ in pairs(_G) do
+  table.insert(allowed_globals, key)
+end
+
+return {
+  -- by default, build all fnl/ files into lua/
+  build = true,
+  -- remove stale lua/ files
+  clean = true,
+  compiler = {
+    modules = {
+      -- enforce unknown variable errors
+      allowedGlobals = allowed_globals
+    }
+  }
+}
+```
+
+Now open a `.fnl` file and save it, you should now have a populated `lua/`
+directory and can pass the appropriate module to Lazy.
+
+```lua
+-- .config/nvim/init.lua
+
+-- ...
+
+-- See Lazy's own documentation for details.
+require("lazy").setup({spec = {import = "plugins"}})
+```
+
+<details>
+<summary>nested</summary>
+nested
+
+</details>
+
 </details>
 
 
@@ -274,9 +329,7 @@ hotpot itself.
 
 ```lua
 require("hotpot").setup({
-  -- provide_require_fennel defaults to disabled to be polite with other
-  -- plugins but enabling it is recommended.
-  provide_require_fennel = false,
+  provide_require_fennel = true,
   enable_hotpot_diagnostics = true,
   compiler = {
     -- options passed to fennel.compile for modules, defaults to {}
@@ -298,10 +351,7 @@ require("hotpot").setup({
 ```
 
 - `provide_require_fennel` inserts a `package.preload` function that will load
-  Hotpot's copy of fennel when you call `(require :fennel)`. This can be useful
-  for ergonomics or for compatibility with libraries that expect Fennel to be in
-  `package.path` without having to pay the cost of loading the Fennel compiler
-  when its not used.
+  Hotpot's copy of fennel when you call `(require :fennel)`.
 
 - `enable_hotpot_diagnostics` enable or disable automatic attachment of
   diagnostics to fennel buffers. See [diagnostics](#diagnostics).