extern/boxes
1
0
Fork 0
mirror of https://github.com/ascii-boxes/boxes.git synced 2025-01-22 05:38:35 +01:00
Code Issues Packages Projects Releases Wiki Activity

Apply new 'markdown' layout to all pages

Browse Source
This commit is contained in:
Thomas Jensen 2015-05-12 23:10:14 +02:00
parent 70cfb5ecc7
commit 9efa6b67f2
22 changed files with 598 additions and 645 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
_includes/boxes/docs/config-complete_exp.md
View File

@ -1,84 +0,0 @@
# Complete Examples
In order to illustrate the *boxes* configuration language described in the previous chapters, we now look at the source code of two complete box designs, one simple and one more complex.
In addition to the examples shown here, please refer to the [official boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config) for tons more.
## Simple Example
BOX simple
sample
++++++++++++
+ +
++++++++++++
ends
shapes {
n("+") s("+") e("+") w("+")
nw("+") ne("+") se("+") sw("+")
}
elastic (n,s,e,w)
END simple
## Complex Example
BOX tjc
author "John Doe <john@doe.com>"
revision "1.1"
revdate "July 16, 1999 (Friday, 18:55h)"
created "April 02, 1999 (Friday, 19:26h)"
Sample
static char *foo (const int a, const int b)
/*
* Do the foo on the bar and around again.
*
* a number of doodlefrobs
* b barfoo mode (0 == off)
*
* Memory will be allocated for the result.
* Should only be called for lines of length > 0;
*
* RETURNS: Success: Pointer to result line
* Error: -1 (e.g. frobs depleted)
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*/
{
static char temp ....
int ii; ....
ends
indent "none" # alternatives: "box", "text"
shapes {
wnw ("/*")
w (" *")
sw ("* ", " *")
ssw ("*", "/")
s (" *", " ")
}
elastic (s, w)
delimiter ?"
replace "\*/" with "*\/" # quote closing comment tags
reverse "\*\\/" to "*/"
padding {
left 2
vertical 1
}
END tjc
Note the `SAMPLE` block of the latter example. It shows much more than just the box itself, trying to give the user an impression of what the box would look like if used in reality. We only need half the backslashes in the `REVERSE` and `REPLACE` statements because we use `delimiter` to change the escape character from backslash to question mark.
[ [up](index.html) \| next ]

63
_includes/boxes/docs/config-general.md
View File

@ -1,63 +0,0 @@
# Box Designs
*Boxes* can draw and remove the boxes whose designs are defined in its configuration file. This page is intended to describe the concept of a *box design*, clarify some terms used to describe a box design, and how to define your own box designs.
## General Box Layout
A box design consists of up to 16 so-called **shapes** which are labeled in a fashion similar to the points of the compass:
+---------+---------+-----------------+---------+---------+
| | | | | |
| NW | NNW | N | NNE | NE |
| | | | | |
+---------+---------+-----------------+---------+---------+
| | padding | |
| WNW | +-- - - - - - - - - - - - - - --+ | ENE |
| | | | | |
+---------+ +---------+
| | | | | |
| | original | |
| W | | input | | E |
| | text | |
| | | | | |
+---------+ +---------+
| | | | | |
| WSW | +-- - - - - - - - - - - - - - --+ | ESE |
| | padding | |
+---------+---------+-----------------+---------+---------+
| | | | | |
| SW | SSW | S | SSE | SE |
| | | | | |
+---------+---------+-----------------+---------+---------+
The sides of the box are sometimes referred to as *top* (instead of north), *right* (instead of east), *bottom* (south), and *left* (west), in order to avoid confusion with *shapes* of the same name. The group of shapes NW, NE, SE, and SW is referred to as the *corner shapes*. The groups of shapes between two corner shapes are called the *side shapes*.
## Shape Restrictions
A design definition does not necessarily need to include specifications for all 16 shapes. You only need to specify the shapes that you need. Of course, at least one shape must be specified.
- All shapes on a vertical side (inluding corners) must be of equal width.
- All shapes on a horizontal side (including corners) must be of equal height.
In order to let the box have a dynamic size, certain side shapes must be drawn repeatedly. Those shapes are called **elastic** shapes.
- At least one shape per side must be elastic.
- Corners may not be elastic.
- No two neighboring shapes may be elastic, i.e. there must always be at least one static shape in between two elastic shapes.
You don't really need to worry about these restrictions. *Boxes* will tell you if you violate any of them. So if *boxes* does not complain, your design is (at least syntactically) great.
## Open Box Sides
Many box designs require open box sides, for instance most regional comments. In response to that insight, it was decided to make empty box sides into a supported feature. Thus, if you define a box side to consist entirely of spaces, that side will be considered **open** and it will not appear in the output.
Of course, you don't need to actually put the empty shapes into the config file, but *boxes* will automagically generate empty shapes if they are needed. (Internally, boxes always need at least 8 shapes - the corners, and one shape per side.) When the box is generated, those empty sides will be left out. Thus, boxes can be created which are open on any side.
## Padding Area
The last thing to mention about a box design is the **padding area**, which surrounds the original input text as shown in the figure above. The padding area is located inside the actual box and consists only of spaces. It is frequently used to keep the text from coming too close to the box (that might not look so good in some cases) unless absolutely necessary. &quot;Absolutely necessary&quot; usually means that the user has specified a very small box size. It is also possible to control the padding from the command line, which is why the above figure shows the padding area as a dotted box.
[ [up](index.html) \| [next](config-syntax.html) ]

26
_includes/boxes/docs/config-step.md
View File

@ -1,26 +0,0 @@
# A New Design, Step By Step
Finally, we will take a brief look at the step-by-step process of creating a new design. A complex new design can be done in less than five minutes!
1. **Create an empty box design.** The only entry so far between the `BOX` and `END` statements is an empty `SAMPLE` block.
1. **Draw your box.** Do it inside the sample block. Just draw it like you think it should look.
1. **Create the `SHAPE` block.** 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 backslashes in the `SHAPE` block for you. Do not double the backslashes before this point, or you will not be able to undo it so easily (see below).
Then escape the double quotes (`"`) by telling your editor to put a backslash in front of every double quote which is part of a string.
- If you've got a lot of double quotes or backslashes in your strings, simply choose some other characters to be the special characters. This is achieved via the [`delimiter` statement](config-syntax.html#delim).
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.
1. **Refine your design.** Repeat appropriate steps until done.
It is precision work to finalize the box design. But this needs to be done only once, and the box design can be shared and reused easily.
[ [up](index.html) \| [next](config-complete_exp.html) ]

153
_includes/boxes/docs/config-syntax.md
View File

@ -1,153 +0,0 @@
# Config File 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.
### Box Design
<pre><b>BOX</b> <i>design_name</i>
entries_and_blocks
<b>END</b> <i>design_name</i></pre>
Every box design definition must have at least a `SHAPE` block, an `ELASTIC` list, and a `SAMPLE` block.
### 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) for many examples).
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.
### Shape Block
<PRE><b>SHAPE</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](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.
### 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.
### 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](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.
### 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. Alternately, you may use the [`delimiter` statement](#delim) to change the string delimiting and escape character.
For more information on how to use regular expressions, please see `man 5 regexp`, under "Basic Regular Expressions" or any other source.
### 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).
<a class="bxOffsetAnchor" name="delim"></a>
### String Delimiters
<PRE><b>DELIM[ITER]</b> <i>chars</i></PRE>
*`chars`* must consist of exactly two characters, the first of which being the escape character, and the second the string delimiter. 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.
For example, consider the literal string `foo":"\"\\bar`:
"foo\":\"\\\"\\\\bar"
Using a `DELIMITER` statement, this looks much simpler:
delimiter ?:
:foo"?:"\"\\bar:
The escape character may be any character you choose. The string delimiter, however, may only be one out of the following:
"~'`!@%&*=:;<>?/|.\
This set may change, but *boxes* will tell you your choices if you make a mistake.
### Name of Author
<PRE><b>AUTHOR</b> &quot;<i>name_of_author</i>&quot;</PRE>
Simply states who the ingenious guy/girl was who created the design. This entry is used when displaying the list of designs (`boxes -l`). The name should include the email address. Ideally, the entry should be usable "as is" in a `TO:` mail header, like this:
author "Thomas Jensen <tj@foobar.com>"
### 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) 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.
[ [up](index.html) \| [next](config-step.html) ]

57
_includes/boxes/docs/faq.md
View File

@ -1,57 +0,0 @@
# FAQ
These are the frequently asked questions about the *boxes* program and their answers.
These questions are *actually* "frequently asked". For general information on the *boxes* program, installation instructions, and information on box design creation please refer to the [*boxes* documentation]({{ site.baseurl }}/docs/).
<a class="bxOffsetAnchor" name="q1"></a>
### Q. 1. What is a text filter program?
There is a [separate page]({{ site.baseurl }}/docs/filters.html) explaining this. *Boxes* is mostly used as such a filter program.
<a class="bxOffsetAnchor" name="q2"></a>
### Q. 2. I have compiled and installed boxes, but when I run it, I get an error message "input in flex scanner failed"!
Upgrade to version 1.0.1 or later. Versions prior to 1.0.1 gave this error message when the config file they were trying to read was in fact a directory. The global config file name is */usr/share/boxes* on most systems. This is the name of the file, not the name of a directory into which a config file would be placed.
<a class="bxOffsetAnchor" name="q3"></a>
### Q. 3. Boxes destroys my tabs!
By default, all tab characters are replaced by spaces. However, you can change this behavior using the `-t` option (since version 1.1). The `-t` option only affects leading tabs. Tabs which end up inside the box are *always* converted into spaces.
Note that you can also set the tab stop distance (== how many spaces per tab) using the `-t` option.
<a class="bxOffsetAnchor" name="q4"></a>
### Q. 4. "Can't read file C:\TEMP\VIO44.TMP" when calling boxes from vim
On Windows, this error message may appear instead of a box when *boxes* is called from vim. This is not a problem of *boxes*. In fact, it's a misleading message from the vim editor which is supposed to tell you that *boxes* is not in your PATH. Solution: Copy *boxes.exe* and *boxes.cfg* to a directory which is in your PATH. (thanks *Jeff Lanzarotta*, 05-Jul-00)
<a class="bxOffsetAnchor" name="q5"></a>
### Q. 5. Compilation
The current version includes changes to solve all compilation issues reported to the author. So please check that you are using the most current version. Still, there are many different systems out there, so here's a short list of things to try:
- `-traditional` flag for regexp package:
Some systems may require you to set or clear the `-traditional` flag from the `CFLAGS` definition in *src/regexp/Makefile*.
- Warnings from flex or bison:
If you get warnings from flex or bison, do a `make clean ; make` from the top level directory. The following warning is harmless:
lexer.l:1309: warning: `yy_flex_realloc' defined but not used
It's a known bug in flex, and has no impact on boxes. You can safely ignore this warning.
- `Bad address` on *boxes* execution after compiling on a 64bit system:
This may happen when the system you are compiling on is 64bit. Boxes is only a 32bit program, so the compiler may have to be forced to 32bit by adding the `-m32` option. (Thanks to <span class="atmention">[@stefanow](https://github.com/stefanow)</span> for [supplying](https://github.com/{{ site.github }}/issues/7) this information!)
In order to do this, use the following command line (works with current sources):
make CFLAGS_ADDTL=-m32 LDFLAGS_ADDTL=-m32

25
_includes/boxes/docs/filters.md
View File

@ -1,25 +0,0 @@
# What are filters?
[Filters](http://en.wikipedia.org/wiki/Filter_%28software%29) are generally programs which read some input text from standard input, perform some modifications on it, and write the modified text to standard output. While a single filter can be used individually, they are frequently strung together to form a pipeline. *Boxes* is such a filter program.
Some text editors *support filters*, which is to say they offer a way to let filter programs make changes to the text being edited. By pressing a key, the user tells the editor to start the filter program (e.g. *boxes*) and feed it the lines of text selected in the editor. Those lines are subsequently replaced with the output from the filter program.
**Here's an example using *boxes*:**
Imagine your editor (in this case, it's [Vim](http://www.vim.org/)) shows the following C code (it could be any text, of course):
<IMG SRC="{{ site.baseurl}}/images/filter1.gif" WIDTH="619" HEIGHT="272" ALT="text before filtering" />
Now you mark some of the lines ...
<IMG SRC="{{ site.baseurl}}/images/filter2.gif" WIDTH="619" HEIGHT="272" ALT="text to be filtered is marked" />
... and press the key which makes vim call the filter program *boxes*:
<IMG SRC="{{ site.baseurl}}/images/filter3.gif" WIDTH="619" HEIGHT="272" ALT="after the filter was applied" />
Voil&aacute;! The marked lines have been fed to *boxes* and replaced by the output of *boxes*. You've got yourself a box! Of course the same mechanism works for box removal - or anything else you can find a filter for. :smile:
Most major text editors support filters, among them [Vim](http://www.vim.org/), [Emacs](http://www.emacs.org/), and [Jed](http://www.jedsoft.org/jed/). There are certainly many, many more.
Please see the [installation section](install.html) in the *boxes* docs for more info on how to make your editor work with *boxes*.

42
_includes/boxes/docs/index.md
View File

@ -1,42 +0,0 @@
# Documentation
1. General
a. [Overview]({{ site.baseurl}}/about.html) &amp; [Features]({{ site.baseurl}}/about.html#some-of-the-features)
b. [News]({{ site.baseurl}}/)
c. [FAQ]({{ site.baseurl}}/docs/faq.html) (Frequently Asked Questions)
1. [Legal Stuff](legal.html)
1. [Examples]({{ site.baseurl}}/examples.html)
a. [Default Action]({{ site.baseurl}}/examples.html)
b. [Choosing a Different Design]({{ site.baseurl}}/examples.html#design)
c. [The &quot;<TT>-a</TT>&quot; option - Alignment, Positioning &amp; Line Justification]({{ site.baseurl}}/examples.html#position)
d. [Size Specification]({{ site.baseurl}}/examples.html#size)
e. [Padding]({{ site.baseurl}}/examples.html#padding)
f. [Regional Comments]({{ site.baseurl}}/examples.html#comments)
g. [Removal of Boxes]({{ site.baseurl}}/examples.html#removal)
h. [Indentation Handling]({{ site.baseurl}}/examples.html#indent)
i. [Use of Regular Expressions]({{ site.baseurl}}/examples.html#regexp)
1. Creating Your Own Designs
a. [Introduction and General Concepts](config-general.html)
b. [Configuration File Syntax](config-syntax.html)
c. [Step-by-Step Guide to a New Design](config-step.html)
d. [Complete examples of box designs](config-complete_exp.html)
e. [List of preconfigured designs]({{ site.baseurl}}/box-designs.txt)
1. [Text Editor Integration](install.html)
a. [Integration with Vim](install.html)
b. [Integration with Jed](install.html#jed)
c. [Integration with Emacs](install.html#emacs)
1. Development
a. [Contributing]({{ site.baseurl}}/contributing.html)
b. [List of Contributors]({{ site.baseurl}}/contributing.html#contributors)
c. [Building from Source]({{ site.baseurl}}/build.html)
d. [Testing]({{ site.baseurl}}/testing.html)
e. [Chronological Change Log](https://github.com/{{ site.github }}/commits/master)
1. [Download]({{ site.baseurl}}/download.html)
1. [*Boxes* manual page](boxes-man-1.html) (also in [troff format](https://github.com/{{ site.github }}/blob/master/doc/boxes.1.in))

116
_includes/boxes/docs/install.md
View File

@ -1,116 +0,0 @@
# Text Editor Integration
This section assumes you already have a working binary of *boxes*. Binaries for some platforms can be obtained through the [download page]({{ site.baseurl}}/download.html). Should your platform be missing from the list, you can still download the source distribution and compile your own binary. This sounds harder than it is.
Although *boxes* can be useful when used on the command line, the more frequent use case will be as a filter tied to your editor. So, how can *boxes* be tied to your editor?
Example config file entries are featured so far for [Vim](http://www.vim.org/), [Jed](http://www.jedsoft.org/jed/), and [Emacs](http://www.gnu.org/software/emacs/). If you know how to to this in other editors, please drop me a line!
## Integration with Vim
To call filters from vim, you need to press `!` in visual mode or `!!` in normal mode. So the easiest way to tie in *boxes* with vim is by adding the following four lines to your *.vimrc*:
vmap ,mc !boxes -d c-cmt<CR>
nmap ,mc !!boxes -d c-cmt<CR>
vmap ,xc !boxes -d c-cmt -r<CR>
nmap ,xc !!boxes -d c-cmt -r<CR>
`<CR>` should be there literally; just paste the lines directly from your browser window. This would comment out the current line or the lines you have marked when you press `,mc` (for *make comment*). Comments can be removed in the same way by pressing `,xc`. Should you feel that `,mc` is too long a combination to type, feel free to choose a shorter one. The above example assumes you are using the standard boxes config file, which features the *c-cmt* design. Of course, the same technique works for any other designs.
While the above example is nice, it does not offer much convenience when you are editing different languages a lot, because you need to remember the hotkey for each different box design. Fortunately, vim has a feature called *autocommands*. They can be used to automatically change the meaning of a key combination depending on what file you edit (any many other things too, of course). Autocommand syntax is
au[tocmd] [group] {event} {pat} [nested] {cmd}
We can leave out the group. For `{event}`, we choose `BufEnter`, which is generated every time you enter a new buffer, e.g. when starting vim or when switching between open files. `{pat}` is a file glob, and `{cmd}` is our call to *boxes*.
The lines below are from the author's *.vimrc*. They can be pasted directly from your browser window. Their effect is that `,mc` and `,xc` always generate the correct comments for many languages, including C, C++, HTML, Java, lex, yacc, shell scripts, Perl, etc. The default key binding is to generate shell comments using a pound sign (file glob of `*` at the start).
autocmd BufEnter * nmap ,mc !!boxes -d pound-cmt<CR>
autocmd BufEnter * vmap ,mc !boxes -d pound-cmt<CR>
autocmd BufEnter * nmap ,xc !!boxes -d pound-cmt -r<CR>
autocmd BufEnter * vmap ,xc !boxes -d pound-cmt -r<CR>
autocmd BufEnter *.html nmap ,mc !!boxes -d html-cmt<CR>
autocmd BufEnter *.html vmap ,mc !boxes -d html-cmt<CR>
autocmd BufEnter *.html nmap ,xc !!boxes -d html-cmt -r<CR>
autocmd BufEnter *.html vmap ,xc !boxes -d html-cmt -r<CR>
autocmd BufEnter *.[chly],*.[pc]c nmap ,mc !!boxes -d c-cmt<CR>
autocmd BufEnter *.[chly],*.[pc]c vmap ,mc !boxes -d c-cmt<CR>
autocmd BufEnter *.[chly],*.[pc]c nmap ,xc !!boxes -d c-cmt -r<CR>
autocmd BufEnter *.[chly],*.[pc]c vmap ,xc !boxes -d c-cmt -r<CR>
autocmd BufEnter *.C,*.cpp,*.java nmap ,mc !!boxes -d java-cmt<CR>
autocmd BufEnter *.C,*.cpp,*.java vmap ,mc !boxes -d java-cmt<CR>
autocmd BufEnter *.C,*.cpp,*.java nmap ,xc !!boxes -d java-cmt -r<CR>
autocmd BufEnter *.C,*.cpp,*.java vmap ,xc !boxes -d java-cmt -r<CR>
autocmd BufEnter .vimrc*,.exrc nmap ,mc !!boxes -d vim-cmt<CR>
autocmd BufEnter .vimrc*,.exrc vmap ,mc !boxes -d vim-cmt<CR>
autocmd BufEnter .vimrc*,.exrc nmap ,xc !!boxes -d vim-cmt -r<CR>
autocmd BufEnter .vimrc*,.exrc vmap ,xc !boxes -d vim-cmt -r<CR>
<a name="jed">&nbsp;</a>
## Integration with Jed
*Andreas Heiduk* (@asheiduk) kindly provided the following excerpt from his *.jedrc*:
%!% Ripped from "pipe.sl"
variable Last_Process_Command = Null_String;
define do_process_region(cmd) {
variable tmp;
tmp = make_tmp_file ("/tmp/jedpipe");
cmd = strncat (cmd, " > ", tmp, " 2>&1", 4);
!if (dupmark ()) error ("Mark not set.");
if (pipe_region (cmd))
{
error ("Process returned a non-zero exit status.");
}
del_region ();
() = insert_file (tmp);
() = delete_file (tmp);
}
define process_region ()
{
variable cmd;
cmd = read_mini ("Pipe to command:", Last_Process_Command, "");
!if (strlen (cmd)) return;
Last_Process_Command = cmd;
do_process_region(cmd);
}
%-----------------------------------------------------------------------
if( BATCH == 0 ){
setkey("process_region", "\e|"); % ESC-Pipe :-)
add_completion("process_region");
% define some often used filters
setkey("do_process_region(\"tal\")", "\et") % tal on esc-t
}
I think it calls [tal](http://www.thomasjensen.com/software/tal/) when you press `ESC-t` (second but last line). Thus, you would have to add a similar line to call *boxes*.
<a name="emacs">&nbsp;</a>
## Integration with Emacs
[Jason L. Shiffer](mailto:jshiffer@zerotao.com) kindly submitted the following information on integrating *boxes* with Emacs:
The simple interface (only a single box style, but easy):
(defun boxes-create ()
(interactive)
(shell-command-on-region (region-beginning) (region-end) "boxes -d c-cmt2" nil 1 nil))
(defun boxes-remove ()
(interactive)
(shell-command-on-region (region-beginning) (region-end) "boxes -r -d c-cmt2" nil 1 nil))
Jason also wrote a [*boxes* mode for Emacs](boxes.el). Remember to update its design list when you add new designs to your config file.

9
_includes/boxes/docs/legal.md
View File

@ -1,9 +0,0 @@
# Legal Terms
*Boxes* is free software under the terms of the <A TARGET="_blank" HREF="http://www.gnu.org/licenses/gpl-2.0.html#TOC1">GNU General Public License, version&nbsp;2</A> (GNU GPL), a copy of which you should have received with your source archive (filename of *COPYING* or *LICENSE*).
Among many other things, the GNU GPL states that there is **no warranty** whatsoever. If *boxes* filters away your master's thesis that's your problem! You are using the program entirely at your own risk. On the other hand, it is free. Here is an excerpt from the GNU GPL:
> **11.** Because the program is licensed free of charge, there is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.<br/>
> **12.** In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.

16
_includes/boxes/docs/releases.md
View File

@ -1,16 +0,0 @@
{% comment %}
Release History
The Release History table is in the releases.html file,
because we needed to be able to change column headings on small screens.
{% endcomment %}
## When to upgrade
Boxes has been around a long time, and it has been very stable. Sometimes, new releases are still required to ensure that *boxes* continues to compile smoothly on a large number of platforms. Whether or not you should upgrade to a new version depends on what you've got, and what you want to do:
- **Building from Source:** If you want to [build from source]({{ site.baseurl}}/build.html), you should always use the latest sources from the above table. You may also clone the repo and build the bleeding edge. Since we have a stable master branch, this will also get you a good build, but it will be a snapshot version.
- **Using a binary:** The last bugfixes and the last functional enhancements were in version 1.1 (of 2006). So if you've got a working 1.1 binary on your system, you're good and you don't need to upgrade. Staying on the even older 1.0.1 will mean that you're missing features (such as better tab handling and the 'mend' option). Anything prior to 1.0.1 should definitely be upgraded.
Note that you can always copy the [latest box designs](https://github.com/{{ site.github }}/blob/master/boxes-config) from GitHub to replace your older *boxes-config* (Unix) or *boxes.cfg* (Windows) - the designs are backwards compatible.

0
_includes/boxes/shortdescription.html → _includes/shortdescription.html
View File

90
docs/config-complete_exp.html
View File

@ -1,9 +1,89 @@
---
layout: default
layout: markdown
title: Docs - Config Examples
---
{% capture includedMarkdown %}{% include boxes/docs/config-complete_exp.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# Complete Examples
In order to illustrate the *boxes* configuration language described in the previous chapters, we now look at the source code of two complete box designs, one simple and one more complex.
In addition to the examples shown here, please refer to the [official boxes config file](https://github.com/{{ site.github }}/blob/master/boxes-config) for tons more.
## Simple Example
BOX simple
sample
++++++++++++
+ +
++++++++++++
ends
shapes {
n("+") s("+") e("+") w("+")
nw("+") ne("+") se("+") sw("+")
}
elastic (n,s,e,w)
END simple
## Complex Example
BOX tjc
author "John Doe <john@doe.com>"
revision "1.1"
revdate "July 16, 1999 (Friday, 18:55h)"
created "April 02, 1999 (Friday, 19:26h)"
Sample
static char *foo (const int a, const int b)
/*
* Do the foo on the bar and around again.
*
* a number of doodlefrobs
* b barfoo mode (0 == off)
*
* Memory will be allocated for the result.
* Should only be called for lines of length > 0;
*
* RETURNS: Success: Pointer to result line
* Error: -1 (e.g. frobs depleted)
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*/
{
static char temp ....
int ii; ....
ends
indent "none" # alternatives: "box", "text"
shapes {
wnw ("/*")
w (" *")
sw ("* ", " *")
ssw ("*", "/")
s (" *", " ")
}
elastic (s, w)
delimiter ?"
replace "\*/" with "*\/" # quote closing comment tags
reverse "\*\\/" to "*/"
padding {
left 2
vertical 1
}
END tjc
Note the `SAMPLE` block of the latter example. It shows much more than just the box itself, trying to give the user an impression of what the box would look like if used in reality. We only need half the backslashes in the `REVERSE` and `REPLACE` statements because we use `delimiter` to change the escape character from backslash to question mark.
[ [up](index.html) \| next ]

69
docs/config-general.html
View File

@ -1,9 +1,68 @@
---
layout: default
layout: markdown
title: Docs - Config Intro
---
{% capture includedMarkdown %}{% include boxes/docs/config-general.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# Box Designs
*Boxes* can draw and remove the boxes whose designs are defined in its configuration file. This page is intended to describe the concept of a *box design*, clarify some terms used to describe a box design, and how to define your own box designs.
## General Box Layout
A box design consists of up to 16 so-called **shapes** which are labeled in a fashion similar to the points of the compass:
+---------+---------+-----------------+---------+---------+
| | | | | |
| NW | NNW | N | NNE | NE |
| | | | | |
+---------+---------+-----------------+---------+---------+
| | padding | |
| WNW | +-- - - - - - - - - - - - - - --+ | ENE |
| | | | | |
+---------+ +---------+
| | | | | |
| | original | |
| W | | input | | E |
| | text | |
| | | | | |
+---------+ +---------+
| | | | | |
| WSW | +-- - - - - - - - - - - - - - --+ | ESE |
| | padding | |
+---------+---------+-----------------+---------+---------+
| | | | | |
| SW | SSW | S | SSE | SE |
| | | | | |
+---------+---------+-----------------+---------+---------+
The sides of the box are sometimes referred to as *top* (instead of north), *right* (instead of east), *bottom* (south), and *left* (west), in order to avoid confusion with *shapes* of the same name. The group of shapes NW, NE, SE, and SW is referred to as the *corner shapes*. The groups of shapes between two corner shapes are called the *side shapes*.
## Shape Restrictions
A design definition does not necessarily need to include specifications for all 16 shapes. You only need to specify the shapes that you need. Of course, at least one shape must be specified.
- All shapes on a vertical side (inluding corners) must be of equal width.
- All shapes on a horizontal side (including corners) must be of equal height.
In order to let the box have a dynamic size, certain side shapes must be drawn repeatedly. Those shapes are called **elastic** shapes.
- At least one shape per side must be elastic.
- Corners may not be elastic.
- No two neighboring shapes may be elastic, i.e. there must always be at least one static shape in between two elastic shapes.
You don't really need to worry about these restrictions. *Boxes* will tell you if you violate any of them. So if *boxes* does not complain, your design is (at least syntactically) great.
## Open Box Sides
Many box designs require open box sides, for instance most regional comments. In response to that insight, it was decided to make empty box sides into a supported feature. Thus, if you define a box side to consist entirely of spaces, that side will be considered **open** and it will not appear in the output.
Of course, you don't need to actually put the empty shapes into the config file, but *boxes* will automagically generate empty shapes if they are needed. (Internally, boxes always need at least 8 shapes - the corners, and one shape per side.) When the box is generated, those empty sides will be left out. Thus, boxes can be created which are open on any side.
## Padding Area
The last thing to mention about a box design is the **padding area**, which surrounds the original input text as shown in the figure above. The padding area is located inside the actual box and consists only of spaces. It is frequently used to keep the text from coming too close to the box (that might not look so good in some cases) unless absolutely necessary. &quot;Absolutely necessary&quot; usually means that the user has specified a very small box size. It is also possible to control the padding from the command line, which is why the above figure shows the padding area as a dotted box.
[ [up](index.html) \| [next](config-syntax.html) ]

32
docs/config-step.html
View File

@ -1,9 +1,31 @@
---
layout: default
layout: markdown
title: Docs - Config Step-by-Step
---
{% capture includedMarkdown %}{% include boxes/docs/config-step.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# A New Design, Step By Step
Finally, we will take a brief look at the step-by-step process of creating a new design. A complex new design can be done in less than five minutes!
1. **Create an empty box design.** The only entry so far between the `BOX` and `END` statements is an empty `SAMPLE` block.
1. **Draw your box.** Do it inside the sample block. Just draw it like you think it should look.
1. **Create the `SHAPE` block.** 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 backslashes in the `SHAPE` block for you. Do not double the backslashes before this point, or you will not be able to undo it so easily (see below).
Then escape the double quotes (`"`) by telling your editor to put a backslash in front of every double quote which is part of a string.
- If you've got a lot of double quotes or backslashes in your strings, simply choose some other characters to be the special characters. This is achieved via the [`delimiter` statement](config-syntax.html#delim).
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.
1. **Refine your design.** Repeat appropriate steps until done.
It is precision work to finalize the box design. But this needs to be done only once, and the box design can be shared and reused easily.
[ [up](index.html) \| [next](config-complete_exp.html) ]

159
docs/config-syntax.html
View File

@ -1,9 +1,158 @@
---
layout: default
layout: markdown
title: Docs - Config File Syntax
---
{% capture includedMarkdown %}{% include boxes/docs/config-syntax.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# Config File 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.
### Box Design
<pre><b>BOX</b> <i>design_name</i>
entries_and_blocks
<b>END</b> <i>design_name</i></pre>
Every box design definition must have at least a `SHAPE` block, an `ELASTIC` list, and a `SAMPLE` block.
### 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) for many examples).
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.
### Shape Block
<PRE><b>SHAPE</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](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.
### 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.
### 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](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.
### 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. Alternately, you may use the [`delimiter` statement](#delim) to change the string delimiting and escape character.
For more information on how to use regular expressions, please see `man 5 regexp`, under "Basic Regular Expressions" or any other source.
### 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).
<a class="bxOffsetAnchor" name="delim"></a>
### String Delimiters
<PRE><b>DELIM[ITER]</b> <i>chars</i></PRE>
*`chars`* must consist of exactly two characters, the first of which being the escape character, and the second the string delimiter. 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.
For example, consider the literal string `foo":"\"\\bar`:
"foo\":\"\\\"\\\\bar"
Using a `DELIMITER` statement, this looks much simpler:
delimiter ?:
:foo"?:"\"\\bar:
The escape character may be any character you choose. The string delimiter, however, may only be one out of the following:
"~'`!@%&*=:;<>?/|.\
This set may change, but *boxes* will tell you your choices if you make a mistake.
### Name of Author
<PRE><b>AUTHOR</b> &quot;<i>name_of_author</i>&quot;</PRE>
Simply states who the ingenious guy/girl was who created the design. This entry is used when displaying the list of designs (`boxes -l`). The name should include the email address. Ideally, the entry should be usable "as is" in a `TO:` mail header, like this:
author "Thomas Jensen <tj@foobar.com>"
### 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) 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.
[ [up](index.html) \| [next](config-step.html) ]

63
docs/faq.html
View File

@ -1,9 +1,62 @@
---
layout: default
layout: markdown
title: FAQ
---
{% capture includedMarkdown %}{% include boxes/docs/faq.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# FAQ
These are the frequently asked questions about the *boxes* program and their answers.
These questions are *actually* "frequently asked". For general information on the *boxes* program, installation instructions, and information on box design creation please refer to the [*boxes* documentation]({{ site.baseurl }}/docs/).
<a class="bxOffsetAnchor" name="q1"></a>
### Q. 1. What is a text filter program?
There is a [separate page]({{ site.baseurl }}/docs/filters.html) explaining this. *Boxes* is mostly used as such a filter program.
<a class="bxOffsetAnchor" name="q2"></a>
### Q. 2. I have compiled and installed boxes, but when I run it, I get an error message "input in flex scanner failed"!
Upgrade to version 1.0.1 or later. Versions prior to 1.0.1 gave this error message when the config file they were trying to read was in fact a directory. The global config file name is */usr/share/boxes* on most systems. This is the name of the file, not the name of a directory into which a config file would be placed.
<a class="bxOffsetAnchor" name="q3"></a>
### Q. 3. Boxes destroys my tabs!
By default, all tab characters are replaced by spaces. However, you can change this behavior using the `-t` option (since version 1.1). The `-t` option only affects leading tabs. Tabs which end up inside the box are *always* converted into spaces.
Note that you can also set the tab stop distance (== how many spaces per tab) using the `-t` option.
<a class="bxOffsetAnchor" name="q4"></a>
### Q. 4. "Can't read file C:\TEMP\VIO44.TMP" when calling boxes from vim
On Windows, this error message may appear instead of a box when *boxes* is called from vim. This is not a problem of *boxes*. In fact, it's a misleading message from the vim editor which is supposed to tell you that *boxes* is not in your PATH. Solution: Copy *boxes.exe* and *boxes.cfg* to a directory which is in your PATH. (thanks *Jeff Lanzarotta*, 05-Jul-00)
<a class="bxOffsetAnchor" name="q5"></a>
### Q. 5. Compilation
The current version includes changes to solve all compilation issues reported to the author. So please check that you are using the most current version. Still, there are many different systems out there, so here's a short list of things to try:
- `-traditional` flag for regexp package:
Some systems may require you to set or clear the `-traditional` flag from the `CFLAGS` definition in *src/regexp/Makefile*.
- Warnings from flex or bison:
If you get warnings from flex or bison, do a `make clean ; make` from the top level directory. The following warning is harmless:
lexer.l:1309: warning: `yy_flex_realloc' defined but not used
It's a known bug in flex, and has no impact on boxes. You can safely ignore this warning.
- `Bad address` on *boxes* execution after compiling on a 64bit system:
This may happen when the system you are compiling on is 64bit. Boxes is only a 32bit program, so the compiler may have to be forced to 32bit by adding the `-m32` option. (Thanks to <span class="atmention">[@stefanow](https://github.com/stefanow)</span> for [supplying](https://github.com/{{ site.github }}/issues/7) this information!)
In order to do this, use the following command line (works with current sources):
make CFLAGS_ADDTL=-m32 LDFLAGS_ADDTL=-m32

31
docs/filters.html
View File

@ -1,9 +1,30 @@
---
layout: default
layout: markdown
title: What are filters?
---
{% capture includedMarkdown %}{% include boxes/docs/filters.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# What are filters?
[Filters](http://en.wikipedia.org/wiki/Filter_%28software%29) are generally programs which read some input text from standard input, perform some modifications on it, and write the modified text to standard output. While a single filter can be used individually, they are frequently strung together to form a pipeline. *Boxes* is such a filter program.
Some text editors *support filters*, which is to say they offer a way to let filter programs make changes to the text being edited. By pressing a key, the user tells the editor to start the filter program (e.g. *boxes*) and feed it the lines of text selected in the editor. Those lines are subsequently replaced with the output from the filter program.
**Here's an example using *boxes*:**
Imagine your editor (in this case, it's [Vim](http://www.vim.org/)) shows the following C code (it could be any text, of course):
<IMG SRC="{{ site.baseurl}}/images/filter1.gif" WIDTH="619" HEIGHT="272" ALT="text before filtering" />
Now you mark some of the lines ...
<IMG SRC="{{ site.baseurl}}/images/filter2.gif" WIDTH="619" HEIGHT="272" ALT="text to be filtered is marked" />
... and press the key which makes vim call the filter program *boxes*:
<IMG SRC="{{ site.baseurl}}/images/filter3.gif" WIDTH="619" HEIGHT="272" ALT="after the filter was applied" />
Voil&aacute;! The marked lines have been fed to *boxes* and replaced by the output of *boxes*. You've got yourself a box! Of course the same mechanism works for box removal - or anything else you can find a filter for. :smile:
Most major text editors support filters, among them [Vim](http://www.vim.org/), [Emacs](http://www.emacs.org/), and [Jed](http://www.jedsoft.org/jed/). There are certainly many, many more.
Please see the [installation section](install.html) in the *boxes* docs for more info on how to make your editor work with *boxes*.

48
docs/index.html
View File

@ -1,8 +1,46 @@
---
layout: default
layout: markdown
---
{% capture includedMarkdown %}{% include boxes/docs/index.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# Documentation
1. General
a. [Overview]({{ site.baseurl}}/about.html) &amp; [Features]({{ site.baseurl}}/about.html#some-of-the-features)
b. [News]({{ site.baseurl}}/)
c. [FAQ]({{ site.baseurl}}/docs/faq.html) (Frequently Asked Questions)
1. [Legal Stuff](legal.html)
1. [Examples]({{ site.baseurl}}/examples.html)
a. [Default Action]({{ site.baseurl}}/examples.html)
b. [Choosing a Different Design]({{ site.baseurl}}/examples.html#design)
c. [The &quot;<TT>-a</TT>&quot; option - Alignment, Positioning &amp; Line Justification]({{ site.baseurl}}/examples.html#position)
d. [Size Specification]({{ site.baseurl}}/examples.html#size)
e. [Padding]({{ site.baseurl}}/examples.html#padding)
f. [Regional Comments]({{ site.baseurl}}/examples.html#comments)
g. [Removal of Boxes]({{ site.baseurl}}/examples.html#removal)
h. [Indentation Handling]({{ site.baseurl}}/examples.html#indent)
i. [Use of Regular Expressions]({{ site.baseurl}}/examples.html#regexp)
1. Creating Your Own Designs
a. [Introduction and General Concepts](config-general.html)
b. [Configuration File Syntax](config-syntax.html)
c. [Step-by-Step Guide to a New Design](config-step.html)
d. [Complete examples of box designs](config-complete_exp.html)
e. [List of preconfigured designs]({{ site.baseurl}}/box-designs.txt)
1. [Text Editor Integration](install.html)
a. [Integration with Vim](install.html)
b. [Integration with Jed](install.html#jed)
c. [Integration with Emacs](install.html#emacs)
1. Development
a. [Contributing]({{ site.baseurl}}/contributing.html)
b. [List of Contributors]({{ site.baseurl}}/contributing.html#contributors)
c. [Building from Source]({{ site.baseurl}}/build.html)
d. [Testing]({{ site.baseurl}}/testing.html)
e. [Chronological Change Log](https://github.com/{{ site.github }}/commits/master)
1. [Download]({{ site.baseurl}}/download.html)
1. [*Boxes* manual page](boxes-man-1.html) (also in [troff format](https://github.com/{{ site.github }}/blob/master/doc/boxes.1.in))

122
docs/install.html
View File

@ -1,9 +1,121 @@
---
layout: default
layout: markdown
title: Editor Integration
---
{% capture includedMarkdown %}{% include boxes/docs/install.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# Text Editor Integration
This section assumes you already have a working binary of *boxes*. Binaries for some platforms can be obtained through the [download page]({{ site.baseurl}}/download.html). Should your platform be missing from the list, you can still download the source distribution and compile your own binary. This sounds harder than it is.
Although *boxes* can be useful when used on the command line, the more frequent use case will be as a filter tied to your editor. So, how can *boxes* be tied to your editor?
Example config file entries are featured so far for [Vim](http://www.vim.org/), [Jed](http://www.jedsoft.org/jed/), and [Emacs](http://www.gnu.org/software/emacs/). If you know how to to this in other editors, please drop me a line!
## Integration with Vim
To call filters from vim, you need to press `!` in visual mode or `!!` in normal mode. So the easiest way to tie in *boxes* with vim is by adding the following four lines to your *.vimrc*:
vmap ,mc !boxes -d c-cmt<CR>
nmap ,mc !!boxes -d c-cmt<CR>
vmap ,xc !boxes -d c-cmt -r<CR>
nmap ,xc !!boxes -d c-cmt -r<CR>
`<CR>` should be there literally; just paste the lines directly from your browser window. This would comment out the current line or the lines you have marked when you press `,mc` (for *make comment*). Comments can be removed in the same way by pressing `,xc`. Should you feel that `,mc` is too long a combination to type, feel free to choose a shorter one. The above example assumes you are using the standard boxes config file, which features the *c-cmt* design. Of course, the same technique works for any other designs.
While the above example is nice, it does not offer much convenience when you are editing different languages a lot, because you need to remember the hotkey for each different box design. Fortunately, vim has a feature called *autocommands*. They can be used to automatically change the meaning of a key combination depending on what file you edit (any many other things too, of course). Autocommand syntax is
au[tocmd] [group] {event} {pat} [nested] {cmd}
We can leave out the group. For `{event}`, we choose `BufEnter`, which is generated every time you enter a new buffer, e.g. when starting vim or when switching between open files. `{pat}` is a file glob, and `{cmd}` is our call to *boxes*.
The lines below are from the author's *.vimrc*. They can be pasted directly from your browser window. Their effect is that `,mc` and `,xc` always generate the correct comments for many languages, including C, C++, HTML, Java, lex, yacc, shell scripts, Perl, etc. The default key binding is to generate shell comments using a pound sign (file glob of `*` at the start).
autocmd BufEnter * nmap ,mc !!boxes -d pound-cmt<CR>
autocmd BufEnter * vmap ,mc !boxes -d pound-cmt<CR>
autocmd BufEnter * nmap ,xc !!boxes -d pound-cmt -r<CR>
autocmd BufEnter * vmap ,xc !boxes -d pound-cmt -r<CR>
autocmd BufEnter *.html nmap ,mc !!boxes -d html-cmt<CR>
autocmd BufEnter *.html vmap ,mc !boxes -d html-cmt<CR>
autocmd BufEnter *.html nmap ,xc !!boxes -d html-cmt -r<CR>
autocmd BufEnter *.html vmap ,xc !boxes -d html-cmt -r<CR>
autocmd BufEnter *.[chly],*.[pc]c nmap ,mc !!boxes -d c-cmt<CR>
autocmd BufEnter *.[chly],*.[pc]c vmap ,mc !boxes -d c-cmt<CR>
autocmd BufEnter *.[chly],*.[pc]c nmap ,xc !!boxes -d c-cmt -r<CR>
autocmd BufEnter *.[chly],*.[pc]c vmap ,xc !boxes -d c-cmt -r<CR>
autocmd BufEnter *.C,*.cpp,*.java nmap ,mc !!boxes -d java-cmt<CR>
autocmd BufEnter *.C,*.cpp,*.java vmap ,mc !boxes -d java-cmt<CR>
autocmd BufEnter *.C,*.cpp,*.java nmap ,xc !!boxes -d java-cmt -r<CR>
autocmd BufEnter *.C,*.cpp,*.java vmap ,xc !boxes -d java-cmt -r<CR>
autocmd BufEnter .vimrc*,.exrc nmap ,mc !!boxes -d vim-cmt<CR>
autocmd BufEnter .vimrc*,.exrc vmap ,mc !boxes -d vim-cmt<CR>
autocmd BufEnter .vimrc*,.exrc nmap ,xc !!boxes -d vim-cmt -r<CR>
autocmd BufEnter .vimrc*,.exrc vmap ,xc !boxes -d vim-cmt -r<CR>
<a name="jed">&nbsp;</a>
## Integration with Jed
*Andreas Heiduk* (@asheiduk) kindly provided the following excerpt from his *.jedrc*:
%!% Ripped from "pipe.sl"
variable Last_Process_Command = Null_String;
define do_process_region(cmd) {
variable tmp;
tmp = make_tmp_file ("/tmp/jedpipe");
cmd = strncat (cmd, " > ", tmp, " 2>&1", 4);
!if (dupmark ()) error ("Mark not set.");
if (pipe_region (cmd))
{
error ("Process returned a non-zero exit status.");
}
del_region ();
() = insert_file (tmp);
() = delete_file (tmp);
}
define process_region ()
{
variable cmd;
cmd = read_mini ("Pipe to command:", Last_Process_Command, "");
!if (strlen (cmd)) return;
Last_Process_Command = cmd;
do_process_region(cmd);
}
%-----------------------------------------------------------------------
if( BATCH == 0 ){
setkey("process_region", "\e|"); % ESC-Pipe :-)
add_completion("process_region");
% define some often used filters
setkey("do_process_region(\"tal\")", "\et") % tal on esc-t
}
I think it calls [tal](http://www.thomasjensen.com/software/tal/) when you press `ESC-t` (second but last line). Thus, you would have to add a similar line to call *boxes*.
<a name="emacs">&nbsp;</a>
## Integration with Emacs
[Jason L. Shiffer](mailto:jshiffer@zerotao.com) kindly submitted the following information on integrating *boxes* with Emacs:
The simple interface (only a single box style, but easy):
(defun boxes-create ()
(interactive)
(shell-command-on-region (region-beginning) (region-end) "boxes -d c-cmt2" nil 1 nil))
(defun boxes-remove ()
(interactive)
(shell-command-on-region (region-beginning) (region-end) "boxes -r -d c-cmt2" nil 1 nil))
Jason also wrote a [*boxes* mode for Emacs](boxes.el). Remember to update its design list when you add new designs to your config file.

15
docs/legal.html
View File

@ -1,9 +1,14 @@
---
layout: default
layout: markdown
title: Legal Stuff
---
{% capture includedMarkdown %}{% include boxes/docs/legal.md %}{% endcapture %}
<div class="bxpage well">
{{ includedMarkdown | markdownify }}
</div>
# Legal Terms
*Boxes* is free software under the terms of the <A TARGET="_blank" HREF="http://www.gnu.org/licenses/gpl-2.0.html#TOC1">GNU General Public License, version&nbsp;2</A> (GNU GPL), a copy of which you should have received with your source archive (filename of *COPYING* or *LICENSE*).
Among many other things, the GNU GPL states that there is **no warranty** whatsoever. If *boxes* filters away your master's thesis that's your problem! You are using the program entirely at your own risk. On the other hand, it is free. Here is an excerpt from the GNU GPL:
> **11.** Because the program is licensed free of charge, there is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.<br/>
> **12.** In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.

21
docs/releases.html
View File

@ -1,13 +1,11 @@
---
layout: default
layout: markdown
title: Release History
---
{% capture includedMarkdown %}{% include boxes/docs/releases.md %}{% endcapture %}
<div class="bxpage well">
<h1 id="release-history">Release History</h1>
# Release History
<p>So far, there were these stable releases:</p>
So far, there were these stable releases:
<table>
<thead>
@ -55,7 +53,14 @@ title: Release History
</tbody>
</table>
<p>Sources and binaries for these releases are available from the above table.</p>
Sources and binaries for these releases are available from the above table.
{{ includedMarkdown | markdownify }}
</div>
## When to upgrade
Boxes has been around a long time, and it has been very stable. Sometimes, new releases are still required to ensure that *boxes* continues to compile smoothly on a large number of platforms. Whether or not you should upgrade to a new version depends on what you've got, and what you want to do:
- **Building from Source:** If you want to [build from source]({{ site.baseurl}}/build.html), you should always use the latest sources from the above table. You may also clone the repo and build the bleeding edge. Since we have a stable master branch, this will also get you a good build, but it will be a snapshot version.
- **Using a binary:** The last bugfixes and the last functional enhancements were in version 1.1 (of 2006). So if you've got a working 1.1 binary on your system, you're good and you don't need to upgrade. Staying on the even older 1.0.1 will mean that you're missing features (such as better tab handling and the 'mend' option). Anything prior to 1.0.1 should definitely be upgraded.
Note that you can always copy the [latest box designs](https://github.com/{{ site.github }}/blob/master/boxes-config) from GitHub to replace your older *boxes-config* (Unix) or *boxes.cfg* (Windows) - the designs are backwards compatible.

2
index.html
View File

@ -3,7 +3,7 @@ layout: default
sedesc: Command line ASCII boxes unlimited!
---
{% include boxes/shortdescription.html %}
{% include shortdescription.html %}
{% for post in paginator.posts %}
<div class="article">