.TH GRAMSCII 1 "19/07/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, 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. .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 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 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 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-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. .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, 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 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 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 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 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 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 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 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 . 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.