Provided by: boxes_2.2.0-2_amd64 bug

NAME

       boxes - text mode box and comment drawing filter

SYNOPSIS

       boxes   [-hlmrv]   [-a format]   [-d design]   [-e eol]  [-f file]  [-i indent]  [-k bool]
       [-n encoding] [-p pad] [-q query] [-s size] [-t tabopts] [infile [outfile]]

DESCRIPTION

       Boxes 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, boxes can also be used to create regional comments in any programming
       language.  New box designs can be added and shared by appending to a configuration file.

       boxes is a command line tool, but also integrates  with  any  text  editor  that  supports
       filters. The boxes website has examples on how to configure editor integration for various
       text editors:
       <URL:https://boxes.thomasjensen.com/editors.html>

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.

       -c string
             Command  line design definition for simple cases. The argument of this option is the
             definition for the "west" (W) shape. The defined shape must consist of  exactly  one
             line, i.e. no multi-line shapes are allowed. The -c 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 -c than to  do  a  complete
             design  definition  in  one's  config file, where the only shape defined is the west
             shape.
             This option implies a -d and does not access the config file.  -c may of  course  be
             used in conjunction with any of the other options. By default, -c is not specified.

       -d string
             Design  selection. The one argument of this option is the name of the design to use,
             which may either be a design's primary name or any of its alias names.

       -e eol
             Override line terminator.  eol can be CR, LF, or CRLF.  The default is  to  use  the
             system-specific line terminator, which means CRLF on Windows, and LF otherwise. This
             option should only be used in an emergency,  because  normally  the  system-specific
             line  terminator  will be just fine. This option is considered experimental, and may
             go away in a future version of boxes.  Let us know in <URL:https://github.com/ascii-
             boxes/boxes/issues/60> if you think we should keep it.

       -f string
             Use  alternate  config  file. The one argument of this option is the name of a valid
             boxes config file. The argument of -f can also  be  a  directory  which  contains  a
             configuration  file.  More information on this topic below in the CONFIGURATION FILE
             section.

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

       -k bool
             Kill leading/trailing blank lines on removal. The value of bool is  either  true  or
             false.   This  option  only  takes  effect  in  connection with -r.  If set to true,
             leading and trailing blank lines will be removed from the output. If set  to  false,
             the entire content of the former box is returned.  The default is false, 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
             true.

       -l    (ell) List designs. Produces a listing of all available box designs  in  the  config
             file,  along  with  a sample box and information about its creator.  Also checks the
             syntax of the entire config file.  If  used  together  with  -d,  displays  detailed
             information about the specified design.

       -m    Mend  box.  This  removes  a  (potentially  broken)  box  as with -r, 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 -k false.

       -n encoding
             Character encoding. Overrides the character encoding of the input and  output  text.
             Choose  from  the  list  shown  by  iconv  -l.  If  an invalid character encoding is
             specified here, UTF-8 is used as a fallback.  The  default  is  to  use  the  system
             encoding, which is normally the best course of action.  So don't specify this option
             unless you have to.

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

       -q query
             Query  designs  by  tag. In contrast to -l, this will only print the matching design
             names. This option is normally used stand-alone; if used in combination  with  other
             options,  behavior  is  undefined.   The query argument is a comma-separated list of
             tags which can be present on a design in order to match. A  tag  may  optionally  be
             prefixed  with  +  in  order  to  require  that it be present, or with - in order to
             exclude designs which have that tag. Each tag can only occur once per query.
             This option is intended for use by scripts. Alias  names  are  printed  below  their
             primary design name, and postfixed with (alias).
             Example: boxes -q programming,-comment

       -r    Remove  an  existing box. 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. 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 'x' 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 -p).
             By default, the smallest possible box is created around the text.

       -t string
             Tab handling. This option controls how tab characters in the input text are handled.
             The  option  string  must  always  begin  with a uint 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.
             Immediately following the tab distance,  an  optional  character  can  be  appended,
             telling boxes how to treat the leading tabs. The following options are available:
             e - expand tabs into spaces
             k - keep tabs as close to what they were as possible
             u - unexpand tabs. This makes boxes turn as many spaces as possible into tabs.

             In order to maintain backwards compatibility, the -t string can be just a number. In
             that case, e is assumed for tab handling, which removes all tabs and  replaces  them
             with spaces. The factory default for the -t option is simply 8, which is just such a
             case.
             For example, you could specify -t 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.

       -v    Print out current version number.

CONFIGURATION FILE

       Boxes will look for the configuration file in several places, some of which are  given  by
       the XDG specification.

       1. -f option [file or dir]
             When a configuration file is specified on the command line, we will use that. The -f
             option can also specify a directory. Any location specified via -f  must  exist,  or
             boxes will terminate with an error.

       2. BOXES environment variable [file or dir]
             If  no  config file is specified on the command line, boxes will check for the BOXES
             environment variable, which may contain a filename or directory to use. Any location
             specified  via  the  BOXES  environment variable must exist, or boxes will terminate
             with an error.

       3. $HOME [dir]
       4. $XDG_CONFIG_HOME/boxes [dir]
       5. $HOME/.config/boxes [dir]
       6. /etc/boxes/boxes-config [file]
       7. /etc/xdg/boxes [dir]
       8. /usr/local/share/boxes [dir]
       9. /usr/share/boxes [dir]
             Either one of these last two directory locations might have the  same  name  as  the
             global  config file from 6. That's fine. It just means that we first look for a file
             of that name, and then for a directory containing the file.

       The XDG environment variable XDG_CONFIG_DIRS is not supported. However, its default  value
       is supported via steps 8 and 9 above.

       In the above list, whenever a step is designated with [dir], the following file names will
       be found, in this order:
             1. .boxes
             2. box-designs
             3. boxes-config
             4. boxes

       As soon as the first valid file is found, we use that and stop the search.

       The recommended location  for  a  user-specific  configuration  file  is  $HOME/.boxes  or
       $HOME/.config/boxes/.boxes.   A   global   configuration   file   should   be  located  at
       /etc/boxes/boxes-config. But all of the other locations are fully supported, too.

       The   syntax   of   boxes   config   files   is    described    on    the    website    at
       <URL:https://boxes.thomasjensen.com/config-syntax.html>.

EXAMPLES

       Examples    on    how    to    invoke   boxes   may   be   found   on   the   website   at
       <URL:https://boxes.thomasjensen.com/examples.html>.
       Try

       echo "Good Bye World!" | boxes -d nuke

       Boxes also combines nicely with other tools. Try

       figlet "boxes . . . !" | lolcat -f | boxes -d unicornthink

AVAILABILITY

       The boxes website  is  <URL:https://boxes.thomasjensen.com/>.  It  contains  a  number  of
       examples illustrating this manual page as well as more in-depth documentation.

AUTHOR

       Boxes  was  made  by  Thomas  Jensen  and  the  boxes  contributors.  It has been lovingly
       maintained since 1999.
       For a full list of contributors, see
       <URL:https://boxes.thomasjensen.com/team.html#contributors>
       and <URL:https://github.com/ascii-boxes/boxes/graphs/contributors>.
       Please refer to the boxes website for the maintainer's current email address.

VERSION

       This is boxes version 2.2.0.

LICENSE

       boxes is free software under the terms of the  GNU  General  Public  License,  version  3.
       Details     in    the    LICENSE    file:    <URL:https://raw.githubusercontent.com/ascii-
       boxes/boxes/v2.2.0/LICENSE>

ENVIRONMENT

       Boxes recognizes the following environment variables:

       BOXES
             Absolute path of the boxes configuration file. If this is specified, it  must  refer
             to an existing file or directory.

       HOME
             The user's home directory.

       XDG_CONFIG_HOME
             The root of the configuration file location as per the XDG specification.

SEE ALSO

       figlet(6), iconv(1), lolcat(6)