1boxes(1) General Commands Manual boxes(1)
2
6 boxes - text mode box and comment drawing filter
7
9 boxes [-hlmrv] [-a format] [-d design] [-f file] [-i indent] [-k bool]
10 [-p pad] [-s size] [-t tabopts] [infile [outfile]]
11
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
25 Options offered by boxes are the following:
26 -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 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 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 The factory default setting for -a is hlvt.
53 -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
58 multi-line shapes are allowed. The -c option is intended as a
59 shortcut for those cases where simple regional comments are to be
60 created, which only need a certain character or sequence of char‐
61 acters to be placed in front of every line. In such cases, it is
62 much more convenient to simply specify -c than to do a complete
63 design definition in one's config file, where the only shape
64 defined is the west shape.
65 This option implies a -d and does not access the config file. -c
66 may of course be used in conjunction with any of the other
67 options. By default, -c is not specified.
68 -d string
70 Design selection. The one argument of this option is the name of
71 the design to use.
72 -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 -h Print usage information.
79 -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 -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 -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 -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 -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 -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 -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 -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 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 -v Print out current version number.
169
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 The syntax of boxes config files is described on the website (see
179 below). They are quite self-explanatory, though.
180
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 Check out vim(1) at <URL:http://www.vim.org/>!
187
189 Boxes was made by Thomas Jensen <boxes@thomasjensen.com>.
190 Please see the boxes website for a current email address.
191
193 This is boxes version 1.1.1.
194
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
202 Boxes recognizes the following environment variables:
203 HOME The user's home directory.
205 BOXES Name of boxes configuration file, if different from ~/.boxes.
207
209 $HOME/.boxes
210 boxes configuration file
211 /usr/share/boxes/boxes
213 system-wide configuration file
214
216 tal(1) , vim(1)
2174th Berkeley Distribution October 19 2012 boxes(1)