1boxes(1)                    General Commands Manual                   boxes(1)
2
3
4

NAME

6       boxes - text mode box and comment drawing filter
7

SYNOPSIS

9       boxes  [-hlmrv] [-a format] [-d design] [-f file] [-i indent] [-k bool]
10       [-p pad] [-s size] [-t tabopts] [infile [outfile]]
11

DESCRIPTION

13       Boxes is a text filter which can draw any kind of box around its  input
14       text.  Box design choices range from simple boxes to complex ASCII art.
15       A box can also be removed and repaired, even if it has been badly  dam‐
16       aged  by  editing  of  the  text inside. Since boxes may be open on any
17       side, boxes can also be used to create regional comments  in  any  pro‐
18       gramming  language.   New  box designs of all sorts can easily be added
19       and shared by appending to a free format configuration file.
20       boxes was originally intended to be used with the vim(1)  text  editor,
21       but  it  can be tied to any text editor which supports filters, as well
22       as called from the command line as a standalone tool.
23

OPTIONS

25       Options offered by boxes are the following:
26
27       -a string
28             Alignment/positioning of text inside box.  This  option  takes  a
29             format string argument which is read from left to right. The for‐
30             mat string may not contain whitespace and must consist of one  or
31             more of the following components:
32
33             hx - horizontal alignment of the input text block inside a poten‐
34             tially larger box. Possible values for x are  l  (ell,  for  left
35             alignment),  c  (center),  or r (right). This does not affect the
36             justification of text lines within the input text block (use  the
37             j argument instead).
38             vx  -  vertical alignment of the input text block inside a poten‐
39             tially larger box. Possible values for x are t  (for  top  align‐
40             ment), c (center), or b (bottom).
41             jx - justification of lines within the input text block. Possible
42             values for x are l (ell, for left justification), c (center),  or
43             r  (right).  This does not affect the alignment of the input text
44             block itself within the box. Use the h and v arguments for  input
45             text block positioning.
46
47             Short hand notations (can be combined with the above arguments):
48             l (ell) - short for hlvcjl
49             c - short for hcvcjc
50             r - short for hrvcjr
51
52             The factory default setting for -a is hlvt.
53
54       -c string
55             Command  line design definition for simple cases. The argument of
56             this option is the definition  for  the  "west"  (W)  shape.  The
57             defined  shape  must  consist of exactly one line, i.e. no multi-
58             line shapes are allowed. The -c option is intended as a  shortcut
59             for those cases where simple regional comments are to be created,
60             which only need a certain character or sequence of characters  to
61             be  placed in front of every line. In such cases, it is much more
62             convenient to simply specify -c than to do a complete design def‐
63             inition in one's config file, where the only shape defined is the
64             west shape.
65             This option implies a -d and does not access the config file.  -c
66             may  of  course  be  used  in  conjuction  with  any of the other
67             options. By default, -c is not specified.
68
69       -d string
70             Design selection. The one argument of this option is the name  of
71             the design to use.
72
73       -f string
74             Use alternate config file. The one argument of this option is the
75             name of a valid boxes config file, containing  new  and  exciting
76             designs!
77
78       -h    Print usage information.
79
80       -i string
81             Indentation  mode.  Possible  arguments  are  "text" (indent text
82             inside of box), "box" (indent box, not text inside  of  box),  or
83             "none"  (throw  away  indentation). Arguments may be abbreviated.
84             The default is to indent the box, but not the text.
85
86       -k bool
87             Kill leading/trailing blank lines on removal. The value  of  bool
88             can  be  specified as on, yes, true, 1, or t, all meaning yes, or
89             off, no, false, 0, or f, which mean no. This is case-insensitive.
90             This  option  only takes effect in connection with -r.  If set to
91             yes, leading and trailing blank lines will be  removed  from  the
92             output.  If  set  to  no, the entire content of the former box is
93             returned.  The default is no, if both the top and the bottom part
94             of  the box are open, as is the case with most regional comments.
95             If the box's design defines a top part  or  a  bottom  part,  the
96             default is yes.
97
98       -l    (ell)  List  designs.  Produces  a  listing  of all available box
99             designs in the config file, along with a sample box and  informa‐
100             tion about it's creator.  Also checks syntax of the entire config
101             file. If used in connection with -d, displays  detailed  informa‐
102             tion about the specified design.
103
104       -m    Mend box. This removes a (potentially broken) box as with -r, and
105             redraws it afterwards. The mended box is drawn according  to  the
106             options  given.  This  may  be important to know when it comes to
107             restoring padding, identation, etc. for the mended  box.  Implies
108             -k false.
109
110       -p string
111             Padding.  Specify  padding  in spaces around the input text block
112             for all sides of the box. The argument  string  may  not  contain
113             whitespace  and  must  consist  of a combination of the following
114             characters, each followed by a number indicating the  padding  in
115             spaces:
116             a - (all) give padding for all sides at once
117             h - (horiz) give padding for both horizontal sides
118             v - (vertical) give padding for both vertical sides
119             b - (bottom) give padding for bottom (south) side
120             l - (left) give padding for left (west) side
121             t - (top) give padding for top (north) side
122             r - (right) give padding for right (east) side
123             Example:  -p  a4t2 would define the padding to be 4 characters on
124             all sides, except for the top of the box, where  the  input  text
125             block will be only 2 lines away from the box.
126             By  default,  unless  specified  otherwise in the config file, no
127             padding is used.
128
129       -r    Remove box. Removes an existing box instead of drawing it.  Which
130             design to use is detected automatically. In order to save time or
131             in case the detection does not decide correctly, combine with  -d
132             to specify the design. The default is to draw a new box.
133
134       -s widthxheight
135             Box  size. This option specifies the desired box size in units of
136             columns (for width) and lines (for height).   If  only  a  single
137             number  is  given  as argument, this number specifies the desired
138             box width. A single number prefixed by 'x' specifies only the box
139             height.   The actual resulting box size may vary depending on the
140             individual shape sizes of the chosen design. Also, other  command
141             line options may influence the box size (such as -p).
142             By default, the smallest possible box is created around the text.
143
144       -t string
145             Tab  handling.  This  option  controls  how tab characters in the
146             input text are handled. The option string must always begin  with
147             a  uint  number  indicating the distance between tab stops. It is
148             important that this value be set correctly, or tabulator  charac‐
149             ters  will upset your input text.  The correct tab distance value
150             depends on the settings used for the text you are  processing.  A
151             common value is 8.
152             Immediately following the tab distance, an optional character can
153             be appended, telling boxes how to treat  the  leading  tabs.  The
154             following options are available:
155             e - expand tabs into spaces
156             k - keep tabs as close to what they were as possible
157             u - unexpand tabs. This makes boxes turn as many spaces as possi‐
158             ble into tabs.
159
160             In order to maintain backwards compatibility, the -t  string  can
161             be  just  a  number. In that case, e is assumed for tab handling,
162             which removes all tabs and replaces them with spaces. The factory
163             default for the -t option is simply 8, which is just such a case.
164             For  example, you could specify -t 4u in order to have your lead‐
165             ing tabs unexpanded. In the box content,  tabs  are  always  con‐
166             verted into spaces. The tab distance in this example is 4.
167
168       -v    Print out current version number.
169

CONFIGURATION FILES

171       Boxes  will  use  the  configuration file specified on the command line
172       (using -f).  If no config file is specified on the command line,  boxes
173       will  check  for  the  BOXES  environment variable, which may contain a
174       filename to  use.  If  BOXES  is  not  set,  boxes  will  try  to  read
175       $HOME/.boxes  and use it as a config file. Failing that, boxes will try
176       to read the system-wide config file (see FILES).
177
178       The syntax of boxes config files  is  described  on  the  website  (see
179       below). They are quite self-explanatory, though.
180

AVAILABILITY

182       Boxes  is  available  from  its  website  at  <URL:http://boxes.thomas
183       jensen.com/>. The website also features a number of examples illustrat‐
184       ing this manual page as well as more in-depth documentation.
185
186       Check out vim(1) at <URL:http://www.vim.org/>!
187

AUTHOR

189       Boxes was made by Thomas Jensen <boxes@thomasjensen.com>.
190       Please see the boxes website for a current email address.
191

VERSION

193       This is boxes version 1.1.
194

BUGS

196       Although  it  is doing fine in most cases, imho the design autodetector
197       needs some more work.
198       Should you notice any  other  unspecified  behavior,  please  tell  the
199       author!
200

ENVIRONMENT

202       Boxes recognizes the following environment variables:
203
204       HOME      The user's home directory.
205
206       BOXES     Name of boxes configuration file, if different from ~/.boxes.
207

FILES

209       $HOME/.boxes
210                 boxes configuration file
211
212       /usr/share/boxes/boxes
213                 system-wide configuration file
214

SEE ALSO

216       tal(1) , vim(1)
217
218
219
2204th Berkeley Distribution        July 22 2006                         boxes(1)
Impressum