[API Change] Base custom writers on Writer type.

The `T.P.Lua.writeCustom` function changed to allow either a TextWriter
or ByteStringWriter to be returned. The global variables
`PANDOC_DOCUMENT` and `PANDOC_WRITER_OPTIONS` are no longer set when the
writer script is loaded. Both variables are still set in classic writers
before the conversion is started, so they can be used when they are
wrapped in functions.

1 files changed, 9 insertions, 1 deletions

diff --git a/doc/custom-writers.md b/doc/custom-writers.md
index fc839c8a0..bb61be9da 100644
--- a/doc/custom-writers.md
+++ b/doc/custom-writers.md
@@ -81,7 +81,7 @@ end
 Custom writers using the new style must contain a global function
 named `Writer`. Pandoc calls this function with the document and
 writer options as arguments, and expects the function to return a
-string.
+UTF-8 encoded string.
 
 ``` lua
 function Writer (doc, opts)
@@ -89,6 +89,14 @@ function Writer (doc, opts)
 end
 ```
 
+Writers that do not return text but binary data should define a
+function with name `BinaryWriter` instead. The function must still
+return a string, but it does not have to be UTF-8 encoded and can
+contain arbitrary binary data.
+
+If both `Writer` and `BinaryWriter` functions are defined, then
+only the `Writer` function will be used.
+
 ## Example: modified Markdown writer
 
 Writers have access to all modules described in the [Lua filters