Description
@tarleb A couple small notes about the Lua interface and documentation:
-
I always have lots of trouble, when I'm looking up documentation, distinguishing the Image function that is used as a handler (https://pandoc.org/lua-filters.html#type-image) and the Image function that is used to produce an image (https://pandoc.org/lua-filters.html#pandoc.image). How can we distinguish these to avoid confusion? Would it help to make the title heading
pandoc.Image(..)
instead ofImage(...)
? Should we have two sections, Handlers and Builders? -
The docs for the Header handler mistakenly say it creates an element. https://pandoc.org/lua-filters.html#type-header
-
For DefinitionList (both handler and builder), there is no documentation about what type the contents list elements have.
-
I wonder whether we need all the namespaces? e.g.
walk_block
is in the mainpandoc
namespace, whileblocks_to_inlines
is inpandoc.util
;read
is inpandoc
, whileciteproc
is inpandoc.utils
-- this is hard to remember, and is there a good reason for it? Also maybeVersion
could go inpandoc
? The existing modules could be preserved and the names reexported frompandoc
, for backwards compatibility. Themediabag
,path
, etc. modules do seem necessary.