add manpage

1 files changed, 375 insertions, 0 deletions

diff --git a/gramscii.1 b/gramscii.1
new file mode 100644
index 0000000..75d26a8
--- /dev/null
+++ b/gramscii.1
@@ -0,0 +1,375 @@
+.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 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 modifided
+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 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 cursos up by 1 row
+.TP 5m
+.BI l
+move the cursos 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.  In
+addition to the relative movement command above, the following global
+positioning commands are available:
+.TP 5m
+.BI g
+move the cursor to the top-left corner of the screen
+.TP 5m
+.BI G
+move the cursos to the bottom-right corner of the screen
+.TP 5m
+.BI m
+move the cursos to the middle of the screen.
+.PP
+Movements command work in the same way in different modes.
+
+.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 to have your box drawn and come 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 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 to make the erase permanent.
+.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 whilt 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 [ESC]
+same as 
+.BI v,
+i.e., leave 
+.B visual
+mode and get back to 
+.B move
+mode.
+.RE
+
+.SS STYLES
+The following commands can be used to  customise the style of lines,
+corners, and arrow start and end points:
+.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) Chamge 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 '>'.
+
+.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" screen 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.