mirror of
https://github.com/ascii-boxes/boxes.git
synced 2024-12-13 18:30:39 +01:00
d48b49df33
Version number and name of global config file are now put in automatically Updates for version 1.0
291 lines
8.7 KiB
Groff
291 lines
8.7 KiB
Groff
.\" @(#)boxes.1 1.0 08/22/99
|
|
.\"
|
|
.\" $Id: boxes.1,v 1.2 1999/08/18 19:14:08 tsjensen Exp tsjensen $
|
|
.\"
|
|
.TH boxes 1 "August 22 1999"
|
|
.UC 4
|
|
.SH NAME
|
|
boxes \- text mode box and comment drawing filter
|
|
.SH SYNOPSIS
|
|
.B boxes
|
|
[-hlrv] [\-a\ format] [\-d\ design] [\-f\ file] [\-i\ indent] [\-k\ bool]
|
|
[\-p\ pad] [\-s\ size] [\-t\ tabs] [infile [outfile]]
|
|
.SH DESCRIPTION
|
|
.I boxes
|
|
is a text filter which can draw any kind of ASCII art box around its input
|
|
text. A box can also be removed, even if it has been badly damaged by
|
|
editing of the text inside. Since boxes may be open on any side,
|
|
.I boxes
|
|
can also be used to create regional comments in any programming language.
|
|
With the help of an editor macro/mapping, damaged boxes can easily be
|
|
repaired. New box designs of all sorts can easily be added and shared by
|
|
appending to a free format configuration file.
|
|
.br
|
|
.I boxes
|
|
was intended to be used with the
|
|
.I vim(1)
|
|
text editor, but can be tied to any text editor which supports filters, as
|
|
well as from the command line as a standalone tool.
|
|
.\" =======================================================================
|
|
.SH OPTIONS
|
|
Options offered by
|
|
.I boxes
|
|
are the following:
|
|
.TP 0.6i
|
|
.B -a \fIstring\fP
|
|
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
|
|
|
|
.B h\fPx
|
|
- horizontal alignment of the input text block inside a potentially larger
|
|
box. Possible values for
|
|
.I x
|
|
are
|
|
.B l
|
|
(ell, for left alignment),
|
|
.B c
|
|
(center), or
|
|
.B r
|
|
(right). This does not affect the justification of text lines within the
|
|
input text block (use the
|
|
.B j
|
|
argument instead).
|
|
.br
|
|
.B v\fPx
|
|
- vertical alignment of the input text block inside a potentially larger
|
|
box. Possible values for
|
|
.I x
|
|
are
|
|
.B t
|
|
(for top alignment),
|
|
.B c
|
|
(center), or
|
|
.B b
|
|
(bottom).
|
|
.br
|
|
.B j\fPx
|
|
- justification of lines within the input text block. Possible values for
|
|
.I x
|
|
are
|
|
.B l
|
|
(ell, for left justification),
|
|
.B c
|
|
(center), or
|
|
.B r
|
|
(right). This does not affect the alignment of the input text block itself
|
|
within the box. Use the
|
|
.B h
|
|
and
|
|
.B v
|
|
arguments for input text block positioning.
|
|
.br
|
|
|
|
Short hand notations (can be combined with the above arguments):
|
|
.br
|
|
.B l
|
|
- (ell) short for
|
|
.B h\fPl\fBv\fPc\fBj\fPl
|
|
.br
|
|
.B c
|
|
- short for
|
|
.B h\fPc\fBv\fPc\fBj\fPc
|
|
.br
|
|
.B r
|
|
- short for
|
|
.B h\fPr\fBv\fPc\fBj\fPr
|
|
.br
|
|
|
|
The factory default setting for
|
|
.B -a
|
|
is
|
|
.B h\fPl\fBv\fPt.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -d \fIstring\fP
|
|
Design selection. The one argument of this option is the name of the design to
|
|
use.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -f \fIstring\fP
|
|
Use alternate config file. The one argument of this option is the name of a
|
|
valid
|
|
.I boxes
|
|
config file, containing new and exciting designs!
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -h
|
|
Print usage information.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -i \fIstring\fP
|
|
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.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -k \fIbool\fP
|
|
Kill leading/trailing blank lines on removal. The value of
|
|
.I bool
|
|
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\fP.
|
|
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.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -l
|
|
(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\fP,
|
|
displays detailed information about the specified design.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -p \fIstring\fP
|
|
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
|
|
- (all) give padding for all sides at once
|
|
.br
|
|
.B h
|
|
- (horiz) give padding for both horizontal sides
|
|
.br
|
|
.B v
|
|
- (vertical) give padding for both vertical sides
|
|
.br
|
|
.B b
|
|
- (bottom) give padding for bottom (south) side
|
|
.br
|
|
.B l
|
|
- (left) give padding for left (west) side
|
|
.br
|
|
.B t
|
|
- (top) give padding for top (north) side
|
|
.br
|
|
.B r
|
|
- (right) give padding for right (east) side
|
|
.br
|
|
Example:
|
|
.B -p a\fP4\fBt\fP2
|
|
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.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -r
|
|
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
|
|
to specify the design. The default is to draw a new box.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -s \fIwidth\fBx\fPheight\fP
|
|
Box size. If a single number is given as argument, this defaults to the box
|
|
width. 'x', followed by a single number specifies the box height. Giving
|
|
both the box width and height is left as an exercise to the reader. :-)
|
|
The actual box size may vary depending on the individual shape sizes.
|
|
By default, the smallest possible box is created around the text.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -t \fIuint\fP
|
|
Distance between tab stops. It is important that this value is set correctly,
|
|
or tabulator characters will upset your input text. The correct value for
|
|
.B -t
|
|
depends on the settings used for the text you are processing. Usually, a
|
|
value of 8 should be okay. The factory default for
|
|
.B -t
|
|
is 8.
|
|
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
.TP 0.6i
|
|
.B -v
|
|
Print out current version number.
|
|
.\" =======================================================================
|
|
.SH CONFIGURATION FILES
|
|
.I Boxes
|
|
will use the configuration file specified on the command line (using
|
|
.B -f\fP).
|
|
If no config file is specified on the command line,
|
|
.I boxes
|
|
will check for the BOXES environment variable, which may contain a filename
|
|
to use. If BOXES is not set,
|
|
.I boxes
|
|
will try to read $HOME/.boxes and use it as a config file. Failing that,
|
|
.I boxes
|
|
will try to read the system-wide config file (see FILES).
|
|
.PP
|
|
The syntax of
|
|
.I boxes
|
|
config files is described on the Web page (see below). They are quite
|
|
self-explanatory, though.
|
|
.\" =======================================================================
|
|
.SH AVAILABILITY
|
|
.I boxes
|
|
is available from its World Wide Web home page at
|
|
http://home.pages.de/~jensen/boxes/. The Web page also features a number of
|
|
examples illustrating this manual page as well as more in-depth
|
|
documentation.
|
|
.PP
|
|
Check out the
|
|
.I vim(1)
|
|
home page at www.vim.org!
|
|
.\" =======================================================================
|
|
.SH AUTHOR
|
|
.I boxes
|
|
was made by Thomas Jensen.
|
|
.br
|
|
Please see the
|
|
.I boxes
|
|
Web page for a current email address.
|
|
.\" =======================================================================
|
|
.SH VERSION
|
|
This is
|
|
.I boxes
|
|
version --BVERSION--.
|
|
.\" =======================================================================
|
|
.SH BUGS
|
|
Although it is doing great in most cases, imho the design autodetector
|
|
needs some more work.
|
|
.br
|
|
Should you notice any other unspecified behavior, please tell the author!
|
|
.\" =======================================================================
|
|
.SH ENVIRONMENT
|
|
.TP 15
|
|
HOME
|
|
The user's home directory.
|
|
.TP 15
|
|
BOXES
|
|
Name of
|
|
.I boxes
|
|
configuration file, if different from ~/.boxes.
|
|
.\" =======================================================================
|
|
.SH FILES
|
|
.TP 15
|
|
$HOME/.boxes
|
|
.I boxes
|
|
configuration file
|
|
.TP 15
|
|
--GLOBALCONF--
|
|
system-wide configuration file
|
|
.\" =======================================================================
|
|
.SH "SEE ALSO"
|
|
.I indent(1)
|
|
,
|
|
.I tal(1)
|
|
,
|
|
.I vim(1)
|