docs(lua): add Lua 5.1 reference manual (#19663)

based on http://www.vim.org/scripts/script.php?script_id=1291
reformatted to match Nvim documentation style; removed irrelevant sections

Co-authored-by: dundargoc <gocundar@gmail.com>
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Co-authored-by: Lewis Russell <lewis6991@gmail.com>

runtime/doc/help.txt

@@ -185,6 +185,7 @@ Other ~
 |channel.txt|		Nvim asynchronous IO
 |dev_style.txt|		Nvim style guide
 |job_control.txt|	Spawn and control multiple processes
+|luaref.txt|		Lua reference manual
 
 						*standard-plugin-list*
 Standard plugins ~

runtime/doc/lua.txt

@@ -37,7 +37,7 @@ separator when searching. For a module `foo.bar`, each directory is searched
 for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`. If no files are found,
 the directories are searched again for a shared library with a name matching
 `lua/foo/bar.?`, where `?` is a list of suffixes (such as `so` or `dll`) derived from
-the initial value of `package.cpath`. If still no files are found, Nvim falls
+the initial value of |package.cpath|. If still no files are found, Nvim falls
 back to Lua's default search mechanism. The first script found is run and
 `require()` returns the value returned by the script if any, else `true`.
 
@@ -46,7 +46,7 @@ with subsequent calls returning the cached value without searching for, or
 executing any script. For further details on `require()`, see the Lua
 documentation at https://www.lua.org/manual/5.1/manual.html#pdf-require.
 
-For example, if 'runtimepath' is `foo,bar` and `package.cpath` was
+For example, if 'runtimepath' is `foo,bar` and |package.cpath| was
 `./?.so;./?.dll` at startup, `require('mod')` searches these paths in order
 and loads the first module found:
 
@@ -59,27 +59,27 @@ and loads the first module found:
     bar/lua/mod.so
     bar/lua/mod.dll
 
-Nvim automatically adjusts `package.path` and `package.cpath` according to the
+Nvim automatically adjusts |package.path| and |package.cpath| according to the
 effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is
-changed. `package.path` is adjusted by simply appending `/lua/?.lua` and
+changed. |package.path| is adjusted by simply appending `/lua/?.lua` and
 `/lua/?/init.lua` to each directory from 'runtimepath' (`/` is actually the
 first character of `package.config`).
 
-Similarly to `package.path`, modified directories from 'runtimepath' are also
+Similarly to |package.path|, modified directories from 'runtimepath' are also
-added to `package.cpath`. In this case, instead of appending `/lua/?.lua` and
+added to |package.cpath|. In this case, instead of appending `/lua/?.lua` and
 `/lua/?/init.lua` to each runtimepath, all unique `?`-containing suffixes of
-the existing `package.cpath` are used. Example:
+the existing |package.cpath| are used. Example:
 
 1. Given that
    - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`;
    - initial (defined at compile-time or derived from
-     `$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains
+     `$LUA_CPATH`/`$LUA_INIT`) |package.cpath| contains
      `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`.
 2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in
    order: parts of the path starting from the first path component containing
    question mark and preceding path separator.
 3. The suffix of `/def/?.so`, namely `/?.so` is not unique, as it’s the same
-   as the suffix of the first path from `package.path` (i.e. `./?.so`). Which
+   as the suffix of the first path from |package.path| (i.e. `./?.so`). Which
    leaves `/?.so` and `/a?d/j/g.elf`, in this order.
 4. 'runtimepath' has three paths: `/foo/bar`, `/xxx;yyy/baz` and `/abc`. The
    second one contains a semicolon which is a paths separator so it is out,
@@ -93,7 +93,7 @@ the existing `package.cpath` are used. Example:
    - `/abc/lua/?.so`
    - `/abc/lua/a?d/j/g.elf`
 
-6. New paths are prepended to the original `package.cpath`.
+6. New paths are prepended to the original |package.cpath|.
 
 The result will look like this:
 
@@ -108,16 +108,16 @@ Note:
   remembered and removed at the next update, while all paths derived from the
   new 'runtimepath' are prepended as described above. This allows removing
   paths when path is removed from 'runtimepath', adding paths when they are
-  added and reordering `package.path`/`package.cpath` content if 'runtimepath'
+  added and reordering |package.path|/|package.cpath| content if 'runtimepath'
   was reordered.
 
 - Although adjustments happen automatically, Nvim does not track current
-  values of `package.path` or `package.cpath`. If you happen to delete some
+  values of |package.path| or |package.cpath|. If you happen to delete some
   paths from there you can set 'runtimepath' to trigger an update: >
       let &runtimepath = &runtimepath
 
 - Skipping paths from 'runtimepath' which contain semicolons applies both to
-  `package.path` and `package.cpath`. Given that there are some badly written
+  |package.path| and |package.cpath|. Given that there are some badly written
   plugins using shell, which will not work with paths containing semicolons,
   it is better to not have them in 'runtimepath' at all.
 
@@ -182,7 +182,7 @@ Lua Patterns                                                    *lua-patterns*
 
 For performance reasons, Lua does not support regular expressions natively.
 Instead, the Lua `string` standard library allows manipulations using a
-restricted set of "patterns", see https://www.lua.org/manual/5.1/manual.html#5.4.1
+restricted set of "patterns", see |luaref-patterns|.
 
 Examples (`string.match` extracts the first match): >
 
@@ -1603,7 +1603,7 @@ list_slice({list}, {start}, {finish})                       *vim.list_slice()*
                     (inclusive)
 
 pesc({s})                                                         *vim.pesc()*
-                Escapes magic chars in a Lua pattern.
+                Escapes magic chars in |lua-patterns|.
 
                 Parameters: ~
                     {s}  (string) String to escape

runtime/lua/vim/shared.lua

@@ -526,7 +526,7 @@ function vim.trim(s)
   return s:match('^%s*(.*%S)') or ''
 end
 
---- Escapes magic chars in a Lua pattern.
+--- Escapes magic chars in |lua-patterns|.
 ---
 ---@see https://github.com/rxi/lume
 ---@param s string String to escape