summaryrefslogtreecommitdiff
path: root/gramscii.1
blob: 6c3847324a050a3130abb7374e76d20d73f7083a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
.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.