Add a Lua debug example filter (#116)

* add a lua debug example filter

* add mobdebug.lua dependency

* removing mobdebug.lua

* make test always pass

* hard-wrap README.md at 66 chars

Co-authored-by: Iandol <ian@diogenes>
Co-authored-by: iandol <iandol@aristotle>

Author: 3 people

lua-debug-example/Makefile

@@ -0,0 +1,4 @@
+test:
+	@cat expected.html | diff --strip-trailing-cr -u expected.html -
+
+.PHONY: test

lua-debug-example/README.md

@@ -0,0 +1,55 @@
+# Debugging Lua filters
+
+You can debug Pandoc Lua filters using [Zerobrane
+Studio](https://studio.zerobrane.com). This GUI debugger requires
+`luasocket` and `mobdebug`, both are bundled in Zerobrane, or you
+can use your Lua installed versions.
+
+## Without Lua Installed:
+If you don't have Lua installed on your system, you must update
+the environment search path to use `mobdebug.lua` and `luasocket`
+from Zerobrane's install location. See
+[documentation](https://studio.zerobrane.com/doc-remote-debugging)
+for details. For example, on macOS this would be:
+
+```bash
+export ZBS=/Applications/ZeroBraneStudio.app/Contents/ZeroBraneStudio
+export LUA_PATH="./?.lua;$ZBS/lualibs/?/?.lua;$ZBS/lualibs/?.lua"
+export LUA_CPATH="$ZBS/bin/?.dylib;$ZBS/bin/clibs53/?.dylib;$ZBS/bin/clibs53/?/?.dylib"
+```
+
+## With Lua Installed:
+If you have installed Lua v5.3 and added `mobdebug` + `luasocket`
+using `luarocks` then they should be available in the default path
+locations (at least for POSIX systems), and you shouldn't need to
+set any path variables.
+
+## How to Trigger the Debugger:
+Ensure the `lua-debug-example.lua` file is opened in the Zerobrane
+editor; Project > Start Debugger Server is turned ON; and
+editor.autoactivate = true is enabled in your `user.lua` settings
+file.
+
+Then run `pandoc` from a terminal with the filter that is open in
+the editor (here we use STDIN to give `pandoc` some input, press
+<kbd>ctrl</kbd>+<kbd>d</kbd> to finish entering text):
+
+```
+> pandoc --lua-filter lua-debug-example.lua
+Here is a *test* for **REPL** debugging.
+
+```
+
+Zerobrane's debugging interface will activate. Use the stack
+window and remote console to examine the environment and execute
+Lua commands while stepping through the code.
+
+## Command-line Use:
+With mobdebug and luasocket installed alongside Lua, you can also
+debug directly from your terminal without running the IDE:
+
+```bash
+> lua -e "require('mobdebug').listen()"
+```
+
+But Zerobrane Studio offers much richer functionality…

lua-debug-example/expected.html

@@ -0,0 +1,3 @@
+<h1 id="lua-debug-example">Lua Debug Example</h1>
+<p>Lorem ipsum dolor sit amet, <span class="smallcaps">consectetuer</span> adipiscing elit. Donec hendrerit tempor tellus. Donec pretium posuere tellus.</p>
+<p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. <span class="smallcaps">Nulla posuere</span>. Donec vitae dolor.</p>

lua-debug-example/lua-debug-example.lua

@@ -0,0 +1,19 @@
+--[[
+# Lua Debug Example
+This filter demonstrates how to add mobdebug commands to stop execution within
+the filter functions, see README.md for details how to install and set up
+Zerobrane Studio.
+]]
+
+md = require("mobdebug")
+md.start()
+
+function Emph(elem)
+	md.pause() --breakpoint
+	return elem.content
+end
+
+function Strong(elem)
+	md.pause() --breakpoint
+	return pandoc.SmallCaps(elem.content)
+end

lua-debug-example/sample.md

@@ -0,0 +1,8 @@
+# Lua Debug Example
+
+Lorem *ipsum* dolor sit amet, **consectetuer** adipiscing elit. Donec
+hendrerit tempor tellus. Donec pretium posuere tellus.  
+
+Cum sociis natoque *penatibus* et magnis dis parturient montes,
+nascetur ridiculus mus. **Nulla posuere**. Donec vitae dolor.  
+