add note about loggers

1 files changed, 27 insertions, 1 deletions

diff --git a/luaotfload-override.lua b/luaotfload-override.lua
index 51d2749..5e642e4 100644
--- a/luaotfload-override.lua
+++ b/luaotfload-override.lua
@@ -6,7 +6,7 @@ if not modules then modules = { } end modules ['luat-ovr'] = {
     license   = "GNU GPL v2"
 }
 
-local module_name = "luaotfload"
+local module_name   = "luaotfload"
 
 local texiowrite_nl = texio.write_nl
 local stringformat  = string.format
@@ -75,6 +75,32 @@ end
 --- at default (zero), we aim to be quiet
 local level_ids = { common  = 1, loading = 2, search  = 3 }
 
+--[[doc--
+
+    The names_report logger is used more or less all over luaotfload.
+    Its requirements are twofold:
+
+    1) Provide two logging channels, the terminal and the log file;
+    2) Allow for control over verbosity levels.
+
+    The first part is addressed by specifying the log *mode* as the
+    first argument that can be either “log”, meaning the log file, or
+    “both”: log file and stdout. Anything else is taken as referring to
+    stdout only.
+
+    Verbosity levels, though not as fine-grained as e.g. Context’s
+    system of tracers, allow keeping the logging spam caused by
+    different subsystems manageable. By default, luaotfload will not
+    emit anything if things are running smoothly on level zero. Only
+    warning messages are relayed, while the other messages are skipped
+    over. (This is a little sub-optimal performance-wise since the
+    function calls to the logger are executed regardless.) The log
+    level during a Luatex run can be adjusted by setting the “loglevel”
+    field in config.luaotfload, or by calling logs.set_loglevel() as
+    defined above.
+
+--doc]]--
+
 local names_report = function (mode, lvl, ...)
     if type(lvl) == "string" then
         lvl = level_ids[lvl]