keynav man page

Hello @ports,

This is 6.6 -stable.

I have been using keynav for several years, but always lacked some
documentation, since neither man keynav nor keynav help give any output.
Of course, there is the /usr/local/share/examples/keynav template, but
it is not as convenient as a man page. I discovered only yesterday that
there is a man page available on-line, keynav.pod.

Since I am not a programmer, and cannot run -current, the only way for
me to contribute to the project is to deal with documentation (and of
course to support OpenBSD foundation) and create the manpage that I was
looking for.

You'll find below a keynav.mdoc file as a proposal for keynav ports.
Any hints to improve the structure with regards to OpenBSD standards
welcome.

I read the mdoc(7) and mandoc(8) man pages, used pod2mdoc to convert
keynav.pod, looked at several base examples (cwm.1, cwm.5, ksh.1,
grep.1, tmux.1) and made the converted file fit mdoc recommandations, as
I understood them.


Here are the main changes I introduced with regards to keynav.pod:
* keystrokes are in angle brackets
* reorder some section options to display them alphabetically
(kept the original order when a re-write might be needed)
* suppressed the Cut&Move section, moved it contents to EXAMPLES;
* created a BUGS section with cut/pasted sentences related to drag.
* suppress CONTACT section, moved it contents to BUGS
* shrink cells shown in cell-table option


--- /dev/null Fri May 1 20:51:33 2020
+++ keynav.mdoc Fri May 1 19:04:39 2020
@@ -0,0 +1,565 @@
+.Dd $Mdocdate$
+.Dt KEYNAV 1
+.Os
+.Sh NAME
+.Nm keynav
+.Nd keyboard navigation tool
+.Sh SYNOPSIS
+.Nm keynav
+.Op optional-startup-commands
+.Sh DESCRIPTION
+.Nm
+is a utility for generally operating your mouse with your keyboard.
+The main usage is to divide the screen into sections, selecting them
+until you end up at the point where you want to move the mouse, or
+click, etc.
+.Pp
+You can pass any valid keynav commands to
+.Nm
+from the command-line.
+Make sure you quote things properly.
+.Pp
+For example, to load another config file or two:
+.Bd -literal -offset indent
+keynav "loadconfig ~/myconfigs/keynavrc,loadconfig ~/myconfig/anotherkeynavrc"
+.Ed
+.Pp
+Another example: daemonize on startup:
+.Bd -literal -offset indent
+keynav daemonize
+.Ed
+.Sh CONFIGURATION
+.Nm
+is configured by default from a config file in your home directory
+.Pa ~/.keynavrc
+or
+.Pa $XDG_CONFIG_HOME/keynav/keynavrc
+per the XDG Base Directory standard (defaulting to
+.Pa ~/.config/keynav/keynavrc
+if
+.Ev XDG_CONFIG_HOME
+is not set).
+.Pp
+The default configuration can be found in the
+.Sx DEFAULT CONFIGURATION
+section.
+.Pp
+.Sq #
+will delimit comments.
+The configuration consists mostly of binding keys to
+.Nm
+commands.
+The following two commands must appear on lines by themselves, not as key
+bindings.
+.Bl -tag -width Ds
+.It Ic clear
+This wil clear all existing keybindings.
+This is useful if, for example, you do not want any of the default
+keybindings that come with
+.Nm .
+.It Ic daemonize
+This will make
+.Nm
+background itself after parsing the config file and setting up
+keybindings.
+If there are errors during keybinding, then
+.Nm
+will not background and will exit with failure.
+.El
+.Pp
+The rest of the configuration has this format
+.Bd -literal -offset indent
+ keybinding keynav-command[,keynav-command,...]
+.Ed
+.Pp
+You can have multiple commands for a single keybinding.
+.Pp
+The way to start
+.Nm
+navigation is to use the
+.Ic start
+command.
+Additionally, any keys with
+.Ic start
+as a command will be grabbed as global hotkeys.
+For example, this configuration:
+.Bd -literal -offset indent
+ ctrl+semicolon start
+ space click 1
+.Ed
+.Pp
+will make
+.Nm
+grab the
+.Aq ctrl + semicolon
+keybinding globally, but it will not grab
+.Aq space .
+The
+.Aq space
+keybinding will only be active while
+.Nm
+is active (after you press a
+key sequence that invokes
+.Ic start
+).
+.Pp
+If you aren't sure what the name of your key is, you can run
+.Xr xev 1
+and press each key you want to learn about while the xev window has
+focus.
+The output will include the keysym name (like Shift_L, or Return, etc)
+.Pp
+Moving on, here are all the keynav commands you can use:
+.Ss CUTS AND MOVES
+Movements are bounded by screen edges.
+See
+.Sx SCREEN EDGES
+for edge and multiple screen handling.
+.Bl -tag -width Ds
+.It Ic cursorzoom Ar width height
+This command centers the
+.Nm
+window on the mouse position and sets the window size to the given width
+and height (in pixels).
+.It Ic cut-down Op Ar value
+This will cut the
+.Nm
+window downwards.
+We will shrink from the top down.
+The default cut
+.Ar value
+, if not specified, is 0.5.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic cut-left Op Ar value
+This will cut the
+.Nm
+window leftwards.
+We will shrink from the right to the left.
+The default cut
+.Ar value
+, if not specified, is 0.5.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic cut-right Op Ar value
+This will cut the
+.Nm
+window rightwards.
+We will shrink from the left to the right.
+The default cut
+.Ar value
+, if not specified, is 0.5.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic cut-up Op Ar value
+This will cut the
+.Nm
+window upwards.
+We will shrink from the bottom upwards.
+The default cut
+.Ar value
+, if not specified, is 0.5.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic move-down Op Ar value
+This will move the window down.
+The default
+.Ar value
+, if not specified, is 1.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic move-left Op Ar value
+This will move the window left.
+The default
+.Ar value
+, if not specified, is 1.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic move-right Op Ar value
+This will move the window right.
+The default
+.Ar value
+, if not specified, is 1.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic move-up Op Ar value
+This will move the window up.
+The default
+.Ar value
+, if not specified, is 1.
+.Pp
+See
+.Sx EXAMPLES
+for what this
+.Ar value
+means.
+.It Ic windowzoom
+This command makes the
+.Nm
+window fit the current application window.
+This is useful if you have your windows in a tiled arrangement.
+.El
+.Ss GRID COMMANDS
+.Bl -tag -width Ds
+.It Ic grid Op Ar COLUMNSxROWS
+The default 'grid' is 2x2.
+If you want more grid cells you can choose
+any number of columns and rows.
+.It Ic grid-nav Op Ar on|off|toggle
+Grid navigation is off by default.
+When turned on, every grid cell will have a two-letter label.
+To select a single cell, you simply type the two letters.
+The
+.Ar toggle
+value will toggle grid-nav.
+.It Ic cell-select Op Ar value
+Cell selection is similar to
+.Ic grid-nav ,
+but less visual.
+You would bind keys to select specific cells.
+With
+.Ic cell-select ,
+there are no labels.
+.Pp
+The
+.Ar value
+can be one of two formats.
+First, the
+.Ar COLUMNxROW
+syntax.
+.Sq cell-select 3x1
+will select column 3, row 1. The second format is simply a
+.Ar number .
+The
+.Ar number
+represents the counting of the cell, starting at the top left and
+working right.
+.Pp
+A visual might help.
+With 'grid 3x3' the following is used with
+.Ic cell-select :
+.Bd -literal
++----------------------------------+
+| | | |
+| 1x1 | 2x1 | 3x1 |
+| 1 | 2 | 3 |
+| | | |
+|----------+-----------+-----------|
+| | | |
+| 1x2 | 2x2 | 3x2 |
+| 4 | 5 | 6 |
+| | | |
+|----------+-----------+-----------|
+| | | |
+| 1x3 | 2x3 | 3x3 |
+| 7 | 8 | 9 |
+| | | |
++----------------------------------+
+.Ed
+.El
+.Ss MOUSE COMMANDS
+.Bl -tag -width Ds
+.It Ic click Op Ar button
+This command will send a mouse click.
+It does not move the mouse, so the click will go wherever the mouse is
+positioned.
+.Pp
+The
+.Em button
+values are:
+.Bl -tag -width Ds -offset indent -compact
+.It Ic 1
+left
+.It Ic 2
+middle
+.It Ic 3
+right
+.It Ic 4
+wheel up
+.It Ic 5
+wheel down.
+.El
+.It Ic doubleclick Op Ar button
+Double clicks, but otherwise is the same as
+.Ic click .
+.It Ic drag Ar button Op Ar modifier-keys
+Starts or ends dragging, depending on state (dragging or not).
+The button values are the same as for
+.Ic click .
+The modifier-keys value allows you to specify any keys to 'hold' while
+dragging, such as
+.Aq alt
+or
+.Aq shift .
+.It Ic warp
+This command moves the mouse pointer to the center of the
+.Nm
+window.
+.El
+.Ss MISC COMMANDS
+.Bl -tag -width Ds
+.It Ic record Op Ar file
+Record actions for replay later.
+Very similar to
+.Sy vim
+.Sq q
+command.
+The first key you press after starting a new recording becomes the
+active key for that recording.
+You cannot record to keys that are already bound to other commands, but
+you can overwrite existing recordings.
+If you want to persist recordings across
+.Nm
+processes (like system or
+.Nm
+restarts, etc) you will want to specify a file, I use
+.Pa ~/.keynav_macros
+but any path will do.
+.Pp
+For example this config:
+.Dl q record
+Pressing
+.Aq q
+then
+.Aq l
+will start recording to the
+.Aq l
+key assuming it's not already bound.
+Then, to stop recording, press
+.Aq q
+again (the record key as configured).
+After that, to replay that recording, simply press
+.Ic playback
+and then
+.Aq l
+while the
+.Nm
+window is active.
+.It Ic playback
+Replay a previously recorded sequence of keys.
+After invoking the command,
+.Nm
+will wait for the key of a previously
+recorded session.
+.It Ic sh Ar command
+Run a command with
+.Bd -literal -offset indent
+/bin/sh -c <command>
+.Ed
+This is slightly outside the scope of keynav, but executing arbitrary
+commands is very useful when combined with
+.Sy xdotool .
+For example, I use this to activate Google Chrome and focus the URL bar:
+.Bd -literal -offset indent
+g sh "xdotool search --name -- '- Google Chrome' windowactivate key --window 0 --clearmodifiers ctrl+l",end
+.Ed
+.It Ic loadconfig Ar path
+Load an additional config file.
+Paths like
+.Pa ~/foo/bar
+are valid and the
+.Pa ~
+will be replaced with your home directory (Value of
+.Ev HOME
+in environment).
+.It Ic start
+Start
+.Nm .
+Any keys with this binding will operate as global bindings to activate
+.Nm .
+.It Ic end
+End
+.Nm .
+This hides the
+.Nm
+window and otherwise makes
+.Nm
+inactive until the next
+.Ic start
+command.
+.It Ic toggle-start
+Toggle
+.Nm .
+If
+.Nm
+is active, this makes it inactive.
+If
+.Nm
+is inactive, this makes it active.
+.It Ic history-back
+Go backwards in command history.
+All activity is tracked in history, so if you want to undo a movement,
+etc, simply use this command.
+.It Ic quit
+Exit
+.Nm .
+The process will shutdown.
+.It Ic restart
+Restart
+.Nm .
+Useful for reloading the configuration.
+.Dv SIGHUP
+and
+.Dv SIGUSR1
+also invoke this command.
+.El
+.Sh SCREEN EDGES
+When moving the
+.Nm
+window around, the window will not go outside of
+the screen boundaries.
+One exception is for multiple displays: a movement outside of the
+current screen can move the
+.Nm
+window to the next screen if
+.Nm
+thinks it's the right thing to do.
+.Pp
+If a move would take you beyond the screen borders, then the window will
+stop moving at the edge.
+.Sh DEFAULT CONFIGURATION
+.Bd -literal -offset indent
+ clear
+ ctrl+semicolon start
+ Escape end
+ ctrl+bracketleft end
+ q record ~/.keynav_macros
+ shift+at playback
+ a history-back
+ h cut-left
+ j cut-down
+ k cut-up
+ l cut-right
+ shift+h move-left
+ shift+j move-down
+ shift+k move-up
+ shift+l move-right
+ space warp,click 1,end
+ Return warp,click 1,end
+ semicolon warp,end
+ w warp
+ t windowzoom
+ c cursorzoom 300 300
+ e end
+ 1 click 1
+ 2 click 2
+ 3 click 3
+ ctrl+h cut-left
+ ctrl+j cut-down
+ ctrl+k cut-up
+ ctrl+l cut-right
+ y cut-left,cut-up
+ u cut-right,cut-up
+ b cut-left,cut-down
+ n cut-right,cut-down
+ shift+y move-left,move-up
+ shift+u move-right,move-up
+ shift+b move-left,move-down
+ shift+n move-right,move-down
+ ctrl+y cut-left,cut-up
+ ctrl+u cut-right,cut-up
+ ctrl+b cut-left,cut-down
+ ctrl+n cut-right,cut-down
+.Ed
+.Sh EXAMPLES
+To make
+.Aq v
+paste things:
+.Pp
+.Dl v sh "xdotool key shift+Insert",end
+.Pp
+To make
+.Aq v
+cut and keep 75% of the window's height.
+That is, if the window is 1000 pixels tall, then after this cut it will
+be 750 pixels tall.
+.Pp
+.Dl v cut-up 0.75
+Values in the range [0,1] are taken to mean a percentage of the window's
+width or height.
+.Pp
+To make
+.Aq v
+move the window to the left by the full width of the window.
+The '1' here means 100% of the width.
+.Pp
+.Dl v move-left 1
+.Pp
+To make
+.Aq v
+move the window down by 100 pixels.
+Values > 1 are taken literally as pixel units.
+.Pp
+.Dl v move-down 100
+.Pp
+See the original author's
+.Pa keynavrc
+as an example, here:
+.Lk https://raw.githubusercontent.com/yjftsjthsd-g/keynav/master/examples/keynavrc.jordan
+.Sh SEE ALSO
+Related:
+xdotool (1)
+.Pp
+Original project site:
+.Lk http://www.semicomplete.com/projects/keynav
+.Pp
+Github:
+.Lk https://github.com/yjftsjthsd-g/keynav
+.Sh AUTHORS
+.Nm
+was originally written by
+.An Jordan Sissel .
+.Pp
+This version includes changes, enhancements, and fixes from at least the
+following (based on git logs):
+.An -nosplit
+.An Brian Cole ,
+.An Dabo Ross ,
+.An Denis Kasak ,
+.An Jordan Sissel ,
+.An Krister Svanlund ,
+.An Marek Marecki ,
+.An Shou Ya ,
+.An Stanislav Seletskiy ,
+.An Tyler Akins ,
+.An aszlig ,
+.An lilydjwg ,
+.An Alex Daniel ,
+.An Michael Sloan
+.Sh BUGS
+Dragging sometimes doesn't work.
+I'm trying to make it more reliable.
+File a bug if you are interested in this feature working :)
+.Pp
+For all questions, comments, bugs, and feature requests, please open an
+issue at:
+.Pp
+.Lk https://github.com/yjftsjthsd-g/keynav/issues