mirror of
https://github.com/ascii-boxes/boxes.git
synced 2025-02-02 10:59:15 +01:00
517 lines
11 KiB
HTML
517 lines
11 KiB
HTML
---
|
|
layout: default
|
|
title: Manpage of boxes(1)
|
|
---
|
|
|
|
<div class="well bxpage">
|
|
<H1>boxes</H1>
|
|
Section: User Commands (1)<BR>Updated: October 19 2012<BR>
|
|
[ <A HREF="#index">Index</A> | <A HREF="index.html">Return to Main Contents</A> ]
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
boxes - text mode box and comment drawing filter
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>boxes</B>
|
|
|
|
[-hlmrv] [-a format] [-d design] [-f file] [-i indent] [-k bool]
|
|
[-p pad] [-s size] [-t tabopts] [infile [outfile]]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<I>Boxes</I>
|
|
|
|
is a text filter which can draw any kind of box around its input text. Box
|
|
design choices range from simple boxes to complex ASCII art. A box can also
|
|
be removed and repaired, even if it has been badly damaged by editing of the
|
|
text inside. Since boxes may be open on any side,
|
|
<I>boxes</I>
|
|
|
|
can also be used to create regional comments in any programming language.
|
|
New box designs of all sorts can easily be added and shared by appending to
|
|
a free format configuration file.
|
|
<BR>
|
|
|
|
<I>boxes</I>
|
|
|
|
was originally intended to be used with the <I>vim(1)</I>
|
|
text editor, but it can be tied to any text editor which supports filters,
|
|
as well as called from the command line as a standalone tool.
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
Options offered by <I>boxes</I> are the following:
|
|
|
|
<DL COMPACT>
|
|
<DT><B>-a </B><I>string</I>
|
|
|
|
<DD>
|
|
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:
|
|
<BR>
|
|
|
|
<P>
|
|
<B>h</B>x
|
|
|
|
- horizontal alignment of the input text block inside a potentially larger
|
|
box. Possible values for
|
|
<I>x</I>
|
|
|
|
are
|
|
<B>l</B>
|
|
|
|
(ell, for left alignment),
|
|
<B>c</B>
|
|
|
|
(center), or
|
|
<B>r</B>
|
|
|
|
(right). This does not affect the justification of text lines within the
|
|
input text block (use the
|
|
<B>j</B>
|
|
|
|
argument instead).
|
|
<BR>
|
|
|
|
<B>v</B>x
|
|
|
|
- vertical alignment of the input text block inside a potentially larger
|
|
box. Possible values for
|
|
<I>x</I>
|
|
|
|
are
|
|
<B>t</B>
|
|
|
|
(for top alignment),
|
|
<B>c</B>
|
|
|
|
(center), or
|
|
<B>b</B>
|
|
|
|
(bottom).
|
|
<BR>
|
|
|
|
<B>j</B>x
|
|
|
|
- justification of lines within the input text block. Possible values for
|
|
<I>x</I>
|
|
|
|
are
|
|
<B>l</B>
|
|
|
|
(ell, for left justification),
|
|
<B>c</B>
|
|
|
|
(center), or
|
|
<B>r</B>
|
|
|
|
(right). This does not affect the alignment of the input text block itself
|
|
within the box. Use the
|
|
<B>h</B>
|
|
|
|
and
|
|
<B>v</B>
|
|
|
|
arguments for input text block positioning.
|
|
<BR>
|
|
|
|
<P>
|
|
Short hand notations (can be combined with the above arguments):
|
|
<BR>
|
|
|
|
<B>l</B>
|
|
|
|
(ell) - short for
|
|
<B>h</B>l<B>v</B>c<B>j</B>l
|
|
|
|
<BR>
|
|
|
|
<B>c</B>
|
|
|
|
- short for
|
|
<B>h</B>c<B>v</B>c<B>j</B>c
|
|
|
|
<BR>
|
|
|
|
<B>r</B>
|
|
|
|
- short for
|
|
<B>h</B>r<B>v</B>c<B>j</B>r
|
|
|
|
<BR>
|
|
|
|
<P>
|
|
The factory default setting for
|
|
<B>-a</B>
|
|
|
|
is
|
|
<B>h</B>l<B>v</B>t.
|
|
|
|
|
|
<DT><B>-c </B><I>string</I>
|
|
|
|
<DD>
|
|
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
|
|
<B>-c</B>
|
|
|
|
option is intended as a shortcut for those cases where simple regional
|
|
comments are to be created, which only need a certain character or sequence
|
|
of characters to be placed in front of every line. In such cases, it is
|
|
much more convenient to simply specify
|
|
<B>-c</B>
|
|
|
|
than to do a complete design definition in one's config file, where the
|
|
only shape defined is the west shape.
|
|
<BR>
|
|
|
|
This option implies a
|
|
<B>-d</B>
|
|
|
|
and does not access the config file.
|
|
<B>-c</B>
|
|
|
|
may of course be used in conjunction with any of the other options. By default,
|
|
<B>-c</B>
|
|
|
|
is not specified.
|
|
|
|
<DT><B>-d </B><I>string</I>
|
|
|
|
<DD>
|
|
Design selection. The one argument of this option is the name of the design to
|
|
use.
|
|
|
|
<DT><B>-f </B><I>string</I>
|
|
|
|
<DD>
|
|
Use alternate config file. The one argument of this option is the name of a
|
|
valid
|
|
<I>boxes</I>
|
|
|
|
config file, containing new and exciting designs!
|
|
|
|
<DT><B>-h</B>
|
|
|
|
<DD>
|
|
Print usage information.
|
|
|
|
<DT><B>-i </B><I>string</I>
|
|
|
|
<DD>
|
|
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 to indent the
|
|
box, but not the text.
|
|
|
|
<DT><B>-k </B><I>bool</I>
|
|
|
|
<DD>
|
|
Kill leading/trailing blank lines on removal. The value of
|
|
<I>bool</I>
|
|
|
|
can be specified as on, yes, true, 1, or t, all meaning yes, or off, no,
|
|
false, 0, or f, which mean no. This is case-insensitive. This option only
|
|
takes effect in connection with
|
|
<B>-r</B>.
|
|
|
|
If set to yes, leading and trailing blank lines will be removed from the
|
|
output. If set to no, the entire content of the former box is returned.
|
|
The default is no, 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 yes.
|
|
|
|
<DT><B>-l</B>
|
|
|
|
<DD>
|
|
(ell) List designs. Produces a listing of all available box designs in the
|
|
config file, along with a sample box and information about it's creator.
|
|
Also checks syntax of the entire config file. If used in connection with
|
|
<B>-d</B>,
|
|
|
|
displays detailed information about the specified design.
|
|
|
|
<DT><B>-m</B>
|
|
|
|
<DD>
|
|
Mend box. This removes a (potentially broken) box as with
|
|
<B>-r</B>,
|
|
|
|
and redraws it afterwards. The mended box is drawn according to the
|
|
options given. This may be important to know when it comes to restoring
|
|
padding, identation, etc. for the mended box. Implies
|
|
<B>-k</B>
|
|
|
|
false.
|
|
|
|
<DT><B>-p </B><I>string</I>
|
|
|
|
<DD>
|
|
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:
|
|
<BR>
|
|
|
|
<B>a</B>
|
|
|
|
- (all) give padding for all sides at once
|
|
<BR>
|
|
|
|
<B>h</B>
|
|
|
|
- (horiz) give padding for both horizontal sides
|
|
<BR>
|
|
|
|
<B>v</B>
|
|
|
|
- (vertical) give padding for both vertical sides
|
|
<BR>
|
|
|
|
<B>b</B>
|
|
|
|
- (bottom) give padding for bottom (south) side
|
|
<BR>
|
|
|
|
<B>l</B>
|
|
|
|
- (left) give padding for left (west) side
|
|
<BR>
|
|
|
|
<B>t</B>
|
|
|
|
- (top) give padding for top (north) side
|
|
<BR>
|
|
|
|
<B>r</B>
|
|
|
|
- (right) give padding for right (east) side
|
|
<BR>
|
|
|
|
Example:
|
|
<B>-p a</B>4<B>t</B>2
|
|
|
|
would define the padding to be 4 characters on all sides, except for the
|
|
top of the box, where the input text block will be only 2 lines away from
|
|
the box.
|
|
<BR>
|
|
|
|
By default, unless specified otherwise in the config file, no padding is
|
|
used.
|
|
|
|
<DT><B>-r</B>
|
|
|
|
<DD>
|
|
Remove box. Removes an existing box instead of drawing it. Which design to
|
|
use is detected automatically. In order to save time or in case the
|
|
detection does not decide correctly, combine with
|
|
<B>-d</B>
|
|
|
|
to specify the design. The default is to draw a new box.
|
|
|
|
<DT><B>-s </B><I>width</I><B>x</B>height
|
|
|
|
<DD>
|
|
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
|
|
<B>-p</B>).
|
|
|
|
<BR>
|
|
|
|
By default, the smallest possible box is created around the text.
|
|
|
|
<DT><B>-t </B><I>string</I>
|
|
|
|
<DD>
|
|
Tab handling. This option controls how tab characters in the input text are
|
|
handled. The option string must always begin with a
|
|
<I>uint</I>
|
|
|
|
number indicating the distance between tab stops. It is important that this
|
|
value be set correctly, or tabulator characters will upset your input text.
|
|
The correct tab distance value depends on the settings used for the text
|
|
you are processing. A common value is 8.
|
|
<BR>
|
|
|
|
Immediately following the tab distance, an optional character can be appended,
|
|
telling
|
|
<I>boxes</I>
|
|
|
|
how to treat the leading tabs. The following options are available:
|
|
<BR>
|
|
|
|
<B>e</B>
|
|
|
|
- expand tabs into spaces
|
|
<BR>
|
|
|
|
<B>k</B>
|
|
|
|
- keep tabs as close to what they were as possible
|
|
<BR>
|
|
|
|
<B>u</B>
|
|
|
|
- unexpand tabs. This makes
|
|
<I>boxes</I>
|
|
|
|
turn as many spaces as possible into tabs.
|
|
<BR>
|
|
|
|
<P>
|
|
In order to maintain backwards compatibility, the
|
|
<B>-t</B>
|
|
|
|
<I>string</I>
|
|
|
|
can be just a number. In that case,
|
|
<B>e</B>
|
|
|
|
is assumed for tab handling, which removes all tabs and replaces them with
|
|
spaces. The factory default for the
|
|
<B>-t</B>
|
|
|
|
option is simply 8, which is just such a case.
|
|
<BR>
|
|
|
|
For example, you could specify
|
|
<B>-t </B>4u
|
|
|
|
in order to have your leading tabs unexpanded. In the box content, tabs are
|
|
always converted into spaces. The tab distance in this example is 4.
|
|
|
|
<DT><B>-v</B>
|
|
<DD>
|
|
Print out current version number.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>CONFIGURATION FILES</H2>
|
|
|
|
<I>Boxes</I>
|
|
|
|
will use the configuration file specified on the command line (using
|
|
<B>-f</B>).
|
|
|
|
If no config file is specified on the command line,
|
|
<I>boxes</I>
|
|
|
|
will check for the BOXES environment variable, which may contain a filename
|
|
to use. If BOXES is not set,
|
|
<I>boxes</I>
|
|
|
|
will try to read $HOME/.boxes and use it as a config file. Failing that,
|
|
<I>boxes</I>
|
|
|
|
will try to read the system-wide config file (see FILES).
|
|
<P>
|
|
|
|
The syntax of
|
|
<I>boxes</I>
|
|
|
|
config files is described on the website (see below). They are quite
|
|
self-explanatory, though.
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
<I>Boxes</I>
|
|
|
|
is available from its website at
|
|
<A HREF="http://boxes.thomasjensen.com/">http://boxes.thomasjensen.com/</A>.
|
|
The website also features a number
|
|
of examples illustrating this manual page as well as more in-depth
|
|
documentation.
|
|
<P>
|
|
|
|
Check out <I>vim(1)</I>
|
|
at <A HREF="http://www.vim.org/" target="_blank">vim.org</A>!
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
<I>Boxes</I>
|
|
|
|
was made by Thomas Jensen < boxes at thomasjensen dot com >.
|
|
<BR>
|
|
|
|
Please see the <I>boxes</I> website for the most current email address.
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
This is <I>boxes</I> version 1.1.1.
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
Although it is doing fine in most cases, imho the design autodetector
|
|
needs some more work.
|
|
<BR>
|
|
|
|
Should you notice any other unspecified behavior, please tell the author!
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
<I>Boxes</I>
|
|
|
|
recognizes the following environment variables:
|
|
<DL COMPACT>
|
|
<DT>HOME<DD>
|
|
The user's home directory.
|
|
<DT>BOXES<DD>
|
|
Name of
|
|
<I>boxes</I>
|
|
configuration file, if different from <tt>~/.boxes</tt>.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT>$HOME/.boxes<DD>
|
|
<I>boxes</I>
|
|
|
|
configuration file
|
|
<DT>/usr/share/boxes<DD>
|
|
system-wide configuration file
|
|
|
|
</DL>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT><A HREF="#lbAB">NAME</A><DD>
|
|
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT><A HREF="#lbAF">CONFIGURATION FILES</A><DD>
|
|
<DT><A HREF="#lbAG">AVAILABILITY</A><DD>
|
|
<DT><A HREF="#lbAH">AUTHOR</A><DD>
|
|
<DT><A HREF="#lbAI">VERSION</A><DD>
|
|
<DT><A HREF="#lbAJ">BUGS</A><DD>
|
|
<DT><A HREF="#lbAK">ENVIRONMENT</A><DD>
|
|
<DT><A HREF="#lbAL">FILES</A><DD>
|
|
<DT><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
</DL>
|
|
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="http://users.actrix.gen.nz/michael/vhman2html.html" target="_blank">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 20:07:24 GMT, October 19, 2012<br/>
|
|
Page created April 06, 1999, last touched: 19-Oct-2012.
|
|
|
|
</div>
|