Boxes v2.2.1 released

_config.yml

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

_posts/2023-08-24-boxes-v2.2.1-released.md

@@ -0,0 +1,25 @@
+---
+layout: post
+title: "New release: boxes v2.2.1"
+date: 2023-08-24 16:48:00 +0200
+release: v2.2.1
+---
+
+Multiple small fixes this time.<!--break-->
+
+- Fix compilation on MacOS [#118](https://github.com/{{ site.github }}/issues/118) (thanks
+  <span class="atmention">[@mathomp4](https://github.com/mathomp4)</span>!)
+- Fix an out-of-bounds access in remove module [!104](https://github.com/{{ site.github }}/pull/104) (thanks
+  <span class="atmention">[@sgn](https://github.com/sgn)</span>!)
+- Fix compilation with Clang16 [#106](https://github.com/{{ site.github }}/issues/106) (thanks
+  <span class="atmention">[@Schievel1](https://github.com/Schievel1)</span>!)
+- <span class="atmention">[@Schievel1](https://github.com/Schievel1)</span> is now also the official maintainer of
+  *boxes* for Gentoo Linux :1st_place_medal:
+- Improve [*boxes* mode for Emacs]({{ site.baseurl}}/editors-emacs.html) including a MELPA package (thanks
+  <span class="atmention">[@Mike-Woolley](https://github.com/Mike-Woolley)</span>!)
+- Better build performance on Windows
+- Ability to create a static binary for Linux, with all dependencies baked in (`make static`)
+  [#100](https://github.com/{{ site.github }}/issues/100)
+- A number of small internal improvements
+
+[[Release History]({{ site.baseurl}}/releases.html)]

pages/boxes-man-1.html

@@ -5,7 +5,7 @@ redirect_from:
   - /docs/boxes-man-1.html
 longContent: true
 created_at: 1999-04-06
-last_modified_at: 2022-09-20 20:19:00 +0200
+last_modified_at: 2023-08-24 16:48:00 +0200
 ---
 
 <h1>boxes</h1>

pages/releases.md

@@ -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 2023-08-24-boxes-v2.2.1-released %}">2.2.1</a></th>
+      <td>August&nbsp;24, 2023</td>
+      <td><a href="https://github.com/{{ site.github }}/tree/v2.2.1">link</a></td>
+      <td><a href="https://github.com/{{ site.github }}/releases/tag/v2.2.1">link</a></td>
+      <td class="d-none d-sm-table-cell">multiple small fixes</td>
+    </tr>
     <tr>
       <th scope="row"><a href="{{ site.baseurl}}{% post_url 2022-09-21-boxes-v2.2.0-released %}">2.2.0</a></th>
       <td>September&nbsp;21, 2022</td>

pages/v2.2.1/box-designs-artwork.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: artwork)'
+permalink: /v2.2.1/box-designs-artwork.html
+designTag: artwork
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-box.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: box)'
+permalink: /v2.2.1/box-designs-box.html
+designTag: box
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-comment.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: comment)'
+permalink: /v2.2.1/box-designs-comment.html
+designTag: comment
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-large.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: large)'
+permalink: /v2.2.1/box-designs-large.html
+designTag: large
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-programming.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: programming)'
+permalink: /v2.2.1/box-designs-programming.html
+designTag: programming
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-scroll.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: scroll)'
+permalink: /v2.2.1/box-designs-scroll.html
+designTag: scroll
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-sign.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: sign)'
+permalink: /v2.2.1/box-designs-sign.html
+designTag: sign
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-simple.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: simple)'
+permalink: /v2.2.1/box-designs-simple.html
+designTag: simple
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs-speech.html

@@ -0,0 +1,10 @@
+---
+layout: designlist
+title: 'List of Box Designs (tag: speech)'
+permalink: /v2.2.1/box-designs-speech.html
+designTag: speech
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/box-designs.html

@@ -0,0 +1,9 @@
+---
+layout: designlist
+title: 'List of Box Designs'
+permalink: /v2.2.1/box-designs.html
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---

pages/v2.2.1/boxes-man-1.html

@@ -0,0 +1,470 @@
+---
+title: Manpage of boxes(1)
+permalink: /v2.2.1/boxes-man-1.html
+longContent: true
+bxVersion: v2.2.1
+created_at: 1999-04-06
+last_modified_at: 2023-08-24 16:48:00 +0200
+---
+
+<h1>boxes</h1>
+
+{% include version-select.html currentVersion=page.bxVersion contentPiece="boxes-man-1" %}
+
+<p>Section: User Commands  (1)<BR>Updated: August 24, 2023</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>
+[-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>
+
+
+{% 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: <b><br>
+-a</b> <i>string</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>
+
+<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
+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>
+
+<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>
+
+<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:11%;"><b>-c</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%;"><b>-d</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:20%;">Override line terminator.
+<i>eol</i> can be <i>CR</i>, <i>LF</i>, or <i>CRLF</i>. The
+default is to use the system-specific line terminator, which
+means <i>CRLF</i> on Windows, and <i>LF</i> 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%;"><b>-f</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%;"><b>--help</b><br><b>-h</b></p>
+
+<p style="margin-left:20%;">Print usage information.</p>
+
+
+<p style="margin-left:11%;"><b>-i</b> <i>string</i></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: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%;"><b>-l</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:11%;"><b>-m</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%;"><b>-n</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%;"><b>-p</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>
+
+<p style="margin-left:11%;"><b>-q</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. <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: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:11%;"><b>-s</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
+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%;"><b>-t</b> <i>string</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>
+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>
+
+<p style="margin-left:20%; margin-top: 1em">In order to
+maintain backwards compatibility, 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.
+<br>
+For example, you could specify <b>-t</b> 4u 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>
+
+
+{% 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. <b><br>
+1.</b> <i>-f</i> option [file or dir]</p>
+
+<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>
+
+<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
+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 <br>
+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>
+
+<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.url }}{{ 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.url }}{{ 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.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 2.2.0.</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 }}/v2.2.0/LICENSE">https://raw.githubusercontent.com/{{ site.github }}/v2.2.0/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>

pages/v2.2.1/config-syntax.md

@@ -0,0 +1,329 @@
+---
+title: Docs - Config File Syntax
+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
+---
+
+# Config File Syntax
+
+{% include version-select.html currentVersion=page.bxVersion contentPiece="config-syntax" %}
+
+
+The *boxes* config file is a succession of box design definitions.
+Everything following a pound sign (`#`) is considered a **comment** (unless, of course, the pound sign is part of a
+string or something).
+*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.
+
+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 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.
+
+
+{% 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 ("///", "\\\\\\")
+    ene ()
+    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.
+
+
+{% 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*:
+
+<PRE><b>TAGS</b> &quot;<i>tag1</i>, <i>tag2</i>, <i>tag3</i>&quot;</PRE>
+
+The legacy notation has the advantage of being backwards compatible with all versions of *boxes*, which is why we use
+it exclusively in the official config file. But once we're reasonably sure that all the world is at least on v2.1.0,
+we can upgrade that.
+
+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#OPTIONS) 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. The [boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config){:target="_blank"}
+includes the entries `CREATED`, `REVISION`, and `REVDATE`, to indicate the creation timestamp, revision number, and
+timestamp of the latest revision, respectively. These other entries are not yet 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 a "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. 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.
+
+
+Read on in the next part: [A New Box Design Step By Step]({{ site.baseurl }}/config-step.html)