sdn/sdn.1

\" https://mandoc.bsd.lv/man/roff.7.html#Sentence_Spacing
.Dd October 27, 2020
.Dt SDN 1
.Os Linux
.Sh NAME
.Nm sdn
.Nd directory navigator
.Sh SYNOPSIS
.Nm sdn
.Op Ar line Ar point
.Nm sdn
.Cm --version
.Sh DESCRIPTION
.Nm
is a simple directory navigator that you can launch while editing shell
commands.
Use the
.Xr sdn-install 1
script to integrate it with your shell, then invoke it at any time with M-o.
.Pp
Press F1 to get a list of active key bindings and their assigned actions,
grouped by their contexts.
.Pp
Program arguments are only used by integration snippets to forward the parent
shell's command line.
The
.Ar point
is given in terms of characters.
.Sh OPTIONS
While some behaviour can be toggled from within the program, some can only be
changed by modifying configuration files manually.
.Pp
The files follow a simple syntax derived from the Bourne shell: each option is
on its own line, with words separated by linear whitespace.
Comments start with a hash (#) and continue until the end of the line.
All special characters may be quoted using either a backslash or single-quoted
strings.
.Pp
The options and the default key bindings controlling them are as follows:
.Bl -tag
.It full-view Em bool No (t)
If non-zero, the equivalent format to
.Ql ls -l
is used to display directory contents rather than simply listing the filenames.
.It gravity Em bool
If non-zero, all entries stick to the bottom of the screen, i.e., all empty
space is at the top.
.It reverse-sort Em bool No (R)
If non-zero, the order of entries is reversed.
.It show-hidden Em bool No (M-.)
If non-zero, filenames beginning with a full stop are shown.
.It ext-helpers Em bool
If non-zero, viewers and editors are launched from the parent shell.
This way you can suspend them and use job control features of the shell.
However it also enforces any pending change to the shell's working directory.
.It sort-column Em number No (< >)
The zero-based index of the
.Ql full-view
column that entries are ordered by.
.El
.Sh ENVIRONMENT
.Bl -tag -width 15n
.It Ev LS_COLORS
Used to retrieve filename colours.
The format is described in
.Xr dir_colors 5
and you can use the
.Xr dircolors 1
utility to initialize this variable.
.It Ev PAGER
The viewer program to be launched by the F3 key binding as well as to show
the internal help message.
If none is set, it defaults to
.Xr less 1 .
.It Ev VISUAL , Ev EDITOR
The editor program to be launched by the F4 key binding.
If neither variable is set, it defaults to
.Xr vi 1 .
.El
.Sh FILES
.Bl -tag -width 25n -compact
.It Pa ~/.config/sdn/config
Program configuration and navigation state, initialized or overwritten on exit.
.It Pa ~/.config/sdn/bindings
Custom key binding overrides.
.It Pa ~/.config/sdn/look
Redefine terminal attributes for UI elements.
.El
.Sh EXAMPLES
.Ss Pa bindings
Key names or combinations follow the Emacs syntax for Control and Meta prefixes
and
.Xr terminfo 5
names are used for special keys.
To obtain more vifm-like controls and Windows-like quit abilities:
.Bd -literal -offset indent
normal h parent
normal l choose
normal M-f4 quit
.Ed
.Pp
Midnight Commander binds the same traversal actions to sequences normally
unknown to ncurses, due to them being missing from terminfo.
You'll need to define them manually to match your terminal.
For rxvt, that would be:
.Bd -literal -offset indent
define C-ppage ^[[5^
define C-npage ^[[6^
normal C-ppage parent
normal C-npage choose
.Ed
.Pp
Escape characters must be inserted verbatim, e.g., by pressing C-v ESC in vi,
or C-q ESC in Emacs.
.Ss Pa look
Terminal attributes are accepted in a format similar to that of
.Xr git-config 1 ,
only named colours aren't supported.
For a black-on-white terminal supporting 256 colours, a theme such as the
following may work:
.Bd -literal -offset indent
cursor 231 202
bar 16 255 ul
cwd bold
input
cmdline 145
.Ed
.Sh REPORTING BUGS
Use
.Lk https://git.janouch.name/p/sdn
to report bugs, request features, or submit pull requests.