extern/boxes
1
0
Fork 0
mirror of https://github.com/ascii-boxes/boxes.git synced 2025-03-15 06:48:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

Boxes 2.3.0 released

Browse Source
This commit is contained in:
Thomas Jensen 2024-01-13 15:01:16 +01:00
parent 464a1ef49b
commit 1c7804706b
No known key found for this signature in database
GPG Key ID: A4ACEE270D0FB7DB
25 changed files with 2678 additions and 299 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
_config.yml
View File

@ -85,8 +85,8 @@ redirect_from:
json: false
# boxes custom variables
currentVersion: '2.2.1'
link_license: 'https://raw.githubusercontent.com/ascii-boxes/boxes/v2.2.1/LICENSE'
currentVersion: '2.3.0'
link_license: 'https://raw.githubusercontent.com/ascii-boxes/boxes/v2.3.0/LICENSE'
# Page frontmatter defaults
defaults:

8
_data/designs-tag-descriptions.yml
View File

@ -2,6 +2,13 @@
tag_descriptions:
artwork: 'are the complex ASCII art boxes.'
box: 'go around the input text.'
color: |-
feature box shapes colored by ANSI escape codes.
<div class="alert alert-info">
<strong>Note:</strong> In order to color the text, <i>boxes</i> will output ANSI escape codes. Usually,
your terminal will interpret them properly. However, many text editors cannot do that, and you may see
gibberish. In that case, consider using a different design or the <code>--no-color</code> option.
</div>
comment: 'are regional comments in some programming language.'
large: 'are intended for large content, like figlet fonts, or just lots of text. They want to be big!'
programming: >
@ -11,3 +18,4 @@ tag_descriptions:
sign: 'depict an ASCII art figure holding or showing a sign which contains the input text.'
simple: 'are plain boxes, typically excluding <code>artwork</code>.'
speech: 'include a speech bubble.'
unicode: 'are in UTF-8 encoding. The others are ASCII.'

1202
_data/designs-v2_3_0.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

75
_posts/2024-02-17-boxes-v2.3.0-released.md Normal file
View File

@ -0,0 +1,75 @@
---
layout: post
title: "New release: boxes v2.3.0"
date: 2024-02-17 14:00:00 +0100
release: v2.3.0
---
Adds support for UTF-8 box designs, and color in box designs.<!--break-->
This is the biggest change to the code base since the original implementation. Although we literally added hundreds
of new tests, it is still quite possible that some bugs slipped in. Please bear with us, and take the time to
[report](https://github.com/{{ site.github }}/issues) (and maybe even fix!) them.
#### Functional Changes
- The *boxes* config file is now UTF-8 encoded, which allows for lots of new box designs based on UTF-8 characters.
Some examples are among the newly added designs below. This includes characters that take up more than one column
in a terminal, such as Chinese script. [#72](https://github.com/{{ site.github }}/issues/72)
- ANSI color codes are now allowed in box shapes (see
[colored box shapes]({{ site.baseurl}}/config-syntax.html#colored-shapes)). It's a bit technical, because you
need to write ANSI color codes, but quite powerful and versatile.
- In order to properly support colors in every terminal, we now depend on the
[ncurses](https://invisible-island.net/ncurses/) library.
- The new command line options `--color` and `--no-color` can be used to force whether colors are printed by *boxes*.
The default is to print colors if the terminal is color-capable.
- Add long options capability to command line. Every existing option stays the same, but can now also be written in
long form, for example `--mend` instead of `-m`. The complete list is on the
[man page]({{ site.baseurl}}/{{ page.release }}/boxes-man-1.html) and in the output of `boxes --help`.
- [Alias definitions]({{ site.baseurl}}/{{ page.release }}/config-syntax.html#box-design) are now active in the config
file for some designs. We have "lua-cmt" and "sql-cmt" as aliases for
"[ada-cmt]({{ site.baseurl}}/{{ page.release }}/box-designs.html#ada-cmt)", and "lua-box" and "sql-box" for
"[ada-box]({{ site.baseurl}}/{{ page.release }}/box-designs.html#ada-box)".
- We dropped the (mostly unused) fields `created`, `revision`, and `revdate` from the *boxes* config file. They were
introduced when Git hadn't been invented yet and *boxes* was versioned with RCS. Today, a look into Git tells us all
about when stuff was created or modified, so we felt this was the time to shed some ballast.
#### Technical / Internal Changes
- Add MacOS to GitHub Actions workflow and support all test categories on MacOS
by <span class="atmention">[@mathomp4](https://github.com/mathomp4)</span>
- Removed linker `--wrap` option so unit tests can run on MacOS by
<span class="atmention">[@chorpler](https://github.com/chorpler)</span>
- Speed up GitHub Actions runs by no longer calculating the coverage per test. Instead, we calculate the overall
coverage. If you need coverage per test you can get it by calling the test runner with `--coverage-per-test` instead
of `--coverage`.
#### New Box Designs
- New box designs
"[ansi]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi)",
"[ansi-dashed]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi-dashed)",
"[ansi-double]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi-double)",
"[ansi-heavy]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi-heavy)",
"[ansi-heavy-dashed]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi-heavy-dashed)",
"[ansi-rounded]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi-rounded)", and
"[ansi-rounded-dashed]({{ site.baseurl}}/{{ page.release }}/box-designs-unicode.html#ansi-rounded-dashed)"
by <span class="atmention">[@chorpler](https://github.com/chorpler)</span>, all taking
advantage of Unicode box drawing characters
- New Box designs
"[info]({{ site.baseurl}}/{{ page.release }}/box-designs-color.html#info)",
"[warning]({{ site.baseurl}}/{{ page.release }}/box-designs-color.html#warning)", and
"[critical]({{ site.baseurl}}/{{ page.release }}/box-designs-color.html#critical)"
by <span class="atmention">[@tsjensen](https://github.com/tsjensen)</span> as examples of colored Unicode boxes.
The "critical" box design even colors its box contents. In the
[design list]({{ site.baseurl}}/{{ page.release }}/box-designs-color.html), colored designs feature a little moon
icon that you can hover over in order to try out a dark background.
- New box design "[dragon]({{ site.baseurl}}/{{ page.release }}/box-designs.html#dragon)"
- The box designs
"[stark2]({{ site.baseurl}}/{{ page.release }}/box-designs.html#stark2)",
"[sunset]({{ site.baseurl}}/{{ page.release }}/box-designs.html#sunset)",
"[whirly]({{ site.baseurl}}/{{ page.release }}/box-designs.html#whirly)", and
"[xes]({{ site.baseurl}}/{{ page.release }}/box-designs.html#xes)"
received some default padding, hopefully making them appear nicer by default.
[[Release History]({{ site.baseurl}}/releases.html)]

2
pages/box-designs.html
View File

@ -4,5 +4,5 @@ title: 'List of Box Designs'
permalink: /box-designs.html
longContent: true
created_at: 1999-04-06
last_modified_at: 2023-03-03 21:15:00 +0100
last_modified_at: 2024-02-17 14:00:00 +0100
---

330
pages/boxes-man-1.html
View File

@ -5,7 +5,7 @@ redirect_from:
- /docs/boxes-man-1.html
longContent: true
created_at: 1999-04-06
last_modified_at: 2023-08-24 16:48:00 +0200
last_modified_at: 2024-02-17 14:00:00 +0100
---
<h1>boxes</h1>
@ -31,10 +31,7 @@ mode box and comment drawing filter</p>
text="SYNOPSIS" %}
<p style="margin-left:11%; margin-top: 1em"><b>boxes</b>
[-hlmrv] [-a&nbsp;format] [-d&nbsp;design] [-e&nbsp;eol]
[-f&nbsp;file] [-i&nbsp;indent] [-k&nbsp;bool]
[-n&nbsp;encoding] [-p&nbsp;pad] [-q&nbsp;query] [-s&nbsp;size]
[-t&nbsp;tabopts] [infile [outfile]]</p>
[options] [infile [outfile]]</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
@ -67,8 +64,10 @@ text editors: <br>
text="OPTIONS" %}
<p style="margin-left:11%; margin-top: 1em">Options offered
by <i>boxes</i> are the following: <b><br>
-a</b> <i>string</i></p>
by <i>boxes</i> are the following:</p>
<p style="margin-left:11%;">
<a name="opt-a"><b>-a</b> <i>format</i></a>, <b>--align</b>=<i>format</i></p>
<p style="margin-left:20%;">Alignment/positioning of text
inside box. This option takes a format string argument which
@ -76,35 +75,37 @@ is read from left to right. The format string may not
contain whitespace and must consist of one or more of the
following components:</p>
<p style="margin-left:20%; margin-top: 1em"><i>h</i>x -
horizontal alignment of the input text block inside a
potentially larger box. Possible values for <i>x</i> are
<i>l</i> (ell, for left alignment), <i>c</i> (center), or
<i>r</i> (right). This does not affect the justification of
text lines within the input text block (use the <i>j</i>
argument instead). <i><br>
v</i>x - vertical alignment of the input text block inside a
potentially larger box. Possible values for <i>x</i> are
<i>t</i> (for top alignment), <i>c</i> (center), or <i>b</i>
(bottom). <i><br>
j</i>x - justification of lines within the input text block.
Possible values for <i>x</i> are <i>l</i> (ell, for left
justification), <i>c</i> (center), or <i>r</i> (right). This
<ul style="margin-left:20%; margin-top: 1em">
<li><b>h</b><i>x</i> -
horizontal alignment of the input text block inside a box.<br>
Possible values for <i>x</i> are <code>l</code> (ell, for left
alignment), <code>c</code> (center), or <code>r</code> (right). This
does not affect the justification of text lines within the
input text block (use the <b>j</b>&nbsp;argument instead).</li>
<li><b>v</b><i>x</i> - vertical alignment of the input text block inside a
box.<br> Possible values for <i>x</i> are <code>t</code> (for top
alignment), <code>c</code> (center), or <code>b</code> (bottom).</li>
<li><b>j</b><i>x</i> - justification of lines within the input text block.<br>
Possible values for <i>x</i> are <code>l</code> (ell, for left
justification), <code>c</code> (center), or <code>r</code> (right). This
does not affect the alignment of the input text block itself
within the box. Use the <i>h</i> and <i>v</i> arguments for
input text block positioning.</p>
within the box. Use the <b>h</b> and <b>v</b> arguments for
input text block positioning.</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">Short hand
notations (can be combined with the above arguments):
<br>
<i>l</i> (ell) - short for <code>hlvcjl</code><br>
<i>c</i> - short for <code>hcvcjc</code><br>
<i>r</i> - short for <code>hrvcjr</code></p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>l</code> (ell) - short for <code>hlvcjl</code></li>
<li style="margin-bottom:0"><code>c</code> - short for <code>hcvcjc</code></li>
<li style="margin-bottom:0"><code>r</code> - short for <code>hrvcjr</code></li>
</ul>
<p style="margin-left:20%; margin-top: 1em">The factory
default setting for <b>-a</b> is <i>h</i>l<i>v</i>t.</p>
<p style="margin-left:20%; margin-top: 1em">The default for
<code>-a</code> is <code>hlvt</code>.</p>
<p style="margin-left:11%;"><b>-c</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-c"><b>-c</b> <i>string</i></a>,
<b>--create</b>=<i>string</i></p>
<p style="margin-left:20%;">Command line design definition
for simple cases. The argument of this option is the
@ -123,19 +124,44 @@ config file. <b>-c</b> may of course be used in conjunction
with any of the other options. By default, <b>-c</b> is not
specified.</p>
<p style="margin-left:11%;"><b>-d</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-color"><b>--color</b></a>,
<a name="opt-nocolor"><b>--no-color</b></a></p>
<p style="margin-left:20%;">Printing of color codes. Box
designs and the text inside a box may contain ANSI color
codes, sometimes called &quot;escape sequences&quot;. In
this way, boxes and text can be colored. <br>
Whether these escape sequences are printed by <i>boxes</i>
is normally determined by the terminal capabilities
(default). Using <b>--color</b>, <i>boxes</i> can be told to
always output escape sequences even if it thinks the
terminal may not understand them. Using <b>--no-color</b>,
escape sequences will never be printed.</p>
<p style="margin-left:20%; margin-top: 1em">Of course, even
with <b>--color</b>, a box will only appear colored if it is
already defined with colors. In case you want to auto-color
some text that isn&rsquo;t yet, take a look at
<i>lolcat</i>. <br>
These options consider all escape sequences to be color
codes. Any other escape sequences present will be printed or
removed along with the color codes.</p>
<p style="margin-left:11%;"><a name="opt-d"><b>-d</b> <i>string</i></a>,
<b>--design</b>=<i>string</i></p>
<p style="margin-left:20%;">Design selection. The one
argument of this option is the name of the design to use,
which may either be a design&rsquo;s primary name or any of
its alias names.</p>
<p style="margin-left:11%;"><b>-e</b> <i>eol</i></p>
<p style="margin-left:11%;"><a name="opt-e"><b>-e</b> <i>eol</i></a>,
<b>--eol</b>=<i>eol</i></p>
<p style="margin-left:20%;">Override line terminator.
<i>eol</i> can be <i>CR</i>, <i>LF</i>, or <i>CRLF</i>. The
<i>eol</i> can be <code>CR</code>, <code>LF</code>, or <code>CRLF</code>. The
default is to use the system-specific line terminator, which
means <i>CRLF</i> on Windows, and <i>LF</i> otherwise. This
means <code>CRLF</code> on Windows, and <code>LF</code> otherwise. This
option should only be used in an emergency, because normally
the system-specific line terminator will be just fine. This
option is considered experimental, and may go away in a
@ -143,7 +169,8 @@ future version of <i>boxes</i>. Let us know in
<a href="https://github.com/{{ site.github }}/issues/60">https://github.com/{{ site.github }}/issues/60</a>
if you think we should keep it.</p>
<p style="margin-left:11%;"><b>-f</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-f"><b>-f</b> <i>string</i></a>,
<b>--config</b>=<i>string</i></p>
<p style="margin-left:20%;">Use alternate config file. The
one argument of this option is the name of a valid
@ -152,20 +179,24 @@ be a directory which contains a configuration file. More
information on this topic below in the CONFIGURATION FILE
section.</p>
<p style="margin-left:11%;"><b>--help</b><br><b>-h</b></p>
<p style="margin-left:11%;"><a name="opt-h"><b>-h</b></a>, <b>--help</b></p>
<p style="margin-left:20%;">Print usage information.</p>
<p style="margin-left:11%;"><a name="opt-i"><b>-i</b> <i>string</i></a>,
<b>--indent</b>=<i>string</i></p>
<p style="margin-left:11%;"><b>-i</b> <i>string</i></p>
<p style="margin-left:20%;">Indentation mode. Possible values for
<i>string</i> are:</p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>text</code> - indent text inside of box</li>
<li style="margin-bottom:0"><code>box</code> - indent box, not text inside of box</li>
<li style="margin-bottom:0"><code>none</code> - discard indentation</li>
</ul>
<p style="margin-left:20%;">Arguments may be abbreviated. The default is <code>box</code>.</p>
<p style="margin-left:20%;">Indentation mode. Possible
arguments are <i>text</i> (indent text inside of box),
<i>box</i> (indent box, not text inside of box), or
<i>none</i> (throw away indentation). Arguments may be
abbreviated. The default is <i>box</i>.</p>
<p style="margin-left:11%;"><b>-k</b> <i>bool</i></p>
<p style="margin-left:11%;"><a name="opt-k"><b>-k</b> <i>bool</i></a>,
<b>--kill-blank</b>, <b>--no-kill-blank</b></p>
<p style="margin-left:20%;">Kill leading/trailing blank
lines on removal. The value of <i>bool</i> is either
@ -178,24 +209,26 @@ the bottom part of the box are open, as is the case with
most regional comments. If the box&rsquo;s design defines a
top part or a bottom part, the default is <i>true</i>.</p>
<p style="margin-left:11%;"><b>-l</b></p>
<p style="margin-left:11%;"><a name="opt-l"><b>-l</b></a>, <b>--list</b></p>
<p style="margin-left:20%;">(ell) List designs. Produces a listing of all available
box designs in the config file, along with a sample box and
information about its creator. Also checks the syntax of the
entire config file. If used together with <b>-d</b>,
displays detailed information about the specified
design.</p>
<p style="margin-left:20%;">List designs. Produces a
listing of all available box designs in the config file,
along with a sample box and information about its creator.
Also checks the syntax of the entire config file. If used in
conjunction with <b>-d</b>, displays detailed information
about the specified design.</p>
<p style="margin-left:11%;"><b>-m</b></p>
<p style="margin-left:11%;"><a name="opt-m"><b>-m</b>,</a> <b>--mend</b></p>
<p style="margin-left:20%;">Mend box. This removes a (potentially broken) box as
with <b>-r</b>, and redraws it afterwards. The mended box is
drawn according to the options given. This may be important
to know when it comes to restoring padding, indentation,
etc. for the mended box. Implies <b>-k</b> <i>false</i>.</p>
<p style="margin-left:20%;">Mend box. This removes a
(potentially broken) box as with <b>-r</b>, and redraws it
afterwards. The mended box is drawn according to the options
given. This may be important to know when it comes to
restoring padding, indentation, etc. for the mended box.
Implies <b>-k</b> <i>false</i>.</p>
<p style="margin-left:11%;"><b>-n</b> <i>encoding</i></p>
<p style="margin-left:11%;"><a name="opt-n"><b>-n</b> <i>encoding</i></a>,
<b>--encoding</b>=<i>encoding</i></p>
<p style="margin-left:20%;">Character encoding. Overrides
the character encoding of the input and output text. Choose
@ -205,32 +238,36 @@ as a fallback. The default is to use the system encoding,
which is normally the best course of action. So don&rsquo;t
specify this option unless you have to.</p>
<p style="margin-left:11%;"><b>-p</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-p"><b>-p</b> <i>string</i></a>,
<b>--padding</b>=<i>string</i></p>
<p style="margin-left:20%;">Padding. Specify padding in
spaces around the input text block for all sides of the box.
The argument string may not contain whitespace and must
consist of a combination of the following characters, each
followed by a number indicating the padding in spaces:
<i><br>
a</i> - (all) give padding for all sides at once <i><br>
h</i> - (horiz) give padding for both horizontal sides
<i><br>
v</i> - (vertical) give padding for both vertical sides
<i><br>
b</i> - (bottom) give padding for bottom (south) side
<i><br>
l</i> - (left) give padding for left (west) side <i><br>
t</i> - (top) give padding for top (north) side <i><br>
r</i> - (right) give padding for right (east) side <br>
Example: <b>-p</b> <i>a</i>4<i>t</i>2 would define the
padding to be 4 characters on all sides, except for the top
of the box, where the input text block will be only 2 lines
away from the box. <br>
By default, unless specified otherwise in the config file,
no padding is used.</p>
followed by a number indicating the padding in spaces:</p>
<p style="margin-left:11%;"><b>-q</b> <i>query</i></p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>a</code> - (all) give padding for all sides at once</li>
<li style="margin-bottom:0"><code>h</code> - (horiz) give padding for both horizontal sides</li>
<li style="margin-bottom:0"><code>v</code> - (vertical) give padding for both vertical sides</li>
<li style="margin-bottom:0"><code>b</code> - (bottom) give padding for bottom (south) side</li>
<li style="margin-bottom:0"><code>l</code> - (left) give padding for left (west) side</li>
<li style="margin-bottom:0"><code>t</code> - (top) give padding for top (north) side</li>
<li style="margin-bottom:0"><code>r</code> - (right) give padding for right (east) side</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">Example:
<code>-p a4t2</code> would define the padding to be
4 characters on all sides, except for the top of the box,
where the input text block will be only 2 lines away from
the box. <br>
The default for this option is determined by the box design
used. If the design does not specify anything, no default
padding is used.</p>
<p style="margin-left:11%;"><a name="opt-q"><b>-q</b> <i>query</i></a>,
<b>--tag-query</b>=<i>query</i></p>
<p style="margin-left:20%;">Query designs by tag. In
contrast to <b>-l</b>, this will only print the matching
@ -241,27 +278,30 @@ list of tags which can be present on a design in order to
match. A tag may optionally be prefixed with <code>+</code> in
order to require that it be present, or with <code>-</code> in
order to exclude designs which have that tag. Each tag can
only occur once per query. <br>
only occur once per query. The special query <i>(all)</i>
matches all box designs, even if they don&apos;t have any
tags. <br>
This option is intended for use by scripts. Alias names are
printed below their primary design name, and postfixed with
<code>(alias)</code>. <br>
Example: <code>boxes -q programming,-comment</code></p>
<p style="margin-left:11%;"><b>-r</b></p>
<p style="margin-left:11%;"><a name="opt-r"><b>-r</b></a>, <b>--remove</b></p>
<p style="margin-left:20%;">Remove an existing box. Which design to use is detected
automatically. In order to save time or in case the
detection does not decide correctly, combine with <b>-d</b>
to specify the design. The default is to draw a new box.</p>
<p style="margin-left:20%;">Remove an existing box. Which
design to use is detected automatically. In order to save
time or in case the detection does not decide correctly,
combine with <b>-d</b> to specify the design.</p>
<p style="margin-left:11%;"><b>-s</b>
<i>width</i><b>x</b><i>height</i></p>
<p style="margin-left:11%;"><a name="opt-s"><b>-s</b>
<i>width</i><b>x</b><i>height</i></a>,
<b>--size</b>=<i>width</i><b>x</b><i>height</i></p>
<p style="margin-left:20%;">Box size. This option specifies
the desired box size in units of columns (for width) and
lines (for height). If only a single number is given as
argument, this number specifies the desired box width. A
single number prefixed by &rsquo;x&rsquo; specifies only the
single number prefixed by <code>x</code> specifies only the
box height. The actual resulting box size may vary depending
on the individual shape sizes of the chosen design. Also,
other command line options may influence the box size (such
@ -269,42 +309,39 @@ as <b>-p</b>). <br>
By default, the smallest possible box is created around the
text.</p>
<p style="margin-left:11%;"><b>-t</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-t"><b>-t</b> <i>tabopts</i></a>,
<b>--tabs</b>=<i>tabopts</i></p>
<p style="margin-left:20%;">Tab handling. This option
controls how tab characters in the input text are handled.
The option string must always begin with a <i>uint</i>
number indicating the distance between tab stops. It is
important that this value be set correctly, or tabulator
characters will upset your input text. The correct tab
distance value depends on the settings used for the text you
are processing. A common value is 8. <br>
The <i>tabopts</i> must always begin with a positive integer
number indicating the distance between tab stops, sometimes
called &quot;spaces per tab&quot;. <br>
Immediately following the tab distance, an optional
character can be appended, telling <i>boxes</i> how to treat
the leading tabs. The following options are available:
<b><br>
e</b> - expand tabs into spaces <b><br>
k</b> - keep tabs as close to what they were as possible
<b><br>
u</b> - unexpand tabs. This makes <i>boxes</i> turn as many
spaces as possible into tabs.</p>
the leading tabs. The following options are available:</p>
<p style="margin-left:20%; margin-top: 1em">In order to
maintain backwards compatibility, the <b>-t</b>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>e</code> - expand tabs into spaces</li>
<li style="margin-bottom:0"><code>k</code> - keep tabs as close to what they were as possible</li>
<li style="margin-bottom:0"><code>u</code> - unexpand tabs. This makes <i>boxes</i> turn as many
spaces as possible into tabs.</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">The <b>-t</b>
<i>string</i> can be just a number. In that case, <b>e</b>
is assumed for tab handling, which removes all tabs and
replaces them with spaces. The factory default for the
<b>-t</b> option is simply 8, which is just such a case.
is assumed for tab handling. The default for the
<b>-t</b> option is simply <code>8</code>, which is just such a case.
<br>
For example, you could specify <b>-t</b> 4u in order to have
For example, you could specify <code>-t 4u</code> in order to have
your leading tabs unexpanded. In the box content, tabs are
always converted into spaces. The tab distance in this
example is 4.</p>
<p style="margin-left:11%;"><b>-v</b></p>
<p style="margin-left:20%;">Print out current version number.</p>
<p style="margin-left:11%;"><a name="opt-v"><b>-v</b></a>, <b>--version</b></p>
<p style="margin-left:20%;">Print out current version
number.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
@ -313,35 +350,31 @@ example is 4.</p>
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
will look for the configuration file in several places, some
of which are given by the XDG specification. <b><br>
1.</b> <i>-f</i> option [file or dir]</p>
of which are given by the XDG specification.
<p style="margin-left:20%;">When a configuration file is
specified on the command line, we will use that. The
<b>-f</b> option can also specify a directory. Any location
specified via <b>-f</b> must exist, or <i>boxes</i> will
terminate with an error.</p>
<ol style="margin-left:11%;">
<li style="margin-bottom:0"><b>-f</b> option [file or dir]<br>When a configuration file is
specified on the command line, we will use that. The
<b>-f</b> option can also specify a directory. Any location
specified via <b>-f</b> must exist, or <i>boxes</i> will
terminate with an error.</li>
<li style="margin-bottom:0"><i>BOXES</i> environment variable [file or dir]<br>
If no config file is specified
on the command line, <i>boxes</i> will check for the BOXES
environment variable, which may contain a filename or
directory to use. Any location specified via the BOXES
environment variable must exist, or <i>boxes</i> will
terminate with an error.</li>
<li style="margin-bottom:0"><i>$HOME</i> [dir]</li>
<li style="margin-bottom:0"><i>$XDG_CONFIG_HOME/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>$HOME/.config/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/share/boxes</i> [file]</li>
<li style="margin-bottom:0"><i>/etc/xdg/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/local/share/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/share/boxes</i> [dir]</li>
</ol>
<p style="margin-left:11%;"><b>2.</b> <i>BOXES</i>
environment variable [file or dir]</p>
<p style="margin-left:20%;">If no config file is specified
on the command line, <i>boxes</i> will check for the BOXES
environment variable, which may contain a filename or
directory to use. Any location specified via the BOXES
environment variable must exist, or <i>boxes</i> will
terminate with an error.</p>
<p style="margin-left:11%;"><b>3.</b> <i>$HOME</i> [dir]
<b><br>
4.</b> <i>$XDG_CONFIG_HOME/boxes</i> [dir] <b><br>
5.</b> <i>$HOME/.config/boxes</i> [dir] <b><br>
6.</b> <i>/usr/share/boxes</i> [file] <b><br>
7.</b> <i>/etc/xdg/boxes</i> [dir] <b><br>
8.</b> <i>/usr/local/share/boxes</i> [dir] <b><br>
9.</b> <i>/usr/share/boxes</i> [dir]</p>
<p style="margin-left:20%;">Either one of these last two
<p style="margin-left:11%;">Either one of these last two
directory locations might have the same name as the global
config file from <b>6</b>. That&rsquo;s fine. It just means
that we first look for a file of that name, and then for a
@ -352,13 +385,14 @@ environment variable <i>XDG_CONFIG_DIRS</i> is not
supported. However, its default value is supported via steps
<b>8</b> and <b>9</b> above. <br>
In the above list, whenever a step is designated with [dir],
the <br>
following file names will be found, in this order:</p>
the following file names will be found, in this order:</p>
<p style="margin-left:20%;"><b>1.</b> .boxes <b><br>
2.</b> box-designs <b><br>
3.</b> boxes-config <b><br>
4.</b> boxes</p>
<ol style="margin-left:11%;">
<li style="margin-bottom:0"><code>.boxes</code></li>
<li style="margin-bottom:0"><code>box-designs</code></li>
<li style="margin-bottom:0"><code>boxes-config</code></li>
<li style="margin-bottom:0"><code>boxes</code></li>
</ol>
<p style="margin-left:11%; margin-top: 1em">As soon as the
first valid file is found, we use that and stop the
@ -373,7 +407,7 @@ fully supported, too.</p>
<p style="margin-left:11%; margin-top: 1em">The syntax of
<i>boxes</i> config files is described on the website at
<a href="{{ site.url }}{{ site.baseurl }}/config-syntax.html">{{ site.url }}{{ site.baseurl }}/config-syntax.html</a>.</p>
<a href="{{ site.baseurl }}/config-syntax.html">{{ site.url }}{{ site.baseurl }}/config-syntax.html</a>.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
@ -383,7 +417,7 @@ fully supported, too.</p>
<p style="margin-left:11%; margin-top: 1em">Examples on how
to invoke <i>boxes</i> may be found on the website at
<a href="{{ site.url }}{{ site.baseurl }}/examples.html">{{ site.url }}{{ site.baseurl }}/examples.html</a>.
<a href="{{ site.baseurl }}/examples.html">{{ site.url }}{{ site.baseurl }}/examples.html</a>.
<br>
Try</p>
@ -417,7 +451,7 @@ was made by Thomas Jensen and the <i>boxes</i> contributors.
It has been lovingly maintained since 1999. <br>
For a full list of contributors, see
<a href="{{ site.baseurl }}/team.html#contributors">{{ site.baseurl }}/team.html#contributors</a>
<a href="{{ site.baseurl }}/team.html#contributors">{{ site.url }}{{ site.baseurl }}/team.html#contributors</a>
and
<a href="https://github.com/{{ site.github }}/graphs/contributors">https://github.com/{{ site.github }}/graphs/contributors</a>.
<br>
@ -450,7 +484,9 @@ License, version 3. Details in the LICENSE file:
level=2 slug="ENVIRONMENT"
text="ENVIRONMENT" %}
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i> recognizes the following environment variables:</p>
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
recognizes the following environment variables:</p>
<dl style="margin-left: 11%">
<dt>BOXES</dt>

2
pages/config-syntax.md
View File

@ -6,7 +6,7 @@ redirect_from:
- /docs/config-syntax.shtml
longContent: true
created_at: 1999-04-06
last_modified_at: 2022-09-22 21:48:00 +0200
last_modified_at: 2024-02-17 14:00:00 +0100
---
# Config File Syntax

9
pages/releases.md
View File

@ -4,7 +4,7 @@ permalink: /releases.html
redirect_from:
- /docs/releases.html
created_at: 2015-03-17 22:06:12 +0100
last_modified_at: 2021-06-14 21:32:00 +0200
last_modified_at: 2024-02-17 14:00:00 +0100
---
# Release Notes
@ -22,6 +22,13 @@ Click on the version numbers to view the release notes for each release.
</tr>
</thead>
<tbody>
<tr>
<th scope="row"><a href="{{ site.baseurl}}{% post_url 2024-02-17-boxes-v2.3.0-released %}">2.3.0</a></th>
<td>February&nbsp;17, 2024</td>
<td><a href="https://github.com/{{ site.github }}/tree/v2.3.0">link</a></td>
<td><a href="https://github.com/{{ site.github }}/releases/tag/v2.3.0">link</a></td>
<td class="d-none d-sm-table-cell">Colored UTF-8 boxes</td>
</tr>
<tr>
<th scope="row"><a href="{{ site.baseurl}}{% post_url 2023-08-24-boxes-v2.2.1-released %}">2.2.1</a></th>
<td>August&nbsp;24, 2023</td>

7
pages/v2.0.0/boxes-man-1.html
View File

@ -291,10 +291,11 @@ $HOME/.boxes and use it as a config file. Failing that,
<p style="margin-left:11%; margin-top: 1em">The syntax of
<i>boxes</i> config files is described on the website.</p>
<h2>EXAMPLES
<a name="EXAMPLES"></a>
</h2>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="EXAMPLES"
text="EXAMPLES" %}
<p style="margin-left:11%; margin-top: 1em">Examples on how
to invoke <i>boxes</i> may be found on the website at

291
pages/v2.2.1/boxes-man-1.html
View File

@ -65,8 +65,10 @@ text editors: <br>
text="OPTIONS" %}
<p style="margin-left:11%; margin-top: 1em">Options offered
by <i>boxes</i> are the following: <b><br>
-a</b> <i>string</i></p>
by <i>boxes</i> are the following:</p>
<p style="margin-left:11%;">
<a name="opt-a"><b>-a</b> <i>format</i></a></p>
<p style="margin-left:20%;">Alignment/positioning of text
inside box. This option takes a format string argument which
@ -74,35 +76,36 @@ is read from left to right. The format string may not
contain whitespace and must consist of one or more of the
following components:</p>
<p style="margin-left:20%; margin-top: 1em"><i>h</i>x -
horizontal alignment of the input text block inside a
potentially larger box. Possible values for <i>x</i> are
<i>l</i> (ell, for left alignment), <i>c</i> (center), or
<i>r</i> (right). This does not affect the justification of
text lines within the input text block (use the <i>j</i>
argument instead). <i><br>
v</i>x - vertical alignment of the input text block inside a
potentially larger box. Possible values for <i>x</i> are
<i>t</i> (for top alignment), <i>c</i> (center), or <i>b</i>
(bottom). <i><br>
j</i>x - justification of lines within the input text block.
Possible values for <i>x</i> are <i>l</i> (ell, for left
justification), <i>c</i> (center), or <i>r</i> (right). This
<ul style="margin-left:20%; margin-top: 1em">
<li><b>h</b><i>x</i> -
horizontal alignment of the input text block inside a box.<br>
Possible values for <i>x</i> are <code>l</code> (ell, for left
alignment), <code>c</code> (center), or <code>r</code> (right). This
does not affect the justification of text lines within the
input text block (use the <b>j</b>&nbsp;argument instead).</li>
<li><b>v</b><i>x</i> - vertical alignment of the input text block inside a
box.<br> Possible values for <i>x</i> are <code>t</code> (for top
alignment), <code>c</code> (center), or <code>b</code> (bottom).</li>
<li><b>j</b><i>x</i> - justification of lines within the input text block.<br>
Possible values for <i>x</i> are <code>l</code> (ell, for left
justification), <code>c</code> (center), or <code>r</code> (right). This
does not affect the alignment of the input text block itself
within the box. Use the <i>h</i> and <i>v</i> arguments for
input text block positioning.</p>
within the box. Use the <b>h</b> and <b>v</b> arguments for
input text block positioning.</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">Short hand
notations (can be combined with the above arguments):
<br>
<i>l</i> (ell) - short for <code>hlvcjl</code><br>
<i>c</i> - short for <code>hcvcjc</code><br>
<i>r</i> - short for <code>hrvcjr</code></p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>l</code> (ell) - short for <code>hlvcjl</code></li>
<li style="margin-bottom:0"><code>c</code> - short for <code>hcvcjc</code></li>
<li style="margin-bottom:0"><code>r</code> - short for <code>hrvcjr</code></li>
</ul>
<p style="margin-left:20%; margin-top: 1em">The factory
default setting for <b>-a</b> is <i>h</i>l<i>v</i>t.</p>
<p style="margin-left:20%; margin-top: 1em">The default for
<code>-a</code> is <code>hlvt</code>.</p>
<p style="margin-left:11%;"><b>-c</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-c"><b>-c</b> <i>string</i></a></p>
<p style="margin-left:20%;">Command line design definition
for simple cases. The argument of this option is the
@ -121,19 +124,19 @@ config file. <b>-c</b> may of course be used in conjunction
with any of the other options. By default, <b>-c</b> is not
specified.</p>
<p style="margin-left:11%;"><b>-d</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-d"><b>-d</b> <i>string</i></a></p>
<p style="margin-left:20%;">Design selection. The one
argument of this option is the name of the design to use,
which may either be a design&rsquo;s primary name or any of
its alias names.</p>
<p style="margin-left:11%;"><b>-e</b> <i>eol</i></p>
<p style="margin-left:11%;"><a name="opt-e"><b>-e</b> <i>eol</i></a></p>
<p style="margin-left:20%;">Override line terminator.
<i>eol</i> can be <i>CR</i>, <i>LF</i>, or <i>CRLF</i>. The
<i>eol</i> can be <code>CR</code>, <code>LF</code>, or <code>CRLF</code>. The
default is to use the system-specific line terminator, which
means <i>CRLF</i> on Windows, and <i>LF</i> otherwise. This
means <code>CRLF</code> on Windows, and <code>LF</code> otherwise. This
option should only be used in an emergency, because normally
the system-specific line terminator will be just fine. This
option is considered experimental, and may go away in a
@ -141,7 +144,7 @@ future version of <i>boxes</i>. Let us know in
<a href="https://github.com/{{ site.github }}/issues/60">https://github.com/{{ site.github }}/issues/60</a>
if you think we should keep it.</p>
<p style="margin-left:11%;"><b>-f</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-f"><b>-f</b> <i>string</i></a></p>
<p style="margin-left:20%;">Use alternate config file. The
one argument of this option is the name of a valid
@ -150,20 +153,22 @@ be a directory which contains a configuration file. More
information on this topic below in the CONFIGURATION FILE
section.</p>
<p style="margin-left:11%;"><b>--help</b><br><b>-h</b></p>
<p style="margin-left:11%;"><a name="opt-h"><b>-h</b></a>, <b>--help</b></p>
<p style="margin-left:20%;">Print usage information.</p>
<p style="margin-left:11%;"><a name="opt-i"><b>-i</b> <i>string</i></a></p>
<p style="margin-left:11%;"><b>-i</b> <i>string</i></p>
<p style="margin-left:20%;">Indentation mode. Possible values for
<i>string</i> are:</p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>text</code> - indent text inside of box</li>
<li style="margin-bottom:0"><code>box</code> - indent box, not text inside of box</li>
<li style="margin-bottom:0"><code>none</code> - discard indentation</li>
</ul>
<p style="margin-left:20%;">Arguments may be abbreviated. The default is <code>box</code>.</p>
<p style="margin-left:20%;">Indentation mode. Possible
arguments are <i>text</i> (indent text inside of box),
<i>box</i> (indent box, not text inside of box), or
<i>none</i> (throw away indentation). Arguments may be
abbreviated. The default is <i>box</i>.</p>
<p style="margin-left:11%;"><b>-k</b> <i>bool</i></p>
<p style="margin-left:11%;"><a name="opt-k"><b>-k</b> <i>bool</i></a></p>
<p style="margin-left:20%;">Kill leading/trailing blank
lines on removal. The value of <i>bool</i> is either
@ -176,24 +181,25 @@ the bottom part of the box are open, as is the case with
most regional comments. If the box&rsquo;s design defines a
top part or a bottom part, the default is <i>true</i>.</p>
<p style="margin-left:11%;"><b>-l</b></p>
<p style="margin-left:11%;"><a name="opt-l"><b>-l</b></a></p>
<p style="margin-left:20%;">(ell) List designs. Produces a listing of all available
box designs in the config file, along with a sample box and
information about its creator. Also checks the syntax of the
entire config file. If used together with <b>-d</b>,
displays detailed information about the specified
design.</p>
<p style="margin-left:20%;">List designs. Produces a
listing of all available box designs in the config file,
along with a sample box and information about its creator.
Also checks the syntax of the entire config file. If used in
conjunction with <b>-d</b>, displays detailed information
about the specified design.</p>
<p style="margin-left:11%;"><b>-m</b></p>
<p style="margin-left:11%;"><a name="opt-m"><b>-m</b></a></p>
<p style="margin-left:20%;">Mend box. This removes a (potentially broken) box as
with <b>-r</b>, and redraws it afterwards. The mended box is
drawn according to the options given. This may be important
to know when it comes to restoring padding, indentation,
etc. for the mended box. Implies <b>-k</b> <i>false</i>.</p>
<p style="margin-left:20%;">Mend box. This removes a
(potentially broken) box as with <b>-r</b>, and redraws it
afterwards. The mended box is drawn according to the options
given. This may be important to know when it comes to
restoring padding, indentation, etc. for the mended box.
Implies <b>-k</b> <i>false</i>.</p>
<p style="margin-left:11%;"><b>-n</b> <i>encoding</i></p>
<p style="margin-left:11%;"><a name="opt-n"><b>-n</b> <i>encoding</i></a></p>
<p style="margin-left:20%;">Character encoding. Overrides
the character encoding of the input and output text. Choose
@ -203,32 +209,34 @@ as a fallback. The default is to use the system encoding,
which is normally the best course of action. So don&rsquo;t
specify this option unless you have to.</p>
<p style="margin-left:11%;"><b>-p</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-p"><b>-p</b> <i>string</i></a></p>
<p style="margin-left:20%;">Padding. Specify padding in
spaces around the input text block for all sides of the box.
The argument string may not contain whitespace and must
consist of a combination of the following characters, each
followed by a number indicating the padding in spaces:
<i><br>
a</i> - (all) give padding for all sides at once <i><br>
h</i> - (horiz) give padding for both horizontal sides
<i><br>
v</i> - (vertical) give padding for both vertical sides
<i><br>
b</i> - (bottom) give padding for bottom (south) side
<i><br>
l</i> - (left) give padding for left (west) side <i><br>
t</i> - (top) give padding for top (north) side <i><br>
r</i> - (right) give padding for right (east) side <br>
Example: <b>-p</b> <i>a</i>4<i>t</i>2 would define the
padding to be 4 characters on all sides, except for the top
of the box, where the input text block will be only 2 lines
away from the box. <br>
By default, unless specified otherwise in the config file,
no padding is used.</p>
followed by a number indicating the padding in spaces:</p>
<p style="margin-left:11%;"><b>-q</b> <i>query</i></p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>a</code> - (all) give padding for all sides at once</li>
<li style="margin-bottom:0"><code>h</code> - (horiz) give padding for both horizontal sides</li>
<li style="margin-bottom:0"><code>v</code> - (vertical) give padding for both vertical sides</li>
<li style="margin-bottom:0"><code>b</code> - (bottom) give padding for bottom (south) side</li>
<li style="margin-bottom:0"><code>l</code> - (left) give padding for left (west) side</li>
<li style="margin-bottom:0"><code>t</code> - (top) give padding for top (north) side</li>
<li style="margin-bottom:0"><code>r</code> - (right) give padding for right (east) side</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">Example:
<code>-p a4t2</code> would define the padding to be
4 characters on all sides, except for the top of the box,
where the input text block will be only 2 lines away from
the box. <br>
The default for this option is determined by the box design
used. If the design does not specify anything, no default
padding is used.</p>
<p style="margin-left:11%;"><a name="opt-q"><b>-q</b> <i>query</i></a></p>
<p style="margin-left:20%;">Query designs by tag. In
contrast to <b>-l</b>, this will only print the matching
@ -239,27 +247,29 @@ list of tags which can be present on a design in order to
match. A tag may optionally be prefixed with <code>+</code> in
order to require that it be present, or with <code>-</code> in
order to exclude designs which have that tag. Each tag can
only occur once per query. <br>
only occur once per query. The special query <i>(all)</i>
matches all box designs, even if they don&apos;t have any
tags. <br>
This option is intended for use by scripts. Alias names are
printed below their primary design name, and postfixed with
<code>(alias)</code>. <br>
Example: <code>boxes -q programming,-comment</code></p>
<p style="margin-left:11%;"><b>-r</b></p>
<p style="margin-left:11%;"><a name="opt-r"><b>-r</b></a></p>
<p style="margin-left:20%;">Remove an existing box. Which design to use is detected
automatically. In order to save time or in case the
detection does not decide correctly, combine with <b>-d</b>
to specify the design. The default is to draw a new box.</p>
<p style="margin-left:20%;">Remove an existing box. Which
design to use is detected automatically. In order to save
time or in case the detection does not decide correctly,
combine with <b>-d</b> to specify the design.</p>
<p style="margin-left:11%;"><b>-s</b>
<i>width</i><b>x</b><i>height</i></p>
<p style="margin-left:11%;"><a name="opt-s"><b>-s</b>
<i>width</i><b>x</b><i>height</i></a></p>
<p style="margin-left:20%;">Box size. This option specifies
the desired box size in units of columns (for width) and
lines (for height). If only a single number is given as
argument, this number specifies the desired box width. A
single number prefixed by &rsquo;x&rsquo; specifies only the
single number prefixed by <code>x</code> specifies only the
box height. The actual resulting box size may vary depending
on the individual shape sizes of the chosen design. Also,
other command line options may influence the box size (such
@ -267,42 +277,38 @@ as <b>-p</b>). <br>
By default, the smallest possible box is created around the
text.</p>
<p style="margin-left:11%;"><b>-t</b> <i>string</i></p>
<p style="margin-left:11%;"><a name="opt-t"><b>-t</b> <i>tabopts</i></a></p>
<p style="margin-left:20%;">Tab handling. This option
controls how tab characters in the input text are handled.
The option string must always begin with a <i>uint</i>
number indicating the distance between tab stops. It is
important that this value be set correctly, or tabulator
characters will upset your input text. The correct tab
distance value depends on the settings used for the text you
are processing. A common value is 8. <br>
The <i>tabopts</i> must always begin with a positive integer
number indicating the distance between tab stops, sometimes
called &quot;spaces per tab&quot;. <br>
Immediately following the tab distance, an optional
character can be appended, telling <i>boxes</i> how to treat
the leading tabs. The following options are available:
<b><br>
e</b> - expand tabs into spaces <b><br>
k</b> - keep tabs as close to what they were as possible
<b><br>
u</b> - unexpand tabs. This makes <i>boxes</i> turn as many
spaces as possible into tabs.</p>
the leading tabs. The following options are available:</p>
<p style="margin-left:20%; margin-top: 1em">In order to
maintain backwards compatibility, the <b>-t</b>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>e</code> - expand tabs into spaces</li>
<li style="margin-bottom:0"><code>k</code> - keep tabs as close to what they were as possible</li>
<li style="margin-bottom:0"><code>u</code> - unexpand tabs. This makes <i>boxes</i> turn as many
spaces as possible into tabs.</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">The <b>-t</b>
<i>string</i> can be just a number. In that case, <b>e</b>
is assumed for tab handling, which removes all tabs and
replaces them with spaces. The factory default for the
<b>-t</b> option is simply 8, which is just such a case.
is assumed for tab handling. The default for the
<b>-t</b> option is simply <code>8</code>, which is just such a case.
<br>
For example, you could specify <b>-t</b> 4u in order to have
For example, you could specify <code>-t 4u</code> in order to have
your leading tabs unexpanded. In the box content, tabs are
always converted into spaces. The tab distance in this
example is 4.</p>
<p style="margin-left:11%;"><b>-v</b></p>
<p style="margin-left:20%;">Print out current version number.</p>
<p style="margin-left:11%;"><a name="opt-v"><b>-v</b></a></p>
<p style="margin-left:20%;">Print out current version
number.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
@ -311,35 +317,31 @@ example is 4.</p>
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
will look for the configuration file in several places, some
of which are given by the XDG specification. <b><br>
1.</b> <i>-f</i> option [file or dir]</p>
of which are given by the XDG specification.
<p style="margin-left:20%;">When a configuration file is
specified on the command line, we will use that. The
<b>-f</b> option can also specify a directory. Any location
specified via <b>-f</b> must exist, or <i>boxes</i> will
terminate with an error.</p>
<ol style="margin-left:11%;">
<li style="margin-bottom:0"><b>-f</b> option [file or dir]<br>When a configuration file is
specified on the command line, we will use that. The
<b>-f</b> option can also specify a directory. Any location
specified via <b>-f</b> must exist, or <i>boxes</i> will
terminate with an error.</li>
<li style="margin-bottom:0"><i>BOXES</i> environment variable [file or dir]<br>
If no config file is specified
on the command line, <i>boxes</i> will check for the BOXES
environment variable, which may contain a filename or
directory to use. Any location specified via the BOXES
environment variable must exist, or <i>boxes</i> will
terminate with an error.</li>
<li style="margin-bottom:0"><i>$HOME</i> [dir]</li>
<li style="margin-bottom:0"><i>$XDG_CONFIG_HOME/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>$HOME/.config/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/share/boxes</i> [file]</li>
<li style="margin-bottom:0"><i>/etc/xdg/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/local/share/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/share/boxes</i> [dir]</li>
</ol>
<p style="margin-left:11%;"><b>2.</b> <i>BOXES</i>
environment variable [file or dir]</p>
<p style="margin-left:20%;">If no config file is specified
on the command line, <i>boxes</i> will check for the BOXES
environment variable, which may contain a filename or
directory to use. Any location specified via the BOXES
environment variable must exist, or <i>boxes</i> will
terminate with an error.</p>
<p style="margin-left:11%;"><b>3.</b> <i>$HOME</i> [dir]
<b><br>
4.</b> <i>$XDG_CONFIG_HOME/boxes</i> [dir] <b><br>
5.</b> <i>$HOME/.config/boxes</i> [dir] <b><br>
6.</b> <i>/usr/share/boxes</i> [file] <b><br>
7.</b> <i>/etc/xdg/boxes</i> [dir] <b><br>
8.</b> <i>/usr/local/share/boxes</i> [dir] <b><br>
9.</b> <i>/usr/share/boxes</i> [dir]</p>
<p style="margin-left:20%;">Either one of these last two
<p style="margin-left:11%;">Either one of these last two
directory locations might have the same name as the global
config file from <b>6</b>. That&rsquo;s fine. It just means
that we first look for a file of that name, and then for a
@ -350,13 +352,14 @@ environment variable <i>XDG_CONFIG_DIRS</i> is not
supported. However, its default value is supported via steps
<b>8</b> and <b>9</b> above. <br>
In the above list, whenever a step is designated with [dir],
the <br>
following file names will be found, in this order:</p>
the following file names will be found, in this order:</p>
<p style="margin-left:20%;"><b>1.</b> .boxes <b><br>
2.</b> box-designs <b><br>
3.</b> boxes-config <b><br>
4.</b> boxes</p>
<ol style="margin-left:11%;">
<li style="margin-bottom:0"><code>.boxes</code></li>
<li style="margin-bottom:0"><code>box-designs</code></li>
<li style="margin-bottom:0"><code>boxes-config</code></li>
<li style="margin-bottom:0"><code>boxes</code></li>
</ol>
<p style="margin-left:11%; margin-top: 1em">As soon as the
first valid file is found, we use that and stop the
@ -371,7 +374,7 @@ fully supported, too.</p>
<p style="margin-left:11%; margin-top: 1em">The syntax of
<i>boxes</i> config files is described on the website at
<a href="{{ site.url }}{{ site.baseurl }}/config-syntax.html">{{ site.url }}{{ site.baseurl }}/config-syntax.html</a>.</p>
<a href="{{ site.baseurl }}/config-syntax.html">{{ site.url }}{{ site.baseurl }}/config-syntax.html</a>.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
@ -381,7 +384,7 @@ fully supported, too.</p>
<p style="margin-left:11%; margin-top: 1em">Examples on how
to invoke <i>boxes</i> may be found on the website at
<a href="{{ site.url }}{{ site.baseurl }}/examples.html">{{ site.url }}{{ site.baseurl }}/examples.html</a>.
<a href="{{ site.baseurl }}/examples.html">{{ site.url }}{{ site.baseurl }}/examples.html</a>.
<br>
Try</p>
@ -415,7 +418,7 @@ was made by Thomas Jensen and the <i>boxes</i> contributors.
It has been lovingly maintained since 1999. <br>
For a full list of contributors, see
<a href="{{ site.baseurl }}/team.html#contributors">{{ site.baseurl }}/team.html#contributors</a>
<a href="{{ site.baseurl }}/team.html#contributors">{{ site.url }}{{ site.baseurl }}/team.html#contributors</a>
and
<a href="https://github.com/{{ site.github }}/graphs/contributors">https://github.com/{{ site.github }}/graphs/contributors</a>.
<br>
@ -440,7 +443,7 @@ maintainer&rsquo;s current email address.</p>
<p style="margin-left:11%; margin-top: 1em"><i>boxes</i> is
free software under the terms of the GNU General Public
License, version 3. Details in the LICENSE file:
<a href="https://raw.githubusercontent.com/{{ site.github }}/v2.2.0/LICENSE">https://raw.githubusercontent.com/{{ site.github }}/v2.2.0/LICENSE</a></p>
<a href="https://raw.githubusercontent.com/{{ site.github }}/{{ page.bxVersion }}/LICENSE">https://raw.githubusercontent.com/{{ site.github }}/{{ page.bxVersion }}/LICENSE</a></p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
@ -448,7 +451,9 @@ License, version 3. Details in the LICENSE file:
level=2 slug="ENVIRONMENT"
text="ENVIRONMENT" %}
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i> recognizes the following environment variables:</p>
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
recognizes the following environment variables:</p>
<dl style="margin-left: 11%">
<dt>BOXES</dt>

2
pages/v2.2.1/config-syntax.md
View File

@ -4,7 +4,7 @@ permalink: /v2.2.1/config-syntax.html
longContent: true
bxVersion: v2.2.1
created_at: 1999-04-06
last_modified_at: 2022-09-22 21:48:00 +0200
last_modified_at: 2023-08-24 21:40:00 +0200
---
# Config File Syntax

10
pages/v2.3.0/box-designs-artwork.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: artwork)'
permalink: /v2.3.0/box-designs-artwork.html
designTag: artwork
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-box.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: box)'
permalink: /v2.3.0/box-designs-box.html
designTag: box
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-color.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: color)'
permalink: /v2.3.0/box-designs-color.html
designTag: color
longContent: false
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-comment.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: comment)'
permalink: /v2.3.0/box-designs-comment.html
designTag: comment
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-large.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: large)'
permalink: /v2.3.0/box-designs-large.html
designTag: large
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-programming.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: programming)'
permalink: /v2.3.0/box-designs-programming.html
designTag: programming
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-scroll.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: scroll)'
permalink: /v2.3.0/box-designs-scroll.html
designTag: scroll
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-sign.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: sign)'
permalink: /v2.3.0/box-designs-sign.html
designTag: sign
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-simple.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: simple)'
permalink: /v2.3.0/box-designs-simple.html
designTag: simple
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-speech.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: speech)'
permalink: /v2.3.0/box-designs-speech.html
designTag: speech
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

10
pages/v2.3.0/box-designs-unicode.html Normal file
View File

@ -0,0 +1,10 @@
---
layout: designlist
title: 'List of Box Designs (tag: unicode)'
permalink: /v2.3.0/box-designs-unicode.html
designTag: unicode
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

9
pages/v2.3.0/box-designs.html Normal file
View File

@ -0,0 +1,9 @@
---
layout: designlist
title: 'List of Box Designs'
permalink: /v2.3.0/box-designs.html
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---

506
pages/v2.3.0/boxes-man-1.html Normal file
View File

@ -0,0 +1,506 @@
---
title: Manpage of boxes(1)
permalink: /v2.3.0/boxes-man-1.html
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---
<h1>boxes</h1>
{% include version-select.html currentVersion=page.bxVersion contentPiece="boxes-man-1" %}
<p>Section: User Commands (1)<BR>Updated: {{ page.last_modified_at | date: "%B %e %Y" }}</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="NAME"
text="NAME" %}
<p style="margin-left:11%; margin-top: 1em">boxes - text
mode box and comment drawing filter</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="SYNOPSIS"
text="SYNOPSIS" %}
<p style="margin-left:11%; margin-top: 1em"><b>boxes</b>
[options] [infile [outfile]]</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="DESCRIPTION"
text="DESCRIPTION" %}
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i> is
a text filter which can draw any kind of box around its
input text. Box design choices range from simple boxes to
complex ASCII art. A box can also be removed and repaired,
even if it has been badly damaged by editing of the text
inside. Since boxes may be open on any side, <i>boxes</i>
can also be used to create regional comments in any
programming language. New box designs can be added and
shared by appending to a configuration file.</p>
<p style="margin-left:11%; margin-top: 1em"><i>boxes</i> is
a command line tool, but also integrates with any text
editor that supports filters. The <i>boxes</i> website has
examples on how to configure editor integration for various
text editors: <br>
<a href="{{ site.baseurl }}/editors.html">{{ site.url }}{{ site.baseurl }}/editors.html</a></p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="OPTIONS"
text="OPTIONS" %}
<p style="margin-left:11%; margin-top: 1em">Options offered
by <i>boxes</i> are the following:</p>
<p style="margin-left:11%;">
<a name="opt-a"><b>-a</b> <i>format</i></a>, <b>--align</b>=<i>format</i></p>
<p style="margin-left:20%;">Alignment/positioning of text
inside box. This option takes a format string argument which
is read from left to right. The format string may not
contain whitespace and must consist of one or more of the
following components:</p>
<ul style="margin-left:20%; margin-top: 1em">
<li><b>h</b><i>x</i> -
horizontal alignment of the input text block inside a box.<br>
Possible values for <i>x</i> are <code>l</code> (ell, for left
alignment), <code>c</code> (center), or <code>r</code> (right). This
does not affect the justification of text lines within the
input text block (use the <b>j</b>&nbsp;argument instead).</li>
<li><b>v</b><i>x</i> - vertical alignment of the input text block inside a
box.<br> Possible values for <i>x</i> are <code>t</code> (for top
alignment), <code>c</code> (center), or <code>b</code> (bottom).</li>
<li><b>j</b><i>x</i> - justification of lines within the input text block.<br>
Possible values for <i>x</i> are <code>l</code> (ell, for left
justification), <code>c</code> (center), or <code>r</code> (right). This
does not affect the alignment of the input text block itself
within the box. Use the <b>h</b> and <b>v</b> arguments for
input text block positioning.</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">Short hand
notations (can be combined with the above arguments):
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>l</code> (ell) - short for <code>hlvcjl</code></li>
<li style="margin-bottom:0"><code>c</code> - short for <code>hcvcjc</code></li>
<li style="margin-bottom:0"><code>r</code> - short for <code>hrvcjr</code></li>
</ul>
<p style="margin-left:20%; margin-top: 1em">The default for
<code>-a</code> is <code>hlvt</code>.</p>
<p style="margin-left:11%;"><a name="opt-c"><b>-c</b> <i>string</i></a>,
<b>--create</b>=<i>string</i></p>
<p style="margin-left:20%;">Command line design definition
for simple cases. The argument of this option is the
definition for the &quot;west&quot; (W) shape. The defined
shape must consist of exactly one line, i.e. no multi-line
shapes are allowed. The <b>-c</b> option is intended as a
shortcut for those cases where simple regional comments are
to be created, which only need a certain character or
sequence of characters to be placed in front of every line.
In such cases, it is much more convenient to simply specify
<b>-c</b> than to do a complete design definition in
one&rsquo;s config file, where the only shape defined is the
west shape. <br>
This option implies a <b>-d</b> and does not access the
config file. <b>-c</b> may of course be used in conjunction
with any of the other options. By default, <b>-c</b> is not
specified.</p>
<p style="margin-left:11%;"><a name="opt-color"><b>--color</b></a>,
<a name="opt-nocolor"><b>--no-color</b></a></p>
<p style="margin-left:20%;">Printing of color codes. Box
designs and the text inside a box may contain ANSI color
codes, sometimes called &quot;escape sequences&quot;. In
this way, boxes and text can be colored. <br>
Whether these escape sequences are printed by <i>boxes</i>
is normally determined by the terminal capabilities
(default). Using <b>--color</b>, <i>boxes</i> can be told to
always output escape sequences even if it thinks the
terminal may not understand them. Using <b>--no-color</b>,
escape sequences will never be printed.</p>
<p style="margin-left:20%; margin-top: 1em">Of course, even
with <b>--color</b>, a box will only appear colored if it is
already defined with colors. In case you want to auto-color
some text that isn&rsquo;t yet, take a look at
<i>lolcat</i>. <br>
These options consider all escape sequences to be color
codes. Any other escape sequences present will be printed or
removed along with the color codes.</p>
<p style="margin-left:11%;"><a name="opt-d"><b>-d</b> <i>string</i></a>,
<b>--design</b>=<i>string</i></p>
<p style="margin-left:20%;">Design selection. The one
argument of this option is the name of the design to use,
which may either be a design&rsquo;s primary name or any of
its alias names.</p>
<p style="margin-left:11%;"><a name="opt-e"><b>-e</b> <i>eol</i></a>,
<b>--eol</b>=<i>eol</i></p>
<p style="margin-left:20%;">Override line terminator.
<i>eol</i> can be <code>CR</code>, <code>LF</code>, or <code>CRLF</code>. The
default is to use the system-specific line terminator, which
means <code>CRLF</code> on Windows, and <code>LF</code> otherwise. This
option should only be used in an emergency, because normally
the system-specific line terminator will be just fine. This
option is considered experimental, and may go away in a
future version of <i>boxes</i>. Let us know in
<a href="https://github.com/{{ site.github }}/issues/60">https://github.com/{{ site.github }}/issues/60</a>
if you think we should keep it.</p>
<p style="margin-left:11%;"><a name="opt-f"><b>-f</b> <i>string</i></a>,
<b>--config</b>=<i>string</i></p>
<p style="margin-left:20%;">Use alternate config file. The
one argument of this option is the name of a valid
<i>boxes</i> config file. The argument of <b>-f</b> can also
be a directory which contains a configuration file. More
information on this topic below in the CONFIGURATION FILE
section.</p>
<p style="margin-left:11%;"><a name="opt-h"><b>-h</b></a>, <b>--help</b></p>
<p style="margin-left:20%;">Print usage information.</p>
<p style="margin-left:11%;"><a name="opt-i"><b>-i</b> <i>string</i></a>,
<b>--indent</b>=<i>string</i></p>
<p style="margin-left:20%;">Indentation mode. Possible values for
<i>string</i> are:</p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>text</code> - indent text inside of box</li>
<li style="margin-bottom:0"><code>box</code> - indent box, not text inside of box</li>
<li style="margin-bottom:0"><code>none</code> - discard indentation</li>
</ul>
<p style="margin-left:20%;">Arguments may be abbreviated. The default is <code>box</code>.</p>
<p style="margin-left:11%;"><a name="opt-k"><b>-k</b> <i>bool</i></a>,
<b>--kill-blank</b>, <b>--no-kill-blank</b></p>
<p style="margin-left:20%;">Kill leading/trailing blank
lines on removal. The value of <i>bool</i> is either
<i>true</i> or <i>false</i>. This option only takes effect
in connection with <b>-r</b>. If set to <i>true</i>, leading
and trailing blank lines will be removed from the output. If
set to <i>false</i>, the entire content of the former box is
returned. The default is <i>false</i>, if both the top and
the bottom part of the box are open, as is the case with
most regional comments. If the box&rsquo;s design defines a
top part or a bottom part, the default is <i>true</i>.</p>
<p style="margin-left:11%;"><a name="opt-l"><b>-l</b></a>, <b>--list</b></p>
<p style="margin-left:20%;">List designs. Produces a
listing of all available box designs in the config file,
along with a sample box and information about its creator.
Also checks the syntax of the entire config file. If used in
conjunction with <b>-d</b>, displays detailed information
about the specified design.</p>
<p style="margin-left:11%;"><a name="opt-m"><b>-m</b>,</a> <b>--mend</b></p>
<p style="margin-left:20%;">Mend box. This removes a
(potentially broken) box as with <b>-r</b>, and redraws it
afterwards. The mended box is drawn according to the options
given. This may be important to know when it comes to
restoring padding, indentation, etc. for the mended box.
Implies <b>-k</b> <i>false</i>.</p>
<p style="margin-left:11%;"><a name="opt-n"><b>-n</b> <i>encoding</i></a>,
<b>--encoding</b>=<i>encoding</i></p>
<p style="margin-left:20%;">Character encoding. Overrides
the character encoding of the input and output text. Choose
from the list shown by <i>iconv -l</i>. If an invalid
character encoding is specified here, <i>UTF-8</i> is used
as a fallback. The default is to use the system encoding,
which is normally the best course of action. So don&rsquo;t
specify this option unless you have to.</p>
<p style="margin-left:11%;"><a name="opt-p"><b>-p</b> <i>string</i></a>,
<b>--padding</b>=<i>string</i></p>
<p style="margin-left:20%;">Padding. Specify padding in
spaces around the input text block for all sides of the box.
The argument string may not contain whitespace and must
consist of a combination of the following characters, each
followed by a number indicating the padding in spaces:</p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>a</code> - (all) give padding for all sides at once</li>
<li style="margin-bottom:0"><code>h</code> - (horiz) give padding for both horizontal sides</li>
<li style="margin-bottom:0"><code>v</code> - (vertical) give padding for both vertical sides</li>
<li style="margin-bottom:0"><code>b</code> - (bottom) give padding for bottom (south) side</li>
<li style="margin-bottom:0"><code>l</code> - (left) give padding for left (west) side</li>
<li style="margin-bottom:0"><code>t</code> - (top) give padding for top (north) side</li>
<li style="margin-bottom:0"><code>r</code> - (right) give padding for right (east) side</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">Example:
<code>-p a4t2</code> would define the padding to be
4 characters on all sides, except for the top of the box,
where the input text block will be only 2 lines away from
the box. <br>
The default for this option is determined by the box design
used. If the design does not specify anything, no default
padding is used.</p>
<p style="margin-left:11%;"><a name="opt-q"><b>-q</b> <i>query</i></a>,
<b>--tag-query</b>=<i>query</i></p>
<p style="margin-left:20%;">Query designs by tag. In
contrast to <b>-l</b>, this will only print the matching
design names. This option is normally used stand-alone; if
used in combination with other options, behavior is
undefined. The <i>query</i> argument is a comma-separated
list of tags which can be present on a design in order to
match. A tag may optionally be prefixed with <code>+</code> in
order to require that it be present, or with <code>-</code> in
order to exclude designs which have that tag. Each tag can
only occur once per query. The special query <i>(all)</i>
matches all box designs, even if they don&apos;t have any
tags. <br>
This option is intended for use by scripts. Alias names are
printed below their primary design name, and postfixed with
<code>(alias)</code>. <br>
Example: <code>boxes -q programming,-comment</code></p>
<p style="margin-left:11%;"><a name="opt-r"><b>-r</b></a>, <b>--remove</b></p>
<p style="margin-left:20%;">Remove an existing box. Which
design to use is detected automatically. In order to save
time or in case the detection does not decide correctly,
combine with <b>-d</b> to specify the design.</p>
<p style="margin-left:11%;"><a name="opt-s"><b>-s</b>
<i>width</i><b>x</b><i>height</i></a>,
<b>--size</b>=<i>width</i><b>x</b><i>height</i></p>
<p style="margin-left:20%;">Box size. This option specifies
the desired box size in units of columns (for width) and
lines (for height). If only a single number is given as
argument, this number specifies the desired box width. A
single number prefixed by <code>x</code> specifies only the
box height. The actual resulting box size may vary depending
on the individual shape sizes of the chosen design. Also,
other command line options may influence the box size (such
as <b>-p</b>). <br>
By default, the smallest possible box is created around the
text.</p>
<p style="margin-left:11%;"><a name="opt-t"><b>-t</b> <i>tabopts</i></a>,
<b>--tabs</b>=<i>tabopts</i></p>
<p style="margin-left:20%;">Tab handling. This option
controls how tab characters in the input text are handled.
The <i>tabopts</i> must always begin with a positive integer
number indicating the distance between tab stops, sometimes
called &quot;spaces per tab&quot;. <br>
Immediately following the tab distance, an optional
character can be appended, telling <i>boxes</i> how to treat
the leading tabs. The following options are available:</p>
<ul style="margin-left:20%; margin-top: 1em">
<li style="margin-bottom:0"><code>e</code> - expand tabs into spaces</li>
<li style="margin-bottom:0"><code>k</code> - keep tabs as close to what they were as possible</li>
<li style="margin-bottom:0"><code>u</code> - unexpand tabs. This makes <i>boxes</i> turn as many
spaces as possible into tabs.</li>
</ul>
<p style="margin-left:20%; margin-top: 1em">The <b>-t</b>
<i>string</i> can be just a number. In that case, <b>e</b>
is assumed for tab handling. The default for the
<b>-t</b> option is simply <code>8</code>, which is just such a case.
<br>
For example, you could specify <code>-t 4u</code> in order to have
your leading tabs unexpanded. In the box content, tabs are
always converted into spaces. The tab distance in this
example is 4.</p>
<p style="margin-left:11%;"><a name="opt-v"><b>-v</b></a>, <b>--version</b></p>
<p style="margin-left:20%;">Print out current version
number.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="CONFIGURATION FILE"
text="CONFIGURATION FILE" %}
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
will look for the configuration file in several places, some
of which are given by the XDG specification.
<ol style="margin-left:11%;">
<li style="margin-bottom:0"><b>-f</b> option [file or dir]<br>When a configuration file is
specified on the command line, we will use that. The
<b>-f</b> option can also specify a directory. Any location
specified via <b>-f</b> must exist, or <i>boxes</i> will
terminate with an error.</li>
<li style="margin-bottom:0"><i>BOXES</i> environment variable [file or dir]<br>
If no config file is specified
on the command line, <i>boxes</i> will check for the BOXES
environment variable, which may contain a filename or
directory to use. Any location specified via the BOXES
environment variable must exist, or <i>boxes</i> will
terminate with an error.</li>
<li style="margin-bottom:0"><i>$HOME</i> [dir]</li>
<li style="margin-bottom:0"><i>$XDG_CONFIG_HOME/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>$HOME/.config/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/share/boxes</i> [file]</li>
<li style="margin-bottom:0"><i>/etc/xdg/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/local/share/boxes</i> [dir]</li>
<li style="margin-bottom:0"><i>/usr/share/boxes</i> [dir]</li>
</ol>
<p style="margin-left:11%;">Either one of these last two
directory locations might have the same name as the global
config file from <b>6</b>. That&rsquo;s fine. It just means
that we first look for a file of that name, and then for a
directory containing the file.</p>
<p style="margin-left:11%; margin-top: 1em">The XDG
environment variable <i>XDG_CONFIG_DIRS</i> is not
supported. However, its default value is supported via steps
<b>8</b> and <b>9</b> above. <br>
In the above list, whenever a step is designated with [dir],
the following file names will be found, in this order:</p>
<ol style="margin-left:11%;">
<li style="margin-bottom:0"><code>.boxes</code></li>
<li style="margin-bottom:0"><code>box-designs</code></li>
<li style="margin-bottom:0"><code>boxes-config</code></li>
<li style="margin-bottom:0"><code>boxes</code></li>
</ol>
<p style="margin-left:11%; margin-top: 1em">As soon as the
first valid file is found, we use that and stop the
search.</p>
<p style="margin-left:11%; margin-top: 1em">The recommended
location for a user-specific configuration file is
<i>$HOME/.boxes</i> or <i>$HOME/.config/boxes/.boxes</i>. A
global configuration file should be located at
<i>/usr/share/boxes</i>. But all of the other locations are
fully supported, too.</p>
<p style="margin-left:11%; margin-top: 1em">The syntax of
<i>boxes</i> config files is described on the website at
<a href="{{ site.baseurl }}/config-syntax.html">{{ site.url }}{{ site.baseurl }}/config-syntax.html</a>.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="EXAMPLES"
text="EXAMPLES" %}
<p style="margin-left:11%; margin-top: 1em">Examples on how
to invoke <i>boxes</i> may be found on the website at
<a href="{{ site.baseurl }}/examples.html">{{ site.url }}{{ site.baseurl }}/examples.html</a>.
<br>
Try</p>
<pre style="margin-left:11%;"><code>echo &quot;Good Bye World!&quot; | boxes -d nuke</code></pre>
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
also combines nicely with other tools. Try</p>
<pre style="margin-left:11%;"><code>figlet &quot;boxes . . . !&quot; | lolcat -f | boxes -d unicornthink</code></pre>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="AVAILABILITY"
text="AVAILABILITY" %}
<p style="margin-left:11%; margin-top: 1em">The
<i>boxes</i> website is
<a href="{{ site.baseurl }}/">{{ site.url }}{{ site.baseurl }}/</a>. It contains a
number of examples illustrating this manual page as well as
more in-depth documentation.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="AUTHOR"
text="AUTHOR" %}
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
was made by Thomas Jensen and the <i>boxes</i> contributors.
It has been lovingly maintained since 1999. <br>
For a full list of contributors, see
<a href="{{ site.baseurl }}/team.html#contributors">{{ site.url }}{{ site.baseurl }}/team.html#contributors</a>
and
<a href="https://github.com/{{ site.github }}/graphs/contributors">https://github.com/{{ site.github }}/graphs/contributors</a>.
<br>
Please refer to the <i>boxes</i> website for the
maintainer&rsquo;s current email address.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="VERSION"
text="VERSION" %}
<p style="margin-left:11%; margin-top: 1em">This is
<i>boxes</i> version {{ page.bxVersion | slice: 1, page.bxVersion.size }}.</p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="LICENSE"
text="LICENSE" %}
<p style="margin-left:11%; margin-top: 1em"><i>boxes</i> is
free software under the terms of the GNU General Public
License, version 3. Details in the LICENSE file:
<a href="https://raw.githubusercontent.com/{{ site.github }}/{{ page.bxVersion }}/LICENSE">https://raw.githubusercontent.com/{{ site.github }}/{{ page.bxVersion }}/LICENSE</a></p>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="ENVIRONMENT"
text="ENVIRONMENT" %}
<p style="margin-left:11%; margin-top: 1em"><i>Boxes</i>
recognizes the following environment variables:</p>
<dl style="margin-left: 11%">
<dt>BOXES</dt>
<dd style="margin-left: 9%;">Absolute path of the <i>boxes</i> configuration file. If this is specified, it must refer
to an existing file or directory.</dd>
<dt>HOME</dt>
<dd style="margin-left: 9%;">The user's home directory.</dd>
<dt>XDG_CONFIG_HOME</dt>
<dd style="margin-left: 9%;">The root of the configuration file location as per the XDG specification.</dd>
</dl>
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="SEE ALSO"
text="SEE ALSO" %}
<p style="margin-left:11%; margin-top: 1em"><b>figlet</b>(6),
<b>iconv</b>(1), <b>lolcat</b>(6)</p>

420
pages/v2.3.0/config-syntax.md Normal file
View File

@ -0,0 +1,420 @@
---
title: Docs - Config File Syntax
permalink: /v2.3.0/config-syntax.html
longContent: true
bxVersion: v2.3.0
created_at: 1999-04-06
last_modified_at: 2024-02-17 14:00:00 +0100
---
# Config File Syntax
{% include version-select.html currentVersion=page.bxVersion contentPiece="config-syntax" %}
The *boxes* config file is a succession of box design definitions.
Its character encoding is UTF-8. Versions of *boxes* prior to v2.3.0 used ASCII-encoded config files.
*Boxes* config files are case insensitive, i.e. upper/lower case does not matter.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3
text="Box Design" %}
<pre><b>BOX</b> <i>design_name</i>
entries_and_blocks
<b>END</b> <i>design_name</i></pre>
A box design may optionally have **alias names** in addition to the primary design name (since *boxes* v2.1.0).
Alias names are appended to the primary design name as a comma-separated list. For example:
<pre><b>BOX</b> <i>design_name</i>, <i>alias1</i>, <i>alias2</i>
entries_and_blocks
<b>END</b> <i>design_name</i></pre>
After the `END` statement, only the primary design name is specified. There is no practical limit to the number of
alias names. Every primary design name and alias name must be unique across the entire config file, including any
parent config files.
Design names and alias names can consist of the ASCII letters `a-z` (both lower- and upper-case, although lower-case is
highly recommended), digits, underscores (`_`), or dashes (`-`). The first character must be a letter.
Every box design definition must have at least a `SHAPE` block, an `ELASTIC` list, and a `SAMPLE` block.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3
text="Comments" %}
Everything following a pound sign (`#`) is considered a comment, as long as the pound sign isn't part of a string
or something.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="sample"
text="Sample Block" %}
<PRE><b>SAMPLE</b>
sample_image_of_box
<b>ENDS</b></PRE>
This is the box image used for the list of available designs. The reason why an image is not simply generated is that
this way, the box can be shown in an environment in which it might actually be used, e.g. with some C code around (see
the [boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"} for many
examples).
The sample itself should be indented by *4 spaces*. This is because all other samples in the config file are also
indented by this value, which simply looks better on the design list.
The `ENDS` statement must stand on a line of its own, although it may be indented. Such a line cannot occur as part of
the sample itself.\\
The `SAMPLE` block is a required entry in every box design definition.
{% include heading.html level=4 text="Colored Samples" %}
<small class="text-muted">(advanced topic)</small>
If a box design uses [colored shapes](#colored-shapes), the sample must also be colored. This may make it less
easily readable in a regular text editor, which is why you are encouraged to add a comment below the sample block
which shows the box without coloring. Just put `# Monochrome sample:` and the uncolored sample below (example: the
box design `warning`).
Colored samples are shown also when displaying the design list, or on the
[design list]({{ site.baseurl }}/{{ thisVersion }}/box-designs-color.html) on the website.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="shapes"
text="Shapes Block" %}
<PRE><b>SHAPES</b> {
<i>shape_name</i> (string_list)
<i>shape_name</i> (string_list)
...
}</PRE>
<i>`shape_name`</i> may be one of `nw`, `nnw`, `n`, `nne`, `ne`, `ene`, `e`, `ese`, `se`, `sse`, `s`, `ssw`, `sw`,
`wsw`, `w`, or `wnw`, corresponding to the [figure shown earlier]({{ site.baseurl }}/config-general.html).
The `string_list` represents the shape itself, line by line. Note that all lines must have equal length. Add extra
spaces if necessary. Note also that double quotes (`"`) which appear as part of a string must be escaped by a preceding
backslash, so as not to terminate the string early. Consequently, all occurrences of backslashes must also be escaped
by adding additional backslashes. The recommended process for creating a string is thus:
1. Type in the string as you think it should look.
1. Make your editor double all backslashes within the string.
1. Escape all double quotes within the string by adding more backslashes.
In Vim, for example, this can be achieved by marking the block, and then typing:
:s/\\/\\\\/g
:s/"/\\"/g
Here are a few examples of valid entries in a `SHAPE` block:
ne ("+++",
"+ +",
"+++")
SSE ("///", "\\\\\\")
s ("\"")
The [`delimiter` statement](#delim) can be used to redefine the string delimiting character and the escape character,
thus eliminating the above backslash problem.
The `SHAPE` block is a required entry in every box design definition.
{% include heading.html level=4 text="Colored Shapes" %}
<small class="text-muted">(advanced topic)</small>
If you don't mind getting technical, it is possible, with some effort, to add ANSI color codes to shapes so that the
created boxes look colorful. One can even design them so that the contents of the box is colored (like in our
`critical` design). These color codes do not count toward shape width.
The color codes are added as explained in this [stackoverflow post](https://stackoverflow.com/a/75985833/1005481).
Just be sure to use only codes that change the text or background color, and not other codes which move the cursor
or clear the screen. *Boxes* will assume that all escape codes are for coloring.
Example:
```
ne ("This is ␛[31mRED␛[0m and ␛[94mBLUE␛[0m text.")
```
eventually gives
<pre><code>This is <span style="color:red;">RED</span> and <span style="color:blue;">BLUE</span> text.
</code></pre>
The "escape" character is an actual escape character (ASCII code 27 (0x1b)). Other ways of expressing this, such as
`\033`, are currently not supported, because it is too likely to conflict with patterns found in ASCII art. If needed,
you can copy&amp;paste an escape character from the *boxes* config file, e.g. from the `warning` design. Do not
copy&amp;paste escape characters from this web page, because we need to use *visible* escape characters here, which are
different code.
It is important to properly terminate the effects, for example by using `␛[0m`. Ideally, this should be done for
each colored character, because that makes it easiest to copy&amp;paste, truncate a shape line or otherwise modify it.
At the very least, any coloring effects must be terminated at the end of a shape line. This aids robustness when a
box gets damaged by editing or removed, in order to make sure users are not left with leaking colors. The only
exception to this rule is when your box makes use of colored box content.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="elastic"
text="Elastic List" %}
<PRE><b>ELASTIC</b> (<i>shape_name</i>, <i>shape_name</i>, ...)</PRE>
Simply lists the shapes which are *elastic*. Elastic shapes are repeated so that the box can grow and shrink to meet
its requested size. Corner shapes may not be elastic. Naturally, there must always be at least one elastic shape per
box side. No two neighboring shapes may be elastic. A typical `ELASTIC` entry would look like this:
elastic (n, e, s, w)
The elastic list is a required entry in every box design definition.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="padding"
text="Padding Block" %}
<PRE><b>PADDING</b> {
side_or_group_of_sides <i>value</i>
side_or_group_of_sides <i>value</i>
...
}</PRE>
Defines the default [padding area]({{ site.baseurl }}/config-general.html#padding-area). Possible values for
`side_or_group_of_sides` are `all`, `horizontal`, `vertical`, `top`, `left`, `right`, or `bottom`. A padding block may
contain an arbitrary number of entries. Entries are read from top to bottom, so that later entries overwrite earlier
entries. In the following example:
padding {
vertical 3
horiz 2
left 4
}
the padding is set to 3 blank lines above the text, 2 spaces to the right of the text, 3 blank lines below the text,
and 4 spaces to the left of the text. These values can be overridden by a different specification on the command line
using the **-p** option.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="regexp"
text="Replace and Reverse Statements" %}
<PRE><b>REPLACE</b> "<i>search_pattern</i>" <b>WITH</b> "<i>replacement_string</i>"
...
<b>REVERSE</b> "<i>search_pattern</i>" <b>TO</b> "<i>replacement_string</i>"
...</PRE>
These statements are used to perform substitutions on the text surrounded by a box. The `REPLACE` statements are
executed on the input text when a box is being created. `REVERSE` statements have the same effect as `REPLACE`
statements, but they are executed after a box has been removed.
In the simplest case, one string is replaced with another:
replace "\\*/" with "*-/"
reverse "\\*-/" to "*/"
The `REPLACE` statement in the above example may be used to quote closing comment tags in the C programming language by
inserting a dash between the asterisk and the slash. The `REVERSE` statement undoes this effect when the box is removed.
The search pattern may be a regular expression, and the replacement string may include backreferences. This gives you
quite a powerful means for text modification. The following example is used to insert a space between all characters of
the input text:
replace "(.)" with "$1 "
reverse "(.) " to "$1"
There may be many `REPLACE`/`REVERSE` statements in one design definition. They will be executed one after the other,
starting from the top.
Note that as in all strings, backslashes must be doubled, i.e. *boxes* "consumes one layer of backslashes". This is
why in the first example, there are two backslashes at the beginning of the search pattern, when only one would have
been needed to escape the star operator.
The [`delimiter` statement](#delim) should not be used to change the string delimiting and escape character in
regular expressions. While this is possible, it only affects *boxes*' processing, not the regular expression engine's.
This will most likely cause confusion.
You may choose if the replacement is performed `once` per line or as many times as necessary to replace all occurrences
of the sarch pattern (`global`). Put this indication in front of the search pattern (the default is `global`):
replace once "foo" with "bar"
We use [PCRE2](https://www.pcre.org/current/doc/html/) regular expression syntax. In order to craft the proper
regular expressions, online tools such as [Regex101](https://regex101.com/) or [Regexper](https://regexper.com/) might
come in handy.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="indent"
text="Indentation Mode" %}
<PRE><b>INDENT</b> "<i>indentmode</i>"</PRE>
This sets the default indentation mode for a design. Possible values for <i>`indentmode`</i> are `"box"`, `"text"`,
and `"none"`. The indent mode specifies how existing text indentation is treated.
- `"box"`, which is the default setting, will cause the box to be indented by the same number of spaces as the text
was. The text itself will not be indented within the box, though.
- `"text"` will not indent the box, but instead retain the text indentation inside the box.
- `"none"` will simply throw away all indentation.
For examples on all three indentation modes please refer to the [example page]({{ site.baseurl}}/examples.html#indent).
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="delim"
text="String Delimiters" %}
<PRE><b>DELIM[ITER]</b> <i>chars</i></PRE>
*`chars`* must consist of exactly two characters:
1. the escape character (first character, one of `@~?!\`)
2. the string delimiter (second character, one of `"~'!|`)
No quotes must be placed around those two characters. The effect is that until the end of the current design or until
the next `DELIMITER` statement, all strings must be enclosed not by the usual double quotes (`"`), but instead by the
character you specify. Also, the delimiter may be escaped not by the usual backslash (`\`), but instead by the escape
character you specify. The escape character and the string delimiter must be different characters, of course.
For example, consider the literal string `"""""`, which would normally be written like this:
"\"\"\"\"\""
Using a `DELIMITER` statement, this looks much simpler:
delimiter \'
'"""""'
This mechanism is intended for box designs which have a lot of backslash or double quote characters in them.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3 slug="credit"
text="Names of Author and Designer" %}
<PRE><b>AUTHOR</b> &quot;<i>name_of_author</i>&quot;</PRE>
Simply states who the person was who coded the box design definition. This entry is used when displaying the list of
designs (`boxes -l`). The value is free text, but it is good if some contact information is included, for example
`John Doe <john@acme.com>`. These days, such openness with one's email address may not suit everyone, so feel free to
give less or differently formatted author information.
<PRE><b>DESIGNER</b> &quot;<i>name_of_designer</i>&quot;</PRE>
In contrast to `author`, which tells us who created the config file entry, the `designer` keyword tells us who created
the box design itself. In other words, this is the artist who originally created the ASCII artwork.
Please try to give both fields always. Especially in those cases where existing ASCII art from the internet is adapted
for use with *boxes*, it is important (and good manners) to give credit to the original artist.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3
text="Tags" %}
Since *boxes* v2.1.0:
<PRE><b>TAGS</b> (&quot;<i>tag1</i>&quot;, &quot;<i>tag2</i>&quot;, &quot;<i>tag3</i>&quot;)</PRE>
or, in all versions of *boxes* (deprecated):
<PRE><b>TAGS</b> &quot;<i>tag1</i>, <i>tag2</i>, <i>tag3</i>&quot;</PRE>
The `tags` statement applies one or more tags to the box design which can later be used to find and select the design
in a tag query. A tag can only contain the lower-case letters `a-z`, digits, or a dash (`-`). It must not start with
a dash, and a tag name can be anything but `none`.
At the end of the output of `boxes -l`, *boxes* will print a summary of all tags found in the configuration,
complete with counts of how often the tag was encountered.
A *tag query* can be issued by invoking `boxes -q`. *Boxes* will then print the names of all matching box designs.
Details about tag queries can be found in the
[manual page]({{ site.baseurl }}/{{ page.bxVersion }}/boxes-man-1.html#opt-q) for the `-q` option.
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=3
text="General Entries" %}
<PRE><b>keyword</b> &quot;<i>string_value</i>&quot;</PRE>
In addition to the author entry, there may be any number of other entries of the above form, giving any kind of
information. These entries are not used by *boxes*, though, and will simply be ignored.
-----
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="parent"
text="Config File Inheritance" %}
A config file may specify one or more other config files as "parents" (since *boxes* v2.1.0). This means that after
the config file is read, *boxes* will also read all the parent configs in order. If a design is found which we don't
know yet, it is added to the list. In other words, all box designs are "inherited" from the parents, and can be
overwritten.
This mechanism works on the box design level. You can only override an entire box design, but not parts of one.
The syntax is
<PRE><b>PARENT</b> <i>path_to_parent_config</i></PRE>
The path to the parent config should be an absolute pathname specifying a config file (not a directory). Spaces are
permitted in this path, and no quotes are used. The file name may contain UTF-8 characters. A parent reference can
only occur outside of any box design definitions. The special keyword `:global:` is used to refer to the *boxes*
global config file.
This syntax implies that there cannot be a comment in the same line as the `parent` reference - it would be considered
part of the file name. Instead, put comments in the line above.
For example, a user wants to add or change a design from the global config. So she creates a config file in ~/.boxes
and places a `parent :global:` statement at the top to inherit the global config. The local / personal config file
contains only the changes / additions.
-----
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
{% include heading.html
level=2 slug="valid-characters"
text="Appendix A: Valid Characters" %}
<small class="text-muted">(advanced topic)</small>
This appendix summarizes which types of characters may occur in various places of the config file. This is really
detail information. Refer to this only in case of problems. Normally, this is a fine section to skip.
| &nbsp; | A | ü | SP | ESC | TAB | CR/LF | BEL |
|:-------------|:-:|:-:|:--:|:---:|:---------------:|:-----:|:---:|
| **Shape** | ✓ | ✓ | ✓ | ✓ | (-)<sup>†</sup> | - | - |
| **Sample** | ✓ | ✓ | ✓ | ✓ | (-)<sup>†</sup> | ✓ | - |
| **Filename** | ✓ | ✓ | ✓ | - | ✓ | - | - |
| **Key** | ✓ | ✓ | - | - | - | - | - |
| **Value** | ✓ | ✓ | ✓ | - | ✓ | - | - |
{:.bxCharTable .table .table-striped}
The column `A` represents regular ASCII characters, `ü` stands for non-ASCII Unicode characters, and `BEL` represents
all non-printable control characters except ESC.
*†*{:.h-h} For historical reasons, tabs can be used in shapes and samples, where they count as one space (but will not
work as one, of course). This is deprecated behavior. In a future version of *boxes*, we will probably disallow the use
of tabs altogether. We do not want tabs in shapes, but currently don't prevent them either.
{: .bxHanging }
The "Shape" row shows which types of characters may occur as part of a box shape. "Sample" refers to the sample
block. "Filename" means the file name given as a [PARENT config](#parent). "Key" is the key of the key/value pairs
that every box design has, such as `author`. "Value" is its value as a string.
<p><br></p>
Read on in the next part: [A New Box Design Step By Step]({{ site.baseurl }}/config-step.html)