From c20d3780b2ac9d1edb143fc18f7f6965867f74f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C5=99emysl=20Eric=20Janouch?= Date: Tue, 27 Oct 2020 04:05:54 +0100 Subject: Make the manpages mostly acceptable Closes #1 --- README.adoc | 10 +++---- sdn-install.1 | 11 +++++--- sdn.1 | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 91 insertions(+), 16 deletions(-) diff --git a/README.adoc b/README.adoc index 8b33d4c..2abe51d 100644 --- a/README.adoc +++ b/README.adoc @@ -50,8 +50,12 @@ Or you can try telling CMake to make a package for you. For Debian it is: There is also a Makefile you can use to quickly build a binary to be copied into the PATH of any machine you want to have 'sdn' on. +Configuration +------------- +For a slightly more technical explanation please refer to manual pages. + Integration ------------ +~~~~~~~~~~~ The package contains an installation script called 'sdn-install' which will bind 'sdn' to Alt-o in your shell's initialisation file. The supported shells are: @@ -64,9 +68,6 @@ elvish is absolutely perverse. And so is integrating 'sdn' into it because it already includes a custom file manager, bound to Ctrl-N (though I find the ranger-like interface confusing and resource-demanding). -Configuration -------------- - Colours ~~~~~~~ Here is an example of a '~/.config/sdn/look' file; the format is similar to @@ -91,7 +92,6 @@ To obtain more vifm-like controls, you may write the following to your .... normal h parent normal l choose -normal ? help .... Helper programs diff --git a/sdn-install.1 b/sdn-install.1 index d39e07b..c186f63 100644 --- a/sdn-install.1 +++ b/sdn-install.1 @@ -1,4 +1,4 @@ -.Dd October 26, 2020 +.Dd October 27, 2020 .Dt SDN-INSTALL 1 .Os Linux .Sh NAME @@ -22,9 +22,14 @@ Merely print the integration snippet for the appropriate shell to the standard output, not changing anything. .It Fl p Ar rcpath Install the integration snippet into a different shell initialization file than -your user's default one. +the default one for your user. .It Fl s Ar shell If you want to integrate .Xr sdn 1 -with a different shell than you're running, use this option to specify it. +with a different shell than the one you're running, use this option to specify +it. .El +.Sh REPORTING BUGS +Use +.Lk https://git.janouch.name/p/sdn +to report bugs, request features, or submit pull requests. diff --git a/sdn.1 b/sdn.1 index e449d77..0185e18 100644 --- a/sdn.1 +++ b/sdn.1 @@ -1,18 +1,59 @@ -.Dd October 26, 2020 +.Dd October 27, 2020 .Dt SDN 1 .Os Linux .Sh NAME .Nm sdn -.Nd simple directory navigator +.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 invoke while editing shell +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 with M-o. +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 (M-< M->) +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 @@ -23,16 +64,45 @@ and you can use the 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. +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. +The editor program to be launched by the F4 key binding. If none is set, +it defaults to +.Xr vi 1 . .El .Sh FILES .Bl -tag -width 25n -compact .It Pa ~/.config/sdn/config -Program configuration and state. +Program configuration and navigation state, initialized or overwritten on exit. .It Pa ~/.config/sdn/bindings -Key binding overrides. +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 +.Ss Pa look +Terminal attributes are accepted in a format similar to that of +.Xr git 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. -- cgit v1.2.3