path: root/gramscii.1

.TH GRAMSCII 1 "28/09/2019" "" ""
.SH NAME
gramscii \- simple editor for ASCII box diagrams
.SH SYNOPSIS
.PP
gramscii
.RI [-s]
.RI [-h]
.RI [file ...]
.PP
.SH DESCRIPTION
.PP
gramscii is a simple interactive editor to create ASCII box-and-arrows
diagrams. It uses vi-like keybindings for drawing and editing boxes
(rectangles, palallelograms, trapezia, triangles), arrows, and text.
.PP
.SH OPTIONS
.TP 5m 
.BI -s
Start gramscii in script-mode. In this mode the screen is set to 25 rows
by 80 columns, no status bar is present, drawings and cursor movements
are not shown, and the state of the screen is dumped to stdout when the
program ends. With this flag, gramscii can be used in a pipeline,
getting commands from stdin (or from a file) and making its output
available for further processing.
.TP
.BI -h
Print short usage unstructions and exit.
.PP
If one or more files are provided after the last option, gramscii will
consider them command files and will read them one after the other
(i.e., as if the characters in the file were typed while gramscii was
running), before accepting commands from stdin. This allows to use
gramscii scripts. For instance, if you start gramscii as:
.EX

    gramscii file.txt

.EE
and  "file.txt" contains the lines:
.EX

    gg10lbLLJJb
    gg10l15jbLLJJ

.EE
then gramscii will show two boxes and then will start accepting
commands as usual. 
.SH COMMANDS
gramscii is a visual modal editor. Commands are associated to
keystrokes, and keystrokes have different meaning in different modes.
The default mode is 
.B move
mode, which allows the user to move the cursor around the screen.
Exiting from any other mode (either via pressing
.B [ESC] 
or by toggling the current mode) automatically puts gramscii in 
.B move
mode. There are four classes of commands in gramscii, namely
.B GENERAL, 
.B MOVEMENTS, 
.B MODES,
and
.B STYLES.
Each of those classes of commands is described in a separate subsection
below.
.SS GENERAL
General commands available in
.B move
mode:
.TP 5m
.BI C
Crop chart to the largest non-blank region. The first line and the first
column of the cropped chart will contain the first non-blank line and
the first non-blank column of the original chart, respectively.
.TP 5m
.BI e
Load (edit) an existing file from disk. gramscii asks the user if they
want to save the current screen (only if the screen has been modified
since the
last 
.BI w
command).
.TP 5m
.BI E
Load (edit) an existing file from disk, discarding any change to the
current screen.
.TP 5m
.BI M a
Mark (label) the current cursor position as 'a'. The label 'a' must be
one of the 26 ASCII alphabetic characters. The cursor can be moved to a
previously marked position using the global positioning command
.B g
(see below). Position marks are case-insensitive, meaning that both 
.I 'c'
and
.I 'C'
indicate the same mark.
.TP 5m
.BI N
Start a new empty screen. If the current screen has been modified since
the last
.BI w
command, gramscii will ask the user if they want to save the current
screen before creating a new one.
.TP 5m
.BI p
Paste the content of the yank buffer at the cursor position. The yank
buffer contains the rectangle yanked/cut in
.B visual
mode. 
.TP 5m
.BI q
Quit gramscii, and prompt for a filename if the current screen contains
unsaved changes.
.TP 5m
.BI Q
Quit gramscii and discard any change to the current screen.
.TP 5m
.BI r
Read a file at the current cursor position. gramscii will prompt for the
name of the file to read. If the first non-blank character of the name
given is a '!', gramscii will run the command specified after '!' in a
shell, and will import its standard output. 
.TP 5m
.BI R
Redraw the screen
.TP 5m
.BI u
Undo the last change. gramscii supports an undo history of indefinite
length. The command 
.BI u
gets the last change from the history, and moves the history pointer
back by one change. See the related command
.BI U
below.
.TP 5m
.BI U
Redo, i.e., cancel a previous
.BI u
command. gramscii supports an undo history of indefinite length. The
command
.BI U
moves to the following change, if possible. For instance, the sequence 
.BI uuU
will go back two changes, and then forward one, effectively resetting
the state of the screen to what it was before the last change occurred.
.TP 5m
.BI w
Write the current screen to a file. If the current screen has already
been associated to a file, use the same filename. Otherwise, the user is
prompted for a filename to save the screen to.
.TP 5m
.BI W
Write the current screen to a new file. This commands acts like
.B w
but always prompts for a file name to use. 
.TP 5m
.BI #
Start a comment. Discard all the characters until a newline is
entered. Useful to include comments in scripts.
   
.SS MOVEMENTS
The following movement commands are available in any mode where cursor
movements are meaningful, currently only 
.B move, box, arrow, parallelogram, trapezium, erase, 
and 
.B visual
(see
.B MODES
below).
.TP 5m
.BI h
move the cursor to the left by 1 column
.TP 5m
.BI j
move the cursor down by 1 row
.TP 5m
.BI k
move the cursor up by 1 row
.TP 5m
.BI l
move the cursor right by 1 column
.PP
gramscii accepts also the uppercase commands 
.B H, J, K, L, 
which will move in the corresponding direction by a LONG_STEP number of
units at a time (defaults to 5, change LONG_STEP in config.h as you
wish).
.TP 5m
.BI g
Initiate a global positioning command (go). These are two- or
three-letter commands starting with a
.BI g
and followed by a direction command, or by a character that indicates a
global position, or by a valid position mark previously defined with 
.B M
and preceded by a single quote. In particular:
.RS
.TP 5m
.BI h
move the cursor to the first column of the current row.
.TP 5m
.BI l
move the cursos to the last column of the current row.
.TP 5m
.BI j
move the cursor to the last row of the current column.
.TP 5m
.BI k
move the cursos to the first row of the current column.
.TP 5m
.BI g
move the cursor to the top-left corner of the screen
.TP 5m
.BI G
move the cursor to the bottom-right corner of the screen
.TP 5m
.BI m
move the cursor to the middle of the screen.
.TP 5m
.BI 'a
(single-quote followed by a character) move the cursor to the position
previously marked (labelled) with character
.BI 'a'
by the command
.B M
(mark). The character 'a' must be one of the 26 ASCII alphabetic
characters. Notice that position marks are case-insensitive, so the two
commands:
.B g'b
and
.B g'B
move the cursor to the position mark associated to the letter 'b', if it
exists.
.PP
If you want to move the cursor to the first row of the current
column, you could use the two-letter command 
.B gk 
(which can be read as "go-up"). Similarly, the command
.B gh
(to be read "go-left"), will move the cursor to the first column of the
current line. Notice that the command 
.B gg
is effectively equivalent to the sequence
.B ghgk
(or 
.B gkgh 
) while the command 
.B gG
is equivalent to 
.B glgj
(or
.B gjgl
).
.PP
Global positioning commands are available in 
.B box, arrow, visual, parallelogram, trapezium, 
and 
.B erase
mode. Notice that
.B gg, gG, gm 
and moves to position marks like
.B g'b, 
are not available in 
.B arrow
mode.
.PP
Typing 
.BI g
followed by any character that is not listed above has no effect on the
cursor.
.SS MULTIPLIERS
Simple cursor movement commands (hjklHJKL) can be preceded by a number
that acts as a multiplier. For instance, the command:
.PP
.RS
14h
.PP
.RE
will move the cursor by 14 steps to the left. Similarily, the command:
.PP
.RS
7J
.PP
.RE
will move the cursor by 7 LONG_STEPs rows down (with the default
LONG_STEP equal to 5, this will correspond to 35 rows down).
.PP
Multipliers can be used whenever a movement command is legal, i.e. in
move, box, arrox, parallelogram, trapezium, visual, and erase mode. So
for instance the sequence:
.RS
ggb13l18jb
.PP
.RE
will draw a 18x13 box whose top-left corner coincides with the top-left
corner of the screen.
.PP
Multipliers are ignored by global positioning commands (i.e., those
starting with 
.B g)
.SS MODES
The currently supported modes are:
.B move,
.B box,
.B parallelogram,
.B trapezium,
.B arrow,
.B erase, 
.B text,
and
.B visual.
The current mode is shown in the
status bar (see
.B STATUS BAR
below for more details). gramscii starts in 
.B move
mode (mov). The following commands are used to change mode:
.TP 7m
.BI [ESC]
Return to
.B move
mode.
.TP 7m 
.BI b 
Toggle
.B box 
mode. All movements in
.B box
mode identify a rectangular box (see
.B
MOVEMENTS
above). When you are happy with the shape of your box, just press 
.B b
again or 
.B [ENTER]
to draw the current box permanently and return to
.B move
mode. The horizontal and vertical borders of the box are drawn using
the current
.B HL
style and the current
.B VL
style, respectively. The corners are drawn using the current
.B CN
style, See
.B STYLES
below for more information. If you press
.B [ESC]
while in box mode, gramscii will return to 
.B move
mode discarding the current box.
.TP 7m
.BI z
Toggle
.B parallelogram
mode. All moves in
.B parallelogram 
mode identify the bounding box of a parallelogram (see
.B MOVEMENTS
above). By default the parallelogram leans to the right. Pressing 
.B Z
while in parallelogram mode toggles the direction towards which the
parallelogram leans. Press
.BI z
again or 
.B [ENTER]
to draw the current parallelogram and return to 
.B move
mode. If you press
.B [ESC]
while in parallelogram mode, the current parallelogram will be discarded
and gramscii will return to 
.B move
mode.
.TP 7m
.BI t
Toggle
.B trapezium
mode. All moves in
.B trapezium 
mode identify the bounding box of a trapezium (see
.B MOVEMENTS
above). A trapezium with a short horizontal side of length zero is a
triangle, and gramscii knows that. By default, the trapezium is
isosceles, with the short side up.
Pressing 
.B T
while in trapezium mode toggles the type and orientation of the
trapezium. Press
.BI t
again or 
.B [ENTER]
to draw the current trapezium and return to 
.B move
mode. If you press
.B [ESC]
while in trapezium mode, the current trapezium will be discarded
and gramscii will return to 
.B move
mode.
.TP 7m
.BI a
Toggle 
.B arrow
mode. All movements in 
.B arrow
mode change the position of the end-point of the current arrow. Press
.BI a
again or 
.B [ENTER]
to draw the current arrow and return to
.B move
mode. If you press 
.B [ESC]
while in arrow mode, gramscii will return to
.B move
mode discarding the current arrow. The horizontal and vertical segments
of the arrow are drawn using the current 
.B HL
and 
.B VL
line styles. Corners are drawn using the current
.B CN
style. Similarly, the start and the end point of the arrow are drawn
using the current
.B SP
and 
.B EP
styles. See
.B STYLES
below for more information.
.TP 7m
.BI A
Exactly as  
.BI a
toggles
.B arrow
mode, but the end point marker is automatically set according to the
direction of the arrow.  
.TP 7m
.BI x
Toggle
.B erase
mode. In erase mode, any character traversed by the cursor is erased,
i.e., reset to the default background character (space). If you press
.BI [ESC]
while in 
.BI erase
mode, the current erase operation is aborted. Press 
.B x
again or 
.B [ENTER]
to make the erase permanent and return to
.B move
mode.
.TP 7m
.BI i
Enter
.B text
mode. While in text mode, each character typed is printed on the screen
at the corresponding location, and the cursor is advanced by a single
position to the right. Movement modes are not allowed while in 
.B text
mode. By pressing
.B [ENTER]
the cursor is placed on the following row (if possible), at the same
column where the cursor was when the command
.BI i
was typed. Press 
.B [ESC]
to exit 
.B text
mode and return to 
.B move
mode.
.TP 7m
.BI v
Toggle
.B visual
mode. Visual mode allows to highlight a rectangular region of the
screen, and to perform an operation into it. After entering
.B visual
mode, you can use
.B MOVEMENTS
commands to highlight a rectangle. Then, you can use one of the
following command on the highlighted region:
.RS
.TP 5m
.BI y
Yank (copy) the highlighted rectangle to the yank buffer. The content of
the yank buffer can be retrieved by using the
.B p
command while in 
.B move
mode. The yank buffer is overwritten by subsequent yank/cut commands.
.TP 5m
.BI x
Cut region. The content of the highlighted rectangle will be put in the
yank buffer and all the characters in the region are set to the default
background character (space). The yank buffer is overwritten by
subsequent yank/cut commands.
.TP 5m
.BI f
Fill region. gramscii will wait for a character on input and then will
fill the highlighted region with that character.
.TP 5m
.BI C
Crop-to-region. Crop the chart to the content of the highlighted region.
Everything else in the screen is erased.
.TP 5m
.BI v
leave 
.B visual
mode and return to
.B move
mode.
.TP 5m
.BI [ENTER]
same as 
.BI v,
i.e., leave 
.B visual
mode and return to 
.B move
mode.
.TP 5m
.BI [ESC]
same as 
.BI v,
i.e., leave 
.B visual
mode and return to 
.B move
mode.
.RE

.SS STYLES
The style of lines, corners and markers can be changed at any time while
in 
.B move, 
.B box,
and 
.B arrow
mode. Some caveats apply to parallelogram and trapezium mode though (see
BUGS).  The following style commands are available: 
.TP 5m
.B .
(dot) Reset all styles to their default values.
.TP 5m
.BI -
(dash) Change the style used for horizontal lines. Indicated in the 
.B STATUS BAR
as "HL". Default is '-'.
.TP 5m
.BI |
(pipe) Change the style used for vertical lines. Indicated in the
.B STATUS BAR
as "VL". Default is '|'.
.TP 5m
.BI +
(plus) Change the style used for corners (i.e., intersections between
horizontal and vertical lines). Indicated in the
.B STATUS BAR
as "CN". Default is '+'.
.TP 5m
.BI <
(less-than) Change the style used for arrow start points. Indicated in
the 
.B STATUS BAR
as "SP". Default is '+'.
.TP 5m
.BI >
(greater-than) Change the style used for arrow end points. Indicated in
the 
.B STATUS BAR
as "EP". Default is '>'.
.PP
If a style command is issued in 
.B box
or 
.B arrow
mode, the new style will be applied to the box/arrow that is currently being
drawn, and will remain active until the next style command is used.

.SH STATUS BAR
Unless script-mode has been requested using option 
.RI -s,
gramscii shows a status bar on the last line of the screen. The bar
reports information about the current screen, and in particular: 
.RS
.TP 10m
x:XXX
Current column position of the cursor (the leftmost column is 0).
.TP 10m
y:YYY
Current row position of the cursor (top is 0).
.TP 10m
MODE: xxx
Current mode. It is one of 
.B mov
(move), 
.B box
(box),
.B par
(parallelogram),
.B trp
(trapezium),
.B arr
(arrow),
.B txt
(text), 
.B del
(erase), or 
.B vis
(visual).
.TP 10m
HL:x
Style used for horizontal lines.
.TP 10m
VL:x
Style used for vertical lines.
.TP 10m
CN:x
Style used for corners.
.TP 10m
SP:x
Style used for arrow starting points.
.TP 10m
EP:x
Style used for arrow end points.
.RE
.PP
The rightmost side of the status bar also reports the name of the file
associated to the current screen:
.RS
.TP 12m
[]
No file is associated to the current screen, and no changes have been
made. The command
.B w
would prompt the user for the name of the file to save the screen to.
.TP 12m
**
The screen has been changed, but there is no file associated to it. The
command 
.B w
would prompt the user for the name of the file to save the screen to.
.TP 12m
[filename]
The screen corresponds to the file "filename" and it has not been
modified since the last write on disk. The command
.B w
would automatically save the screen into "filename".
.TP 12m
*filename*
The screen is associated to the file "filename", but the current buffer
includes some changes that have not been saved to the disk. The command 
.B w
would automatically save the screen into "filename".
.RE
.SH BUGS
gramscii currently manages only a fixed screen of the same size of the
screen where it starts from. This will be changed in a future release to
support scrolling and "virtual" screens of any (reasonable) size.
.PP
It is not currently possible to change the style of the oblique sides of
a parallelogram or of a trapezium.
.PP
The trapezium routine does not handle well the case of trapezia whose 
height would yield a negative length for the small horizontal side.
Nevertheless, an exceptionally creative user might consider this a
feature, rather than a bug.
.SH AUTHORS
gramscii is written and maintained by Vincenzo "KatolaZ" Nicosia
<katolaz@freaknet.org>. You can use, copy, modify, and redistribute
gramscii under the terms of the GNU General Public License, version 3 of
the License or, at your option, any later version.