diff --git a/_config.yml b/_config.yml index 56f3e46..5b9e25e 100644 --- a/_config.yml +++ b/_config.yml @@ -70,8 +70,8 @@ redirect_from: json: false # boxes custom variables -currentVersion: '2.1.0' -link_license: 'https://raw.githubusercontent.com/ascii-boxes/boxes/v2.1.0/LICENSE' +currentVersion: '2.1.1' +link_license: 'https://raw.githubusercontent.com/ascii-boxes/boxes/v2.1.1/LICENSE' # Page frontmatter defaults defaults: diff --git a/pages/box-designs.html b/pages/box-designs.html index 3104290..9857729 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-04-03 09:23:00 +0200 +last_modified_at: 2021-06-14 21:32:00 +0200 --- -57 Available Styles in "boxes-config": +59 Available Styles in "boxes-config": -------------------------------------- ada-box @@ -326,21 +326,21 @@ html-cmt ian_jones unknown artist, coded by Karl E. Jorgensen : - \\\/// - / _ _ \ - (| (.)(.) |) -.----------------------.OOOo--()--oOOO.-----------------. -| | -| Your Text Here Your Text Here Your Text Here Your Tex | -| Your Text Here Your Text Here Your Text Here Your Tex | -| Your Text Here Your Text Here Your Text Here Your Tex | -| Your Text Here Your Text Here Your Text Here Your Tex | -| | -'--------------------.oooO------------------------------' - ( ) Oooo. - \ ( ( ) - \_) ) / - (_/ + \\\/// + / _ _ \ + (| (.)(.) |) + .----------------------.OOOo--()--oOOO.-----------------. + | | + | Your Text Here Your Text Here Your Text Here Your Tex | + | Your Text Here Your Text Here Your Text Here Your Tex | + | Your Text Here Your Text Here Your Text Here Your Tex | + | Your Text Here Your Text Here Your Text Here Your Tex | + | | + '--------------------.oooO------------------------------' + ( ) Oooo. + \ ( ( ) + \_) ) / + (_/ important @@ -400,9 +400,9 @@ javadoc jstone schallee_@_darkmist.net, coded by Ed Schaller: - /*----------------+ - | toast is yummy | - +----------------*/ + /*----------------+ + | toast is yummy | + +----------------*/ lisp-cmt @@ -432,6 +432,32 @@ Joan G. Stark , coded by Thomas Jensen: (((__) (__))) +normand +Normand Veilleux, coded by Thomas Jensen: + + __,:,__ __,:,__ __,:,__ __,:,__ Normand __,:,__ + ,ad88P`Y88ba, ,ad88P`Y88ba, ,ad88P`Y88ba, ,ad88P`Y88ba, ,ad88P`Y88ba, + ad88888' `88888ba ad88888' `88888ba ad88888' `88888ba ad88888' `88888ba ad88888' `88888ba + ,d88888P' `Y88888b, ,d88888P' `Y88888b, ,d88888P' `Y88888b, ,d88888P' `Y88888b, ,d88888P' `Y88888b, + ,d888P"' `"Y888b,d888P"' `"Y888b,d888P"' `"Y888b,d888P"' `"Y888b,d888P"' `"Y888b, + :([" ``":"'' ``":"'' ``":"'' ``":"'' "]): + `Y88ba, ,ad88P' + `88888ba ad88888' + `Y88888b, ,d88888P' + `"Y888b, Thank you for visiting https://asciiart.website/ ,d888P"' + "]): This ASCII pic can be found at :([" + ,ad88P' https://asciiart.website/index.php?art=art%20and%20design/borders `Y88ba, + ad88888' `88888ba + ,d88888P' `Y88888b, + ,d888P"' `"Y888b, + :([" __,:,__ __,:,__ __,:,__ __,:,__ "]): + `Y88ba, ,ad88P`Y88ba, ,ad88P`Y88ba, ,ad88P`Y88ba, ,ad88P`Y88ba, ,ad88P' + `88888ba ad88888' `88888ba ad88888' `88888ba ad88888' `88888ba ad88888' `88888ba ad88888' + `Y88888b, ,d88888P' `Y88888b, ,d88888P' `Y88888b, ,d88888P' `Y88888b, ,d88888P' `Y88888b, ,d88888P' + `"Y888b,d888P"' `"Y888b,d888P"' `"Y888b,d888P"' `"Y888b,d888P"' `"Y888b,d888P"' + ``":"'' ``":"'' ``":"'' ``":"'' Veilleux ``":"'' + + nuke Joan G. Stark , coded by Thomas Jensen: @@ -463,14 +489,14 @@ unknown artist, coded by Thomas Jensen: peek unknown artist, coded by Thomas Jensen: - /* _\|/_ - (o o) - +----oOO-{_}-OOo---------------------+ - | | - | C function headers? | - | | - | | - +-----------------------------------*/ + /* _\|/_ + (o o) + +----oOO-{_}-OOo---------------------+ + | | + | C function headers? | + | | + | | + +-----------------------------------*/ pound-cmt @@ -487,9 +513,9 @@ Thomas Jensen: This can be used for marking code changes with your initials (I don't like it, but some people work this way): - for (j=0; j: - /"\/\_..---------------------------------._/\/"\ -( _|| ||| Scroll-AKN... ||| ||_ ) - \_/\/ || ------------------------------ || \/\_/ - || Original Design by "akn" (???) || - || Implemented in boxes by: || - || -~{ Tristano Ajmone }~- || - /"\/\_|----------------------------------|_/\/"\ -( _| |_ ) - \_/\/ `----------------------------------' \/\_/ + /"\/\_..---------------------------------._/\/"\ + ( _|| ||| Scroll-AKN... ||| ||_ ) + \_/\/ || ------------------------------ || \/\_/ + || Original Design by "akn" (???) || + || Implemented in boxes by: || + || -~{ Tristano Ajmone }~- || + /"\/\_|----------------------------------|_/\/"\ + ( _| |_ ) + \_/\/ `----------------------------------' \/\_/ shell @@ -665,28 +691,28 @@ tex-cmt twisted Michael Naylor , coded by Tristano Ajmone : -._____. ._____. .________________________________________. ._____. ._____. -| ._. | | ._. | | .____________________________________. | | ._. | | ._. | -| !_| |_|_|_! | | !____________________________________! | | !_| |_|_|_! | -!___| |_______! !________________________________________! !___| |_______! -.___|_|_| |____________________________________________________|_|_| |___. -| ._____| |________________________________________________________| |_. | -| !_! | | | | | ! !_! | -!_____! | | * * * * * * * * * * * TWISTED * * * * * * * * * * | | !_____! -._____. | | -----------------------|------------------------- | | ._____. -| ._. | | | Just another cool ascii frame, brought to you by: | | | ._. | -| | | | | | | | | | | | -| | | | | | -~{ Tristano Ajmone }~- | | | | | | -| !_! | | | -----------------------|------------------------- | | ! !_! | -!_____! | | Derived from an ascii frame originally created by: | | !_____! -._____. | | | | ._____. -| ._. | | | -~{ Michael Naylor }~ | | | ._. | -| !_| |_|_|____________________________________________________| |_|_|_! | -!___| |________________________________________________________| |_______! -.___|_|_| |___. .________________________________________. .___|_|_| |___. -| ._____| |_. | | .____________________________________. | | ._____| |_. | -| !_! | | !_! | | !____________________________________! | | !_! | | !_! | -!_____! !_____! !________________________________________! !_____! !_____! + ._____. ._____. .________________________________________. ._____. ._____. + | ._. | | ._. | | .____________________________________. | | ._. | | ._. | + | !_| |_|_|_! | | !____________________________________! | | !_| |_|_|_! | + !___| |_______! !________________________________________! !___| |_______! + .___|_|_| |____________________________________________________|_|_| |___. + | ._____| |________________________________________________________| |_. | + | !_! | | | | | ! !_! | + !_____! | | * * * * * * * * * * * TWISTED * * * * * * * * * * | | !_____! + ._____. | | -----------------------|------------------------- | | ._____. + | ._. | | | Just another cool ascii frame, brought to you by: | | | ._. | + | | | | | | | | | | | | + | | | | | | -~{ Tristano Ajmone }~- | | | | | | + | !_! | | | -----------------------|------------------------- | | ! !_! | + !_____! | | Derived from an ascii frame originally created by: | | !_____! + ._____. | | | | ._____. + | ._. | | | -~{ Michael Naylor }~ | | | ._. | + | !_| |_|_|____________________________________________________| |_|_|_! | + !___| |________________________________________________________| |_______! + .___|_|_| |___. .________________________________________. .___|_|_| |___. + | ._____| |_. | | .____________________________________. | | ._____| |_. | + | !_! | | !_! | | !____________________________________! | | !_! | | !_! | + !_____! !_____! !________________________________________! !_____! !_____! underline @@ -699,35 +725,35 @@ Elmar Loos : unicornsay unknown artist, coded by Mike Meyer : - _________________________________ - / \ - | E L E C T R O L Y T E S | - \___________________________ __'\ - |/ \\ - \ \\ . - |\\/| - / " '\ - . . . - / ) | - ' _.' | - '-'/ \ + _________________________________ + / \ + | E L E C T R O L Y T E S | + \___________________________ __'\ + |/ \\ + \ \\ . + |\\/| + / " '\ + . . . + / ) | + ' _.' | + '-'/ \ unicornthink unknown artist, coded by Mike Meyer : - _________________________________ - / \ - | E L E C T R O L Y T E S | - \______________________________ '\ - () \\ - O \\ . - o |\\/| - / " '\ - . . . - / ) | - ' _.' | - '-'/ \ + _________________________________ + / \ + | E L E C T R O L Y T E S | + \______________________________ '\ + () \\ + O \\ . + o |\\/| + / " '\ + . . . + / ) | + ' _.' | + '-'/ \ vim-box @@ -746,6 +772,30 @@ Bram Moolenaar, coded by Thomas Jensen: " +weave +dc, coded by Thomas Jensen: + + _ _ _ _ _ _ _ _ _ _ _ + .-"-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-,_,-'_`-,. + ( ,-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-<.>-'_,-~-} ;. + \ \.'_>-._`-<_>-._`-<_>-._`-<_>-._`-<_>-._`-<_>-._`-<_>-._`-<_>-._`-<_>-._`-<_>-._`-._~--. \ . + /\ \/ ,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._`./ \ \ . + dc(`/ / `/ /.) ) . + \ \ / \ / / \ / . + \ \') ) ( (,\ \ . + / \ / / Thank you for visiting https://asciiart.website/ \ / \ \ . + ( (`/ / This ASCII pic can be found at / /.) ) . + \ \ / \ https://asciiart.website/index.php?art=art%20and%20design/borders / / \ / . + \ \') ) ( (,\ \ . + / \ / / \ / \ \ . + ( (`/ / / /.) ) . + \ \ / \ _ _ _ _ _ _ _ _ _ / / \ /. + \ `.\ `-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_`-._,-'_/,\ \ . + ( `. `,~-._`-<,>-._`-<,>-._`-<,>-._`-<,>-._`-<,>-._`-<,>-._`-<,>-._`-<,>-._`-<,>-._`-=,' ,\ \ . + `. `'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,-<_>-'_,"-' ; . + `-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-._,-' `-.-' . + + whirly unknown artist, coded by Thomas Jensen: diff --git a/pages/boxes-man-1.html b/pages/boxes-man-1.html index 4b4eb98..ac9b763 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-04-24 14:44:35 +0200 +last_modified_at: 2021-06-14 21:32:00 +0200 ---

boxes

@@ -13,7 +13,7 @@ last_modified_at: 2021-04-24 14:44:35 +0200 {% assign thisVersion = site.currentVersion | prepend: 'v' -%} {% include version-select.html currentVersion=thisVersion contentPiece="boxes-man-1" %} -

Section: User Commands (1)
Updated: April 18 2021

+

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

{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %} diff --git a/pages/config-best-practices.md b/pages/config-best-practices.md index beb5799..e6fb09a 100644 --- a/pages/config-best-practices.md +++ b/pages/config-best-practices.md @@ -29,6 +29,7 @@ through this list. don't use this tag. - `box` - It's a box that goes around the input text, i.e. at most one open side. - `comment` - A regional comment in a programming language. + - `large` - A box intended for large content, like figlet fonts, or just lots of text. It wants to be big! - `programming` - All comments in a programming language, including boxes which are valid comments. Anything tagged `comment` would also be tagged `programming`. - `sign` - An ASCII art figure holding or showing a sign which contains the input text. diff --git a/pages/config-step.md b/pages/config-step.md index 8afd685..c8c118c 100644 --- a/pages/config-step.md +++ b/pages/config-step.md @@ -23,9 +23,6 @@ done in less than five minutes! Create your shapes by pasting from the `SAMPLE` block. Remember that all lines in shape definitions must be of equal length. - 1. **Add the other entries.** - You must at least add the `ELASTIC` entry, but this is also the time to add any other entries you might need. - 1. **Take care of quoting.** There are two ways to do that: - If there are only a few double quotes or backslashes in your strings, tell your editor to double all @@ -36,6 +33,14 @@ done in less than five minutes! the special characters. This is achieved via the [`delimiter` statement]({{ site.baseurl }}/config-syntax.html#delim). + It might help to do this in the Vim editor using our + [boxes syntax](https://raw.githubusercontent.com/ascii-boxes/boxes/master/boxes.vim). It understands `delim` + statements and can help correct the escaping by highlighting were stuff is still broken. But use any editor you + like, of course. + + 1. **Add the other entries.** + You must at least add the `ELASTIC` entry, but this is also the time to add any other entries you might need. + 1. **Do not leave your editor just yet.** Instead try out your design. This is because if you made a mistake with the line lengths or something, you can still easily undo the doubling of backslashes. Otherwise, it may become difficult to judge how long a line is. diff --git a/pages/config-syntax.md b/pages/config-syntax.md index 73a2403..be34419 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-05-28 22:11:00 +0200 +last_modified_at: 2021-06-14 21:32:00 +0200 --- # Config File Syntax @@ -274,7 +274,7 @@ 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. +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. @@ -320,6 +320,9 @@ The path to the parent config should be an absolute pathname specifying a config 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. diff --git a/pages/v2.1.1/boxes-man-1.html b/pages/v2.1.1/boxes-man-1.html new file mode 100644 index 0000000..9a620ac --- /dev/null +++ b/pages/v2.1.1/boxes-man-1.html @@ -0,0 +1,470 @@ +--- +title: Manpage of boxes(1) +permalink: /v2.1.1/boxes-man-1.html +longContent: true +bxVersion: v2.1.1 +created_at: 1999-04-06 +last_modified_at: 2021-06-14 21:32:00 +0200 +--- + +

boxes

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

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

+ + +{% 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 {{ site.currentVersion }}.

+ + +{% 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 2. Details in the LICENSE file: +{{ site.link_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.1.1/config-syntax.md b/pages/v2.1.1/config-syntax.md new file mode 100644 index 0000000..6727520 --- /dev/null +++ b/pages/v2.1.1/config-syntax.md @@ -0,0 +1,329 @@ +--- +title: Docs - Config File Syntax +permalink: /v2.1.1/config-syntax.html +longContent: true +bxVersion: v2.1.1 +created_at: 1999-04-06 +last_modified_at: 2021-06-14 21:32: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. Not 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)