diff --git a/_config.yml b/_config.yml index 5b9e25e..52c1ade 100644 --- a/_config.yml +++ b/_config.yml @@ -70,8 +70,8 @@ redirect_from: json: false # boxes custom variables -currentVersion: '2.1.1' -link_license: 'https://raw.githubusercontent.com/ascii-boxes/boxes/v2.1.1/LICENSE' +currentVersion: '2.2.0' +link_license: 'https://raw.githubusercontent.com/ascii-boxes/boxes/v2.2.0/LICENSE' # Page frontmatter defaults defaults: diff --git a/index.md b/index.md index 1f3d2a9..1047c14 100644 --- a/index.md +++ b/index.md @@ -145,4 +145,4 @@ box is added or removed. New box designs of all sorts can easily be added and shared by appending to a free format configuration file. Be creative! -*Boxes* is free software under the GNU General Public License, version 2 ([GPLv2]({{ site.link_license }})). +*Boxes* is free software under the GNU General Public License, version 3 ([GPLv3]({{ site.link_license }})). diff --git a/pages/box-designs.html b/pages/box-designs.html index 1ed7c9d..70123ce 100644 --- a/pages/box-designs.html +++ b/pages/box-designs.html @@ -4,10 +4,10 @@ title: List of Box Designs permalink: /box-designs.html longContent: true created_at: 1999-04-06 -last_modified_at: 2021-06-14 21:32:00 +0200 +last_modified_at: 2022-09-22 22:06:00 +0200 --- -59 Available Styles in "boxes-config": +61 Available Styles in "boxes-config": -------------------------------------- ada-box @@ -195,6 +195,21 @@ unknown artist, coded by Thomas Jensen: (_____)---------------(_____) +cowsay +Tony Monroe, coded by David Yang : + + _____________________________ + / \ + | Boxes can have the cow too | + \ / + ----------------------------- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || + + diamonds Joan G. Stark , coded by Thomas Jensen: @@ -688,6 +703,25 @@ tex-cmt % +tux +Tony Monroe, coded by David Yang : + + _________________ + / \ + | Tux talks too | + \ / + ----------------- + \ + \ + .--. + |o_o | + |:_/ | + // \ \ + (| | ) + /'\_ _/`\ + \___)=(___/ + + twisted Michael Naylor , coded by Tristano Ajmone : diff --git a/pages/boxes-man-1.html b/pages/boxes-man-1.html index ac9b763..29ae857 100644 --- a/pages/boxes-man-1.html +++ b/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: 2021-06-14 21:32:00 +0200 +last_modified_at: 2022-09-20 20:19:00 +0200 ---

boxes

@@ -13,13 +13,13 @@ last_modified_at: 2021-06-14 21:32:00 +0200 {% assign thisVersion = site.currentVersion | prepend: 'v' -%} {% include version-select.html currentVersion=thisVersion contentPiece="boxes-man-1" %} -

Section: User Commands (1)
Updated: June 14 2021

+

Section: User Commands (1)
Updated: September 20 2022

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="NAME" - text="NAME" %} + level=2 slug="NAME" + text="NAME" %}

boxes - text mode box and comment drawing filter

@@ -27,8 +27,8 @@ mode box and comment drawing filter

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="SYNOPSIS" - text="SYNOPSIS" %} + level=2 slug="SYNOPSIS" + text="SYNOPSIS" %}

boxes [-hlmrv] [-a format] [-d design] [-e eol] @@ -39,8 +39,8 @@ mode box and comment drawing filter

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="DESCRIPTION" - text="DESCRIPTION" %} + level=2 slug="DESCRIPTION" + text="DESCRIPTION" %}

Boxes is a text filter which can draw any kind of box around its @@ -63,8 +63,8 @@ text editors:
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="OPTIONS" - text="OPTIONS" %} + level=2 slug="OPTIONS" + text="OPTIONS" %}

Options offered by boxes are the following:
@@ -96,10 +96,10 @@ input text block positioning.

Short hand notations (can be combined with the above arguments): -
-l (ell) - short for hlvcjl
-c - short for hcvcjc
-r - short for hrvcjr

+
+l (ell) - short for hlvcjl
+c - short for hcvcjc
+r - short for hrvcjr

The factory default setting for -a is hlvt.

@@ -308,8 +308,8 @@ example is 4.

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="CONFIGURATION FILE" - text="CONFIGURATION FILE" %} + level=2 slug="CONFIGURATION FILE" + text="CONFIGURATION FILE" %}

Boxes will look for the configuration file in several places, some @@ -378,8 +378,8 @@ fully supported, too.

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="EXAMPLES" - text="EXAMPLES" %} + level=2 slug="EXAMPLES" + text="EXAMPLES" %}

Examples on how to invoke boxes may be found on the website at @@ -397,8 +397,8 @@ also combines nicely with other tools. Try

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="AVAILABILITY" - text="AVAILABILITY" %} + level=2 slug="AVAILABILITY" + text="AVAILABILITY" %}

The boxes website is @@ -409,8 +409,8 @@ more in-depth documentation.

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="AUTHOR" - text="AUTHOR" %} + level=2 slug="AUTHOR" + text="AUTHOR" %}

Boxes was made by Thomas Jensen and the boxes contributors. @@ -427,8 +427,8 @@ maintainer’s current email address.

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="VERSION" - text="VERSION" %} + level=2 slug="VERSION" + text="VERSION" %}

This is boxes version {{ site.currentVersion }}.

@@ -436,19 +436,19 @@ maintainer’s current email address.

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="LICENSE" - text="LICENSE" %} + level=2 slug="LICENSE" + text="LICENSE" %}

boxes is free software under the terms of the GNU General Public -License, version 2. Details in the LICENSE file: +License, version 3. Details in the LICENSE file: {{ site.link_license }}

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="ENVIRONMENT" - text="ENVIRONMENT" %} + level=2 slug="ENVIRONMENT" + text="ENVIRONMENT" %}

Boxes recognizes the following environment variables:

@@ -465,8 +465,8 @@ to an existing file or directory. {% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} {% include heading.html - level=2 slug="SEE ALSO" - text="SEE ALSO" %} + level=2 slug="SEE ALSO" + text="SEE ALSO" %}

figlet(6), iconv(1), lolcat(6)

diff --git a/pages/config-syntax.md b/pages/config-syntax.md index 30beb6c..822e52e 100644 --- a/pages/config-syntax.md +++ b/pages/config-syntax.md @@ -6,7 +6,7 @@ redirect_from: - /docs/config-syntax.shtml longContent: true created_at: 1999-04-06 -last_modified_at: 2021-06-14 21:32:00 +0200 +last_modified_at: 2022-09-22 21:48:00 +0200 --- # Config File Syntax @@ -280,8 +280,8 @@ At the end of the output of `boxes -l`, *boxes* will print a summary of all tags 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 }}/boxes-man-1.html#OPTIONS) for the `-q` -option. +Details about tag queries can be found in the +[manual page]({{ site.baseurl }}/boxes-man-1.html#OPTIONS) for the `-q` option. {% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} diff --git a/pages/v2.0.0/boxes-man-1.html b/pages/v2.0.0/boxes-man-1.html index b97596b..e178bb9 100644 --- a/pages/v2.0.0/boxes-man-1.html +++ b/pages/v2.0.0/boxes-man-1.html @@ -358,7 +358,7 @@ maintainer’s current email address.

boxes is free software under the terms of the GNU General Public License, version 2. Details in the LICENSE file: -https://raw.githubusercontent.com/{{ site.github }}/{{ page.bxVersion }}/LICENSE

+https://raw.githubusercontent.com/{{ site.github }}/v2.0.0/LICENSE

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} diff --git a/pages/v2.1.0/boxes-man-1.html b/pages/v2.1.0/boxes-man-1.html index 690f26f..87bbe6a 100644 --- a/pages/v2.1.0/boxes-man-1.html +++ b/pages/v2.1.0/boxes-man-1.html @@ -440,7 +440,7 @@ maintainer’s current email address.

boxes is free software under the terms of the GNU General Public License, version 2. Details in the LICENSE file: -{{ site.link_license }}

+https://raw.githubusercontent.com/{{ site.github }}/v2.1.0/LICENSE

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} diff --git a/pages/v2.1.1/boxes-man-1.html b/pages/v2.1.1/boxes-man-1.html index 9a620ac..58e758c 100644 --- a/pages/v2.1.1/boxes-man-1.html +++ b/pages/v2.1.1/boxes-man-1.html @@ -429,7 +429,7 @@ maintainer’s current email address.

text="VERSION" %}

This is -boxes version {{ site.currentVersion }}.

+boxes version 2.1.1.

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} @@ -440,7 +440,7 @@ maintainer’s current email address.

boxes is free software under the terms of the GNU General Public License, version 2. Details in the LICENSE file: -{{ site.link_license }}

+https://raw.githubusercontent.com/{{ site.github }}/v2.1.1/LICENSE

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} diff --git a/pages/v2.2.0/boxes-man-1.html b/pages/v2.2.0/boxes-man-1.html new file mode 100644 index 0000000..cb640fe --- /dev/null +++ b/pages/v2.2.0/boxes-man-1.html @@ -0,0 +1,470 @@ +--- +title: Manpage of boxes(1) +permalink: /v2.2.0/boxes-man-1.html +longContent: true +bxVersion: v2.2.0 +created_at: 1999-04-06 +last_modified_at: 2022-09-20 20:19:00 +0200 +--- + +

boxes

+ +{% include version-select.html currentVersion=page.bxVersion contentPiece="boxes-man-1" %} + +

Section: User Commands (1)
Updated: September 20 2022

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="NAME" + text="NAME" %} + +

boxes - text +mode box and comment drawing filter

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="SYNOPSIS" + text="SYNOPSIS" %} + +

boxes +[-hlmrv] [-a format] [-d design] [-e eol] +[-f file] [-i indent] [-k bool] +[-n encoding] [-p pad] [-q query] [-s size] +[-t tabopts] [infile [outfile]]

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="DESCRIPTION" + text="DESCRIPTION" %} + +

Boxes 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, boxes +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.

+ +

boxes is +a command line tool, but also integrates with any text +editor that supports filters. The boxes website has +examples on how to configure editor integration for various +text editors:
+ +{{ site.url }}{{ site.baseurl }}/editors.html

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="OPTIONS" + text="OPTIONS" %} + +

Options offered +by boxes are the following:
+-a string

+ +

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:

+ +

hx - +horizontal alignment of the input text block inside a +potentially larger box. Possible values for x are +l (ell, for left alignment), c (center), or +r (right). This does not affect the justification of +text lines within the input text block (use the j +argument instead).
+vx - vertical alignment of the input text block inside a +potentially larger box. Possible values for x are +t (for top alignment), c (center), or b +(bottom).
+jx - justification of lines within the input text block. +Possible values for x are l (ell, for left +justification), c (center), or r (right). This +does not affect the alignment of the input text block itself +within the box. Use the h and v arguments for +input text block positioning.

+ +

Short hand +notations (can be combined with the above arguments): +
+l (ell) - short for hlvcjl
+c - short for hcvcjc
+r - short for hrvcjr

+ +

The factory +default setting for -a is hlvt.

+ +

-c string

+ +

Command line design definition +for simple cases. The argument of this option is the +definition for the "west" (W) shape. The defined +shape must consist of exactly one line, i.e. no multi-line +shapes are allowed. The -c 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 +-c than to do a complete design definition in +one’s config file, where the only shape defined is the +west shape.
+This option implies a -d and does not access the +config file. -c may of course be used in conjunction +with any of the other options. By default, -c is not +specified.

+ +

-d string

+ +

Design selection. The one +argument of this option is the name of the design to use, +which may either be a design’s primary name or any of +its alias names.

+ +

-e eol

+ +

Override line terminator. +eol can be CR, LF, or CRLF. The +default is to use the system-specific line terminator, which +means CRLF on Windows, and LF 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 boxes. Let us know in +https://github.com/{{ site.github }}/issues/60 +if you think we should keep it.

+ +

-f string

+ +

Use alternate config file. The +one argument of this option is the name of a valid +boxes config file. The argument of -f can also +be a directory which contains a configuration file. More +information on this topic below in the CONFIGURATION FILE +section.

+ +

--help
-h

+ +

Print usage information.

+ + +

-i string

+ +

Indentation mode. Possible +arguments are text (indent text inside of box), +box (indent box, not text inside of box), or +none (throw away indentation). Arguments may be +abbreviated. The default is box.

+ +

-k bool

+ +

Kill leading/trailing blank +lines on removal. The value of bool is either +true or false. This option only takes effect +in connection with -r. If set to true, leading +and trailing blank lines will be removed from the output. If +set to false, the entire content of the former box is +returned. The default is false, if both the top and +the bottom part of the box are open, as is the case with +most regional comments. If the box’s design defines a +top part or a bottom part, the default is true.

+ +

-l

+ +

(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 -d, +displays detailed information about the specified +design.

+ +

-m

+ +

Mend box. This removes a (potentially broken) box as +with -r, 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 -k false.

+ +

-n encoding

+ +

Character encoding. Overrides +the character encoding of the input and output text. Choose +from the list shown by iconv -l. If an invalid +character encoding is specified here, UTF-8 is used +as a fallback. The default is to use the system encoding, +which is normally the best course of action. So don’t +specify this option unless you have to.

+ +

-p string

+ +

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: +
+a - (all) give padding for all sides at once
+h - (horiz) give padding for both horizontal sides +
+v - (vertical) give padding for both vertical sides +
+b - (bottom) give padding for bottom (south) side +
+l - (left) give padding for left (west) side
+t - (top) give padding for top (north) side
+r - (right) give padding for right (east) side
+Example: -p a4t2 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.
+By default, unless specified otherwise in the config file, +no padding is used.

+ +

-q query

+ +

Query designs by tag. In +contrast to -l, 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 query 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 + in +order to require that it be present, or with - in +order to exclude designs which have that tag. Each tag can +only occur once per query.
+This option is intended for use by scripts. Alias names are +printed below their primary design name, and postfixed with +(alias).
+Example: boxes -q programming,-comment

+ +

-r

+ +

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 -d +to specify the design. The default is to draw a new box.

+ +

-s +widthxheight

+ +

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 ’x’ 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 -p).
+By default, the smallest possible box is created around the +text.

+ +

-t string

+ +

Tab handling. This option +controls how tab characters in the input text are handled. +The option string must always begin with a uint +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.
+Immediately following the tab distance, an optional +character can be appended, telling boxes how to treat +the leading tabs. The following options are available: +
+e - expand tabs into spaces
+k - keep tabs as close to what they were as possible +
+u - unexpand tabs. This makes boxes turn as many +spaces as possible into tabs.

+ +

In order to +maintain backwards compatibility, the -t +string can be just a number. In that case, e +is assumed for tab handling, which removes all tabs and +replaces them with spaces. The factory default for the +-t option is simply 8, which is just such a case. +
+For example, you could specify -t 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.

+ +

-v

+ +

Print out current version number.

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="CONFIGURATION FILE" + text="CONFIGURATION FILE" %} + +

Boxes +will look for the configuration file in several places, some +of which are given by the XDG specification.
+1. -f option [file or dir]

+ +

When a configuration file is +specified on the command line, we will use that. The +-f option can also specify a directory. Any location +specified via -f must exist, or boxes will +terminate with an error.

+ +

2. BOXES +environment variable [file or dir]

+ +

If no config file is specified +on the command line, boxes 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 boxes will +terminate with an error.

+ +

3. $HOME [dir] +
+4. $XDG_CONFIG_HOME/boxes [dir]
+5. $HOME/.config/boxes [dir]
+6. /usr/share/boxes [file]
+7. /etc/xdg/boxes [dir]
+8. /usr/local/share/boxes [dir]
+9. /usr/share/boxes [dir]

+ +

Either one of these last two +directory locations might have the same name as the global +config file from 6. That’s fine. It just means +that we first look for a file of that name, and then for a +directory containing the file.

+ +

The XDG +environment variable XDG_CONFIG_DIRS is not +supported. However, its default value is supported via steps +8 and 9 above.
+In the above list, whenever a step is designated with [dir], +the
+following file names will be found, in this order:

+ +

1. .boxes
+2. box-designs
+3. boxes-config
+4. boxes

+ +

As soon as the +first valid file is found, we use that and stop the +search.

+ +

The recommended +location for a user-specific configuration file is +$HOME/.boxes or $HOME/.config/boxes/.boxes. A +global configuration file should be located at +/usr/share/boxes. But all of the other locations are +fully supported, too.

+ +

The syntax of +boxes config files is described on the website at +{{ site.url }}{{ site.baseurl }}/config-syntax.html.

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="EXAMPLES" + text="EXAMPLES" %} + +

Examples on how +to invoke boxes may be found on the website at +{{ site.url }}{{ site.baseurl }}/examples.html. +
+Try

+ +
echo "Good Bye World!" | boxes -d nuke
+ +

Boxes +also combines nicely with other tools. Try

+ +
figlet "boxes . . . !" | lolcat -f | boxes -d unicornthink
+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="AVAILABILITY" + text="AVAILABILITY" %} + +

The +boxes website is +{{ site.url }}{{ site.baseurl }}/. It contains a +number of examples illustrating this manual page as well as +more in-depth documentation.

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="AUTHOR" + text="AUTHOR" %} + +

Boxes +was made by Thomas Jensen and the boxes contributors. +It has been lovingly maintained since 1999.
+For a full list of contributors, see + +{{ site.baseurl }}/team.html#contributors +and +https://github.com/{{ site.github }}/graphs/contributors. +
+Please refer to the boxes website for the +maintainer’s current email address.

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="VERSION" + text="VERSION" %} + +

This is +boxes version 2.2.0.

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="LICENSE" + text="LICENSE" %} + +

boxes is +free software under the terms of the GNU General Public +License, version 3. Details in the LICENSE file: +https://raw.githubusercontent.com/{{ site.github }}/v2.2.0/LICENSE

+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="ENVIRONMENT" + text="ENVIRONMENT" %} + +

Boxes recognizes the following environment variables:

+ +
+
BOXES
+
Absolute path of the boxes configuration file. If this is specified, it must refer +to an existing file or directory.
+
HOME
+
The user's home directory.
+
XDG_CONFIG_HOME
+
The root of the configuration file location as per the XDG specification.
+
+ + +{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} +{% include heading.html + level=2 slug="SEE ALSO" + text="SEE ALSO" %} + +

figlet(6), +iconv(1), lolcat(6)

diff --git a/pages/v2.2.0/config-syntax.md b/pages/v2.2.0/config-syntax.md new file mode 100644 index 0000000..7932d10 --- /dev/null +++ b/pages/v2.2.0/config-syntax.md @@ -0,0 +1,329 @@ +--- +title: Docs - Config File Syntax +permalink: /v2.2.0/config-syntax.html +longContent: true +bxVersion: v2.2.0 +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" %} + +
BOX design_name
+    entries_and_blocks
+END design_name
+ +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: + +
BOX design_name, alias1, alias2
+    entries_and_blocks
+END design_name
+ +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" %} + +
SAMPLE
+    sample_image_of_box
+ENDS
+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" %} + +
SHAPES {
+    shape_name (string_list)
+    shape_name (string_list)
+    ...
+}
+`shape_name` 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" %} + +
ELASTIC (shape_name, shape_name, ...)
+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" %} + +
PADDING {
+    side_or_group_of_sides value
+    side_or_group_of_sides value
+    ...
+}
+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" %} + +
REPLACE "search_pattern" WITH "replacement_string"
+...
+REVERSE "search_pattern" TO "replacement_string"
+...
+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" %} + +
INDENT "indentmode"
+This sets the default indentation mode for a design. Possible values for `indentmode` 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" %} + +
DELIM[ITER] chars
+ +*`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" %} + +
AUTHOR "name_of_author"
+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 `. These days, such openness with one's email address may not suit everyone, so feel free to +give less or differently formatted author information. + +
DESIGNER "name_of_designer"
+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: + +
TAGS ("tag1", "tag2", "tag3")
+ +or, in all versions of *boxes*: + +
TAGS "tag1, tag2, tag3"
+ +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" %} + +
keyword "string_value"
+ +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 + +
PARENT path_to_parent_config
+ +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)