FAQ

These are the frequently asked questions about the boxes program and their answers.

These questions are actually “frequently asked”. For general information on the boxes program, installation instructions, and information on box design creation please refer to the boxes documentation.

Q. 1. What is a text filter program?

There is a separate page explaining this. Boxes is mostly used as such a filter program.

Q. 2. Error message "input in flex scanner failed"

Upgrade to version 1.0.1 or later. Versions prior to 1.0.1 gave this error message when the config file they were trying to read was in fact a directory. The global config file name is /usr/share/boxes on most systems. This is the name of the file, not the name of a directory into which a config file would be placed.

Q. 3. Boxes destroys my tabs!

By default, all tab characters are replaced by spaces. However, you can change this behavior using the -t option (since version 1.1). The -t option only affects leading tabs. Tabs which end up inside the box are always converted into spaces.
Note that you can also set the tab stop distance (== how many spaces per tab) using the -t option.

Q. 4. "Can't read file C:\TEMP\VIO44.TMP" when calling boxes from vim

On Windows, this error message may appear instead of a box when boxes is called from vim. This is not a problem of boxes. In fact, it’s a misleading message from the vim editor which is supposed to tell you that boxes is not in your PATH. Solution: Copy boxes.exe and boxes.cfg to a directory which is in your PATH. (thanks Jeff Lanzarotta, 05-Jul-00)

Q. 5. Compilation

Detailed information on how to build boxes from source is collected on the build page.

In addition to that, the following issues have occurred:

• Custom library locations
  If you have manually provided some of the libraries that boxes uses for building, such as pcre2 or libunistring, you may need to tell our build where to find them. For this, use the CFLAGS_ADDTL and LDFLAGS_ADDTL environment variables. They can be used to add options to the compiler and linker calls. For example:

  make CFLAGS_ADDTL=-I/Users/USER/local/include LDFLAGS_ADDTL=-L/Users/USER/local/lib
  

• Bad address on boxes execution after compiling on a 64bit system: This may happen when the system you are compiling on is 64bit. Boxes is only a 32bit program, so the compiler may have to be forced to 32bit by adding the -m32 option. (Thanks to @stefanow for supplying this information!) In order to do this, use the following command line (works with current sources):

  make CFLAGS_ADDTL=-m32 LDFLAGS_ADDTL=-m32
  

• Compilation on SLES:
  On SLES, you might need to add -std=c99 as observed by @mathomp4 in #74.

Q. 6. Character Encoding

Since v2.0.0, boxes supports different character encodings for input/output text. The config file, however, is still ASCII (we are working on that). boxes normally picks up your system encoding, which on most systems, is simply UTF-8. You can override this behavior with -n. boxes shows what it thinks is the system encoding when you call boxes -h - the displayed default value for -n is the system encoding.

Q. 7. How to align a box within a terminal window?

The boxes options only allow aligning the text within a box, but it is actually possible to use boxes to align the entire box within a terminal window. At least on Unix / Linux … we don’t currently know how to do this on Windows.

This method assumes that tput cols yields the width of the terminal window. If it doesn’t, you’d have to find another way to get this information, for example a $COLUMNS environment variable.

Centered:

echo -e foo\\ncenter | boxes -d parchment -p h5 | boxes -s $(tput cols) -c x -a hc -i none | cut -c 2-

Right-aligned:

echo -e foo\\nright-aligned | boxes -d parchment -p h5 | boxes -s $(tput cols) -c x -a hr -i none | sed -e 's/^x/ /'

Note that we -a hc instead of just -ac, because we want to align the whole block of text, not individual lines.
The result looks like this:

Q. 8. Can you rewrite this in X?

Short answer: No.

Long answer: I know, boxes is written in C, which was a perfectly reasonable choice given that it was made in the 1990s. A lot of software was written in C at the time. It was one of the most portable ways of writing software. And it requires no runtime like Java or Python would. Today (2024), we have Go, and Rust, and other comparatively new languages available that would be a great fit for boxes and offer far superior developer experience. So why not rewrite boxes in one of those?

As Joel Spolsky explains in his epic blog post “Things You Should Never Do, Part I”, rewriting a codebase is most likely a horrible mistake, and generally a project that is likely to fail. Even if it wasn’t really a rewrite, but rather we take the C code and cross-compile it to something else, that would at best double our maintenance effort. I’ve been maintaining boxes for over 25 years now, and you can imagine that my life is very different now than it was then. boxes is kept going on a very slim time budget. I need to be careful and choose my battles wisely. That doesn’t mean large efforts are totally out of the question, as we see with Unicode and color support which was eventually added. But it took many years to do that. A rewrite, or even just a major increase in support effort, is just not possible.

So it comes down to effort for me. On the upside, that means that if you were to contribute a reimplementation of boxes in another language, and that implementation passed the end-to-end test suite, then that’s great! If you’d be willing to do all the maintenance, I would host it under the ascii-boxes group on GitHub!