From 0ef0625dc23bfcd543c0fe70043936946e25250e Mon Sep 17 00:00:00 2001 From: Harry Jeffery Date: Wed, 29 Nov 2017 21:57:24 +0000 Subject: Write docs with asciidoc --- Makefile | 4 + README.md | 3 +- doc/imv.1 | 167 --------------------------------------- doc/imv.1.txt | 189 ++++++++++++++++++++++++++++++++++++++++++++ doc/imv.5.txt | 234 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ files/imv_config | 74 +----------------- 6 files changed, 431 insertions(+), 240 deletions(-) delete mode 100644 doc/imv.1 create mode 100644 doc/imv.1.txt create mode 100644 doc/imv.5.txt diff --git a/Makefile b/Makefile index 15caa29..016fa8d 100644 --- a/Makefile +++ b/Makefile @@ -50,13 +50,17 @@ clean: $(RM) -Rf $(BUILDDIR) install: $(TARGET) + a2x --no-xmllint --doctype manpage --format manpage doc/imv.1.txt + a2x --no-xmllint --doctype manpage --format manpage doc/imv.5.txt install -D -m 0755 $(TARGET) $(DESTDIR)$(BINPREFIX)/imv install -D -m 0644 doc/imv.1 $(DESTDIR)$(MANPREFIX)/man1/imv.1 + install -D -m 0644 doc/imv.5 $(DESTDIR)$(MANPREFIX)/man5/imv.5 install -D -m 0644 files/imv.desktop $(DESTDIR)$(DATAPREFIX)/applications/imv.desktop install -D -m 0644 files/imv_config $(DESTDIR)$(CONFIGPREFIX)/imv_config uninstall: $(RM) $(DESTDIR)$(BINPREFIX)/imv $(RM) $(DESTDIR)$(MANPREFIX)/man1/imv.1 + $(RM) $(DESTDIR)$(MANPREFIX)/man5/imv.5 $(RM) $(DESTDIR)$(DATAPREFIX)/applications/imv.desktop @echo "$(DESTDIR)$(CONFIGPREFIX)/imv_config has not been removed. Please remove it manually." diff --git a/README.md b/README.md index c412880..d80fdc0 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,8 @@ cycling through the list. Installation ------------ -`imv` depends on `pthreads`, `FontConfig`, `SDL2`, `SDL_TTF`, and `FreeImage`. +`imv` depends on `pthreads`, `FontConfig`, `SDL2`, `SDL_TTF`, `FreeImage`, +and `asciidoc`. $ make # make install 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* :: + Start with the given path, or index selected. + +*-e* :: + Set the overlay's font name. + +*-b* :: + Set the background colour. Can either be a 6-digit hexadecimal colour code + or 'checks' to show a chequered background. + +*-t* :: + 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* :: + Pan the view by the given amounts. + +*select_rel* :: + Select a different image. '1' is the next one, '-1' is the previous. + +*select_abs* :: + 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* :: + 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* :: + 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* :: + Set the current scaling mode. + +*slideshow_duration* :: + 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 +with contributions from other developers. + +Full source code and other information can be found at +. + +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* = :: + Set the background in imv. Can either be a 6-digit hexadecimal colour code, + or 'checks' for a chequered background. Defaults to '000000' + +*fullscreen* = :: + Start imv fullscreen. Defaults to 'false'. + +*list_files_at_exit* = :: + Print open files to stdout at exit, each on a separate line. + Defaults to 'false'. + +*loop_input* = :: + Return to first image after viewing the last one. Defaults to 'true'. + +*overlay* = :: + Start with the overlay visible. Defaults to 'false'. + +*overlay_font* = :: + Use the specified font in the overlay. Defaults to 'Monospace:24'. + +*overlay_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* = :: + Load input paths recursively. Defaults to 'false'. + +*scaling_mode* = :: + 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* = :: + 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* = :: + Stay full screen even when imv loses focus. Defaults to 'false'. + +*suppess_default_binds* = :: + Disable imv's built-in binds so they don't conflict with custom ones. + Defaults to 'false'. + +*title_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* = :: + 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: +''. + +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 '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) diff --git a/files/imv_config b/files/imv_config index f676963..443e2f2 100644 --- a/files/imv_config +++ b/files/imv_config @@ -2,64 +2,11 @@ [options] -# Start fullscreen -# fullscreen = true - -# Start with overlay visible -# overlay = true - -# Method used for upscaling images. Can be 'linear' or 'nearest_neighbour' -# upscaling_method = linear - -# Recurse into subdirectories when opening a path -# recursive = true - -# When we reach the end of the open images, don't go back to the start again -# loop_input = false - -# Print all the images still open when we quit -# list_files_at_exit = true - -# Scaling mode, one of: none, shrink, and full -# scaling_mode = none - -# Background, either a hex colour code or 'checks' -# background = 000000 - -# Change to the next image automatically after 3 seconds -# slideshow_duration = 3 - -# Font to use for the overlay -# overlay_font = Monospace:24 - -# Stay fullscreen when we lose focus -# stay_fullscreen_on_focus_loss = true - -# Disable imv's builtin binds so they don't conflict with the ones in this config +# Suppress built-in key bindings, and specify them explicitly in this +# config file. suppress_default_binds = true -# Set the text used for the title and overlay. Environment variables -# can be used, as can $(command) shell expansion, etc. -# imv exports details about its state and the current image through various -# environment variables. - -# Available values: -# imv_current_file - path of currently opened image -# imv_scaling_mode - name of the current scaling mode -# imv_loading - 1 when 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 current image -# imv_height - height of 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 - -# title_text = imv - [${imv_current_index}/${imv_file_count}] $imv_current_file -# overlay_text = ${imv_width}x${imv_height} @$ {imv_scale}% [$imv_scaling_mode] - [aliases] -# Create some command aliases q = quit next = select_rel 1 previous = select_rel -1 @@ -67,23 +14,6 @@ n = select_rel 1 p = select_rel -1 [binds] -# Add some custom key bindings to imv - -# Some keys have special names: -# < -> Less -# > -> Greater -# [ -> LeftSquareBracket -# ] -> RightSquareBracket -# = -> Equals -# Left arrow key -> Left -# Up arrow key -> Up -# Right arrow key -> Right -# Down arrow key -> Down - -# Keys can have the modifiers 'Ctrl+' 'Meta+' and 'Shift+' in front of them, -# in that order. Keys with special names, or with a modifier are enclosed in -# '<' and '>'. - q = quit # Image navigation -- cgit v1.2.3