boxes/docs/boxes-man-1.html

---
layout: default
title: Manpage of boxes(1)
---

<div class="well bxpage">

<h1>boxes</h1>
Section: User Commands  (1)<BR>Updated: February 16 2021<BR>
[ <A HREF="index.html">Return to Main Contents</A> ]

<h2>NAME
<a name="NAME"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">boxes - text
mode box and comment drawing filter</p>

<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><b>boxes</b>
[-hlmrv] [-a&nbsp;format] [-d&nbsp;design] [-f&nbsp;file]
[-i&nbsp;indent] [-k&nbsp;bool] [-n&nbsp;encoding]
[-p&nbsp;pad] [-s&nbsp;size] [-t&nbsp;tabopts] [infile
[outfile]]</p>

<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i> is
a text filter which can draw any kind of box around its
input text. Box design choices range from simple boxes to
complex ASCII art. A box can also be removed and repaired,
even if it has been badly damaged by editing of the text
inside. Since boxes may be open on any side, <i>boxes</i>
can also be used to create regional comments in any
programming language. New box designs of all sorts can
easily be added and shared by appending to a configuration
file.</p>

<p style="margin-left:11%; margin-top: 1em"><i>boxes</i> is
a command line tool, but also integrates with any text
editor that supports filters. The <i>boxes</i> website has
examples on how to configure editor integration for various
text editors: <br>

<a href=https://boxes.thomasjensen.com/docs/install.html>https://boxes.thomasjensen.com/docs/install.html</a></p>

<h2>OPTIONS
<a name="OPTIONS"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">Options offered
by <i>boxes</i> are the following: <b><br>
-a</b> <i>string</i></p>

<p style="margin-left:20%;">Alignment/positioning of text
inside box. This option takes a format string argument which
is read from left to right. The format string may not
contain whitespace and must consist of one or more of the
following components:</p>

<p style="margin-left:20%; margin-top: 1em"><b>h</b>x -
horizontal alignment of the input text block inside a
potentially larger box. Possible values for <i>x</i> are
<b>l</b> (ell, for left alignment), <b>c</b> (center), or
<b>r</b> (right). This does not affect the justification of
text lines within the input text block (use the <b>j</b>
argument instead). <b><br>
v</b>x - vertical alignment of the input text block inside a
potentially larger box. Possible values for <i>x</i> are
<b>t</b> (for top alignment), <b>c</b> (center), or <b>b</b>
(bottom). <b><br>
j</b>x - justification of lines within the input text block.
Possible values for <i>x</i> are <b>l</b> (ell, for left
justification), <b>c</b> (center), or <b>r</b> (right). This
does not affect the alignment of the input text block itself
within the box. Use the <b>h</b> and <b>v</b> arguments for
input text block positioning.</p>

<p style="margin-left:20%; margin-top: 1em">Short hand
notations (can be combined with the above arguments):
<b><br>
l</b> (ell) - short for <b>h</b>l<b>v</b>c<b>j</b>l <b><br>
c</b> - short for <b>h</b>c<b>v</b>c<b>j</b>c <b><br>
r</b> - short for <b>h</b>r<b>v</b>c<b>j</b>r</p>

<p style="margin-left:20%; margin-top: 1em">The factory
default setting for <b>-a</b> is <b>h</b>l<b>v</b>t.</p>

<p style="margin-left:11%;"><b>-c</b> <i>string</i></p>

<p style="margin-left:20%;">Command line design definition
for simple cases. The argument of this option is the
definition for the &quot;west&quot; (W) shape. The defined
shape must consist of exactly one line, i.e. no multi-line
shapes are allowed. The <b>-c</b> option is intended as a
shortcut for those cases where simple regional comments are
to be created, which only need a certain character or
sequence of characters to be placed in front of every line.
In such cases, it is much more convenient to simply specify
<b>-c</b> than to do a complete design definition in
one&rsquo;s config file, where the only shape defined is the
west shape. <br>
This option implies a <b>-d</b> and does not access the
config file. <b>-c</b> may of course be used in conjunction
with any of the other options. By default, <b>-c</b> is not
specified.</p>

<p style="margin-left:11%;"><b>-d</b> <i>string</i></p>

<p style="margin-left:20%;">Design selection. The one
argument of this option is the name of the design to
use.</p>

<p style="margin-left:11%;"><b>-f</b> <i>string</i></p>

<p style="margin-left:20%;">Use alternate config file. The
one argument of this option is the name of a valid
<i>boxes</i> config file, containing new and exciting
designs!</p>

<p style="margin-left:11%;"><b>-h</b></p>

<p style="margin-left:20%;">Print usage information.</p>

<p style="margin-left:11%;"><b>-i</b> <i>string</i></p>

<p style="margin-left:20%;">Indentation mode. Possible
arguments are &quot;text&quot; (indent text inside of box),
&quot;box&quot; (indent box, not text inside of box), or
&quot;none&quot; (throw away indentation). Arguments may be
abbreviated. The default is to indent the box, but not the
text.</p>

<p style="margin-left:11%;"><b>-k</b> <i>bool</i></p>

<p style="margin-left:20%;">Kill leading/trailing blank
lines on removal. The value of <i>bool</i> can be specified
as on, yes, true, 1, or t, all meaning yes, or off, no,
false, 0, or f, which mean no. This is case-insensitive.
This option only takes effect in connection with <b>-r</b>.
If set to yes, leading and trailing blank lines will be
removed from the output. If set to no, the entire content of
the former box is returned. The default is no, if both the
top and the bottom part of the box are open, as is the case
with most regional comments. If the box&rsquo;s design
defines a top part or a bottom part, the default is yes.</p>

<p style="margin-left:11%;"><b>-l</b></p>

<p style="margin-left:20%;">(ell) List designs. Produces a listing of all available
box designs in the config file, along with a sample box and
information about it&rsquo;s creator. Also checks syntax of
the entire config file. If used in connection with
<b>-d</b>, displays detailed information about the specified
design.</p>

<p style="margin-left:11%;"><b>-m</b></p>

<p style="margin-left:20%;">Mend box. This removes a (potentially broken) box as
with <b>-r</b>, and redraws it afterwards. The mended box is
drawn according to the options given. This may be important
to know when it comes to restoring padding, indentation,
etc. for the mended box. Implies <b>-k</b> false.</p>

<p style="margin-left:11%;"><b>-n</b> <i>encoding</i></p>

<p style="margin-left:20%;">Character encoding. Overrides
the character encoding of the input and output text. Choose
from the list shown by <i>iconv -l</i>. If an invalid
character encoding is specified here, <i>UTF-8</i> is used
as a fallback. The default is to use the system encoding,
which is normally the best course of action. So don&rsquo;t
specify this option unless you have to.</p>

<p style="margin-left:11%;"><b>-p</b> <i>string</i></p>

<p style="margin-left:20%;">Padding. Specify padding in
spaces around the input text block for all sides of the box.
The argument string may not contain whitespace and must
consist of a combination of the following characters, each
followed by a number indicating the padding in spaces:
<b><br>
a</b> - (all) give padding for all sides at once <b><br>
h</b> - (horiz) give padding for both horizontal sides
<b><br>
v</b> - (vertical) give padding for both vertical sides
<b><br>
b</b> - (bottom) give padding for bottom (south) side
<b><br>
l</b> - (left) give padding for left (west) side <b><br>
t</b> - (top) give padding for top (north) side <b><br>
r</b> - (right) give padding for right (east) side <br>
Example: <b>-p a</b>4<b>t</b>2 would define the padding to
be 4 characters on all sides, except for the top of the box,
where the input text block will be only 2 lines away from
the box. <br>
By default, unless specified otherwise in the config file,
no padding is used.</p>

<p style="margin-left:11%;"><b>-r</b></p>

<p style="margin-left:20%;">Remove box. Removes an existing box instead of drawing
it. Which design to use is detected automatically. In order
to save time or in case the detection does not decide
correctly, combine with <b>-d</b> to specify the design. The
default is to draw a new box.</p>

<p style="margin-left:11%;"><b>-s</b>
<i>width</i><b>x</b><i>height</i></p>

<p style="margin-left:20%;">Box size. This option specifies
the desired box size in units of columns (for width) and
lines (for height). If only a single number is given as
argument, this number specifies the desired box width. A
single number prefixed by &rsquo;x&rsquo; specifies only the
box height. The actual resulting box size may vary depending
on the individual shape sizes of the chosen design. Also,
other command line options may influence the box size (such
as <b>-p</b>). <br>
By default, the smallest possible box is created around the
text.</p>

<p style="margin-left:11%;"><b>-t</b> <i>string</i></p>

<p style="margin-left:20%;">Tab handling. This option
controls how tab characters in the input text are handled.
The option string must always begin with a <i>uint</i>
number indicating the distance between tab stops. It is
important that this value be set correctly, or tabulator
characters will upset your input text. The correct tab
distance value depends on the settings used for the text you
are processing. A common value is 8. <br>
Immediately following the tab distance, an optional
character can be appended, telling <i>boxes</i> how to treat
the leading tabs. The following options are available:
<b><br>
e</b> - expand tabs into spaces <b><br>
k</b> - keep tabs as close to what they were as possible
<b><br>
u</b> - unexpand tabs. This makes <i>boxes</i> turn as many
spaces as possible into tabs.</p>

<p style="margin-left:20%; margin-top: 1em">In order to
maintain backwards compatibility, the <b>-t</b>
<i>string</i> can be just a number. In that case, <b>e</b>
is assumed for tab handling, which removes all tabs and
replaces them with spaces. The factory default for the
<b>-t</b> option is simply 8, which is just such a case.
<br>
For example, you could specify <b>-t</b> 4u in order to have
your leading tabs unexpanded. In the box content, tabs are
always converted into spaces. The tab distance in this
example is 4.</p>

<p style="margin-left:11%;"><b>-v</b></p>

<p style="margin-left:20%;">Print out current version number.</p>


<h2>CONFIGURATION FILES
<a name="CONFIGURATION FILES"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
will use the configuration file specified on the command
line (using <b>-f</b>). If no config file is specified on
the command line, <i>boxes</i> will check for the BOXES
environment variable, which may contain a filename to use.
If BOXES is not set, <i>boxes</i> will try to read
$HOME/.boxes and use it as a config file. Failing that,
<i>boxes</i> will try to read the system-wide config file
(see FILES).</p>

<p style="margin-left:11%; margin-top: 1em">The syntax of
<i>boxes</i> config files is described on the website.</p>

<h2>EXAMPLES
<a name="EXAMPLES"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">Examples on how
to invoke <i>boxes</i> may be found on the website at
<a href=https://boxes.thomasjensen.com/examples.html>https://boxes.thomasjensen.com/examples.html</a>.
Try</p>

<p style="margin-left:11%; margin-top: 1em">
<pre style="margin-left:11%"><code>echo &quot;Good Bye World!&quot; | boxes -d nuke</code></pre></p>

<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
also combines nicely with other tools. Try</p>

<p style="margin-left:11%; margin-top: 1em">
<pre style="margin-left:11%"><code>figlet &quot;boxes . . . !&quot; | lolcat -f | boxes -d unicornthink</code></pre></p>

<h2>AVAILABILITY
<a name="AVAILABILITY"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">The
<i>boxes</i> website is
<a href=https://boxes.thomasjensen.com/>https://boxes.thomasjensen.com/</a>. It contains a
number of examples illustrating this manual page as well as
more in-depth documentation.</p>

<h2>AUTHOR
<a name="AUTHOR"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
was made by Thomas Jensen and many great contributors. <br>
For a full list, see <br>

<a href=https://boxes.thomasjensen.com/contributing.html#contributors>https://boxes.thomasjensen.com/contributing.html#contributors</a>
<br>
and
<a href=https://github.com/ascii-boxes/boxes/graphs/contributors>https://github.com/ascii-boxes/boxes/graphs/contributors</a>.
<br>
Please refer to the <i>boxes</i> website for the
maintainer&rsquo;s current email address.</p>

<h2>VERSION
<a name="VERSION"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">This is
<i>boxes</i> version 2.0.0.</p>

<h2>LICENSE
<a name="LICENSE"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><i>boxes</i> is
free software under the terms of the GNU General Public
License, version 2. Details in the LICENSE file:
<a href=https://raw.githubusercontent.com/ascii-boxes/boxes/v2.0.0/LICENSE>https://raw.githubusercontent.com/ascii-boxes/boxes/v2.0.0/LICENSE</a></p>

<h2>ENVIRONMENT
<a name="ENVIRONMENT"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
recognizes the following environment variables:</p>

<p style="margin-left:11%; margin-top: 1em">HOME</p>

<p style="margin-left:26%;">The user&rsquo;s home directory.</p>

<p style="margin-left:11%; margin-top: 1em">BOXES</p>

<p style="margin-left:26%;">Name of <i>boxes</i> configuration file, if different
from ~/.boxes.</p>



<h2>FILES
<a name="FILES"></a>
</h2>

<p style="margin-left:11%; margin-top: 1em">$HOME/.boxes</p>

<p style="margin-left:26%;"><i>boxes</i> configuration file
(takes precedence over system-wide configuration file)</p>

<p style="margin-left:11%;">/usr/share/boxes</p>

<p style="margin-left:26%;">system-wide configuration
file</p>

<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>



<p style="margin-left:11%; margin-top: 1em"><b>figlet</b>(6),
<b>iconv</b>(1), <b>lolcat</b>(6)</p>
</div>