NAME
boxes - text mode box and comment drawing filter
SYNOPSIS
boxes [-hlrv] [-a format] [-d design] [-f file] [-i indent] [-k bool]
[-p pad] [-s size] [-t tabs] [infile [outfile]]
DESCRIPTION
boxes is a text filter which can draw any kind of ASCII art box around
its input text. A box can also be removed, even if it has been badly
damaged by editing of the text inside. Since boxes may be open on any
side, boxes can also be used to create regional comments in any
programming language. With the help of an editor macro/mapping,
damaged boxes can easily be repaired. New box designs of all sorts can
easily be added and shared by appending to a free format configuration
file.
boxes was intended to be used with the vim(1) text editor, but can be
tied to any text editor which supports filters, as well as from the
command line as a standalone tool.
OPTIONS
Options offered by boxes are the following:
-a string
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:
hx - horizontal alignment of the input text block inside a
potentially larger box. Possible values for x are l (ell, for
left alignment), c (center), or r (right). This does not affect
the justification of text lines within the input text block (use
the j argument instead).
vx - vertical alignment of the input text block inside a
potentially larger box. Possible values for x are t (for top
alignment), c (center), or b (bottom).
jx - justification of lines within the input text block. Possible
values for x are l (ell, for left justification), c (center), or
r (right). This does not affect the alignment of the input text
block itself within the box. Use the h and v arguments for input
text block positioning.
Short hand notations (can be combined with the above arguments):
l - (ell) short for hlvcjl
c - short for hcvcjc
r - short for hrvcjr
The factory default setting for -a is hlvt.
-d string
Design selection. The one argument of this option is the name of
the design to use.
-f string
Use alternate config file. The one argument of this option is the
name of a valid boxes config file, containing new and exciting
designs!
-h Print usage information.
-i string
Indentation mode. Possible arguments are "text" (indent text
inside of box), "box" (indent box, not text inside of box), or
"none" (throw away indentation). Arguments may be abbreviated.
The default is to indent the box, but not the text.
-k bool
Kill leading/trailing blank lines on removal. The value of bool
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 -r. 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’s design defines a top part or a bottom part, the
default is yes.
-l (ell) List designs. Produces a listing of all available box
designs in the config file, along with a sample box and
information about it’s creator. Also checks syntax of the entire
config file. If used in connection with -d, displays detailed
information about the specified design.
-p string
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:
a - (all) give padding for all sides at once
h - (horiz) give padding for both horizontal sides
v - (vertical) give padding for both vertical sides
b - (bottom) give padding for bottom (south) side
l - (left) give padding for left (west) side
t - (top) give padding for top (north) side
r - (right) give padding for right (east) side
Example: -p a4t2 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.
By default, unless specified otherwise in the config file, no
padding is used.
-r 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 -d
to specify the design. The default is to draw a new box.
-s widthxheight
Box size. If a single number is given as argument, this defaults
to the box width. ’x’, followed by a single number specifies the
box height. Giving both the box width and height is left as an
exercise to the reader. :-) The actual box size may vary
depending on the individual shape sizes. By default, the
smallest possible box is created around the text.
-t uint
Distance between tab stops. It is important that this value is
set correctly, or tabulator characters will upset your input
text. The correct value for -t depends on the settings used for
the text you are processing. Usually, a value of 8 should be
okay. The factory default for -t is 8.
-v Print out current version number.
CONFIGURATION FILES
Boxes will use the configuration file specified on the command line
(using -f). If no config file is specified on the command line, boxes
will check for the BOXES environment variable, which may contain a
filename to use. If BOXES is not set, boxes will try to read
$HOME/.boxes and use it as a config file. Failing that, boxes will try
to read the system-wide config file (see FILES).
The syntax of boxes config files is described on the Web page (see
below). They are quite self-explanatory, though.
AVAILABILITY
boxes is available from its World Wide Web home page at
http://home.pages.de/~jensen/boxes/. The Web page also features a
number of examples illustrating this manual page as well as more in-
depth documentation.
Check out the vim(1) home page at www.vim.org!
AUTHOR
boxes was made by Thomas Jensen.
Please see the boxes Web page for a current email address.
VERSION
This is boxes version 1.0.1a.
BUGS
Although it is doing great in most cases, imho the design autodetector
needs some more work.
Should you notice any other unspecified behavior, please tell the
author!
ENVIRONMENT
HOME The user’s home directory.
BOXES Name of boxes configuration file, if different from
~/.boxes.
FILES
$HOME/.boxes boxes configuration file
/etc/boxes/boxes-config
system-wide configuration file
SEE ALSO
indent(1) , tal(1) , vim(1)