diff options
| author | Přemysl Eric Janouch <p@janouch.name> | 2022-01-24 08:41:05 +0100 |
|---|---|---|
| committer | Přemysl Eric Janouch <p@janouch.name> | 2022-01-25 05:54:00 +0100 |
| commit | ee71fb0dd0cd3e8d1cfdd2eae9b4b4e741e51d6a (patch) | |
| tree | 9b74e948237f734d4c03febeb537d8e3c4075ce1 | |
| parent | 381e5f57c76d978994b6cdeecc8f9a19717ed12b (diff) | |
| download | fiv-ee71fb0dd0cd3e8d1cfdd2eae9b4b4e741e51d6a.tar.gz fiv-ee71fb0dd0cd3e8d1cfdd2eae9b4b4e741e51d6a.tar.xz fiv-ee71fb0dd0cd3e8d1cfdd2eae9b4b4e741e51d6a.zip | |
Start a basic user guide
Move some information out there from the README.
| -rw-r--r-- | README.adoc | 25 | ||||
| -rw-r--r-- | docs/fiv.html | 120 | ||||
| -rw-r--r-- | docs/fiv.webp (renamed from fiv.webp) | bin | 155162 -> 155162 bytes | |||
| -rw-r--r-- | docs/stylesheet.css | 8 | ||||
| -rw-r--r-- | fiv.c | 22 | ||||
| -rw-r--r-- | meson.build | 13 |
6 files changed, 164 insertions, 24 deletions
diff --git a/README.adoc b/README.adoc index f43cc59..d303cee 100644 --- a/README.adoc +++ b/README.adoc @@ -3,7 +3,7 @@ fiv 'fiv' is a slightly unconventional, general-purpose image browser and viewer. -image::fiv.webp["Screenshot of both the browser and the viewer"] +image::docs/fiv.webp["Screenshot of both the browser and the viewer"] Features -------- @@ -22,7 +22,7 @@ Explicit non-goals - Following the latest GNOME HIG to the letter--header bars are deliberately avoided, for their general user hostility. - Portability to non-UNIXy systems, although patches are welcome. - - Memory efficiency is secondary to both performance and development time. + - Memory efficiency is secondary to both performance and development effort. Aspirations ----------- @@ -40,7 +40,7 @@ Build dependencies: Meson, pkg-config + Runtime dependencies: gtk+-3.0, glib>=2.64, pixman-1, shared-mime-info, libturbojpeg, libwebp, spng>=0.7.0 + Optional dependencies: lcms2, LibRaw, librsvg-2.0, xcursor, libheif, libtiff, -gdk-pixbuf-2.0, ExifTool +gdk-pixbuf-2.0, ExifTool, resvg (unstable API, needs to be requested explicitly) $ git clone --recursive https://git.janouch.name/p/fiv.git $ meson builddir @@ -52,23 +52,10 @@ direct installations. To test the program, help it find its custom thumbnailer: $ PATH=$(pwd):$PATH ./fiv -Pressing F1 will give you a convenient list of keyboard shortcuts. - -Configuration +Documentation ------------- -The standard means to adjust the looks of the program is through GTK+ 3 CSS. -As an example, to tightly pack browser items, put the following in your -_~/.config/gtk-3.0/gtk.css_: - - fiv-browser { -FivBrowser-spacing: 0; padding: 0; border: 0; margin: 0; } - -Similarly, you can adjust some of the key bindings, as per the command table -in link:fiv-view.h[]: - - @binding-set ViewBindings { bind 'p' { 'command' (print) }; } - fiv-view { -gtk-key-bindings: ViewBindings; } - -Should you want to experiment, you will find the GTK+ inspector very helpful. +For information concerning usage, refer to link:docs/fiv.html[the user guide], +which can be invoked from within the program by pressing F1. Contributing and Support ------------------------ diff --git a/docs/fiv.html b/docs/fiv.html new file mode 100644 index 0000000..b913f0d --- /dev/null +++ b/docs/fiv.html @@ -0,0 +1,120 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="UTF-8"> +<title>fiv: User Guide</title> +<link rel="stylesheet" href="stylesheet.css"> +<style> +q:lang(en):before { content: "‘"; } +q:lang(en):after { content: "’"; } +</style> +</head> +<body> + +<h1>fiv: User Guide</h1> + +<p class="details"> +<span id="author">Přemysl Eric Janouch</span><br> +<span id="email"><a href="mailto:p@janouch.name">p@janouch.name</a></span><br> +<span id="revnumber">version 0.0.0,</span> +<span id="revdate">2022-01-25</span> + +<p class="figure"><img src="fiv.webp" alt="fiv's browser and viewer"> + +<h2>Introduction</h2> + +<p><i>fiv</i> is a general-purpose image browser and viewer. This document will +guide you through the application and help to familiarize you with it. + +<h2>Controls</h2> + +<p><i>fiv</i> is designed with computer mice having dedicated forwards/backwards +and page up/down buttons in mind, such as SteelSeries Sensei series. Ozone Neon +series may also be mapped this way. Your experience may be degraded with other +kinds of devices. + +<p>Controls should generally be accessible through the keyboard. Pressing Ctrl+? +will give you a convenient overview of all shortcuts. In addition to these, +remember that you may often use Ctrl+Tab and F6 to navigate to different groups +of widgets. + +<h2>Browser</h2> + +<p><i>fiv</i> normally starts in a file browser view. On the left side of the +window, you'll find your GTK+ bookmarks, mounted locations as recognized by +GVfs, an item for entering arbitrary filesystem paths or URIs, view controls, +and finally breadcrumbs leading to the currently opened directory, as well as +its descendants. + +<p>You can open items in a new window either by middle clicking on them either +directly, or with the Ctrl key pressed down. Right clicking the directory view +offers a context menu for opening files, or even the directory itself, +in a different application. + +<h2>Viewer</h2> + +<p>The image viewer may be both entered (so long as you have a file selected) +and exited using the Enter key. This way you may easily switch between the two +modes. When using the mouse, the forwards and backwards buttons will fulfill +the same function. + +<p>Double clicking the image switches full-screen view, and the mouse wheel +adjusts the zoom level. + +<p>Files are iterated in the same order, and using the same filtering as in +the browser. + +<p> + +<h2>File formats</h2> + +<p>The list of all supported file formats may be obtained by running: + +<pre> +fiv --list-supported-media-types +</pre> + +Unless it has been turned off in your installation, you may extend it through +gdk-pixbuf modules. + +<h2>Thumbnails</h2> + +<p><i>fiv</i> uses a custom way of storing thumbnails, and doesn't currently +provide any means of invalidating this cache. Should you find out that your +<i>~/.cache/thumbnails</i> directory is taking up too much space, run: + +<pre> +rm -rf ~/.cache/thumbnails/wide-* +</pre> + +<h2>Configuration</h2> + +<p>The standard means to adjust the looks of the program is through GTK+ 3 CSS. +As an example, to tightly pack browser items, put the following in your +<i>~/.config/gtk-3.0/gtk.css</i>: + +<pre> +fiv-browser { -FivBrowser-spacing: 0; padding: 0; border: 0; margin: 0; } +</pre> + +<p>Similarly, you can adjust some of the key bindings, as per the command table +in the <i>fiv-view.h</i> source file: + +<pre> +@binding-set ViewBindings { bind 'p' { 'command' (print) }; } +fiv-view { -gtk-key-bindings: ViewBindings; } +</pre> + +<p>Should you want to experiment, you will find the GTK+ inspector very helpful. + +<script> +var toc = '', all = document.querySelectorAll('h2') +for (var i = 0; i < all.length; i++) { + var name = all[i].innerHTML.replace(/[^0-9a-z]/ig, '-') + toc += '<li><p><a href="#' + name + '">' + all[i].innerHTML + '</a></li>' + all[i].id = name + all[i].innerHTML = (i + 1) + '. ' + all[i].innerHTML +} +all[0].insertAdjacentHTML('beforebegin', + '<h2>Table of Contents</h2><ol>' + toc + '</ol>') +</script> Binary files differdiff --git a/docs/stylesheet.css b/docs/stylesheet.css new file mode 100644 index 0000000..b4b5b2d --- /dev/null +++ b/docs/stylesheet.css @@ -0,0 +1,8 @@ +body { max-width: 50em; margin: 0 auto 4em auto; padding: 0 2em; + font-family: sans-serif; } h1, h2, h3 { font-weight: normal; } +h1 { font-size: 2.5em; } h2 { font-size: 2em; } h3 { font-size: 1.33em; } +h2 { padding-top: .67em; border-top: 1px solid silver; } +p { line-height: 1.5; } .figure { text-align: center; } img { max-width: 100%; } +q { font-style: normal; } .details { border-bottom: 1px solid silver; } +.details br { display: none; } .details br + span:before { content: " — "; } +pre { padding: 0 1em; } @@ -994,6 +994,22 @@ on_window_state_event(G_GNUC_UNUSED GtkWidget *widget, } static void +show_help_contents(void) +{ + gchar *filename = g_strdup_printf("%s.html", PROJECT_NAME); + gchar *path = g_build_filename(PROJECT_DOCDIR, filename, NULL); + g_free(filename); + GError *error = NULL; + gchar *uri = g_filename_to_uri(path, NULL, &error); + g_free(path); + + // For some reason, it doesn't work with a parent window. + if (!uri || !gtk_show_uri_on_window(NULL, uri, GDK_CURRENT_TIME, &error)) + show_error_dialog(error); + g_free(uri); +} + +static void on_help_destroyed(GtkWidget *window, GtkWidget **storage) { g_return_if_fail(*storage == window); @@ -1101,7 +1117,7 @@ on_key_press(G_GNUC_UNUSED GtkWidget *widget, GdkEventKey *event, on_open(); return TRUE; case GDK_KEY_F1: - show_help_shortcuts(); + show_help_contents(); return TRUE; case GDK_KEY_F9: gtk_widget_set_visible(g.browser_sidebar, @@ -1612,6 +1628,9 @@ make_menu_bar(void) gtk_menu_item_set_submenu(GTK_MENU_ITEM(item_file), menu_file); gtk_menu_shell_append(GTK_MENU_SHELL(g.menu), item_file); + GtkWidget *item_contents = gtk_menu_item_new_with_mnemonic("_Contents"); + g_signal_connect_swapped(item_contents, "activate", + G_CALLBACK(show_help_contents), NULL); GtkWidget *item_shortcuts = gtk_menu_item_new_with_mnemonic("_Keyboard Shortcuts"); g_signal_connect_swapped(item_shortcuts, "activate", @@ -1621,6 +1640,7 @@ make_menu_bar(void) G_CALLBACK(show_about_dialog), g.window); GtkWidget *menu_help = gtk_menu_new(); + gtk_menu_shell_append(GTK_MENU_SHELL(menu_help), item_contents); gtk_menu_shell_append(GTK_MENU_SHELL(menu_help), item_shortcuts); gtk_menu_shell_append(GTK_MENU_SHELL(menu_help), item_about); GtkWidget *item_help = gtk_menu_item_new_with_mnemonic("_Help"); diff --git a/meson.build b/meson.build index 6b92b6f..9ef54de 100644 --- a/meson.build +++ b/meson.build @@ -73,9 +73,13 @@ if not get_option('resvg').disabled() endif endif +# XXX: https://github.com/mesonbuild/meson/issues/825 +docdir = get_option('datadir') / 'doc' / meson.project_name() + conf = configuration_data() conf.set_quoted('PROJECT_NAME', meson.project_name()) conf.set_quoted('PROJECT_VERSION', meson.project_version()) +conf.set_quoted('PROJECT_DOCDIR', get_option('prefix') / docdir) conf.set('HAVE_JPEG_QS', libjpegqs.found()) conf.set('HAVE_LCMS2', lcms2.found()) conf.set('HAVE_LIBRAW', libraw.found()) @@ -111,7 +115,7 @@ endif # XXX: With gdk-pixbuf, this even depends on currently installed modules. if meson.is_cross_build() install_data('fiv.desktop', - install_dir : get_option('datadir') + '/applications') + install_dir : get_option('datadir') / 'applications') else # XXX: The exe path may not contain spaces--quoting is a bitch in Meson. desktop = custom_target('desktop', @@ -122,11 +126,12 @@ else $0 = $0 type ";" } 1' "exe=$1" "$2"''', 'sh', exe, '@INPUT@'], capture : true, install : true, - install_dir : get_option('datadir') + '/applications', + install_dir : get_option('datadir') / 'applications', ) endif install_data('fiv-browse.desktop', - install_dir : get_option('datadir') + '/applications') + install_dir : get_option('datadir') / 'applications') install_data('fiv.svg', - install_dir : get_option('datadir') + '/icons/hicolor/scalable/apps') + install_dir : get_option('datadir') / 'icons/hicolor/scalable/apps') +install_subdir('docs', install_dir : docdir, strip_directory : true) |
