Seth Woolley's Man Viewer

boxes(1) - boxes - text mode box and comment drawing filter - man 1 boxes

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

boxes(1)                                                              boxes(1)



NAME
       boxes - text mode box and comment drawing filter(1,3x,3x curs_util)

SYNOPSIS
       boxes  [-hlrv]  [-a format] [-d design] [-f file(1,n)] [-i indent] [-k bool]
       [-p pad] [-s size] [-t tabs] [infile [outfile]]

DESCRIPTION
       boxes is a text filter(1,3x,3x curs_util) which can draw any kind of ASCII art box  around
       its  input  text.  A box can also be removed, even if(3,n) it has been badly
       damaged by editing of the text inside. Since boxes may be open(2,3,n)  on  any
       side,  boxes  can  also be used to create regional comments in(1,8) 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(3,n)
             Alignment/positioning of text inside box.  This  option  takes  a
             format string(3,n) argument which is read(2,n,1 builtins) from left to right. The for-
             mat string(3,n) 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 poten-
             tially 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 poten-
             tially larger box. Possible values for x are t  (for  top  align-
             ment), 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(3,n)
             Design  selection. The one argument of this option is the name of
             the design to use.

       -f string(3,n)
             Use alternate config(1,5) file. The one argument of this option is the
             name  of  a  valid boxes config(1,5) file(1,n), containing new and exciting
             designs!

       -h    Print usage information.

       -i string(3,n)
             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(1,8) connection with -r.  If  set(7,n,1 builtins)  to
             yes,  leading  and  trailing blank lines will be removed from the
             output. If set(7,n,1 builtins) to no, the entire content of  the  former  box  is
             returned.  The default is no, if(3,n) both the top and the bottom part
             of the box are open(2,3,n), 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(1,8) the config(1,5) file(1,n), along with a sample box and informa-
             tion about it's creator.  Also checks syntax of the entire config(1,5)
             file.  If  used in(1,8) connection with -d, displays detailed informa-
             tion about the specified design.

       -p string(3,n)
             Padding. Specify padding in(1,8) spaces around the  input  text  block
             for  all  sides  of  the box. The argument string(3,n) may not contain
             whitespace and must consist of a  combination  of  the  following
             characters,  each  followed by a number indicating the padding in(1,8)
             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(1,8)  the  config(1,5)  file(1,n),  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(1,2,n) or
             in(1,8)  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 depend-
             ing on the individual shape sizes.  By default, the smallest pos-
             sible box is created around the text.

       -t uint
             Distance  between  tab  stops. It is important that this value is
             set(7,n,1 builtins) 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(1,3,5) number.

CONFIGURATION FILES
       Boxes  will  use  the  configuration file(1,n) specified on the command line
       (using -f).  If no config(1,5) file(1,n) 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(7,n,1 builtins),  boxes  will  try  to  read(2,n,1 builtins)
       $HOME/.boxes  and use it as a config(1,5) file. Failing that, boxes will try
       to read(2,n,1 builtins) the system-wide config(1,5) file(1,n) (see FILES).

       The syntax of boxes config(1,5) 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  num-
       ber  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,3,5) 1.0.1.

BUGS
       Although it is doing great in(1,8) 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(1,n),  if(3,n)  different  from
                      ~/.boxes.

FILES
       $HOME/.boxes   boxes configuration file(1,n)

       /usr/local/share/boxes
                      system-wide configuration file(1,n)

SEE ALSO
       indent(1) , tal(1) , vim(1)



4th Berkeley Distribution       August 22 1999                        boxes(1)

References for this manual (incoming links)