boxes(1)						      General Commands Manual							  boxes(1)

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  pro-
       gramming 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  align-
	     ment), 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 white-
	     space 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  exam-
       ples 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)

4th Berkeley Distribution					  August 22 1999							  boxes(1)