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] [-e eol] [-f file] [-i indent]
10 [-k bool] [-n encoding] [-p pad] [-q query] [-s size] [-t tabopts] [in‐
11 file [outfile]]
12
14 Boxes is a text filter which can draw any kind of box around its input
15 text. Box design choices range from simple boxes to complex ASCII art.
16 A box can also be removed and repaired, even if it has been badly dam‐
17 aged by editing of the text inside. Since boxes may be open on any
18 side, boxes can also be used to create regional comments in any pro‐
19 gramming language. New box designs can be added and shared by append‐
20 ing to a configuration file.
21 boxes is a command line tool, but also integrates with any text editor
23 that supports filters. The boxes website has examples on how to config‐
24 ure editor integration for various text editors:
25 <URL:https://boxes.thomasjensen.com/editors.html>
26
28 Options offered by boxes are the following:
29 -a string
31 Alignment/positioning of text inside box. This option takes a
32 format string argument which is read from left to right. The for‐
33 mat string may not contain whitespace and must consist of one or
34 more of the following components:
35 hx - horizontal alignment of the input text block inside a poten‐
37 tially larger box. Possible values for x are l (ell, for left
38 alignment), c (center), or r (right). This does not affect the
39 justification of text lines within the input text block (use the
40 j argument instead).
41 vx - vertical alignment of the input text block inside a poten‐
42 tially larger box. Possible values for x are t (for top align‐
43 ment), c (center), or b (bottom).
44 jx - justification of lines within the input text block. Possible
45 values for x are l (ell, for left justification), c (center), or
46 r (right). This does not affect the alignment of the input text
47 block itself within the box. Use the h and v arguments for input
48 text block positioning.
49 Short hand notations (can be combined with the above arguments):
51 l (ell) - short for hlvcjl
52 c - short for hcvcjc
53 r - short for hrvcjr
54 The factory default setting for -a is hlvt.
56 -c string
58 Command line design definition for simple cases. The argument of
59 this option is the definition for the "west" (W) shape. The de‐
60 fined shape must consist of exactly one line, i.e. no multi-line
61 shapes are allowed. The -c option is intended as a shortcut for
62 those cases where simple regional comments are to be created,
63 which only need a certain character or sequence of characters to
64 be placed in front of every line. In such cases, it is much more
65 convenient to simply specify -c than to do a complete design def‐
66 inition in one's config file, where the only shape defined is the
67 west shape.
68 This option implies a -d and does not access the config file. -c
69 may of course be used in conjunction with any of the other op‐
70 tions. By default, -c is not specified.
71 -d string
73 Design selection. The one argument of this option is the name of
74 the design to use, which may either be a design's primary name or
75 any of its alias names.
76 -e eol
78 Override line terminator. eol can be CR, LF, or CRLF. The de‐
79 fault is to use the system-specific line terminator, which means
80 CRLF on Windows, and LF otherwise. This option should only be
81 used in an emergency, because normally the system-specific line
82 terminator will be just fine. This option is considered experi‐
83 mental, and may go away in a future version of boxes. Let us
84 know in <URL:https://github.com/ascii-boxes/boxes/issues/60> if
85 you think we should keep it.
86 -f string
88 Use alternate config file. The one argument of this option is the
89 name of a valid boxes config file. The argument of -f can also be
90 a directory which contains a configuration file. More information
91 on this topic below in the CONFIGURATION FILE section.
92 --help
94 -h Print usage information.
95 -i string
97 Indentation mode. Possible arguments are text (indent text inside
98 of box), box (indent box, not text inside of box), or none (throw
99 away indentation). Arguments may be abbreviated. The default is
100 box.
101 -k bool
103 Kill leading/trailing blank lines on removal. The value of bool
104 is either true or false. This option only takes effect in con‐
105 nection with -r. If set to true, leading and trailing blank
106 lines will be removed from the output. If set to false, the en‐
107 tire content of the former box is returned. The default is
108 false, if both the top and the bottom part of the box are open,
109 as is the case with most regional comments. If the box's design
110 defines a top part or a bottom part, the default is true.
111 -l (ell) List designs. Produces a listing of all available box de‐
113 signs in the config file, along with a sample box and information
114 about its creator. Also checks the syntax of the entire config
115 file. If used together with -d, displays detailed information
116 about the specified design.
117 -m Mend box. This removes a (potentially broken) box as with -r, and
119 redraws it afterwards. The mended box is drawn according to the
120 options given. This may be important to know when it comes to
121 restoring padding, indentation, etc. for the mended box. Implies
122 -k false.
123 -n encoding
125 Character encoding. Overrides the character encoding of the input
126 and output text. Choose from the list shown by iconv -l. If an
127 invalid character encoding is specified here, UTF-8 is used as a
128 fallback. The default is to use the system encoding, which is
129 normally the best course of action. So don't specify this option
130 unless you have to.
131 -p string
133 Padding. Specify padding in spaces around the input text block
134 for all sides of the box. The argument string may not contain
135 whitespace and must consist of a combination of the following
136 characters, each followed by a number indicating the padding in
137 spaces:
138 a - (all) give padding for all sides at once
139 h - (horiz) give padding for both horizontal sides
140 v - (vertical) give padding for both vertical sides
141 b - (bottom) give padding for bottom (south) side
142 l - (left) give padding for left (west) side
143 t - (top) give padding for top (north) side
144 r - (right) give padding for right (east) side
145 Example: -p a4t2 would define the padding to be 4 characters on
146 all sides, except for the top of the box, where the input text
147 block will be only 2 lines away from the box.
148 By default, unless specified otherwise in the config file, no
149 padding is used.
150 -q query
152 Query designs by tag. In contrast to -l, this will only print the
153 matching design names. This option is normally used stand-alone;
154 if used in combination with other options, behavior is undefined.
155 The query argument is a comma-separated list of tags which can be
156 present on a design in order to match. A tag may optionally be
157 prefixed with + in order to require that it be present, or with -
158 in order to exclude designs which have that tag. Each tag can
159 only occur once per query.
160 This option is intended for use by scripts. Alias names are
161 printed below their primary design name, and postfixed with
162 (alias).
163 Example: boxes -q programming,-comment
164 -r Remove an existing box. Which design to use is detected automati‐
166 cally. In order to save time or in case the detection does not
167 decide correctly, combine with -d to specify the design. The de‐
168 fault is to draw a new box.
169 -s widthxheight
171 Box size. This option specifies the desired box size in units of
172 columns (for width) and lines (for height). If only a single
173 number is given as argument, this number specifies the desired
174 box width. A single number prefixed by 'x' specifies only the box
175 height. The actual resulting box size may vary depending on the
176 individual shape sizes of the chosen design. Also, other command
177 line options may influence the box size (such as -p).
178 By default, the smallest possible box is created around the text.
179 -t string
181 Tab handling. This option controls how tab characters in the in‐
182 put text are handled. The option string must always begin with a
183 uint number indicating the distance between tab stops. It is im‐
184 portant that this value be set correctly, or tabulator characters
185 will upset your input text. The correct tab distance value de‐
186 pends on the settings used for the text you are processing. A
187 common value is 8.
188 Immediately following the tab distance, an optional character can
189 be appended, telling boxes how to treat the leading tabs. The
190 following options are available:
191 e - expand tabs into spaces
192 k - keep tabs as close to what they were as possible
193 u - unexpand tabs. This makes boxes turn as many spaces as possi‐
194 ble into tabs.
195 In order to maintain backwards compatibility, the -t string can
197 be just a number. In that case, e is assumed for tab handling,
198 which removes all tabs and replaces them with spaces. The factory
199 default for the -t option is simply 8, which is just such a case.
200 For example, you could specify -t 4u in order to have your lead‐
201 ing tabs unexpanded. In the box content, tabs are always con‐
202 verted into spaces. The tab distance in this example is 4.
203 -v Print out current version number.
205
207 Boxes will look for the configuration file in several places, some of
208 which are given by the XDG specification.
209 1. -f option [file or dir]
211 When a configuration file is specified on the command line, we
212 will use that. The -f option can also specify a directory. Any
213 location specified via -f must exist, or boxes will terminate
214 with an error.
215 2. BOXES environment variable [file or dir]
217 If no config file is specified on the command line, boxes will
218 check for the BOXES environment variable, which may contain a
219 filename or directory to use. Any location specified via the
220 BOXES environment variable must exist, or boxes will terminate
221 with an error.
222 3. $HOME [dir]
224 4. $XDG_CONFIG_HOME/boxes [dir]
225 5. $HOME/.config/boxes [dir]
226 6. /usr/share/boxes/boxes [file]
227 7. /etc/xdg/boxes [dir]
228 8. /usr/local/share/boxes [dir]
229 9. /usr/share/boxes [dir]
230 Either one of these last two directory locations might have the
231 same name as the global config file from 6. That's fine. It just
232 means that we first look for a file of that name, and then for a
233 directory containing the file.
234 The XDG environment variable XDG_CONFIG_DIRS is not supported. However,
236 its default value is supported via steps 8 and 9 above.
237 In the above list, whenever a step is designated with [dir], the fol‐
239 lowing file names will be found, in this order:
240 1. .boxes
241 2. box-designs
242 3. boxes-config
243 4. boxes
244 As soon as the first valid file is found, we use that and stop the
246 search.
247 The recommended location for a user-specific configuration file is
249 $HOME/.boxes or $HOME/.config/boxes/.boxes. A global configuration file
250 should be located at /usr/share/boxes/boxes. But all of the other loca‐
251 tions are fully supported, too.
252 The syntax of boxes config files is described on the website at
254 <URL:https://boxes.thomasjensen.com/config-syntax.html>.
255
257 Examples on how to invoke boxes may be found on the website at
258 <URL:https://boxes.thomasjensen.com/examples.html>.
259 Try
260 echo "Good Bye World!" | boxes -d nuke
262 Boxes also combines nicely with other tools. Try
264 figlet "boxes . . . !" | lolcat -f | boxes -d unicornthink
266
268 The boxes website is <URL:https://boxes.thomasjensen.com/>. It contains
269 a number of examples illustrating this manual page as well as more
270 in-depth documentation.
271
273 Boxes was made by Thomas Jensen and the boxes contributors. It has been
274 lovingly maintained since 1999.
275 For a full list of contributors, see
276 <URL:https://boxes.thomasjensen.com/team.html#contributors>
277 and <URL:https://github.com/ascii-boxes/boxes/graphs/contributors>.
278 Please refer to the boxes website for the maintainer's current email
279 address.
280
282 This is boxes version 2.2.0.
283
285 boxes is free software under the terms of the GNU General Public Li‐
286 cense, version 3. Details in the LICENSE file:
287 <URL:https://raw.githubusercontent.com/ascii-boxes/boxes/v2.2.0/LI‐
288 CENSE>
289
291 Boxes recognizes the following environment variables:
292 BOXES
294 Absolute path of the boxes configuration file. If this is speci‐
295 fied, it must refer to an existing file or directory.
296 HOME
298 The user's home directory.
299 XDG_CONFIG_HOME
301 The root of the configuration file location as per the XDG speci‐
302 fication.
303
305 figlet(6), iconv(1), lolcat(6)
3064th Berkeley Distribution June 14 2021 boxes(1)