@@ -797,9 +797,19 @@ M.UpperAlpha = "UpperAlpha"
797797-- @section helpers
798798
799799--- Parse the given string into a Pandoc document.
800−-- @tparam string markup the markup to be parsed
800+-- The method used to interpret input is specified by *format*. Acceptable
801+-- values for this parameter are equal to those that can be given to the
802+-- `--from` command line option.
803+-- @tparam string markup the markup to be parsed
801804-- @tparam[opt] string format format specification, defaults to "markdown".
802805-- @return Doc pandoc document
806+-- @usage
807+-- local org_markup = "/emphasis/" -- Input to be read
808+-- local document = pandoc.read(org_markup, "org")
809+-- -- Get the first block of the document
810+-- local block = document.blocks[1]
811+-- -- The inline element in that block is an `Emph`
812+-- assert(block.content[1].t == "Emph")
803813function M.read(markup, format)
804814 format = format or "markdown"
805815 local pd = pandoc.__read(format, markup)