path: root/gramscii.1

.TH GRAMSCII 1 "19/07/2019" "" ""
.SH NAME
gramscii \- simple editor for ASCII box diagrams
.SH SYNOPSIS
.PP
gramscii
.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, 
arrows, and text.
.PP
.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 R
Redraw the screen
.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 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 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 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.
   
.SS MOVEMENTS
The following movement commands are available in any mode where cursor
movements are meaningful, currently only 
.B move, box, arrow, 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 5 units at a time.
.TP 5m
.BI g
Initiate a global positioning command (go). These are two-letter
commands starting with a
.BI g
and followed by a direction command or by a character that indicates a
global position, namely:
.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.
.PP
For instance, if you want to move the cursor to the first row of the
current column, you would 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
Typing 
.BI g
followed by any character that is not listed above has no effect on the
cursor.
.RE

.SS MODES
The currently supported modes are:
.B move,
.B box,
.B arrow, 
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 get back 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 come back to 
.B move
mode discarding the current box.
.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 come back to
.B move
mode. If you press 
.B [ESC]
while in box mode, gramscii will come back 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 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 get back 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 x
Erase region. All the characters in the region are set to the default
background character (space).
.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 v
leave 
.B visual
mode and get back to
.B move
mode.
.TP 5m
.BI [ENTER]
same as 
.BI v,
i.e., leave 
.B visual
mode and get back to 
.B move
mode.
.TP 5m
.BI [ESC]
same as 
.BI v,
i.e., leave 
.B visual
mode and get back 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. 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
gramscii shows a status bar on the last line of the screen. The bar
shows 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 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 25 rows by 100
columns. This will be changed in a future release to support scrolling
and "virtual" screens of any (reasonable) size.
.PP
gramscii currently does
.B not
provide an "undo" command. This requires a restructuring of buffer
management, and will most probably be implemented in a future release.
.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.