.TH DTE 1 "February 2021"
.nh
.ad l
.
.SH NAME
dte \- A small, configurable text editor
.SH SYNOPSIS
\fBdte\fR
[\fB\-HR\fR]
[\fB\-c\fR \fIcommand\fR]
[\fB\-t\fR \fIctag\fR]
[\fB\-r\fR \fIrcfile\fR]
[[\fB+\fRline] \fIfile\fR]...
.br
\fBdte\fR [\fB\-h\fR|\fB\-B\fR|\fB\-K\fR|\fB\-V\fR|\fB\-b\fR \fIrcname\fR|\fB\-s\fR \fIfile\fR]
.P
.SH OPTIONS
.TP
\fB\-c\fR \fIcommand\fR
Run \fIcommand\fR, after reading the rc file and opening any \fIfile\fR
arguments. See \fBdterc\fR(5) for available commands.
.PP
.TP
\fB\-t\fR \fIctag\fR
Jump to source location of \fIctag\fR. Requires \fBtags\fR file generated
by \fBctags\fR(1).
.PP
.TP
\fB\-r\fR \fIrcfile\fR
Read configuration from \fIrcfile\fR instead of \fB~/.dte/rc\fR.
.PP
.TP
\fB\-s\fR \fIfile\fR
Load \fIfile\fR as a \fBdte\-syntax\fR(5) file and exit. Any errors
encountered are printed to \fBstderr\fR(3) and the exit status is
set appropriately.
.PP
.TP
\fB\-b\fR \fIrcname\fR
Dump the contents of the built\-in rc or syntax file named \fIrcname\fR
and exit.
.PP
.TP
\fB\-B\fR
Print a list of all built\-in config names that can be used with the
\fB\-b\fR option and exit.
.PP
.TP
\fB\-H\fR
Don't load history files at startup or save history files on exit (see
\fBFILES\fR section below). History features will work as usual but will
be in\-memory only and not persisted to the filesystem.
.PP
.TP
\fB\-R\fR
Don't read the rc file.
.PP
.TP
\fB\-K\fR
Start in a special mode that continuously reads input and prints the
symbolic name of each pressed key.
.PP
.TP
\fB\-h\fR
Display the help summary and exit.
.PP
.TP
\fB\-V\fR
Display the version number and exit.
.PP
.SH KEY BINDINGS
There are 3 editor modes, each having a different set of key bindings.
Normal mode bindings can be customized by using the \fBbind\fR command
(see \fBdterc\fR(5)) or displayed using the \fBshow bind\fR command.
.P
The key bindings listed below are in the same format as accepted by
the \fBbind\fR command. In particular, key combinations are represented
as follows:
.P
\(bu \fBM\-x\fR is Alt+x
.br
\(bu \fBC\-V\fR (or \fB^V\fR) is Ctrl+v
.br
\(bu \fBS\-left\fR is Shift+left
.br
\(bu \fBC\-M\-S\-left\fR is Ctrl+Alt+Shift+left
.br
.P
.SS Normal Mode
Normal mode is the mode the editor starts in. Pressing basic keys
(i.e. without modifiers) simply inserts text into the buffer. There
are also various key combinations bound by default:
.P
.TP
\fBS\-up\fR, \fBS\-down\fR, \fBS\-left\fR, \fBS\-right\fR
Move cursor and select characters
.PP
.TP
\fBC\-S\-left\fR, \fBC\-S\-right\fR
Move cursor and select whole words
.PP
.TP
\fBC\-S\-up\fR, \fBC\-S\-down\fR
Move cursor and select whole lines
.PP
.TP
\fB^C\fR
Copy current line or selection
.PP
.TP
\fB^X\fR
Cut current line or selection
.PP
.TP
\fB^V\fR
Paste
.PP
.TP
\fB^Z\fR
Undo
.PP
.TP
\fB^Y\fR
Redo
.PP
.TP
\fBM\-x\fR
Enter command mode
.PP
.TP
\fB^F\fR
Enter search mode
.PP
.TP
\fBF3\fR
Search next
.PP
.TP
\fBF4\fR
Search previous
.PP
.TP
\fB^T\fR
Open new buffer
.PP
.TP
\fBM\-1\fR, \fBM\-2\fR ... \fBM\-9\fR
Switch to buffer 1 (or 2, 3, 4, etc.)
.PP
.TP
\fB^W\fR
Close current buffer
.PP
.TP
\fB^S\fR
Save
.PP
.TP
\fB^Q\fR
Quit
.PP
.SS Command Mode
Command mode allows running various editor commands using a language
similar to Unix shell. The \fBnext\fR and \fBprev\fR commands switch
to the next/previous file. The \fBopen\fR, \fBsave\fR and \fBquit\fR
commands should be self\-explanatory. For a full list of available
commands, see \fBdterc\fR(5).
.P
The key bindings for command mode are:
.P
.TP
\fBup\fR, \fBdown\fR
Browse previous command history.
.PP
.TP
\fBtab\fR
Auto\-complete current command or argument
.PP
.TP
\fB^A\fR, \fBhome\fR
Go to beginning of command line
.PP
.TP
\fB^B\fR, \fBleft\fR
Move left
.PP
.TP
\fB^C\fR, \fB^G\fR, \fBEsc\fR
Exit command mode
.PP
.TP
\fB^D\fR, \fBdelete\fR
Delete
.PP
.TP
\fB^E\fR, \fBend\fR
Go to end of command line
.PP
.TP
\fB^F\fR, \fBright\fR
Move right
.PP
.TP
\fB^K\fR, \fBM\-delete\fR
Delete to end of command line
.PP
.TP
\fB^U\fR
Delete to beginning of command line
.PP
.TP
\fB^W\fR, \fBM\-C\-?\fR (Alt+Backspace)
Erase word
.PP
.SS Search Mode
Search mode allows entering a regular expression to search in the
current buffer.
.P
The key bindings for search mode are mostly the same as in command mode,
plus these additional keys:
.P
.TP
\fBM\-c\fR
Toggle case sensitive search option.
.PP
.TP
\fBM\-r\fR
Reverse search direction.
.PP
.TP
\fBEnter\fR
Perform regex search.
.PP
.TP
\fBM\-Enter\fR
Perform plain\-text search (escapes the regex).
.PP
.SH ENVIRONMENT
The following environment variables are inspected at startup:
.P
.TP
\fBDTE_HOME\fR
User configuration directory. Defaults to \fB$HOME/.dte\fR if not set.
.PP
.TP
\fBHOME\fR
User home directory. Used when expanding \fB~/\fR in filenames and also
to determine the default value for \fBDTE_HOME\fR.
.PP
.TP
\fBXDG_RUNTIME_DIR\fR
Directory used to store lock files. Defaults to \fB$DTE_HOME\fR if not set.
.PP
.TP
\fBTERM\fR
Terminal identifier. Used to determine which terminal capabilities are
supported.
.PP
.TP
\fBCOLORTERM\fR
Enables support for 24\-bit terminal colors, if set to \fBtruecolor\fR.
.PP
.SH FILES
.TP
\fB$DTE_HOME/rc\fR
User configuration file. See \fBdterc\fR(5) for a full list of
available commands and options or run "dte \-b rc" to see the built\-in,
default config.
.PP
.TP
\fB$DTE_HOME/syntax/*\fR
User syntax files. These override the syntax files that come with
the program. See \fBdte\-syntax\fR(5) for more information or run
"dte \-b syntax/dte" for a basic example.
.PP
.TP
\fB$DTE_HOME/file\-history\fR
History of edited files and cursor positions. Used only if the
\fBfile\-history\fR option is enabled.
.PP
.TP
\fB$DTE_HOME/command\-history\fR
History of \fBdterc\fR(5) commands used while in command mode.
.PP
.TP
\fB$DTE_HOME/search\-history\fR
History of search patterns used while in search mode.
.PP
.TP
\fB$XDG_RUNTIME_DIR/dte\-locks\fR
List of files currently open in a dte process (if the \fBlock\-files\fR
option is enabled).
.PP
.SH EXIT STATUS
.TP
\fB0\fR
Program exited normally.
.PP
.TP
\fB64\fR
Command\-line usage error (see "synopsis" above).
.PP
.TP
\fB65\fR
Input data error (e.g. data specified by the \fB\-s\fR option).
.PP
.TP
\fB71\fR
Operating system error.
.PP
.TP
\fB74\fR
Input/output error.
.PP
Note: the above exit codes are set by the editor itself, with values in
accordance with \fBsysexits\fR(3). The exit code may also be set to values
in the range \fB0\fR..\fB125\fR by the \fBquit\fR command.
.P
.SH EXAMPLES
Open \fB/etc/passwd\fR with cursor on line 3:
.P
.IP
.nf
\f[C]
dte\ +3\ /etc/passwd
\f[]
.fi
.PP
Run several commands at startup:
.P
.IP
.nf
\f[C]
dte\ \-c\ 'set\ filetype\ sh;\ insert\ \-m\ "#!/bin/sh\\n"'
\f[]
.fi
.PP
Read a buffer from standard input:
.P
.IP
.nf
\f[C]
echo\ 'Hello,\ World!'\ |\ dte
\f[]
.fi
.PP
Interactively filter a shell pipeline:
.P
.IP
.nf
\f[C]
echo\ 'A\ B\ C\ D\ E\ F'\ |\ tr\ '\ '\ '\\n'\ |\ dte\ |\ tac
\f[]
.fi
.PP
.SH NOTES
It's advised to NOT run shell pipelines with multiple interactive
programs that try to control the terminal. For example:
.P
.IP
.nf
\f[C]
echo\ 'Don't\ run\ this\ example!!'\ |\ dte\ |\ less
\f[]
.fi
.PP
A shell will run these processes in parallel and both \fBdte\fR(1) and \fBless\fR
will then try to control the terminal at the same time; clobbering the
input/output of both.
.P
.
.SH SEE ALSO
\fBdterc\fR(5),
\fBdte\-syntax\fR(5)
.SH AUTHORS
Craig Barnes
.br
Timo Hirvonen