Burro

Hello world!

Introducing Burro and this blog • 2023-06-20Michael Rees


Overview

Burro is a new digital typesetting language, designed with ease of typing in mind. It aims to combine the light syntax and convenience of Markdown with the power of TeX.

Burro is intended for text-heavy documents. Here are a few types of documents for which Burro is well suited:

  • Résumés
  • User manuals
  • Concert programs
  • Letters
  • Novels

Note that scientific papers are not listed! Burro is happy to stand aside and let TeX's dominance in that field remain unopposed. Burro restricts its niche to text and images, which lets it focus on what it does best. Burro does aim to become a competitor to TeX in plain typesetting.

If you've used groff, Burro might seem familiar to you, which is no accident! I often describe Burro as a spiritual successor to the mom macro set for groff. mom is the direct inspiration for Burro.

The URL for these posts is https://burro.sh/blog, which I guess makes this a blog. If I could get away with it, I might call this a dlog, short for "development log." Another good name would be "development diary." I'll make weekly posts discussing the latest development news, features added, bugs fixed, etc. When I've been too busy to make any actual progress, I'll instead post something about the vision/roadmap or features that are already implemented but worth noting.

Current status

The current version of Burro is a rewrite of an old project. I first started working on Burro in 2018. The problem was that the original syntax was horrible. I lost enthusiasm because I knew I needed to think of a different approach, but couldn't find it at the time.

In January 2023, I began sketching out some new ideas and liked the direction Burro went in. I implemented them—first in OCaml, then in Rust after deciding I wanted access to rustybuzz—and the new version of Burro was born.

If you looked at the main repository sometime last week, you'd be forgiven for thinking that Burro was dead. Before yesterday, the most recent commit was February 25, nearly four months ago. The project was never dead, just in a form of hibernation. After that February 25 commit, I began working on adding columns. This ended up being annoyingly tricky—not impossible by any means, but there were many problems to work through. At the same time, my personal life entered one of its busiest stretches ever. (I'm an organist for my day job, and gave 10 concerts between January and June this year, which doesn't count Holy Week!) I didn't have time to work out those kinks, so I had to step away for a while.

Now that the aforementioned period has settled down, I'm able to resume work on Burro. Burro is already reasonably powerful. Many important features are still missing, but you can successfully create documents with the existing commands.

What's next?

Here's a rough sketch of what's left to do prior to the 0.1 release:

  • Tab stops
  • Continued work on columns (e.g., manual column breaks, balanced column mode)
  • Individual margin controls
  • Additional font weights

All open bugs (not planned features) on the issue tracker will be fixed before 0.1.

Documentation has not been a priority yet, but all of the commands will be documented before the 0.1 release. The documentation will be written in—what else?—Burro!

Similarly, Burro only supports English so far. This will remain true until after 0.1. Burro will support all languages and scripts, including right-to-left scripts and similar, by its 1.0 release.

The main focus in 0.2 will be a macro system. This will enable users to create their own commands and share packages rather than having to insert the same formatting every time. Some commands that are currently built-in may move to being macros, and some planned macros might end up being commands. Expect fluidity here!

Want to help?

Wonderful! I'm planning on handling the features discussed above up until 0.1 myself, but here's a list of things that the Burro community will need that it would be great to have others start on:

  • Editor plugins
  • Burro-to-Markdown and Markdown-to-Burro converters
  • Layout tests

You're also welcome to fix any bugs in the issue tracker.

Following the 0.1 release, I'll formalize a contributing process and make it easier to collaborate on planned features. Those will then be open to the community as well.

Of course, the most important thing you can do to help Burro is to use it and share your experience!

Thank you for your interest in Burro. Welcome to the community!

Have a comment or want to start a discussion? Please email it to the Burro discussion list!