size: 4 KiB

  

.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DJOT" "1" "" "djot 0.2.1" ""
.hy
.SH NAME
.PP
djot \[en] converts djot markup.
.SH SYNOPSIS
.PP
djot options [file..]
.SH DESCRIPTION
.PP
djot is a command-line parser for djot markup (https://djot.net).
It can produce
.IP \[bu] 2
an HMTL document (default behavior)
.IP \[bu] 2
a stream of annotated tokens with byte offsets (\f[V]--matches\f[R])
.IP \[bu] 2
an AST in either human-readable or JSON form (\f[V]--ast\f[R]).
.SH OPTIONS
.TP
\f[V]--matches, -m\f[R]
Show matches (annotated tokens with source positions).
.TP
\f[V]--ast\f[R], \f[V]-a\f[R]
Produce and render an abstract syntax tree.
.TP
\f[V]--json\f[R], \f[V]-j\f[R]
Use machine-readable JSON format when used with \f[V]--matches\f[R] or
\f[V]--ast\f[R].
.TP
\f[V]--sourcepos\f[R], \f[V]-p\f[R]
Include source positions in the AST or HTML document.
.TP
\f[V]--filter\f[R] \f[I]FILE\f[R], \f[V]-f\f[R] \f[I]FILE\f[R]
Run the filter defined in \f[I]FILE\f[R] on the AST between parsing and
rendering.
The \f[V]--filter\f[R] option may be used multiple times; filters will
be applied in the order specified on the command line.
See FILTERS below for a description of filters.
.TP
\f[V]--verbose\f[R], \f[V]-v\f[R]
Verbose output, including warnings.
.TP
\f[V]--version\f[R]
Print the djot version.
.TP
\f[V]--help\f[R], \f[V]-h\f[R]
Print usage information.
.SH FILTERS
.PP
Filters are small Lua programs that modify the parsed document prior to
rendering.
Here is an example of a filter that capitalizes all the content text in
a document:
.IP
.nf
\f[C]
return {
  str = function(e)
     e.text = e.text:upper()
   end
}
\f[R]
.fi
.PP
Save this as \f[V]caps.lua\f[R] use tell djot to use it using
.IP
.nf
\f[C]
djot --filter caps input.djot
\f[R]
.fi
.PP
Note that djot will search your LUA_PATH for the filter if it is not
found in the working directory, so you can in principle install filters
using luarocks.
.PP
Here\[cq]s a filter that prints a list of all the URLs you link to in a
document.
This filter doesn\[cq]t alter the document at all; it just prints the
list to stderr.
.IP
.nf
\f[C]
return {
  link = function(el)
    io.stderr:write(el.destination .. \[dq]\[rs]n\[dq])
  end
}
\f[R]
.fi
.PP
A filter walks the document\[cq]s abstract syntax tree, applying
functions to like-tagged nodes, so you will want to get familiar with
how djot\[cq]s AST is designed.
The easiest way to do this is to use \f[V]djot --ast\f[R].
.PP
By default filters do a bottom-up traversal; that is, the filter for a
node is run after its children have been processed.
It is possible to do a top-down travel, though, and even to run separate
actions on entering a node (before processing the children) and on
exiting (after processing the children).
To do this, associate the node\[cq]s tag with a table containing
\f[V]enter\f[R] and/or \f[V]exit\f[R] functions.
The following filter will capitalize text that is nested inside
emphasis, but not other text:
.IP
.nf
\f[C]
local capitalize = 0
return {
   emph = {
     enter = function(e)
       capitalize = capitalize + 1
     end,
     exit = function(e)
       capitalize = capitalize - 1
     end,
   },
   str = function(e)
     if capitalize > 0 then
       e.text = e.text:upper()
      end
   end
}
\f[R]
.fi
.PP
For a top-down traversal, you\[cq]d just use the \f[V]enter\f[R]
functions.
If the tag is associated directly with a function, as in the first
example above, it is treated as an \[ga]exit\[cq] function.
.PP
It is possible to inhibit traversal into the children of a node, by
having the \f[V]enter\f[R] function return the value true (or any truish
value, say \f[V]\[dq]stop\[dq]\f[R]).
This can be used, for example, to prevent the contents of a footnote
from being processed:
.IP
.nf
\f[C]
return {
 footnote = {
   enter = function(e)
     return true
   end
  }
}
\f[R]
.fi
.PP
A single filter may return a table with multiple tables, which will be
applied sequentially.
.SH AUTHORS
.PP
John MacFarlane (<jgm@berkeley.edu>).