Debian Codegraph @

doc/boxes.1.in

raw
1 .\" @(#)boxes.1 2.3.1 10/03/2024
2 .\"
3 .TH boxes 1 "October 10 2024"
4 .UC 4
5 .SH NAME
6 boxes \- text mode box and comment drawing filter
7 .SH SYNOPSIS
8 .B boxes
9 [options] [infile [outfile]]
10 .SH DESCRIPTION
11 .I Boxes
12 is a text filter which can draw any kind of box around its input text. Box
13 design choices range from simple boxes to complex ASCII art. A box can also
14 be removed and repaired, even if it has been badly damaged by editing of the
15 text inside. Since boxes may be open on any side,
16 .I boxes
17 can also be used to create regional comments in any programming language.
18 New box designs can be added and shared by appending to a configuration file.
19 .LP
20 .I boxes
21 is a command line tool, but also integrates with any text editor that
22 supports filters. The
23 .I boxes
24 website has examples on how to configure editor integration for various
25 text editors:
26 .br
27 <URL:https://boxes.thomasjensen.com/editors.html>
28 .\" =======================================================================
29 .SH OPTIONS
30 Options offered by
31 .I boxes
32 are the following:
33 .TP 0.6i
34 \fB\-a\fP \fIformat\fP, \fB\-\-align\fP=\fIformat\fP
35 Alignment/positioning of text inside box. This option takes a format string
36 argument which is read from left to right. The format string may not
37 contain whitespace and must consist of one or more of the following
38 components:
39 .br
40
41 .I h\fPx
42 \- horizontal alignment of the input text block inside a box. Possible values
43 for
44 .I x
45 are
46 .I l
47 (ell, for left alignment),
48 .I c
49 (center), or
50 .I r
51 (right). This does not affect the justification of text lines within the
52 input text block (use the
53 .I j
54 argument instead).
55 .br
56 .I v\fPx
57 \- vertical alignment of the input text block inside a box. Possible values
58 for
59 .I x
60 are
61 .I t
62 (for top alignment),
63 .I c
64 (center), or
65 .I b
66 (bottom).
67 .br
68 .I j\fPx
69 \- justification of lines within the input text block. Possible values for
70 .I x
71 are
72 .I l
73 (ell, for left justification),
74 .I c
75 (center), or
76 .I r
77 (right). This does not affect the alignment of the input text block itself
78 within the box. Use the
79 .I h
80 and
81 .I v
82 arguments for input text block positioning.
83 .br
84
85 Short hand notations (can be combined with the above arguments):
86 .br
87 .I l
88 (ell) \- short for
89 .I h\fPl\fIv\fPc\fIj\fPl
90 .br
91 .I c
92 \- short for
93 .I h\fPc\fIv\fPc\fIj\fPc
94 .br
95 .I r
96 \- short for
97 .I h\fPr\fIv\fPc\fIj\fPr
98 .br
99
100 The default for
101 .B \-a
102 is
103 .I h\fPl\fIv\fPt.
104 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
105 .TP 0.6i
106 \fB\-c\fP \fIstring\fP, \fB\-\-create\fP=\fIstring\fP
107 Command line design definition for simple cases. The argument of this
108 option is the definition for the "west" (W) shape. The defined shape must
109 consist of exactly one line, i.e. no multi\-line shapes are allowed. The
110 .B \-c
111 option is intended as a shortcut for those cases where simple regional
112 comments are to be created, which only need a certain character or sequence
113 of characters to be placed in front of every line. In such cases, it is
114 much more convenient to simply specify
115 .B \-c
116 than to do a complete design definition in one's config file, where the
117 only shape defined is the west shape.
118 .br
119 This option implies a
120 .B \-d
121 and does not access the config file.
122 .B \-c
123 may of course be used in conjunction with any of the other options. By default,
124 .B \-c
125 is not specified.
126 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
127 .TP 0.6i
128 \fB\-\-color\fP, \fB\-\-no\-color\fP
129 Printing of color codes. Box designs and the text inside a box may contain ANSI
130 color codes, sometimes called "escape sequences". In this way, boxes and text
131 can be colored.
132 .br
133 Whether these escape sequences are printed by
134 .I boxes
135 is normally determined by the terminal capabilities (default). Using
136 \fB\-\-color\fP,
137 .I boxes
138 can be told to always output escape sequences even if it thinks the terminal
139 may not understand them. Using \fB\-\-no\-color\fP, escape sequences will
140 never be printed.
141
142 Of course, even with
143 .B \-\-color\fP,
144 a box will only appear colored if it is already defined with colors. In case
145 you want to auto-color some text that isn't yet, take a look at
146 .I lolcat\fP.
147 .br
148 These options consider all escape sequences to be color codes. Any other
149 escape sequences present will be printed or removed along with the color codes.
150 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
151 .TP 0.6i
152 \fB\-d\fP \fIstring\fP, \fB\-\-design\fP=\fIstring\fP
153 Design selection. The one argument of this option is the name of the design to
154 use, which may either be a design's primary name or any of its alias names.
155 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
156 .TP 0.6i
157 \fB\-e\fP \fIeol\fP, \fB\-\-eol\fP=\fIeol\fP
158 Override line terminator.
159 .I eol
160 can be
161 .I CR\fP,
162 .I LF\fP, or
163 .I CRLF\fP.
164 The default is to use the system-specific line terminator, which means
165 .I CRLF
166 on Windows, and
167 .I LF
168 otherwise. This option should only be used in an emergency, because normally
169 the system-specific line terminator will be just fine. This option is
170 considered experimental, and may go away in a future version of
171 .I boxes\fP.
172 Let us know in <URL:https://github.com/ascii-boxes/boxes/issues/60> if you
173 think we should keep it.
174 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
175 .TP 0.6i
176 \fB\-f\fP \fIstring\fP, \fB\-\-config\fP=\fIstring\fP
177 Use alternate config file. The one argument of this option is the name of a
178 valid
179 .I boxes
180 config file. The argument of
181 .B \-f
182 can also be a directory which contains a configuration file. More information
183 on this topic below in the CONFIGURATION FILE section.
184 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
185 .TP 0.6i
186 \fB\-h\fP, \fB\-\-help\fP
187 Print usage information.
188 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
189 .TP 0.6i
190 \fB\-i\fP \fIstring\fP, \fB\-\-indent\fP=\fIstring\fP
191 Indentation mode. Possible arguments are
192 .I text
193 (indent text inside of box),
194 .I box
195 (indent box, not text inside of box), or
196 .I none
197 (throw away indentation). Arguments may be abbreviated. The default is
198 .I box\fP.
199 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
200 .TP 0.6i
201 \fB\-k\fP \fIbool\fP, \fB\-\-kill\-blank\fP, \fB\-\-no\-kill\-blank\fP
202 Kill leading/trailing blank lines on removal. The value of
203 .I bool
204 is either
205 .I true
206 or
207 .I false\fP.
208 This option only takes effect in connection with
209 .B \-r\fP.
210 If set to
211 .I true\fP,
212 leading and trailing blank lines will be removed from the
213 output. If set to
214 .I false\fP,
215 the entire content of the former box is returned.
216 The default is
217 .I false\fP,
218 if both the top and the bottom part of the box are open, as is the case with
219 most regional comments. If the box's design defines a top part or a bottom
220 part, the default is
221 .I true\fP.
222 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
223 .TP 0.6i
224 \fB\-l\fP, \fB\-\-list\fP
225 List designs. Produces a listing of all available box designs in the
226 config file, along with a sample box and information about its creator.
227 Also checks the syntax of the entire config file. If used in conjunction
228 with
229 .B \-d\fP,
230 displays detailed information about the specified design.
231 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
232 .TP 0.6i
233 \fB\-m\fP, \fB\-\-mend\fP
234 Mend box. This removes a (potentially broken) box as with
235 .B \-r\fP,
236 and redraws it afterwards. The mended box is drawn according to the
237 options given. This may be important to know when it comes to restoring
238 padding, indentation, etc. for the mended box. Implies
239 .B \-k
240 .I false\fP.
241 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
242 .TP 0.6i
243 \fB\-n\fP \fIencoding\fP, \fB\-\-encoding\fP=\fIencoding\fP
244 Character encoding. Overrides the character encoding of the input and output
245 text. Choose from the list shown by \fIiconv -l\fP. If an invalid character
246 encoding is specified here, \fIUTF-8\fP is used as a fallback. The default
247 is to use the system encoding, which is normally the best course of action.
248 So don't specify this option unless you have to.
249 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
250 .TP 0.6i
251 \fB\-p\fP \fIstring\fP, \fB\-\-padding\fP=\fIstring\fP
252 Padding. Specify padding in spaces around the input text block for all
253 sides of the box. The argument string may not contain whitespace and must
254 consist of a combination of the following characters, each followed by a
255 number indicating the padding in spaces:
256 .br
257
258 .I a
259 \- (all) give padding for all sides at once
260 .br
261 .I h
262 \- (horiz) give padding for both horizontal sides
263 .br
264 .I v
265 \- (vertical) give padding for both vertical sides
266 .br
267 .I b
268 \- (bottom) give padding for bottom (south) side
269 .br
270 .I l
271 \- (left) give padding for left (west) side
272 .br
273 .I t
274 \- (top) give padding for top (north) side
275 .br
276 .I r
277 \- (right) give padding for right (east) side
278 .br
279
280 Example:
281 .B \-p
282 .I a\fP4\fIt\fP2
283 would define the padding to be 4 characters on all sides, except for the
284 top of the box, where the input text block will be only 2 lines away from
285 the box.
286 .br
287 The default for this option is determined by the box design used. If the
288 design does not specify anything, no default padding is used.
289 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
290 .TP 0.6i
291 \fB\-q\fP \fIquery\fP, \fB\-\-tag\-query\fP=\fIquery\fP
292 Query designs by tag. In contrast to
293 .B \-l\fP,
294 this will only print the matching design names. This option is normally used
295 stand-alone; if used in combination with other options, behavior is undefined.
296 The
297 .I query
298 argument is a comma-separated list of tags which can be present on a design
299 in order to match. A tag may optionally be prefixed with
300 .I \+
301 in order to require that it be present, or with
302 .I \-
303 in order to exclude designs which have that tag. Each tag can only occur once
304 per query. The special query
305 .I (all)
306 matches all box designs, even if they don't have any tags.
307 .br
308 This option is intended for use by scripts. Alias names are printed below
309 their primary design name, and postfixed with
310 .I (alias)\fP.
311 .br
312 Example:
313 .I boxes -q programming,-comment
314 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
315 .TP 0.6i
316 \fB\-r\fP, \fB--remove\fP
317 Remove an existing box. Which design to use is detected automatically. In
318 order to save time or in case the detection does not decide correctly, combine
319 with
320 .B \-d
321 to specify the design.
322 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
323 .TP 0.6i
324 \fB\-s\fP \fIwidth\fP\fBx\fP\fIheight\fP, \fB\-\-size\fP=\fIwidth\fP\fBx\fP\fIheight\fP
325 Box size. This option specifies the desired box size in units of columns
326 (for width) and lines (for height).
327 If only a single number is given as argument, this number specifies the
328 desired box width. A single number prefixed by 'x' specifies only the box
329 height. The actual resulting box size may vary depending on the individual
330 shape sizes of the chosen design. Also, other command line options may
331 influence the box size (such as
332 .B \-p\fP).
333 .br
334 By default, the smallest possible box is created around the text.
335 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
336 .TP 0.6i
337 \fB\-t\fP \fItabopts\fP, \fB\-\-tabs\fP=\fItabopts\fP
338 Tab handling. This option controls how tab characters in the input text are
339 handled. The
340 .I tabopts
341 must always begin with a positive integer number indicating the distance
342 between tab stops, sometimes called "spaces per tab".
343 .br
344 Immediately following the tab distance, an optional character can be appended,
345 telling
346 .I boxes
347 how to treat the leading tabs. The following options are available:
348 .br
349
350 .B e
351 \- expand tabs into spaces
352 .br
353 .B k
354 \- keep tabs as close to what they were as possible
355 .br
356 .B u
357 \- unexpand tabs. This makes
358 .I boxes
359 turn as many spaces as possible into tabs.
360 .br
361
362 The
363 .B \-t
364 .I string
365 can be just a number. In that case,
366 .B e
367 is assumed for tab handling. The factory default for the
368 .B \-t
369 option is simply 8, which is just such a case.
370 .br
371 For example, you could specify
372 .B \-t \fP4u
373 in order to have your leading tabs unexpanded. In the box content, tabs are
374 always converted into spaces. The tab distance in this example is 4.
375 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
376 .TP 0.6i
377 \fB\-v\fP, \fB\-\-version\fP
378 Print out current version number.
379 .\" =======================================================================
380 .SH CONFIGURATION FILE
381 .I Boxes
382 will look for the configuration file in several places, some of which are
383 given by the XDG specification.
384 .TP 0.6i
385 \fB1.\fP \fI\-f\fP option [file or dir]
386 When a configuration file is specified on the command line, we will use that. The
387 .B \-f
388 option can also specify a directory. Any location specified via
389 .B \-f
390 must exist, or
391 .I boxes
392 will terminate with an error.
393 .TP 0.6i
394 \fB2.\fP \fIBOXES\fP environment variable [file or dir]
395 If no config file is specified on the command line,
396 .I boxes
397 will check for the BOXES environment variable, which may contain a filename or
398 directory to use. Any location specified via the BOXES environment variable
399 must exist, or
400 .I boxes
401 will terminate with an error.
402 .TP 0.6i
403 \fB3.\fP \fI$HOME\fP [dir]
404 .TQ
405 \fB4.\fP \fI$XDG_CONFIG_HOME/boxes\fP [dir]
406 .TQ
407 \fB5.\fP \fI$HOME/.config/boxes\fP [dir]
408 .TQ
409 \fB6.\fP \fI--GLOBALCONF--\fP [file]
410 .TQ
411 \fB7.\fP \fI/etc/xdg/boxes\fP [dir]
412 .TQ
413 \fB8.\fP \fI/usr/local/share/boxes\fP [dir]
414 .TQ
415 \fB9.\fP \fI/usr/share/boxes\fP [dir]
416 Either one of these last two directory locations might have the same name as the
417 global config file from \fB6\fP. That's fine. It just means that we first
418 look for a file of that name, and then for a directory containing the file.
419 .P
420 The XDG environment variable \fIXDG_CONFIG_DIRS\fP is not supported. However,
421 its default value is supported via steps \fB8\fP and \fB9\fP above.
422 .TP 0.6i
423 In the above list, whenever a step is designated with [dir], the following file names will be found, in this order:
424 .br
425 \fB1.\fP .boxes
426 .br
427 \fB2.\fP box-designs
428 .br
429 \fB3.\fP boxes-config
430 .br
431 \fB4.\fP boxes
432 .LP
433 As soon as the first valid file is found, we use that and stop the search.
434 .P
435 The recommended location for a user-specific configuration file is
436 \fI$HOME/.boxes\fP or \fI$HOME/.config/boxes/.boxes\fP. A global
437 configuration file should be located at \fI--GLOBALCONF--\fP. But all of the
438 other locations are fully supported, too.
439 .P
440 The syntax of
441 .I boxes
442 config files is described on the website at
443 <URL:https://boxes.thomasjensen.com/config-syntax.html>.
444 .\" =======================================================================
445 .SH EXAMPLES
446 Examples on how to invoke
447 .I boxes
448 may be found on the website at
449 <URL:https://boxes.thomasjensen.com/examples.html>.
450 .br
451 Try
452 .P
453 \fIecho "Good Bye World!" | boxes -d nuke\fP
454 .P
455 .I Boxes
456 also combines nicely with other tools. Try
457 .P
458 \fIfiglet "boxes . . . !" | lolcat -f | boxes -d unicornthink\fP
459 .\" =======================================================================
460 .SH AVAILABILITY
461 The
462 .I boxes
463 website is <URL:https://boxes.thomasjensen.com/>. It contains a number
464 of examples illustrating this manual page as well as more in\-depth
465 documentation.
466 .\" =======================================================================
467 .SH AUTHOR
468 .I Boxes
469 was made by Thomas Jensen and the \fIboxes\fP contributors. It has been
470 lovingly maintained since 1999.
471 .br
472 For a full list of contributors, see
473 .br
474 <URL:https://boxes.thomasjensen.com/team.html#contributors>
475 .br
476 and <URL:https://github.com/ascii-boxes/boxes/graphs/contributors>.
477 .br
478 Please refer to the
479 .I boxes
480 website for the maintainer's current email address.
481 .\" =======================================================================
482 .SH VERSION
483 This is
484 .I boxes
485 version --BVERSION--.
486 .\" =======================================================================
487 .SH LICENSE
488 .I boxes
489 is free software under the terms of the GNU General Public License,
490 version 3. Details in the LICENSE file:
491 <URL:https://raw.githubusercontent.com/ascii-boxes/boxes/v--BVERSION--/LICENSE>
492 .\" =======================================================================
493 .SH ENVIRONMENT
494 .I Boxes
495 recognizes the following environment variables:
496 .HP 0.6i
497 BOXES
498 .br
499 Absolute path of the
500 .I boxes
501 configuration file. If this is specified, it must refer to an existing file
502 or directory.
503 .HP 0.6i
504 HOME
505 .br
506 The user's home directory.
507 .TP 0.6i
508 XDG_CONFIG_HOME
509 The root of the configuration file location as per the XDG specification.
510 .\" =======================================================================
511 .SH "SEE ALSO"
512 .BR figlet (6),
513 .BR iconv (1),
514 .BR lolcat (6)