gdritter repos telml / master README.md
master

Tree @master (Download .tar.gz)

README.md @masterview markup · raw · history · blame

telml

This is the repository for both the telml and the telml-markup packages. The former implements a TeX-inspired data format, while the latter uses that data format to implement a lightweight, extensible markup format.

What Is TeLML?

TeLML is a markup language I created for personal projects. You probably don't want to use it! There's a good chance it doesn't cover your use case, it's still subject to breaking changes, it's kind of wonky, and it's probably still very buggy!

Still want to know more? Okay: TeLML is specifically a TeX-inspired markup language that I created because I wanted a markup language that 1. looked pleasant to me and 2. was easy to extend with new constructs. As such, there are two layers to TeLML:

  1. The data layer, which defines how to map a source file to a simple AST. This AST is not inherently associated with any particular semantics, but is rather a tree with a particular constrained shape. This layer is implemented in the telml library.
  2. The markup layer, which defines a common set of interpretations for various AST chunks. This markup layer is HTML-inspired and therefore features basic constructs like emphasis, lists, tables, and images, but is specifically designed to be extended with new, application-specific constructs. This layer is implemented in the telml-markup library.

The data layer is straightforward: it borrows LaTeX syntax in a very rigid, specific way. A document is a sequence of fragments; in turn, a fragment is either a chunk of raw text, or a tag associated with an alphanumeric name and a sequence of documents. A tag takes the form \tag_name{document1|document2|document3|...}. In order to use any of the reserved characters \, {, }, or | in plain text, they should be escaped with a preceeding \ character. Additionally, at the top-level, TeLML files are parsed as a series of documents, split on double-newlines.

This generic framework allows tags to be inserted easily into existing text in a way that's lightweight and natural-looking to a user of something like TeX. This system is, however, more consisten than TeX: for example, all tags have payloads, so standalone TeX commands like \em are not valid documents; all tag names must be followed by curly braces, like \em{}.

The telml-markup library lets you interpret a pretty standard set of tags as HTML, and additionally lets you add new custom tags to the mix. That library is less well-specified, and could probably change radically if I decide I want the semantics of tags to change.

Frequently Asked Questions

Nobody has asked me these, but I assume that if someone wanted to ask me questions, they would probably be some of these.

Why?

It's my party, and I'll bikeshed if I want to.

Why not Markdown?

Markdown isn't easily extensible, and also it's fraught with edge-cases and difficult to implement in a new language. TeLML is extensible, and it's easy to write a naïve recursive descent parser for it in basically any language.

Why not XML?

I know XML is eXtensible, after all, but—do you want to write XML by hand? Because I don't. Yeah, \em{foo} is more heavyweight than Markdown's _foo_, but it's also a fair bit more lightweight than XML's <em>foo</em>.

Why not ReStructured Text?

Because I didn't know about its extensibility when I started writing TeLML, and now this exists and I use it and I don't really want to switch.

Are there other language implementations?

I have less-polished Scheme and Rust implementations that I haven't put online yet. I'm planning on using the Rust implementation for a project at some point, so it might show up before too long.

Why is your code so bad?

Get bent, pal.

Historical Note

This repository contains a cabal.project file, which facilitates building multiple packages together; this repository had previously been used for just the telml package, and the corresponding telml-markup repository is left but will not be updated.