tine.1

.Dd $Mdocdate$
.Dt TINE 1
.Os
.Sh NAME
.Nm tine
.Nd a simple text editor
.Sh SYNOPSIS
.Nm
.Op Fl n
.Op Fl r
.Op Fl t
.Ar
.Sh DESCRIPTION
.Nm
is a full-screen text editor.
It is modeled after the venerable
.Em ED
text editor from the TRIPOS and AmigaOS operating systems.
.Pp
.Nm
requires at least one argument:
the name of a file to edit.
This file need not exist when
.Nm
starts;
it will be created when it is saved.
.Pp
Subsequent arguments starting with
.Li "+"
followed by at least one decimal digit are treated as line numbers:
.Nm
will move to the specified line after starting up.
Other arguments are treated as the names of command files
.Pq "that is, files containing sequences of extended commands"
and are executed in order.
.Pp
Note that it is possible to interleave line specifications and extended command files.
.Sh EDITING
.Ss "Quirks"
.Nm
is an attempt to clone the behavior of a much older editor.
It often does not work like a more modern text editor:
in particular, its handling of whitespace, tabs, and newlines is often markedly different.
If you find yourself surprised by the behavior of the editor,
consider it instead a small walk down memory lane.
.Ss "The Display"
.Nm
divides the screen into two areas,
the
.Em file
area and the
.Em "status line" "."
.Pp
The file area displays a the contents of the file being edited.
The file area acts as a
.Dq window
onto the file,
showing a rectangular portion of it.
If the portion of the file shown on screen does not reach the bottom of the file area,
the portion beyond the end of the file is indicated by a gray or checkboard pattern.
.Pp
When editing the file,
the file area is updated in real time to display the contents as they change.
The file on disk is not modified until
.Nm
is told to save the file.
.Pp
Note that
.Nm
does not constrain the cursor to the text of a line.
Text can be typed anywhere on a line,
and
.Nm
will automatically insert spaces as appropriate.
.Pp
Also note that,
by default,
the
.Em Tab
key does not insert tab or space characters, but only advances the cursor.
.Pp
The status line shows information about the current editing session.
It contains the following fields:
.Bl -tag -width Ds
.It "File="
The name of the file being edited.
If there are changes that have not yet been saved,
this field is prefixed with an asterisk.
Long filenames will be ellipsized for display.
.It "Line="
The line number of the file on which the cursor is positioned.
.It "Col="
The column number of the file in which the cursor is positioned.
.It "Block="
If no block is defined
.Po
see the
.Ic BB ","
.Ic BS ","
and
.Ic BE
extended commands
.Pc ","
this field will display
.Li "??" "."
If the starting line of a block has been defined,
the first question mark will be replaced by
.Li "S" "."
If the ending line of a block has been defined,
the second question mark will be replaced by
.Li "E" "."
.It "Tabs="
Displays a number indicating how many spaces the tab key will advance the cursor.
This number can be adjusted using the
.Ic ST
extended command.
If the tab key has been configured to insert tabs rather than move the cursor
.Po
see the
.Ic CT
and
.Ic ET
extended commands
.Pc ","
this field will be prefixed with an asterisk.
.It "Margins="
This field displays the current margins.
The first number represents the left margin
.Pq "which always has a value" ","
and the second number represents the right margin.
The left margin is 1 if it is not otherwise specified;
the right margin is displayed as
.Li "?"
if not specified.
The margins can be set via the
.Ic SL
and
.Ic SR
extended commands,
and reset to their defaults using the
.Ic RM
command.
.Pp
If the right margin on the current line is currently ignored
.Po
see the
.Ic EX
command
.Pc ","
this field will be prefixed with an asterisk.
.Pp
If auto-indent is currently enabled
.Po
see the
.Ic AI
and
.Ic NI
commands
.Pc ","
the left margin is displayed as
.Li ">" "."
.El
.Pp
If an error occurs, the contents of the status line are replaced with an error message
until the next keystroke.
.Pp
By default,
the status line appears at the bottom of the display.
By starting
.Nm
with the
.Fl t
flag,
the status line will appear at the top.
.Pp
By default,
the file area is displayed in normal video and the status line
appears in reverse video.
By starting
.Nm
with the
.Fl r
flag,
this is reversed.
.Ss "Word Wrap and Margins"
.Nm
maintains a left and right margin,
settable with the
.Ic SL
and
.Ic SR
commands respectively.
New lines will by default start offset to the left margin
.Pq "though the cursor can be moved to before the left margin if desired"
and words will wrap at the right margin.
.Nm
supports only simple wrapping:
long words with no spaces that consume the entire width of a line between the margins will not be wrapped.
.Ss "Startup Files"
On startup,
.Nm
will execute the file
.Pa "${XDG_CONFIG_HOME}/.tine/tinerc"
if it exists,
with
.Ev "${XDG_CONFIG_HOME}"
defaulting to
.Pa "${HOME}/.config" "."
If that file does not exist,
the directories named in
.Ev "${XDG_CONFIG_DIRS}"
are inspected similarly,
with
.Ev "${XDG_CONFIG_DIRS}"
defaulting to
.Pa "/etc/xdg" "."
.Pp
A file of the form
.Pa "tinerc.EXT" ","
where
.Em EXT
is the
.Dq "extension"
of the filename
.Pq "the part after the last '.' character"
is also executed if it exists.
If the named file has no extension,
the whole filename is treated as the extension.
.Pp
In startup files, blank lines are ignored.
Lines whose first non-whitespace character is a single quote are considered commentary.
.Pp
Calling
.Nm
with the
.Fl n
flag suppresses the automatic exection of these files.
.Ss "The Block"
Some contiguous sequence of lines in the file can be specially marked;
these lines are referred to as
.Dq "the block" "."
The block can be manipulated in various ways,
and several extended commands refer to it in some way.
Note that the block is  cleared
.Pq "that is, lines are no longer specially marked"
when a file is modified in certain ways.
In general, any command that inserts or deletes a line will clear the block.
An exception to this is the
.Ic IB
command,
which inserts a copy of the block elsewhere in the file.
.Pp
Lines that are part of the block are displayed in reverse video.
Note that it is not possible to have the block begin or end in the middle of a line.
.Ss "Immediate Mode"
When
.Nm
starts,
it is in
.Em immediate
mode.
In immediate mode,
as the name implies,
commands are executed immediately.
Most of these
.Dq "commands"
are simply the normal actions of editing:
inserting characters by typing them on the keyboard,
moving the cursor in various directions via the cursor movement keys,
and so on.
.Pp
Some commands,
however,
are entered by pressing the control key and one other key simultaneously.
These commands perform more complicated manipulations on the file being edited.
.Ss "Immediate Mode Commands"
The following commands are available in immediate mode:
.Bl -tag -width Ds
.It Tab
By default, advances the cursor to the next tab stop
.Po
it does
.Em not
insert a tab character
.Pc "."
This behavior can be modified by the
.Ic ET
command,
which causes
.Em Tab
to insert actual tab characters.
The width of tabstops is controlled by the
.Ic ST
command.
.It Backspace
Deletes the character to the left of the cursor.
.It Insert
Inserts a new line above the current line.
.It Home
Moves to the beginning of the first line.
.It End
Moves to the beginning of the last line.
.It Up / Down / Left / Right
Move one unit in the specified direction.
.It Shift-Left / Shift-Right
Move to the start/end of the current line.
.It Enter
Insert a new line at the cursor.
.It Next / Previous Page
Move up/down one page.
.It F1 - F10
Executes the extended command assigned to the given key.
.It Escape
Enters extended command mode.
.It Ctrl-]
Go to the end of the line or, if there, to the start.
.It Ctrl-A
Inserts a line below the current one.
.It Ctrl-B
Deletes the current line.
.It Ctrl-D
Moves down one page.
.It Ctrl-E
Moves to the top of the screen or, if there, to the bottom.
.It Ctrl-F
Flips the case of the character under the cursor.
.It Ctrl-G
Repeats the last extended mode command.
.It Ctrl-K
Sets a block mark.
Executing this command twice will mark a block without needing to resort to extended commands.
.It Ctrl-L
Inserts a copy of the last deleted line.
.It Ctrl-N
Joins the current and next line.
.It Ctrl-O
Deletes the word/spaces immediately following the cursor.
.It Ctrl-P
If the cursor is on an opening or closing bracket,
jump to the corresponding opening or closing bracket.
.It Ctrl-Q
Quote the next character typed.
That is, insert the next character literally, even if it would normally be a command.
.It Ctrl-R
Move to the space following the previous word.
.It Ctrl-T
Move to the first character of the next word.
.It Ctrl-U
Move up one page.
.It Ctrl-W
Delete the previous word.
.It Ctrl-V
Redraw the screen.
.It Ctrl-Y
Delete from the cursor to the end of the current line.
.It Ctrl-Z
Go back to previous position before the last large cursor movement.
.El
.Pp
Note that any of the sequences above that are prefixed with
.Em Ctrl
can be remapped using the
.Ic MC
extended command.
.Sh "Extended Mode Commands"
.Nm
has a powerful editing command language.
Extended mode commands can be entered while editing by pressing
.Li Escape
and then entering the command on the command line
.Pq "which temporarily replaces the status line on the display" "."
.Pp
Most
.Pq "but not all"
of the immediate mode commands above can be used when editing an extended command.
Pressing
.Em Enter
will execute the command line and return to immediate mode,
while pressing
.Em Escape
or
.Em Ctrl-J
will execute the command line and remain in extended command mode.
.Em Ctrl-C
will cancel the current command and return to immediate mode.
.Pp
While in extended command mode,
a virtual cursor is displayed in reverse video in the file area for reference.
This is most useful when executing commands by pressing escape and remaining in extended command mode.
.Pp
.Nm
maintains a history of extended commands executed,
and this history can be browsed using the up and down arrow keys to move backwards and forwards in history.
Earlier commands can be edited before executing them.
.Ss "The Extended Mode Command Language"
An extended command looks like:
.Bd -literal -offset indent
repeat-count command-name argument
.Ed
.Pp
The
.Li "repeat-count"
is specified in decimal,
and specifies how many times the following command should be repeated
It is optional,
the default is 1.
A repeat count of
.Li RP
means that the command should be repeated until it fails.
The
.Li RP
specification is not case-sensitive.
.Pp
The command name is required, and consists of one or two letters.
Command names are not case-sensitive.
A listing of extended mode commands is available below.
.Pp
Each command takes exactly zero or one argument of a given type,
though some commands provide a useful default if it is not specified.
Arguments can be strings, numbers, or two strings together.
Strings can be delimited by any non-alphanumeric character except semicolon and parentheses.
This allows the use of a delimiter character that does not appear in the string itself.
.Pp
Multiple commands can be specified on the same command line by separating them with semicolons.
Multiple commands can be grouped into one logical command by enclosing them in parentheses.
.Pp
Pressing any key while an extended command is running will abort execution.
.Pp
Whitespace can be omitted where its absence does not result in any ambiguity.
This includes whitespace between commands and arguments,
or whitespace between numeric repeat counts and command names.
.Pp
Below is a list of what extended mode commands are available;
in their descriptions,
.Li n
refers to a numeric argument;
.Li "/s/"
to a string argument with
.Li "/"
representing the delimiter character;
and
.Li "/s/t/"
representing two strings together with
.Li "/"
again representing the delimiter.
The final delimiter in a string or strings can be elided at the end of a command line.
.Bl -tag -width Ds
.It "A/s/"
.Dq "After"
Insert a line after the current line, containing the string
.Ar s "."
.It "AI"
.Dq "Auto-Indent"
Enable auto-indent mode.
.It "B"
.Dq "Bottom"
Moves to the bottom of the file.
.It "BB"
.Dq "Block Both"
Sets the current line to the beginning or end of the block,
as appropriate.
.It "BE"
.Dq "Block End"
Specifies that the block should end at the current line.
.It "BF/s/"
.Dq "Backwards Find"
Searches backwards through the file for the given string.
If unspecified, the last string used in a
.Ic BF ","
.Ic F ","
.Ic E ","
or
.Ic "EQ"
command is reused.
.It "BM n"
.Dq "BookMark"
Set bookmark
.Ar n
to the current cursor position.
.Ar n
must be between one and ten, inclusive.
.It "BS"
.Dq "Block Start"
Specifies that the block should start at the current line.
.It "BT"
.Dq "Back Tab"
Move the cursor to the previous tab position.
.It "CB"
.Dq "Clear Block"
Clears the block.
.It "CD"
.Dq "Cursor Down"
Move the cursor down one line without changing its column.
.It "CE"
.Dq "Cursor End"
Move the cursor to the end of the current line.
.It "CF n"
.Dq "Call Function"
Call the extended command bound to function key
.Ar n "."
.Ar n
must be between one and ten, inclusive.
.It "CJ"
.Dq "Cursor Jump
Move the cursor to the end of the current line;
if it is already there, move it to the beginning.
.It "CL"
.Dq "Cursor Left"
Move the cursor left one screen position.
.It "CR"
.Dq "Cursor Right"
Move the cursor right one screen position.
.It "CS"
.Dq "Cursor Start"
Move the cursor to the start of the line.
.It "CT"
.Dq "Collapse Tabs"
Cause the tab key to advance the cursor without inserting any characters.
.It "CU"
.Dq "Cursor Up"
Move the cursor up one line without changing its column.
.It "D"
.Dq "Delete"
Delete the current line.
.It "DB"
.Dq "Delete Block"
Delete the block.
.It "DC"
.Dq "Delete Character"
Delete the character under the cursor.
.It "DF"
.Dq "Display Functions"
Display the extended commands bound to the function keys.
.It "DL"
.Dq "Delete Left"
Delete the character to the left of the cursor.
.It "DO/s/"
.Dq "DO command"
Temporarily suspend
.Nm
and execute
.Ar s
as an operating system command.
.It "DP"
.Dq "Delete Previous"
Delete the word or spaces preceding the cursor.
.It "DW"
.Dq "Delete Word"
Delete the word or spaces following the cursor.
.It "E/s/t/"
.Dq "Exchange"
Exchange the next instance of
.Ar s
with
.Ar t "."
This is generally useful with a repetition count.
.It "EL"
.Dq "Erase in Line"
Delete to the end of the line.
.It "EP"
.Dq "End Page"
Move to the beginning of the text on the screen or,
if already there,
to the end of the text on the screen.
.It "EQ"
.Dq "Exchange with Query"
Like
.Ic
but the user is prompted before each exchange action.
Replying
.Li n
will not exchange the given instance.
.It "ET"
.Dq "Expand Tabs"
Cause the tab key to insert literal tab characters.
.It "EX"
.Dq "EXpand margins"
Ignore the right-hand margin for this line.
This effect is canceled when the cursor leaves the current line.
.It "F/s/"
.Dq "Find"
Search forwards through the file for string
.Ar s "."
If
.Ar s
is omitted,
the last string searched for in a
.Ic F ","
.Ic BF ","
.Ic E ","
or
.Ic EQ
command is used.
.It "FB/s/"
.Dq "Filter Block"
Filter block through operating system command
.Ar s "."
The existing block is passed as the command's standard input,
and is replaced with the command's standard output.
.It "FC"
.Dq "Flip Case"
Flip the case of the character under the cursor,
and move one position to the right.
.It "GB"
.Dq "Go Back"
Returns to the previous location,
before any long-distance movement commands.
.It "GM n"
.Dq "Go to Mark"
Go to bookmark
.Ar n "."
.It "I/s/"
.Dq "Insert"
Insert a line above the current line containing the string
.Ar s "."
.It "IB"
.Dq "Insert Block"
Insert a copy of the block at the current line.
Unlike most actions that insert lines into the file,
this does not clear the block.
.It "IF/s/"
.Dq "Insert File"
Insert the contents of file
.Ar s
at the current cursor position.
.It "IM"
.Dq "Ignore Match"
Disable
.Dq "show matching brace"
mode; see the
.Ic "MS"
command for details.
.It "J"
.Dq "Join"
Join the current line and the next.
.It "LC"
.Dq "LowerCase"
Cause subsequent
.Ic F ","
.Ic BF ","
.Ic E ","
and
.Ic "EQ"
commands to ignore case while searching.
.It "M n"
.Dq "Move"
Move to line
.Ar n "."
.It "MC/s/t/"
.Dq "Map Control"
Cause
.Nm
to interpret the pressing of
.Li Ctrl-s
as if
.Li Ctrl-t
had been pressed.
In this case,
.Ar s
and
.Ar t
must be single-character strings.
.It "MS"
.Dq "Match Show"
Enable
.Dq "show matching brace"
mode.
In this mode,
when typing a brace character,
the cursor will briefly move to the matching brace character if available,
similar to if the
.Ic "SB"
command had been invoked.
.It "N"
.Dq "Next line"
Move to the beginning of the next line.
.It "NI"
.Dq "Normal Indent"
Disable auto-indent mode.
.It "P"
.Dq "Previous line"
Move to the beginning of the previous line.
.It "PD"
.Dq "Page Down"
Move down one page.
.It "PH n"
.Dq "Page Height"
Set the number of lines in a page to
.Ar n "."
The default is 12.
.It "PU"
.Dq "Page Up"
Move up one page.
.It "Q"
.Dq "Quit"
Quit without saving.
If the file has unsaved changes, the user is prompted to confirm.
.It "QY"
.Dq "Quit, answer Yes"
Quit without saving.
No prompting is done if there are unsaved changes.
.It "RD"
.Dq "Restore Deleted"
Insert a copy of the last line deleted with the
.Li "Ctrl-B"
or
.Ic "D"
commands.
.It "RF/s/"
.Dq "Run File"
Read file
.Ar "s"
and execute its contents as a sequence of
.Nm
extended commands.
.It "RM"
.Dq "Reset Margins"
Reset the margins to their defaults
.Pq "that is, 1 for the left margin and undefined for the right" "."
.It "S"
.Dq "Split"
Split the current line at the cursor position.
.It "SA/s/"
.Dq "SAve"
Save the file to the filename
.Ar s "."
If
.Ar s
is omitted,
the name given to
.Nm
at startup is used.
.It "SB"
.Dq "Show Block"
Move the display such that the first line of the block is visible on the screen.
.It "SD n"
.Dq "Set Delay"
Set the time used to show matching brackets
.Po
see the
.Ic "MS"
command
.Pc
to
.Ar n
milliseconds.
The default is 200.
.It "SF/s/t/"
.Dq "Set Function"
Set function key
.Ar s
to the extended command
.Ar t "."
Note that
.Ar s
must be a decimal number between one and ten, inclusive.
.It "SH"
.Dq "SHow"
Display some information about the current state of the editor.
.It "SL n"
.Dq "Set Left"
Set the left margin to column
.Ar n "."
If
.Ar n
is omitted, use the current cursor column.
.It "SM"
.Dq "Show Matching"
If the cursor is over a bracket character,
move to the matching bracket character.
.It "SR n"
.Dq "Set Right"
Set the right margin to column
.Ar n "."
If
.Ar n
is omitted, use the current cursor column.
.It "ST n"
.Dq "Set Tab"
Set the tab distance to
.Ar n
columns.
This is the number of columns advanced by the tab key when it is not configured to insert literal tabs,
and the number of spaces literal tabs will take up when displayed on the screen.
.It "T"
.Dq "Top"
Move to the top of the file.
.It "TB"
.Dq "TaB"
Move to the next tabstop or,
if the tab key is configured to insert literal tabs,
insert a tab.
.It "TY/s/"
.Dq "TYpe"
Insert the string
.Ar s
as if it had been typed at the keyboard.
.It "U"
.Dq "Undo"
Undo the last file modification.
.It "UC"
.Dq "UpperCase"
Cause subsequent
.Ic F ","
.Ic BF ","
.Ic E ","
and
.Ic "EQ"
commands to respect case while searching.
.It "WB/s/"
.Dq "Write Block"
Write the contents of the block to the file
.Ar s "."
.It "WN"
.Dq "Word Next"
Move to the first character of the next word.
.It "WP"
.Dq "Word Previous"
Move to the space following the last character of the previous word.
.It "X"
.Dq "eXit"
Exit, saving any changes.
No prompting is performed.
.It "XQ"
.Dq "eXit with Query"
Exit, prompting to save first if the file has been changed.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev TERM
Indciates the terminal type under which
.Nm
is running.
.It Ev ESCDELAY
This variable specifies the number of milliseconds
.Nm
will wait after seeing an escape character for a special character sequence to complete.
By default, this is 1000
.Pq "one second" "."
.It Ev LC_CTYPE Ev LC_ALL Ev LANG
These variables are consulted to determine the encoding used for textual data.
.It Ev HOME Ev XDG_CONFIG_HOME Ev XDG_CONFIG_DIRS
These variables are consulted to determine paths for startup files.
.Sh FILES
.Bl -tag -width Ds
.It ".../.tine/tinerc"
This file is automatically executed at startup.
It is located using the XDG Specification for configuration files.
.It ".../.tine/.tinerc.EXT"
This file is automatically executed if the extension of the filename passed at startup matches
.Li EXT "."
If the passed filename has no extension, the whole filename is treated as the extension.
.El
.Sh EXAMPLES
The following extended command will mimic the pre-AmigaDOS 2.0 meanings of the
.Li Ctrl-U
and
.Li Ctrl-D
commands:
.Bd -literal
   MC/U/D/;MC/D/U/
.Ed
.Pp
The following extended command will move to the top of the file,
make searches case-insensitive,
and then find and exchange each instance of
.Li foo
with
.Li bar ","
prompting the user before each exchange,
and then inserting the text
.Li "baz"
before the
.Pq "possibly exchanged"
text:
.Bd -literal
   T;RP(EQ/foo/bar/;TY/baz/)
.Ed
.Pp
This command might be useful to place in the
.Pa "${XDG_CONFIG_HOME}/tine/tinerc.Makefile"
file to set expanded tab mode automatically when editing makefiles:
.Bd -literal
   ET
.Ed
.Pp
This sets the F3 key to preview the file being edited as a man page:
.Bd -literal
   SF%3%T;BS;B;BE;WB"/tmp/mtmp";CB;DO"man /tmp/mtmp;rm -f /tmp/mtmp";GB%
.Ed
.Pp
This marks the whole file as the block by going to the top and setting the block start,
going to the bottom and setting the block end,
writing the block to a temporary file,
clearing the block,
calling the
.Xr man 1
command to display the man page and the
.Xr rm 1
command to delete the temporary file,
and then finally returning the cursor to the remembered position before all this happend.
.Sh HISTORY
.Nm
is a modern-day attempt to clone the
.Em ED
display editor from MetaComCo
.Po
.Do
.Nm
.Dc
is a rather feeble attempt at a recursive acronym:
.Dq "tine Is Not ED"
.Pc "."
.Pp
.Em ED
was written in the early 1980's as a display editor for the Cambridge TRIPOS operating system.
TRIPOS later formed the core of AmigaDOS;
.Em ED
came along with it.
.Pp
.Nm
shares no code with
.Em ED ","
nor does anyone involved with MetaComCo, the University of Cambridge, Amiga, or TRIPOS endorse or have anything to do with this project...
though the author wishes to extend his heartfelt thanks to each of them for many years of enjoyable hacking.
.Sh BUGS
The only language in which output is produced and documentation is provided is English,
regardless of the user's preferred language.
.Pp
While
.Nm
handles nonspacing and combining characters reasonably well,
there is no support for right-to-left or bidirectional text,
nor is there any support for more complex textual forms that are common in many languages.
.Pp
The screen update algorithm is wasteful of resources;
a much more efficient mechanism should be used.
.Pp
There is no support for file locking and nothing prevents two instances of
.Nm
from modifying the same file concurrently.
.Pp
History browsing in the extended command line is a little nonintuitive.