gdritter repos telml / e7adc06
Add a top-level README with some details Getty Ritter 8 years ago
1 changed file(s) with 87 addition(s) and 9 deletion(s). Collapse all Expand all
+87
-9
README.md less more
11 # telml
22
33 This is the repository for both the `telml` and the `telml-markup`
4 packages. The former implements a TeX-inspired data format, while
5 the latter uses that data format to implement a lightweight,
6 extensible markup format.
4 packages. The former implements a TeX-inspired data format, while the
5 latter uses that data format to implement a lightweight, extensible
6 markup format.
77
8 This repository contains a
9 [cabal.project file](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/), which facilitates building multiple packages together;
10 this repository had previously been used for just the `telml` package,
11 and the corresponding
12 [`telml-markup`](https://github.com/aisamanra/telml-markup)
13 repository is left but will not be updated.
8 ## What Is TeLML?
9
10 TeLML is a markup language I created for personal projects. You
11 probably don't want to use it! There's a good chance it doesn't cover
12 your use case, it's still subject to breaking changes, it's kind of
13 wonky, and it's probably still very buggy!
14
15 Still want to know more? Okay: TeLML is specifically a TeX-inspired
16 markup language that I created because I wanted a markup language
17 that 1. looked pleasant to me and 2. was easy to extend with new
18 constructs. As such, there are two layers to TeLML:
19
20 1. The data layer, which defines how to map a source file to a simple
21 AST. This AST is not inherently associated with any particular
22 semantics, but is rather a tree with a particular constrained shape.
23 This layer is implemented in the `telml` library.
24 2. The markup layer, which defines a common set of interpretations
25 for various AST chunks. This markup layer is HTML-inspired and
26 therefore features basic constructs like emphasis, lists, tables,
27 and images, but is specifically designed to be extended with new,
28 application-specific constructs. This layer is implemented in the
29 `telml-markup` library.
30
31 The data layer is straightforward: it borrows LaTeX syntax in a very
32 rigid, specific way. A _document_ is a sequence of fragments; in turn,
33 a _fragment_ is either a chunk of raw text, or a _tag_ associated with
34 an alphanumeric name and a sequence of documents. A _tag_ takes the
35 form `\tag_name{document1|document2|document3|...}`. In order to use
36 any of the reserved characters `\`, `{`, `}`, or `|` in plain text,
37 they should be escaped with a preceeding `\` character. Additionally,
38 at the top-level, TeLML files are parsed as a series of documents,
39 split on double-newlines.
40
41 This generic framework allows tags to be inserted easily into existing
42 text in a way that's lightweight and natural-looking to a user of
43 something like TeX. This system is, however, more consisten than TeX:
44 for example, all tags have payloads, so standalone TeX commands like
45 `\em` are not valid documents; all tag names must be followed by curly
46 braces, like `\em{}`.
47
48 The `telml-markup` library lets you interpret a pretty standard set of
49 tags as HTML, and additionally lets you add new custom tags to the
50 mix. That library is less well-specified, and could probably change
51 radically if I decide I want the semantics of tags to change.
52
53 ## Frequently Asked Questions
54
55 ### Why?
56
57 It's my party, and I'll bikeshed if I want to.
58
59 ### Why Not Markdown?
60
61 Markdown isn't easily extensible, and also it's fraught with
62 edge-cases and difficult to implement in a new language. TeLML is
63 extensible, and it's easy to write a naïve recursive descent parser
64 for it in basically any language.
65
66 ### Why Not XML?
67
68 I know XML is eXtensible, after all, but—do _you_ want to write XML by
69 hand? Because _I_ don't. Yeah, `\em{foo}` is more heavyweight than
70 Markdown's `_foo_`, but it's also a fair bit more lightweight than
71 XML's `<em>foo</em>`.
72
73 ### Why Not ReST?
74
75 Because I didn't know about its extensibility when I started writing
76 TeLML, and now this exists and I use it and I don't really want to
77 switch.
78
79 ### Why is your code so bad?
80
81 Get bent, pal.
82
83 ## Historical Note
84
85 This repository contains a [cabal.project
86 file](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/),
87 which facilitates building multiple packages together; this repository
88 had previously been used for just the `telml` package, and the
89 corresponding
90 [`telml-markup`](https://github.com/aisamanra/telml-markup) repository
91 is left but will not be updated.