aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.adoc25
-rw-r--r--docs/fiv.html120
-rw-r--r--docs/fiv.webp (renamed from fiv.webp)bin155162 -> 155162 bytes
-rw-r--r--docs/stylesheet.css8
-rw-r--r--fiv.c22
-rw-r--r--meson.build13
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>
diff --git a/fiv.webp b/docs/fiv.webp
index ef47681..ef47681 100644
--- a/fiv.webp
+++ b/docs/fiv.webp
Binary files differ
diff --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; }
diff --git a/fiv.c b/fiv.c
index 49a04a5..33bb961 100644
--- a/fiv.c
+++ b/fiv.c
@@ -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)