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] [-e eol] [-f file] [-i indent]
10       [-k bool] [-n encoding] [-p pad] [-q query] [-s size] [-t tabopts] [in‐
11       file [outfile]]
12

DESCRIPTION

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
22       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/docs/install.html>
26

OPTIONS

28       Options offered by boxes are the following:
29
30       -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
36             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
50             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
55             The factory default setting for -a is hlvt.
56
57       -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
72       -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
77       -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
87       -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
93       --help
94       -h    Print usage information.
95
96       -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
102       -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
112       -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
118       -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
124       -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
132       -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
151       -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
165       -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
170       -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
180       -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
196             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
204       -v    Print out current version number.
205

CONFIGURATION FILE

207       Boxes  will  look for the configuration file in several places, some of
208       which are given by the XDG specification.
209
210       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
216       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
223       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
235       The XDG environment variable XDG_CONFIG_DIRS is not supported. However,
236       its default value is supported via steps 8 and 9 above.
237
238       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
245       As soon as the first valid file is found, we  use  that  and  stop  the
246       search.
247
248       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
253       The syntax of boxes  config  files  is  described  on  the  website  at
254       <URL:https://boxes.thomasjensen.com/docs/config-syntax.html>.
255

EXAMPLES

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
261       echo "Good Bye World!" | boxes -d nuke
262
263       Boxes also combines nicely with other tools. Try
264
265       figlet "boxes . . . !" | lolcat -f | boxes -d unicornthink
266

AVAILABILITY

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

AUTHOR

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

VERSION

282       This is boxes version 2.1.0.
283

LICENSE

285       boxes is free software under the terms of the GNU  General  Public  Li‐
286       cense,     version     2.     Details     in    the    LICENSE    file:
287       <URL:https://raw.githubusercontent.com/ascii-boxes/boxes/v2.1.0/LI
288       CENSE>
289

ENVIRONMENT

291       Boxes recognizes the following environment variables:
292
293       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
297       HOME
298             The user's home directory.
299
300       XDG_CONFIG_HOME
301             The root of the configuration file location as per the XDG speci‐
302             fication.
303

SEE ALSO

305       figlet(6), iconv(1), lolcat(6)
306
307
308
3094th Berkeley Distribution        April 17 2021                        boxes(1)
Impressum