From 75c791b4fea141417fa088b9f5b9861ef57f4790 Mon Sep 17 00:00:00 2001
From: Albert Krewinkel <albert+github@zeitkraut.de>
Date: Sat, 9 Feb 2019 22:56:49 +0100
Subject: Lua filters: load module `pandoc` before calling `init.lua` (#5287)

The file `init.lua` in pandoc's data directory is run as part of
pandoc's Lua initialization process. Previously, the `pandoc` module was
loaded in `init.lua`, and the structure for marshaling was set-up after.
This allowed simple patching of element marshaling, but made using
`init.lua` more difficult:

  - it encouraged mixing essential initialization with user-defined
    customization;

  - upstream changes to init.lua had to be merged manually;

  - accidentally breaking marshaling by removing required modules was
    possible;

Instead, all required modules are now loaded before calling `init.lua`.
The file can be used entirely for user customization. Patching
marshaling functions, while discouraged, is still possible via the
`debug` module.
---
 doc/lua-filters.md | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

(limited to 'doc')

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 01d2b1a87..09116cc16 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -219,21 +219,15 @@ Some pandoc functions have been made available in lua:
 
 # Lua interpreter initialization
 
-The way the Lua interpreter is set-up can be controlled by
-placing a file `init.lua` in pandoc's data directory. The
-default init file loads the `pandoc` and `pandoc.mediabag`
-modules:
+Initialization of pandoc's Lua interpreter can be controlled by
+placing a file `init.lua` in pandoc's data directory. A common
+use-case would be to load additional modules, or even to alter
+default modules.
 
-``` {.lua}
-pandoc = require 'pandoc'
-pandoc.mediabag = require 'pandoc.mediabag'
-```
-
-A common use-case would be to add code to load additional
-modules or to alter default modules. E.g., the following snippet
-adds all unicode-aware functions defined in the [`text`
-module](#module-text) to the default `string` module, prefixed
-with the string `uc_`.
+The following snippet is an example of code that might be useful
+when added to `init.lua`. The snippet adds all unicode-aware
+functions defined in the [`text` module] to the default `string`
+module, prefixed with the string `uc_`.
 
 ``` {.lua}
 for name, fn in pairs(require 'text') do
@@ -244,6 +238,8 @@ end
 This makes it possible to apply these functions on strings using
 colon syntax (`mystring:uc_upper()`).
 
+[`text` module]: #module-text
+
 # Examples
 
 The following filters are presented as examples.
-- 
cgit v1.2.3