| 1 |
# telml
|
| 2 |
|
| 3 |
The `telml` command-line program is the easiest way to use `telml` for your purposes. This allows you to convert a document from `telml` to HTML quickly. It also allows you to create new tags by implementing them in the Lua programming language, to easily create a richer document.
|
| 4 |
|
| 5 |
For documentation on the TeLML language itself, see [the data format documentation](https://github.com/aisamanra/telml/blob/master/telml/README.md).
|
| 6 |
|
| 7 |
## Simple usage
|
| 8 |
|
| 9 |
The usual use is as follows:
|
| 10 |
|
| 11 |
```
|
| 12 |
$ telml my-document.telml --tags=my-tags.lua
|
| 13 |
```
|
| 14 |
|
| 15 |
The `--tags` argument is optional, if you only want to use the built-in tags. You can also explicitly opt out of the built-in tags with `--no-default-tags`.
|
| 16 |
|
| 17 |
## Writing custom tags
|
| 18 |
|
| 19 |
Within the tag file, you should define your custom tags on the `telml` global table. For example, if I want a new tag called `\excited{...}` that adds an exclamation point after its argument, I can implement it like this:
|
| 20 |
|
| 21 |
```lua
|
| 22 |
-- implement a macro so that
|
| 23 |
-- \excited{Hello} => Hello!
|
| 24 |
function telml.excited(param)
|
| 25 |
return param .. "!"
|
| 26 |
end
|
| 27 |
```
|
| 28 |
|
| 29 |
TeLML recognizes tags whose names aren't valid Lua identifiers: in that case, you can always use the element access syntax to define the function as well:
|
| 30 |
|
| 31 |
```lua
|
| 32 |
-- implement a macro so that
|
| 33 |
-- \weird-name{Hello} => Hello???
|
| 34 |
telml["weird-name"] = function(param)
|
| 35 |
return param .. "???"
|
| 36 |
end
|
| 37 |
```
|
| 38 |
|
| 39 |
Lua's global state is persisted across macro invocations, so you can implement custom tags that implement non-idempotent behavior.
|
| 40 |
|
| 41 |
```lua
|
| 42 |
section = 0
|
| 43 |
function telml.section(name)
|
| 44 |
section = section + 1
|
| 45 |
return "<h1>" .. section .. ": " .. name .. "</h1>"
|
| 46 |
end
|
| 47 |
-- This produces an `h1` with an increasing number each time, so
|
| 48 |
-- \section{Foo} => <h1>1: Foo</h1>
|
| 49 |
-- \section{Bar} => <h1>2: Foo</h1>
|
| 50 |
-- \section{Baz} => <h1>3: Foo</h1>
|
| 51 |
```
|
| 52 |
|
| 53 |
You can also implement n-ary functions or variadic functions and invoke those using the TeLML multi-argument syntax:
|
| 54 |
|
| 55 |
```lua
|
| 56 |
-- implement a macro so that
|
| 57 |
-- \frac{2|4} => <sup>2</sup>/<sub>4</sub>
|
| 58 |
function telml.frac(num, denom)
|
| 59 |
return "<sup>" .. num .. "</sup>/<sub>" .. denom .. "</sub>"
|
| 60 |
end
|
| 61 |
|
| 62 |
-- implement a macro so that
|
| 63 |
-- \enum{a|b|c} => 1. a; 2. b; 3. c;
|
| 64 |
function telml.enum(...)
|
| 65 |
local args = {...}
|
| 66 |
local result = ""
|
| 67 |
for idx, arg in ipairs(args) do
|
| 68 |
result = result .. idx .. ". " .. arg .. "; "
|
| 69 |
end
|
| 70 |
return result
|
| 71 |
end
|
| 72 |
```
|
| 73 |
|
| 74 |
It is an error to return something which isn't a string or something that can be trivially converted into a string. It's also an error to include a field on the `telml` object that's not a function, and it's an error to redefine `telml` to something which isn't a table.
|
| 75 |
|
| 76 |
However, it's worth noting that Lua is pretty lax about argument-passing. Lua allows you to pass too many arguments (in which case later arguments are ignored) or too few (in which case later arguments are provided with `nil`) and TeLML inherits this behavior. If you're worried about this, you can use variadic syntax and produce explicit errors.
|
| 77 |
|
| 78 |
```lua
|
| 79 |
-- this allows \excited{a|b} and produces "a!"
|
| 80 |
function telml.excited(x)
|
| 81 |
return x .. "!"
|
| 82 |
end
|
| 83 |
|
| 84 |
-- this will fail with \excited{a|b}
|
| 85 |
function telml.safe_excited(...)
|
| 86 |
local args = {...}
|
| 87 |
if #args ~= 1 then
|
| 88 |
error("safe_excited: expected one argument, got " .. #args)
|
| 89 |
end
|
| 90 |
return args[1] .. "!"
|
| 91 |
end
|
| 92 |
```
|
| 93 |
|
| 94 |
## Built-in tags
|
| 95 |
|
| 96 |
The current built-in tags are implemented in the `telml` program. Note that most built-in tags are more particular about argument count and will balk if provided more or fewer arguments than they expect.
|
| 97 |
|
| 98 |
This list is currently subject to change.
|
| 99 |
|
| 100 |
- `\em{foo}` for italics: `<em>foo</em>`
|
| 101 |
- `\strong{foo}` for bolding: `<strong>foo</strong>`
|
| 102 |
- `\h1{foo}`, `\h2{foo}`, and so forth for headers: `<h1>foo</h1>`
|
| 103 |
- `\p{foo}` for explicit paragraphs: `<p>foo</p>`
|
| 104 |
- `\blockquote{foo}` for block quotations: `<blockquote>foo</blockquote>`
|
| 105 |
- `\tt{foo}` for inline code: `<code>foo</code>`
|
| 106 |
- `\code{foo}` for code blocks: `<pre><code>foo</code></pre>`
|
| 107 |
- `\ul{a|b}` for unordered lists: `<ul><li>a</li><li>b</li></ul>`
|
| 108 |
- `\ol{a|b}` for ordered lists: `<ol><li>a</li><li>b</li></ol>`
|
| 109 |
- `\br{}` for explicit line breaks: `<br/>`
|
| 110 |
- `\comment{foo}` for including ignored comments
|
| 111 |
- `\link{target|text}` for links: `<a href="target">text</a>`
|
| 112 |
- `\img{target|alt-text}` for links: `<img src="target">alt-text</img>`
|