gramscii.1 - gramscii - A simple editor for ASCII box-and-arrow charts
DIR Log
DIR Files
DIR Refs
DIR Tags
DIR README
DIR LICENSE
---
gramscii.1 (16676B)
---
1 .TH GRAMSCII 1 "28/09/2019" "" ""
2 .SH NAME
3 gramscii \- simple editor for ASCII box diagrams
4 .SH SYNOPSIS
5 .PP
6 gramscii
7 .RI [-s]
8 .RI [-h]
9 .RI [file ...]
10 .PP
11 .SH DESCRIPTION
12 .PP
13 gramscii is a simple interactive editor to create ASCII box-and-arrows
14 diagrams. It uses vi-like keybindings for drawing and editing boxes
15 (rectangles, palallelograms, trapezia, triangles), arrows, and text.
16 .PP
17 .SH OPTIONS
18 .TP 5m
19 .BI -s
20 Start gramscii in script-mode. In this mode the screen is set to 25 rows
21 by 80 columns, no status bar is present, drawings and cursor movements
22 are not shown, and the state of the screen is dumped to stdout when the
23 program ends. With this flag, gramscii can be used in a pipeline,
24 getting commands from stdin (or from a file) and making its output
25 available for further processing.
26 .TP
27 .BI -h
28 Print short usage unstructions and exit.
29 .PP
30 If one or more files are provided after the last option, gramscii will
31 consider them command files and will read them one after the other
32 (i.e., as if the characters in the file were typed while gramscii was
33 running), before accepting commands from stdin. This allows to use
34 gramscii scripts. For instance, if you start gramscii as:
35 .EX
36
37 gramscii file.txt
38
39 .EE
40 and "file.txt" contains the lines:
41 .EX
42
43 gg10lbLLJJb
44 gg10l15jbLLJJ
45
46 .EE
47 then gramscii will show two boxes and then will start accepting
48 commands as usual.
49 .SH COMMANDS
50 gramscii is a visual modal editor. Commands are associated to
51 keystrokes, and keystrokes have different meaning in different modes.
52 The default mode is
53 .B move
54 mode, which allows the user to move the cursor around the screen.
55 Exiting from any other mode (either via pressing
56 .B [ESC]
57 or by toggling the current mode) automatically puts gramscii in
58 .B move
59 mode. There are four classes of commands in gramscii, namely
60 .B GENERAL,
61 .B MOVEMENTS,
62 .B MODES,
63 and
64 .B STYLES.
65 Each of those classes of commands is described in a separate subsection
66 below.
67 .SS GENERAL
68 General commands available in
69 .B move
70 mode:
71 .TP 5m
72 .BI C
73 Crop chart to the largest non-blank region. The first line and the first
74 column of the cropped chart will contain the first non-blank line and
75 the first non-blank column of the original chart, respectively.
76 .TP 5m
77 .BI e
78 Load (edit) an existing file from disk. gramscii asks the user if they
79 want to save the current screen (only if the screen has been modified
80 since the
81 last
82 .BI w
83 command).
84 .TP 5m
85 .BI E
86 Load (edit) an existing file from disk, discarding any change to the
87 current screen.
88 .TP 5m
89 .BI M a
90 Mark (label) the current cursor position as 'a'. The label 'a' must be
91 one of the 26 ASCII alphabetic characters. The cursor can be moved to a
92 previously marked position using the global positioning command
93 .B g
94 (see below). Position marks are case-insensitive, meaning that both
95 .I 'c'
96 and
97 .I 'C'
98 indicate the same mark.
99 .TP 5m
100 .BI N
101 Start a new empty screen. If the current screen has been modified since
102 the last
103 .BI w
104 command, gramscii will ask the user if they want to save the current
105 screen before creating a new one.
106 .TP 5m
107 .BI p
108 Paste the content of the yank buffer at the cursor position. The yank
109 buffer contains the rectangle yanked/cut in
110 .B visual
111 mode.
112 .TP 5m
113 .BI q
114 Quit gramscii, and prompt for a filename if the current screen contains
115 unsaved changes.
116 .TP 5m
117 .BI Q
118 Quit gramscii and discard any change to the current screen.
119 .TP 5m
120 .BI r
121 Read a file at the current cursor position. gramscii will prompt for the
122 name of the file to read. If the first non-blank character of the name
123 given is a '!', gramscii will run the command specified after '!' in a
124 shell, and will import its standard output.
125 .TP 5m
126 .BI R
127 Redraw the screen
128 .TP 5m
129 .BI u
130 Undo the last change. gramscii supports an undo history of indefinite
131 length. The command
132 .BI u
133 gets the last change from the history, and moves the history pointer
134 back by one change. See the related command
135 .BI U
136 below.
137 .TP 5m
138 .BI U
139 Redo, i.e., cancel a previous
140 .BI u
141 command. gramscii supports an undo history of indefinite length. The
142 command
143 .BI U
144 moves to the following change, if possible. For instance, the sequence
145 .BI uuU
146 will go back two changes, and then forward one, effectively resetting
147 the state of the screen to what it was before the last change occurred.
148 .TP 5m
149 .BI w
150 Write the current screen to a file. If the current screen has already
151 been associated to a file, use the same filename. Otherwise, the user is
152 prompted for a filename to save the screen to.
153 .TP 5m
154 .BI W
155 Write the current screen to a new file. This commands acts like
156 .B w
157 but always prompts for a file name to use.
158 .TP 5m
159 .BI #
160 Start a comment. Discard all the characters until a newline is
161 entered. Useful to include comments in scripts.
162
163 .SS MOVEMENTS
164 The following movement commands are available in any mode where cursor
165 movements are meaningful, currently only
166 .B move, box, arrow, parallelogram, trapezium, erase,
167 and
168 .B visual
169 (see
170 .B MODES
171 below).
172 .TP 5m
173 .BI h
174 move the cursor to the left by 1 column
175 .TP 5m
176 .BI j
177 move the cursor down by 1 row
178 .TP 5m
179 .BI k
180 move the cursor up by 1 row
181 .TP 5m
182 .BI l
183 move the cursor right by 1 column
184 .PP
185 gramscii accepts also the uppercase commands
186 .B H, J, K, L,
187 which will move in the corresponding direction by a LONG_STEP number of
188 units at a time (defaults to 5, change LONG_STEP in config.h as you
189 wish).
190 .TP 5m
191 .BI g
192 Initiate a global positioning command (go). These are two- or
193 three-letter commands starting with a
194 .BI g
195 and followed by a direction command, or by a character that indicates a
196 global position, or by a valid position mark previously defined with
197 .B M
198 and preceded by a single quote. In particular:
199 .RS
200 .TP 5m
201 .BI h
202 move the cursor to the first column of the current row.
203 .TP 5m
204 .BI l
205 move the cursos to the last column of the current row.
206 .TP 5m
207 .BI j
208 move the cursor to the last row of the current column.
209 .TP 5m
210 .BI k
211 move the cursos to the first row of the current column.
212 .TP 5m
213 .BI g
214 move the cursor to the top-left corner of the screen
215 .TP 5m
216 .BI G
217 move the cursor to the bottom-right corner of the screen
218 .TP 5m
219 .BI m
220 move the cursor to the middle of the screen.
221 .TP 5m
222 .BI 'a
223 (single-quote followed by a character) move the cursor to the position
224 previously marked (labelled) with character
225 .BI 'a'
226 by the command
227 .B M
228 (mark). The character 'a' must be one of the 26 ASCII alphabetic
229 characters. Notice that position marks are case-insensitive, so the two
230 commands:
231 .B g'b
232 and
233 .B g'B
234 move the cursor to the position mark associated to the letter 'b', if it
235 exists.
236 .PP
237 If you want to move the cursor to the first row of the current
238 column, you could use the two-letter command
239 .B gk
240 (which can be read as "go-up"). Similarly, the command
241 .B gh
242 (to be read "go-left"), will move the cursor to the first column of the
243 current line. Notice that the command
244 .B gg
245 is effectively equivalent to the sequence
246 .B ghgk
247 (or
248 .B gkgh
249 ) while the command
250 .B gG
251 is equivalent to
252 .B glgj
253 (or
254 .B gjgl
255 ).
256 .PP
257 Global positioning commands are available in
258 .B box, arrow, visual, parallelogram, trapezium,
259 and
260 .B erase
261 mode. Notice that
262 .B gg, gG, gm
263 and moves to position marks like
264 .B g'b,
265 are not available in
266 .B arrow
267 mode.
268 .PP
269 Typing
270 .BI g
271 followed by any character that is not listed above has no effect on the
272 cursor.
273 .SS MULTIPLIERS
274 Simple cursor movement commands (hjklHJKL) can be preceded by a number
275 that acts as a multiplier. For instance, the command:
276 .PP
277 .RS
278 14h
279 .PP
280 .RE
281 will move the cursor by 14 steps to the left. Similarily, the command:
282 .PP
283 .RS
284 7J
285 .PP
286 .RE
287 will move the cursor by 7 LONG_STEPs rows down (with the default
288 LONG_STEP equal to 5, this will correspond to 35 rows down).
289 .PP
290 Multipliers can be used whenever a movement command is legal, i.e. in
291 move, box, arrox, parallelogram, trapezium, visual, and erase mode. So
292 for instance the sequence:
293 .RS
294 ggb13l18jb
295 .PP
296 .RE
297 will draw a 18x13 box whose top-left corner coincides with the top-left
298 corner of the screen.
299 .PP
300 Multipliers are ignored by global positioning commands (i.e., those
301 starting with
302 .B g)
303 .SS MODES
304 The currently supported modes are:
305 .B move,
306 .B box,
307 .B parallelogram,
308 .B trapezium,
309 .B arrow,
310 .B erase,
311 .B text,
312 and
313 .B visual.
314 The current mode is shown in the
315 status bar (see
316 .B STATUS BAR
317 below for more details). gramscii starts in
318 .B move
319 mode (mov). The following commands are used to change mode:
320 .TP 7m
321 .BI [ESC]
322 Return to
323 .B move
324 mode.
325 .TP 7m
326 .BI b
327 Toggle
328 .B box
329 mode. All movements in
330 .B box
331 mode identify a rectangular box (see
332 .B
333 MOVEMENTS
334 above). When you are happy with the shape of your box, just press
335 .B b
336 again or
337 .B [ENTER]
338 to draw the current box permanently and return to
339 .B move
340 mode. The horizontal and vertical borders of the box are drawn using
341 the current
342 .B HL
343 style and the current
344 .B VL
345 style, respectively. The corners are drawn using the current
346 .B CN
347 style, See
348 .B STYLES
349 below for more information. If you press
350 .B [ESC]
351 while in box mode, gramscii will return to
352 .B move
353 mode discarding the current box.
354 .TP 7m
355 .BI z
356 Toggle
357 .B parallelogram
358 mode. All moves in
359 .B parallelogram
360 mode identify the bounding box of a parallelogram (see
361 .B MOVEMENTS
362 above). By default the parallelogram leans to the right. Pressing
363 .B Z
364 while in parallelogram mode toggles the direction towards which the
365 parallelogram leans. Press
366 .BI z
367 again or
368 .B [ENTER]
369 to draw the current parallelogram and return to
370 .B move
371 mode. If you press
372 .B [ESC]
373 while in parallelogram mode, the current parallelogram will be discarded
374 and gramscii will return to
375 .B move
376 mode.
377 .TP 7m
378 .BI t
379 Toggle
380 .B trapezium
381 mode. All moves in
382 .B trapezium
383 mode identify the bounding box of a trapezium (see
384 .B MOVEMENTS
385 above). A trapezium with a short horizontal side of length zero is a
386 triangle, and gramscii knows that. By default, the trapezium is
387 isosceles, with the short side up.
388 Pressing
389 .B T
390 while in trapezium mode toggles the type and orientation of the
391 trapezium. Press
392 .BI t
393 again or
394 .B [ENTER]
395 to draw the current trapezium and return to
396 .B move
397 mode. If you press
398 .B [ESC]
399 while in trapezium mode, the current trapezium will be discarded
400 and gramscii will return to
401 .B move
402 mode.
403 .TP 7m
404 .BI a
405 Toggle
406 .B arrow
407 mode. All movements in
408 .B arrow
409 mode change the position of the end-point of the current arrow. Press
410 .BI a
411 again or
412 .B [ENTER]
413 to draw the current arrow and return to
414 .B move
415 mode. If you press
416 .B [ESC]
417 while in arrow mode, gramscii will return to
418 .B move
419 mode discarding the current arrow. The horizontal and vertical segments
420 of the arrow are drawn using the current
421 .B HL
422 and
423 .B VL
424 line styles. Corners are drawn using the current
425 .B CN
426 style. Similarly, the start and the end point of the arrow are drawn
427 using the current
428 .B SP
429 and
430 .B EP
431 styles. See
432 .B STYLES
433 below for more information.
434 .TP 7m
435 .BI A
436 Exactly as
437 .BI a
438 toggles
439 .B arrow
440 mode, but the end point marker is automatically set according to the
441 direction of the arrow.
442 .TP 7m
443 .BI x
444 Toggle
445 .B erase
446 mode. In erase mode, any character traversed by the cursor is erased,
447 i.e., reset to the default background character (space). If you press
448 .BI [ESC]
449 while in
450 .BI erase
451 mode, the current erase operation is aborted. Press
452 .B x
453 again or
454 .B [ENTER]
455 to make the erase permanent and return to
456 .B move
457 mode.
458 .TP 7m
459 .BI i
460 Enter
461 .B text
462 mode. While in text mode, each character typed is printed on the screen
463 at the corresponding location, and the cursor is advanced by a single
464 position to the right. Movement modes are not allowed while in
465 .B text
466 mode. By pressing
467 .B [ENTER]
468 the cursor is placed on the following row (if possible), at the same
469 column where the cursor was when the command
470 .BI i
471 was typed. Press
472 .B [ESC]
473 to exit
474 .B text
475 mode and return to
476 .B move
477 mode.
478 .TP 7m
479 .BI v
480 Toggle
481 .B visual
482 mode. Visual mode allows to highlight a rectangular region of the
483 screen, and to perform an operation into it. After entering
484 .B visual
485 mode, you can use
486 .B MOVEMENTS
487 commands to highlight a rectangle. Then, you can use one of the
488 following command on the highlighted region:
489 .RS
490 .TP 5m
491 .BI y
492 Yank (copy) the highlighted rectangle to the yank buffer. The content of
493 the yank buffer can be retrieved by using the
494 .B p
495 command while in
496 .B move
497 mode. The yank buffer is overwritten by subsequent yank/cut commands.
498 .TP 5m
499 .BI x
500 Cut region. The content of the highlighted rectangle will be put in the
501 yank buffer and all the characters in the region are set to the default
502 background character (space). The yank buffer is overwritten by
503 subsequent yank/cut commands.
504 .TP 5m
505 .BI f
506 Fill region. gramscii will wait for a character on input and then will
507 fill the highlighted region with that character.
508 .TP 5m
509 .BI C
510 Crop-to-region. Crop the chart to the content of the highlighted region.
511 Everything else in the screen is erased.
512 .TP 5m
513 .BI v
514 leave
515 .B visual
516 mode and return to
517 .B move
518 mode.
519 .TP 5m
520 .BI [ENTER]
521 same as
522 .BI v,
523 i.e., leave
524 .B visual
525 mode and return to
526 .B move
527 mode.
528 .TP 5m
529 .BI [ESC]
530 same as
531 .BI v,
532 i.e., leave
533 .B visual
534 mode and return to
535 .B move
536 mode.
537 .RE
538
539 .SS STYLES
540 The style of lines, corners and markers can be changed at any time while
541 in
542 .B move,
543 .B box,
544 and
545 .B arrow
546 mode. Some caveats apply to parallelogram and trapezium mode though (see
547 BUGS). The following style commands are available:
548 .TP 5m
549 .B .
550 (dot) Reset all styles to their default values.
551 .TP 5m
552 .BI -
553 (dash) Change the style used for horizontal lines. Indicated in the
554 .B STATUS BAR
555 as "HL". Default is '-'.
556 .TP 5m
557 .BI |
558 (pipe) Change the style used for vertical lines. Indicated in the
559 .B STATUS BAR
560 as "VL". Default is '|'.
561 .TP 5m
562 .BI +
563 (plus) Change the style used for corners (i.e., intersections between
564 horizontal and vertical lines). Indicated in the
565 .B STATUS BAR
566 as "CN". Default is '+'.
567 .TP 5m
568 .BI <
569 (less-than) Change the style used for arrow start points. Indicated in
570 the
571 .B STATUS BAR
572 as "SP". Default is '+'.
573 .TP 5m
574 .BI >
575 (greater-than) Change the style used for arrow end points. Indicated in
576 the
577 .B STATUS BAR
578 as "EP". Default is '>'.
579 .PP
580 If a style command is issued in
581 .B box
582 or
583 .B arrow
584 mode, the new style will be applied to the box/arrow that is currently being
585 drawn, and will remain active until the next style command is used.
586
587 .SH STATUS BAR
588 Unless script-mode has been requested using option
589 .RI -s,
590 gramscii shows a status bar on the last line of the screen. The bar
591 reports information about the current screen, and in particular:
592 .RS
593 .TP 10m
594 x:XXX
595 Current column position of the cursor (the leftmost column is 0).
596 .TP 10m
597 y:YYY
598 Current row position of the cursor (top is 0).
599 .TP 10m
600 MODE: xxx
601 Current mode. It is one of
602 .B mov
603 (move),
604 .B box
605 (box),
606 .B par
607 (parallelogram),
608 .B trp
609 (trapezium),
610 .B arr
611 (arrow),
612 .B txt
613 (text),
614 .B del
615 (erase), or
616 .B vis
617 (visual).
618 .TP 10m
619 HL:x
620 Style used for horizontal lines.
621 .TP 10m
622 VL:x
623 Style used for vertical lines.
624 .TP 10m
625 CN:x
626 Style used for corners.
627 .TP 10m
628 SP:x
629 Style used for arrow starting points.
630 .TP 10m
631 EP:x
632 Style used for arrow end points.
633 .RE
634 .PP
635 The rightmost side of the status bar also reports the name of the file
636 associated to the current screen:
637 .RS
638 .TP 12m
639 []
640 No file is associated to the current screen, and no changes have been
641 made. The command
642 .B w
643 would prompt the user for the name of the file to save the screen to.
644 .TP 12m
645 **
646 The screen has been changed, but there is no file associated to it. The
647 command
648 .B w
649 would prompt the user for the name of the file to save the screen to.
650 .TP 12m
651 [filename]
652 The screen corresponds to the file "filename" and it has not been
653 modified since the last write on disk. The command
654 .B w
655 would automatically save the screen into "filename".
656 .TP 12m
657 *filename*
658 The screen is associated to the file "filename", but the current buffer
659 includes some changes that have not been saved to the disk. The command
660 .B w
661 would automatically save the screen into "filename".
662 .RE
663 .SH BUGS
664 gramscii currently manages only a fixed screen of the same size of the
665 screen where it starts from. This will be changed in a future release to
666 support scrolling and "virtual" screens of any (reasonable) size.
667 .PP
668 It is not currently possible to change the style of the oblique sides of
669 a parallelogram or of a trapezium.
670 .PP
671 The trapezium routine does not handle well the case of trapezia whose
672 height would yield a negative length for the small horizontal side.
673 Nevertheless, an exceptionally creative user might consider this a
674 feature, rather than a bug.
675 .SH AUTHORS
676 gramscii is written and maintained by Vincenzo "KatolaZ" Nicosia
677 <katolaz@freaknet.org>. You can use, copy, modify, and redistribute
678 gramscii under the terms of the GNU General Public License, version 3 of
679 the License or, at your option, any later version.