Man Linux: Main Page and Category List


       boxes - text mode box and comment drawing filter


       boxes  [-hlrv]  [-a format] [-d design] [-f file] [-i indent] [-k bool]
       [-p pad] [-s size] [-t tabs] [infile [outfile]]


       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
       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 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

       -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
             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.


       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.


       boxes  is  available  from  its   World   Wide   Web   home   page   at  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!


       boxes was made by Thomas Jensen.
       Please see the boxes Web page for a current email address.


       This is boxes version 1.0.1a.


       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


       HOME           The user’s home directory.

       BOXES          Name  of  boxes  configuration  file,  if different from


       $HOME/.boxes   boxes configuration file

                      system-wide configuration file


       indent(1) , tal(1) , vim(1)