aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPřemysl Eric Janouch <p@janouch.name>2020-10-27 04:05:54 +0100
committerPřemysl Eric Janouch <p@janouch.name>2020-10-27 04:17:52 +0100
commitc20d3780b2ac9d1edb143fc18f7f6965867f74f9 (patch)
treebc6ff362af8daa5a461c424a4af9b509ab05f97e
parent22725ba3b7114baf88f186330ce2ebb16794e1d8 (diff)
downloadsdn-c20d3780b2ac9d1edb143fc18f7f6965867f74f9.tar.gz
sdn-c20d3780b2ac9d1edb143fc18f7f6965867f74f9.tar.xz
sdn-c20d3780b2ac9d1edb143fc18f7f6965867f74f9.zip
Make the manpages mostly acceptable
Closes #1
-rw-r--r--README.adoc10
-rw-r--r--sdn-install.111
-rw-r--r--sdn.186
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.