commit 4b2801f07dbfc124f04ab0aeaf05ee36f9e1f836
parent 7960e435bff5c425f81274ab0058b443575cb574
Author: lumidify <nobody@lumidify.org>
Date: Sat, 25 Dec 2021 11:54:42 +0100
Improve documentation
Diffstat:
4 files changed, 139 insertions(+), 28 deletions(-)
diff --git a/README b/README
@@ -5,6 +5,9 @@ ledit is a vi-like text editor for people who switch between keyboard
layouts frequently and/or work with languages that require complex text
layout.
+Additionally, it allows multiple views on a text buffer so that different
+parts of a file can be shown at the same time.
+
REQUIREMENTS: pango, xlib (extensions: xkb, xdbe)
The documentation can be viewed in ledit.1 or at the following locations:
diff --git a/keys_basic.c b/keys_basic.c
@@ -1,3 +1,4 @@
+/* FIXME: check allowed modes at beginning of functions */
/* FIXME: the stacks here are shared for all views which can cause weird
behavior, but I'm not sure what would be more logical */
/* FIXME: cursor isn't shown properly on spaces at end of softlines */
@@ -1432,7 +1433,6 @@ static struct action
move_to_eol(ledit_view *view, char *text, size_t len) {
(void)text;
(void)len;
- CHECK_VIEW_LOCKED(view);
motion_callback cb;
int num = get_key_repeat_and_motion_cb(view, &cb);
if (num == -1)
diff --git a/ledit.1 b/ledit.1
@@ -1,12 +1,3 @@
-.\" TODO:
-.\" paste buffer line vs. char oriented
-.\" bigword, etc.
-.\" commands - no good way for mapping found
-.\" difference between unicode char and grapheme
-.\" x, X currently delete graphemes
-.\" everything assumed to be utf8
-.\" marks sometimes char, sometimes line based
-.\"
.\" WARNING: Some parts of this are stolen shamelessly from OpenBSD's
.\" vi(1) manpage!
.Dd December 18, 2021
@@ -23,6 +14,9 @@
is a vi-like text editor for people who switch between keyboard layouts
frequently and/or work with languages that require complex text layout.
.Pp
+Additionally, it allows multiple views on a text buffer so that
+different parts of a file can be shown at the same time.
+.Pp
It is assumed that readers of this manual page are already familiar
with
.Xr vi 1 .
@@ -31,6 +25,8 @@ Differences with
are documented, but it is very likely that many have been missed.
If you find an important difference that is not documented, please
contact me.
+.Pp
+WARNING: All input data is assumed to be utf8!
.Sh ANTI-DESCRIPTION
.Nm
is not a code editor.
@@ -49,6 +45,37 @@ that is not the main goal.
.Pp
.Nm
is not a good text editor.
+.Sh BASIC CONCEPTS
+Some terminology should probably be explained in order to understand the
+rest of this manual.
+.Bl -tag -width Ds
+.It Ar word
+Whatever Pango defines a word to be.
+This probably uses Unicode semantics (UAX #29), but I'm not entirely sure.
+.It Ar bigword
+A set of non-whitespace characters.
+.It Ar character
+A Unicode character.
+Note that, when used as an argument (for instance when setting a mark),
+.Ar character
+can mean pretty much any string, as long as it is given to the program
+in one event.
+Yes, this is inconsistent and confusing.
+.It Ar grapheme
+As defined by Unicode (UAX #29).
+A grapheme may be composed of multiple Unicode characters.
+The cursor is only allowed to be at valid grapheme boundaries, but
+some operations work with characters, while other work with graphemes.
+.El
+.Pp
+Another important concept is the paste buffer.
+When text is deleted or explicitly copied (yanked), it is written to the
+paste buffer so that it can be pasted later.
+The paste buffer is either character or line based, depending on whether
+the deletion/copying operation was line or character based.
+If a character based paste buffer is pasted, the text is inserted right
+at the cursor position.
+When it is line based, the text is inserted after the line.
.Sh KEY BINDINGS
The key bindings listed here are given as the default English bindings.
These will, of course, not be accurate for other languages or if
@@ -115,7 +142,7 @@ This changes behavior depending on the hard/soft line mode.
.Xc
Move the cursor right
.Ar count
-characters in the current line.
+graphemes in the current line.
Note that this is a visual operation, i.e. the cursor will still move right
if the text is right-to-left.
.Pp
@@ -133,7 +160,7 @@ if the text is right-to-left.
.Xc
Move the cursor left
.Ar count
-characters in the current line.
+graphemes in the current line.
Note that this is a visual operation, i.e. the cursor will still move left
if the text is right-to-left.
.Pp
@@ -159,7 +186,7 @@ This changes behavior depending on the hard/soft line mode.
.Xc
Delete
.Ar count
-characters after the cursor on the current line and copy the
+graphemes after the cursor on the current line and copy the
deleted text into the paste buffer.
.Pp
.It Xo
@@ -168,7 +195,7 @@ deleted text into the paste buffer.
.Xc
Delete
.Ar count
-characters before the cursor on the current line and copy the
+graphemes before the cursor on the current line and copy the
deleted text into the paste buffer.
.Pp
.It Xo
@@ -489,16 +516,19 @@ Jump to a position previously marked as
.Aq Cm character
with
.Cm m .
+Note that this will jump to the exact line and character position that
+was marked, but when used as a motion, it will be line based.
+This is somewhat inconsistent, so it will probably be changed at some point.
.Pp
.It Xo
.Cm r
.Aq Cm character
.Xc
-Replace the character at the current cursor position with
+Replace the grapheme at the current cursor position with
.Aq Cm character .
.Pp
.It Cm ^
-Move to the first non-whitespace character on the current line.
+Move to the first non-whitespace cursor position on the current line.
This changes behavior depending on the hard/soft line mode.
.Pp
.It Xo
@@ -574,7 +604,9 @@ Return to normal mode.
All regular keys simply insert the corresponding text at the current cursor
position.
.Pp
-The cursor keys, backspace, delete, and return all work as expected.
+The cursor keys, backspace, delete, and return all work as expected,
+although it should be noted that backspace and delete currently always
+delete a single unicode character instead of a grapheme.
.Pp
Additionally, the following keys are supported:
.Pp
@@ -595,6 +627,7 @@ an entire insert session to be one operation.
.It Aq Cm escape
Return to normal mode.
.El
+.Pp
Note that many keys that are common in other editors are not recognized currently.
That will hopefully be fixed in the future.
.Ss LINE EDITING MODE
@@ -650,16 +683,22 @@ the default English bindings are shown because implementing anything else
would require work.
.El
.Sh COMMANDS
-Note: The terminology is currently a bit inconsistent.
+Note that the terminology is currently a bit inconsistent.
Sometimes,
.Dq commands
refers to the key commands, sometimes to the commands
written in the line editor, which are documented in this section.
.Pp
-Note that the commands which take filenames currently use the entire rest of
+Also note that the commands which take filenames currently use the entire rest of
the line as the filename instead of doing any string parsing.
This may be changed in the future.
.Pp
+The commands do not fit in very well with the rest of the program since they
+are hard-coded in English and cannot be remapped in other languages.
+This is because it isn't entirely clear how a remapping would even work
+because the commands are shown on screen, which might look weird, especially
+if they are remapped to non-printable characters.
+.Pp
.Bl -tag -width Ds -compact
.It Xo
.Cm :w
@@ -713,7 +752,8 @@ in the given line range.
.Pp
Instead of
.Cm / ,
-any other unicode character may be used. The first unicode character after the
+any other unicode character may be used.
+The first unicode character after the
.Cm s
is used as the delimiter.
.Pp
@@ -770,9 +810,77 @@ selects text, which is always copied into the X11 primary selection.
Note that text selection currently does not work in the line editor
because the author is too lazy to implement that.
.Sh CONFIGURATION
-(Todo) - also document weirdness with xkb language strings
+.Nm
+currently has to be configured entirely by changing header files and
+recompiling.
+This will probably be changed in the future, but there hasn't been
+time for it yet.
+.Pp
+There are four configuration headers:
+.Bl -tag -width Ds
+.It Pa config.h
+This contains several timing parameters that most users will probably
+not need to change.
+.It Pa keys_config.h
+This contains the list of languages for which keys are available.
+The language strings in
+.Va key_langs
+are matched exactly with the strings returned by XKB, which seem to
+sometimes be different on different systems, so they will probably
+need to be configured properly.
+.It Pa keys_basic_config.h
+This contains the keys used during regular text editing.
+The first entry in each key is the text that is associated with the text.
+If this is
+.Dv NULL ,
+the third entry, which may contain a symbolic key name, is used for the
+matching instead.
+If the key text is an empty string, it is a catch-all, and the actual
+text is given to the handling function.
+.Pp
+Note that the list of keys is currently traversed from top to bottom,
+so catch-all keys should all be in the end in order to not inferfere
+with other mappings.
+.Pp
+The second entry is a mask of modifier keys that need to be
+pressed during the key press.
+If this is set to
+.Dv XK_ANY_MOD ,
+the modifier keys are ignored.
+.Pp
+The other entries should not be touched unless the actual handling
+function implemented in
+.Pa keys_basic.c
+has been changed.
+.Pp
+Note that the key handling is currently a bit weird, so there might
+be unexpected results sometimes.
+Please report these.
+.It Pa keys_command_config.h
+This is similar to
+.Pa keys_basic_config.h ,
+but contains the keys used during line editing mode or while performing
+commands such as substitution with confirmation.
+.El
+.Pp
+This short explanation of the configuration is not very good currently.
+That will hopefully be changed in the future.
.Sh MISCELLANEOUS
-(Todo) - document emergency dumps
+.Nm
+includes a fair number of sanity checks (asserts) to make sure some illegal
+conditions never occur.
+If one of these checks fails,
+.Nm
+will write the error to stderr and abort.
+In order to avoid losing work, it will attempt to write out the entire
+contents of the buffer to a new file whose name is based on the current
+filename, but with
+.Dq -emergency-dump-
+and a random string of characters
+appended.
+Perhaps this functionality will be removed once
+.Nm
+is perfect and all bugs have been removed.
.Sh EXIT STATUS
.Ex -std
.Sh QUIRKS
@@ -782,10 +890,9 @@ This causes weird cursor jumps when working with bidirectional text in normal mo
This may be fixed in the future, but it currently is not clear how to make the
behavior more logical.
.Pp
-Since a new mode group is started each time insert is entered, when text
-is typed in one view in insert, then in another view, and then again in
-the first one, the last two inserts will be undone in one go since both
-views were in insert already.
+Due to the way undo is implemented, when text is typed in one view in insert
+mode, then in another view, and then again in the first one, the last two
+inserts will be undone in one go since both views were in insert already.
I'm not sure how to make this more logical, though.
Maybe it could be
.Dq improved
@@ -798,7 +905,9 @@ added or deleted in another view.
Additionally, when a new view is created, the scroll offset from the old view
is taken, which may be weird if the window of the new view is a different size.
.Pp
-(Todo) - document weirdness with spaces at end of line in normal mode
+Spaces at the ends of lines are weird because they have to be drawn manually
+instead of highlighting them and letting Pango take care of it because the
+Pango developers decided to hide spaces at the end of a line.
.Sh SEE ALSO
.Xr ed 1 ,
.Xr vi 1 ,
diff --git a/ledit.c b/ledit.c
@@ -3,7 +3,6 @@
/* FIXME: generally optimize redrawing */
/* FIXME: Just use int for everything? size_t just doesn't seem to be worth it */
/* FIXME: Make scrolling more smooth */
-/* FIXME: Document that everything is assumed to be utf8 */
/* FIXME: Only redraw part of screen if needed */
/* FIXME: overflow in repeated commands */
/* FIXME: Use PANGO_PIXELS() */
