Document the inability to create buffers during initialization.

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/manual.md b/doc/manual.md
index 64e9608f..c1c6fec4 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -940,9 +940,15 @@ mind:
 * Be aware of the programming languages Textadept supports and do not use any
   module names that match the name of a lexer in the *lexers/* directory unless
   you are creating a language module.
+* Do not call any functions that create buffers and views (e.g. `ui.print()`,
+  `io.open_file()`, and `buffer.new()`) at file-level scope. This will result in
+  hard errors as Textadept initializes. Those types of function calls must occur
+  within functions (e.g. in a key binding, menu item, or
+  [`events.INITIALIZED`][] event handler).
 * Additional documentation on creating language modules can be found in the
   the [language module API documentation][].
 
+[`events.INITIALIZED`]: api.html#events.INITIALIZED
 [language module API documentation]: api.html#_M
 
 - - -
@@ -971,6 +977,14 @@ items, and changing the theme. This manual discusses these specific
 customizations, minus theming, in the sections below. Theming is covered in a
 later section.
 
+Note: Do not call any functions that create buffers and views (e.g.
+`ui.print()`, `io.open_file()`, and `buffer.new()`) at the file-level scope of
+*~/.textadept/init.lua*. This will result in hard errors as Textadept
+initializes. Those types of function calls must occur within functions (e.g. in
+a key binding, menu item, or [`events.INITIALIZED`][] event handler).
+
+[`events.INITIALIZED`]: api.html#events.INITIALIZED
+
 ### Editor Preferences
 
 Editor preferences are stored in a [`buffer`][] object. Normally, each buffer