DOC: lua: Document the filter instance declaration of Lua filters

The filter instance mode documentation claims that the supported filter
classes are documented in the section 9 of the configuration manual, but
the Lua filters are missing: they are not built-in classes, they are
registered by the Lua scripts with core.register_filter() and are
declared with the "lua" filter class. The Lua API documentation only
shows the legacy declaration of a Lua filter.

Document the "filter-config lua id <name>" declaration in the Lua API
documentation, next to the legacy one: the instance id selects the
registered filter to instantiate, the optional "enabled" token activates
the instance, and the other arguments are the same as for the legacy
declaration. Mention that contrary to the legacy "filter" directive, the
Lua filters may be declared in defaults sections with the new mode, to
be inherited by the proxies using them. Finally, point to the Lua API
documentation from the introduction of the section 9.

diff --git a/doc/configuration.txt b/doc/configuration.txt
index b80479f48905563c8b4473cbc5589e33da36b95f..23acb5ccc0e29ab4bcf1242f5c0a9d456d0c18ec 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -31510,6 +31510,10 @@ with "filter-config" may differ from the legacy filter name; it is given in
 the documentation of each filter. The "filter-config" syntax is documented
 below the legacy one.
 
+The Lua filters are not documented here: they are registered by Lua scripts
+with core.register_filter() and are declared with the "lua" filter class.
+See the Lua API documentation for their declaration syntax.
+
 The filter instances of a proxy may be inspected with the "show filter
 classes" and "show filter instances" CLI commands (see the management
 manual).

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index e46adc4432389a76a712b5c9ca2c6b8db18f3843..8632aaf6a19ae8238cae5c29a50d3450ef57fe4e 100644 (file)
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -706,6 +706,20 @@ Core class
     mode http
     filter lua.my-filter arg1 arg2 arg3
 
+With the filter instance mode, the same filter is declared like this::
+
+  filter-config lua id my-filter enabled arg1 arg2 arg3
+
+The instance id selects the registered filter to instantiate: the instance
+with id 'my-filter' instantiates the filter registered as "lua.my-filter".
+The optional "enabled" token activates the instance, which may also be
+enabled or disabled later with the "filter-enable" and "filter-disable"
+directives. The other arguments are the same as for the legacy declaration
+and are passed to the registration function. Contrary to the legacy "filter"
+directive, "filter-config lua" is also allowed in defaults sections, the
+instances being inherited by the proxies using them. See the
+"filter-config" entry in the configuration manual for the details.
+
 ..
 
   :see: :js:class:`Filter`