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 [-n encoding] [-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 configuration file.
20 boxes is a command line tool, but also integrates with any text editor
22 that supports filters. The boxes website has examples on how to config‐
23 ure editor integration for various text editors:
24 <URL:https://boxes.thomasjensen.com/docs/install.html>
25
27 Options offered by boxes are the following:
28 -a string
30 Alignment/positioning of text inside box. This option takes a
31 format string argument which is read from left to right. The for‐
32 mat string may not contain whitespace and must consist of one or
33 more of the following components:
34 hx - horizontal alignment of the input text block inside a poten‐
36 tially larger box. Possible values for x are l (ell, for left
37 alignment), c (center), or r (right). This does not affect the
38 justification of text lines within the input text block (use the
39 j argument instead).
40 vx - vertical alignment of the input text block inside a poten‐
41 tially larger box. Possible values for x are t (for top align‐
42 ment), c (center), or b (bottom).
43 jx - justification of lines within the input text block. Possible
44 values for x are l (ell, for left justification), c (center), or
45 r (right). This does not affect the alignment of the input text
46 block itself within the box. Use the h and v arguments for input
47 text block positioning.
48 Short hand notations (can be combined with the above arguments):
50 l (ell) - short for hlvcjl
51 c - short for hcvcjc
52 r - short for hrvcjr
53 The factory default setting for -a is hlvt.
55 -c string
57 Command line design definition for simple cases. The argument of
58 this option is the definition for the "west" (W) shape. The
59 defined shape must consist of exactly one line, i.e. no
60 multi-line shapes are allowed. The -c option is intended as a
61 shortcut for those cases where simple regional comments are to be
62 created, which only need a certain character or sequence of char‐
63 acters to be placed in front of every line. In such cases, it is
64 much more convenient to simply specify -c than to do a complete
65 design definition in one's config file, where the only shape
66 defined is the west shape.
67 This option implies a -d and does not access the config file. -c
68 may of course be used in conjunction with any of the other
69 options. By default, -c is not specified.
70 -d string
72 Design selection. The one argument of this option is the name of
73 the design to use.
74 -f string
76 Use alternate config file. The one argument of this option is the
77 name of a valid boxes config file, containing new and exciting
78 designs!
79 -h Print usage information.
81 -i string
83 Indentation mode. Possible arguments are "text" (indent text
84 inside of box), "box" (indent box, not text inside of box), or
85 "none" (throw away indentation). Arguments may be abbreviated.
86 The default is to indent the box, but not the text.
87 -k bool
89 Kill leading/trailing blank lines on removal. The value of bool
90 can be specified as on, yes, true, 1, or t, all meaning yes, or
91 off, no, false, 0, or f, which mean no. This is case-insensitive.
92 This option only takes effect in connection with -r. If set to
93 yes, leading and trailing blank lines will be removed from the
94 output. If set to no, the entire content of the former box is
95 returned. The default is no, if both the top and the bottom part
96 of the box are open, as is the case with most regional comments.
97 If the box's design defines a top part or a bottom part, the
98 default is yes.
99 -l (ell) List designs. Produces a listing of all available box
101 designs in the config file, along with a sample box and informa‐
102 tion about it's creator. Also checks syntax of the entire config
103 file. If used in connection with -d, displays detailed informa‐
104 tion about the specified design.
105 -m Mend box. This removes a (potentially broken) box as with -r, and
107 redraws it afterwards. The mended box is drawn according to the
108 options given. This may be important to know when it comes to
109 restoring padding, indentation, etc. for the mended box. Implies
110 -k false.
111 -n encoding
113 Character encoding. Overrides the character encoding of the input
114 and output text. Choose from the list shown by iconv -l. If an
115 invalid character encoding is specified here, UTF-8 is used as a
116 fallback. The default is to use the system encoding, which is
117 normally the best course of action. So don't specify this option
118 unless you have to.
119 -p string
121 Padding. Specify padding in spaces around the input text block
122 for all sides of the box. The argument string may not contain
123 whitespace and must consist of a combination of the following
124 characters, each followed by a number indicating the padding in
125 spaces:
126 a - (all) give padding for all sides at once
127 h - (horiz) give padding for both horizontal sides
128 v - (vertical) give padding for both vertical sides
129 b - (bottom) give padding for bottom (south) side
130 l - (left) give padding for left (west) side
131 t - (top) give padding for top (north) side
132 r - (right) give padding for right (east) side
133 Example: -p a4t2 would define the padding to be 4 characters on
134 all sides, except for the top of the box, where the input text
135 block will be only 2 lines away from the box.
136 By default, unless specified otherwise in the config file, no
137 padding is used.
138 -r Remove box. Removes an existing box instead of drawing it. Which
140 design to use is detected automatically. In order to save time or
141 in case the detection does not decide correctly, combine with -d
142 to specify the design. The default is to draw a new box.
143 -s widthxheight
145 Box size. This option specifies the desired box size in units of
146 columns (for width) and lines (for height). If only a single
147 number is given as argument, this number specifies the desired
148 box width. A single number prefixed by 'x' specifies only the box
149 height. The actual resulting box size may vary depending on the
150 individual shape sizes of the chosen design. Also, other command
151 line options may influence the box size (such as -p).
152 By default, the smallest possible box is created around the text.
153 -t string
155 Tab handling. This option controls how tab characters in the
156 input text are handled. The option string must always begin with
157 a uint number indicating the distance between tab stops. It is
158 important that this value be set correctly, or tabulator charac‐
159 ters will upset your input text. The correct tab distance value
160 depends on the settings used for the text you are processing. A
161 common value is 8.
162 Immediately following the tab distance, an optional character can
163 be appended, telling boxes how to treat the leading tabs. The
164 following options are available:
165 e - expand tabs into spaces
166 k - keep tabs as close to what they were as possible
167 u - unexpand tabs. This makes boxes turn as many spaces as possi‐
168 ble into tabs.
169 In order to maintain backwards compatibility, the -t string can
171 be just a number. In that case, e is assumed for tab handling,
172 which removes all tabs and replaces them with spaces. The factory
173 default for the -t option is simply 8, which is just such a case.
174 For example, you could specify -t 4u in order to have your lead‐
175 ing tabs unexpanded. In the box content, tabs are always con‐
176 verted into spaces. The tab distance in this example is 4.
177 -v Print out current version number.
179
181 Boxes will use the configuration file specified on the command line
182 (using -f). If no config file is specified on the command line, boxes
183 will check for the BOXES environment variable, which may contain a
184 filename to use. If BOXES is not set, boxes will try to read
185 $HOME/.boxes and use it as a config file. Failing that, boxes will try
186 to read the system-wide config file (see FILES).
187 The syntax of boxes config files is described on the website.
189
191 Examples on how to invoke boxes may be found on the website at
192 <URL:https://boxes.thomasjensen.com/examples.html>. Try
193 echo "Good Bye World!" | boxes -d nuke
195 Boxes also combines nicely with other tools. Try
197 figlet "boxes . . . !" | lolcat -f | boxes -d unicornthink
199
201 The boxes website is <URL:https://boxes.thomasjensen.com/>. It contains
202 a number of examples illustrating this manual page as well as more
203 in-depth documentation.
204
206 Boxes was made by Thomas Jensen and many great contributors.
207 For a full list, see
208 <URL:https://boxes.thomasjensen.com/contributing.html#contributors>
209 and <URL:https://github.com/ascii-boxes/boxes/graphs/contributors>.
210 Please refer to the boxes website for the maintainer's current email
211 address.
212
214 This is boxes version 2.0.0.
215
217 boxes is free software under the terms of the GNU General Public
218 License, version 2. Details in the LICENSE file:
219 <URL:https://raw.githubusercontent.com/ascii-
220 boxes/boxes/v2.0.0/LICENSE>
221
223 Boxes recognizes the following environment variables:
224 HOME The user's home directory.
226 BOXES Name of boxes configuration file, if different from ~/.boxes.
228
230 $HOME/.boxes
231 boxes configuration file (takes precedence over system-wide
232 configuration file)
233 /usr/share/boxes/boxes
235 system-wide configuration file
236
238 figlet(6), iconv(1), lolcat(6)
2394th Berkeley Distribution February 14 2021 boxes(1)