Write docs with asciidoc

3 files changed, 423 insertions, 167 deletions

diff --git a/doc/imv.1 b/doc/imv.1
deleted file mode 100644
index a117f10..0000000
--- a/doc/imv.1
+++ /dev/null
@@ -1,167 +0,0 @@
-.Dd August 22, 2017
-.Dt IMV 1
-.Os
-.Sh NAME
-.Nm imv
-.Nd view images
-.Sh SYNOPSIS
-.Nm
-.Op Fl adfhlrSsux
-.Op Fl b Ar color
-.Op Fl e Ar font:size
-.Op Fl n Ar position
-.Op Fl t Ar seconds
-.Op Ar
-.Sh DESCRIPTION
-.Nm
-is an image viewer for
-.Xr X 7
-and Wayland, aimed at users of tiling window managers.
-It supports a wide variety of image file formats, including animated gif files.
-.Nm
-reloads the current image if it detects changes to the file.
-.Pp
-.Nm
-accepts following flags:
-.Bl -tag -width Ds
-.It Fl a
-.Dq actual size
-mode: show images at actual size.
-.It Fl b Ar color
-Set the background color.
-Either
-.Ar checks
-or a hex color value.
-Defaults to
-.Ar 000000 .
-.It Fl e Ar font:size
-Set the font used by the overlay.
-.Ar font
-can be any valid system font, such as FreeSans, FreeMono, etc.
-Defaults to
-.Ar Monospace:24 ,
-which is the default monospace font, as configured in
-.Xr fonts.conf 5 .
-.It Fl d
-Show textual overlay.
-.It Fl f
-Start in full screen mode.
-.It Fl h
-Print help message.
-.It Fl l
-List open files on exit.
-.It Fl n Ar position
-Start at specific position in image list.
-.Ar position
-may be expressed as a number or as a path of an image.
-.It Fl r
-Recursively search input paths for files.
-.It Fl S
-.Dq scale to fit
-mode: grow or shrink image to fit window.
-This is the default.
-.It Fl s
-.Dq shrink to fit
-mode: shrink image to fit window.
-Images that are smaller then window are shown at actual size.
-.It Fl t Ar seconds 
-Set the slideshow delay in seconds.
-Fractional numbers are accepted.
-Setting this to zero disables slideshow mode, which is the default.
-.It Fl u
-Use nearest neighbour resampling.
-Recommended for pixel art.
-.It Fl x
-Quit after the final image.
-.El
-.Ss Reading from standard input
-When run with argument
-.Sq - ,
-.Nm
-reads image from standard input.
-Argument
-.Sq -
-may occur among other arguments, but only once.
-.Pp
-If no arguments supplied, reads list of files from standard input.
-.Pp
-.Sh CONTROLS
-.Bl -tag -width Ds
-.It Aq Cm left mouse button
-Pan relative to mouse motion.
-.It Aq Cm mouse wheel
-Zoom in and out.
-.It Cm q
-Quit.
-.It Ao Cm left Ac | Cm \&[
-Change to previous image.
-.It Ao Cm right Ac | Cm \&]
-Change to next image.
-.It Cm i | Cm + | Aq Cm up
-Zoom in.
-.It Cm o | Cm - | Aq Cm down
-Zoom out.
-.It Cm r
-Reset view
-.It Cm a
-View image at actual size.
-.It Cm c
-Center image in window.
-.It Cm h
-Pan left.
-.It Cm j
-Pan down.
-.It Cm k
-Pan up.
-.It Cm l
-Pan right.
-.It Cm x
-Close current image.
-.It Cm X
-Close current image and remove it from disk.
-.It Cm d
-Toggle display of textual overlay.
-.It Cm f
-Toggle fullscreen.
-.It Cm SPACE
-Toggle gif playback.
-.It Cm .
-Step forward one frame (when playing gifs).
-.It Cm p
-Print current image path to stdout
-.It Cm s
-Switch scaling mode.
-Available modes are:
-.Dq actual size
-.Pq don't scale images ,
-.Dq best fit
-.Pq downscale images to fit window, but don't scale smaller images ,
-.Dq perfect fit
-.Pq upscale or downscale images to fit window
-.Pq default ,
-in this order.
-.It Cm t
-Increase slideshow delay by one second
-.It Cm T
-Decrease slideshow delay by one second.
-When delay is zero, slideshow mode is disabled.
-.Sh EXAMPLES
-Load all files from directory
-.Pa dir :
-.Pp
-.Dl $ ls dir | imv
-or
-.Dl $ ls dir | xargs imv
-.Sh LEGAL
-This program is free software; you can redistribute it and/or modify it under
-the terms of the GNU General Public License as published by the Free Software
-Foundation; either version 2 of the License, or (at your option) any later
-version.
-.Pp
-This software uses the FreeImage open source image library.
-See
-.Lk http://freeimage.sourceforge.net
-for details.
-FreeImage is used under the GNU GPLv2.
-.Sh AUTHOR
-.An Harry Jeffery
diff --git a/doc/imv.1.txt b/doc/imv.1.txt
new file mode 100644
index 0000000..46662f4
--- /dev/null
+++ b/doc/imv.1.txt
@@ -0,0 +1,189 @@
+/////
+vim:set ts=4 sw=4 tw=82 noet:
+/////
+:quotes.~:
+
+imv (1)
+=======
+
+Name
+----
+imv - Image viewer for X11 and Wayland
+
+Description
+-----------
+
+imv is an image viewer for X11 and Wayland, aimed at users of tiling window
+managers. It supports a wide variety of image file formats, including animated
+gif files. imv will automatically reload the current image, if it is changed on
+disk.
+
+Synopsis
+--------
+'imv' [options] [paths...]
+
+Options
+-------
+
+*-h*::
+	Show help message and quit.
+
+*-r*::
+	Load directories recursively.
+
+*-a*::
+	Default to displaying images at actual size.
+
+*-s*::
+	Default to shrinking images to fit the window, but not expanding them.
+
+*-S*::
+	Default to scaling images to fit the window perfectly.
+
+*-u*::
+	Set scaling method to 'nearest neighbour'.
+
+*-d*::
+	Start with overlay visible.
+
+*-x*::
+	Disable looping of input paths.
+
+*-l*::
+	List open files at exit.
+
+*-n* <path|index>::
+	Start with the given path, or index selected.
+
+*-e* <font_name>::
+	Set the overlay's font name.
+
+*-b* <background>::
+	Set the background colour. Can either be a 6-digit hexadecimal colour code
+	or 'checks' to show a chequered background.
+
+*-t* <slideshow_duration>::
+	Start in slideshow mode, with each image shown for the given number of
+	seconds.
+
+Commands
+--------
+
+Commands can be entered by pressing *:*. imv supports the following commands:
+
+*quit*::
+	Quit imv.
+
+*pan* <x> <y>::
+	Pan the view by the given amounts.
+
+*select_rel* <offset>::
+	Select a different image. '1' is the next one, '-1' is the previous.
+
+*select_abs* <index>::
+	Select an image by index. '1' is the first image, '2' the second, etc.
+	The last image can be indexed as '-1', the second last as '-2'.
+
+*zoom* <amount|'actual'>::
+	Zoom into the image by the given amount. Negative values zoom out.
+	'actual' resets the zoom to 100%, showing the image at its actual size.
+
+*close*::
+	Close the currently selected image.
+
+*fullscreen*::
+	Toggle fullscreen.
+
+*overlay*::
+	Toggle the overlay.
+
+*exec* <command>::
+	Execute a shell command. imv provides various environment variables to the
+	command executed. These are documented in the 'Environment Variables'
+	section.
+
+*center*::
+	Recenter the selected image.
+
+*reset*::
+	Reset the view, centering the image and using the current scaling mode to
+	rescale it.
+
+*next_frame*::
+	If an animated gif is currently being displayed, load the next frame.
+
+*toggle_playing*::
+	Toggle playback of the current image if it is an animated gif.
+
+*scaling_mode* <none|shrink|full>::
+	Set the current scaling mode.
+
+*slideshow_duration* <amount>::
+	Change the slideshow duration by the given amount in seconds.
+
+Configuration
+-------------
+
+The path to a config file can be given via the *$imv_config* environment
+variable. If not found, imv will search for it in the following locations:
+
+- $HOME/.imv_config
+- $HOME/.imv/config
+- $XDG_CONFIG_HOME/imv/config (recommended)
+- /usr/local/etc/imv_config
+- /etc/imv_config
+
+A default config file is shipped with imv into /etc/imv_config
+
+For documentation on the config file format, see **imv**(5).
+
+Environment Variables
+---------------------
+
+When imv executes a command, it provides a number of environment variables,
+exposing imv's state. These environment variables are also available when
+customising the window's title, or the overlay text.
+
+*$imv_current_file*::
+	Path of currently selected image.
+
+*$imv_scaling_mode*::
+	Name of the current scaling mode.
+
+*$imv_loading*::
+	1 if a new image is loading, 0 otherwise.
+
+*$imv_current_index*::
+	Index of current image, from 1-N.
+
+*$imv_file_count*::
+	Total number of files.
+
+*$imv_width*::
+	Width of the current image.
+
+*$imv_height*::
+	Height of the current image.
+
+*$imv_scale*::
+	Scaling of current image in percent.
+
+*$imv_slideshow_duration*::
+	Number of seconds each image is shown for.
+
+*$imv_slideshow_elapsed*::
+	How long the current image has been shown for.
+
+Authors
+-------
+
+imv is written and maintained by Harry Jeffery <harry@exec64.co.uk>
+with contributions from other developers.
+
+Full source code and other information can be found at
+<https://github.com/eXeC64/imv>.
+
+See Also
+--------
+
+**imv**(5)
diff --git a/doc/imv.5.txt b/doc/imv.5.txt
new file mode 100644
index 0000000..0328dfb
--- /dev/null
+++ b/doc/imv.5.txt
@@ -0,0 +1,234 @@
+/////
+vim:set ts=4 sw=4 tw=82 noet:
+/////
+:quotes.~:
+
+imv (5)
+=======
+
+Name
+----
+imv - imv configuration file
+
+Description
+-----------
+
+imv can be customised with this configuration file, changing its default
+behaviour, key bindings, and appearance.
+
+The imv configuration file is an ini-style file, with multiple 'key = value'
+settings, separated into several '[section]'s.
+
+Options
+-------
+
+The *[options]* section accepts the following settings:
+
+*background* = <hex-code|'checks'>::
+	Set the background in imv. Can either be a 6-digit hexadecimal colour code,
+	or 'checks' for a chequered background. Defaults to '000000'
+
+*fullscreen* = <true|false>::
+	Start imv fullscreen. Defaults to 'false'.
+
+*list_files_at_exit* = <true|false>::
+	Print open files to stdout at exit, each on a separate line.
+	Defaults to 'false'.
+
+*loop_input* = <true|false>::
+	Return to first image after viewing the last one. Defaults to 'true'.
+
+*overlay* = <true|false>::
+	Start with the overlay visible. Defaults to 'false'.
+
+*overlay_font* = <typeface:size>::
+	Use the specified font in the overlay. Defaults to 'Monospace:24'.
+
+*overlay_text* = <text>::
+	Use the given text as the overlay's text. The provided text is shell
+	expanded, so the output of commands can be used: '$(ls)' as can environment
+	variables, including the ones accessible to imv's 'exec' command.
+
+*recursively* = <true|false>::
+	Load input paths recursively. Defaults to 'false'.
+
+*scaling_mode* = <none|shrink|full>::
+	Set scaling mode to use. 'none' will show each image at its actual size.
+	'shrink' will scale down the image to fit inside the window. 'full' will
+	both scale up and scale down the image to fit perfectly inside the window.
+	Defaults to 'full'.
+
+*slideshow_duration* = <duration>::
+	Start imv in slideshow mode, and set the amount of time to show each image
+	for in seconds. Defaults to '0', i.e. no slideshow.
+
+*stay_fullscreen_on_focus_loss* = <true|false>::
+	Stay full screen even when imv loses focus. Defaults to 'false'.
+
+*suppess_default_binds* = <true|false>::
+	Disable imv's built-in binds so they don't conflict with custom ones.
+	Defaults to 'false'.
+
+*title_text* = <text>::
+	Use the given text as the window's title. The provided text is shell
+	expanded, so the output of commands can be used: '$(ls)' as can environment
+	variables, including the ones accessible to imv's 'exec' command.
+
+*upscaling_method* = <linear|nearest_neighbour>::
+	Use the specified method to upscale images. Defaults to 'linear'.
+
+Aliases
+-------
+
+The *[aliases]* section allows imv's commands to be aliases. For example:
+'q = quit' would add a 'q' command that simply executes the 'quit' command.
+And 'next = select_rel 1' would add a 'next' command to imv.
+
+Binds
+-----
+
+The *[binds]* section allows custom key bindings to be added to imv.
+
+Binds are in the format 'key combination = command'. A key combination can
+consist of multiple keys in succession.
+
+Single keys such as 'q' are just that: 'q = quit' will bind the 'q' key to the
+'quit' command.
+
+Modifier keys can be specified by prefixing them: 'Ctrl+q', 'Meta+f',
+'Shift+g'. If multiple modifier keys are desired, they are specified in the
+order 'Ctrl+Meta+Shift'. When a key's name is more than a single character,
+or a modifier is used it must be wrapped in '<' and '>', for example:
+'<Ctrl+q>'.
+
+Multiple keys in succession can be specified by listing them in order:
+'gg = select_abs 0' will bind two presses of the 'g' key to jump to the first
+image, and '<Ctrl+a>p = exec echo hi' will bind the key sequence of 'Ctrl+a'
+followed by 'p' to executing the shell command 'echo hi'.
+
+N.B. Special characters such as '!' are not named directly, and are accessed
+by their regular key, combined with the shift modifier: 'Shift+1'.
+
+Some keys, such as '<', and '>' have special names, to avoid conflits with
+the bind syntax, or the config file format. Other keys with no character
+associated with them, such as the 'Return' key or the arrow keys also have
+special names. These are as follows:
+
+*Application*::
+	The Application / Compose / Context Menu / Alt Gr key.
+
+*AudioMute*::
+	The mute volume key.
+
+*AudioNext*::
+	The next track media key.
+
+*AudioPlay*::
+	The play media key.
+
+*AudioPrev*::
+	The previous track media key.
+
+*AudioStop*::
+	The stop media key.
+
+*Backspace*::
+	The backspace key.
+
+*BrightnessDown*::
+	The brightness down key.
+
+*BrightnessUp*::
+	The brightness up key.
+
+*Cancel*::
+	The cancel key.
+
+*Clear*::
+	The clear key.
+
+*Delete*::
+	The delete key.
+
+*Down*::
+	The down arrow key.
+
+*Eject*::
+	The eject key.
+
+*End*::
+	The end key.
+
+*Escape*::
+	The Esc / escape key.
+
+*Equals*::
+	The = key.
+
+*F<1-24>*::
+	The F keys.
+
+*Home*::
+	The home key.
+
+*Keypad <00|000|0-9>*::
+	The numeric keypad number keys.
+
+*Keypad Backspace*::
+	The numeric keypad backspace key.
+
+*Keypad Clear*::
+	The numeric keypad clear key.
+
+*Keypad Enter*::
+	The numeric keypad enter key.
+
+*Keypad -*::
+	The numeric keypad subtract key.
+
+*Keypad +*::
+	The numeric keypad add key.
+
+**Left*::
+	The left arrow key.
+
+LeftSquareBracket*::
+	The [ key.
+
+*Mute*::
+	The mute key.
+
+*PageDown*::
+	The page down key.
+
+*PageUp*::
+	The page down key.
+
+*Pause*::
+	The pause key.
+
+*Return*::
+	The return / enter key.
+
+*Right*::
+	The right arrow key.
+
+*RightSquareBracket*::
+	The ] key.
+
+*Space*::
+	The space bar.
+
+*Up*::
+	The up arrow key.
+
+*VolumeDown*::
+	The volume down key.
+
+*VolumeUp*::
+	The volume up key.
+
+See Also
+--------
+
+**imv**(1)