p
/
fiv
1
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Start a basic user guide 

Move some information out there from the README.
This commit is contained in:
Přemysl Eric Janouch 2022-01-24 08:41:05 +01:00
parent 381e5f57c7
commit ee71fb0dd0
Signed by: p
GPG Key ID: A0420B94F92B9493
6 changed files with 164 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.adoc
View File

@ -3,7 +3,7 @@ fiv
'fiv' is a slightly unconventional, general-purpose image browser and viewer. '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 Features
-------- --------
@ -22,7 +22,7 @@ Explicit non-goals
- Following the latest GNOME HIG to the letter--header bars are deliberately - Following the latest GNOME HIG to the letter--header bars are deliberately
avoided, for their general user hostility. avoided, for their general user hostility.
- Portability to non-UNIXy systems, although patches are welcome. - 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 Aspirations
----------- -----------
@ -40,7 +40,7 @@ Build dependencies: Meson, pkg-config +
Runtime dependencies: gtk+-3.0, glib>=2.64, pixman-1, shared-mime-info, Runtime dependencies: gtk+-3.0, glib>=2.64, pixman-1, shared-mime-info,
libturbojpeg, libwebp, spng>=0.7.0 + libturbojpeg, libwebp, spng>=0.7.0 +
Optional dependencies: lcms2, LibRaw, librsvg-2.0, xcursor, libheif, libtiff, 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 $ git clone --recursive https://git.janouch.name/p/fiv.git
$ meson builddir $ meson builddir
@ -52,23 +52,10 @@ direct installations. To test the program, help it find its custom thumbnailer:
$ PATH=$(pwd):$PATH ./fiv $ PATH=$(pwd):$PATH ./fiv
Pressing F1 will give you a convenient list of keyboard shortcuts. Documentation
Configuration
------------- -------------
The standard means to adjust the looks of the program is through GTK+ 3 CSS. For information concerning usage, refer to link:docs/fiv.html[the user guide],
As an example, to tightly pack browser items, put the following in your which can be invoked from within the program by pressing F1.
_~/.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.
Contributing and Support Contributing and Support
------------------------ ------------------------

120
docs/fiv.html Normal file
View File

@ -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>

0
fiv.webp → docs/fiv.webp
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 152 KiB

After

Width:  |  Height:  |  Size: 152 KiB

8
docs/stylesheet.css Normal file
View File

@ -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; }

22
fiv.c
View File

@ -993,6 +993,22 @@ on_window_state_event(G_GNUC_UNUSED GtkWidget *widget,
gtk_image_set_from_icon_name(image, name, GTK_ICON_SIZE_BUTTON); gtk_image_set_from_icon_name(image, name, GTK_ICON_SIZE_BUTTON);
} }
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 static void
on_help_destroyed(GtkWidget *window, GtkWidget **storage) on_help_destroyed(GtkWidget *window, GtkWidget **storage)
{ {
@ -1101,7 +1117,7 @@ on_key_press(G_GNUC_UNUSED GtkWidget *widget, GdkEventKey *event,
on_open(); on_open();
return TRUE; return TRUE;
case GDK_KEY_F1: case GDK_KEY_F1:
show_help_shortcuts(); show_help_contents();
return TRUE; return TRUE;
case GDK_KEY_F9: case GDK_KEY_F9:
gtk_widget_set_visible(g.browser_sidebar, 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_item_set_submenu(GTK_MENU_ITEM(item_file), menu_file);
gtk_menu_shell_append(GTK_MENU_SHELL(g.menu), item_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 = GtkWidget *item_shortcuts =
gtk_menu_item_new_with_mnemonic("_Keyboard Shortcuts"); gtk_menu_item_new_with_mnemonic("_Keyboard Shortcuts");
g_signal_connect_swapped(item_shortcuts, "activate", g_signal_connect_swapped(item_shortcuts, "activate",
@ -1621,6 +1640,7 @@ make_menu_bar(void)
G_CALLBACK(show_about_dialog), g.window); G_CALLBACK(show_about_dialog), g.window);
GtkWidget *menu_help = gtk_menu_new(); 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_shortcuts);
gtk_menu_shell_append(GTK_MENU_SHELL(menu_help), item_about); gtk_menu_shell_append(GTK_MENU_SHELL(menu_help), item_about);
GtkWidget *item_help = gtk_menu_item_new_with_mnemonic("_Help"); GtkWidget *item_help = gtk_menu_item_new_with_mnemonic("_Help");

13
meson.build
View File

@ -73,9 +73,13 @@ if not get_option('resvg').disabled()
endif endif
endif endif
# XXX: https://github.com/mesonbuild/meson/issues/825
docdir = get_option('datadir') / 'doc' / meson.project_name()
conf = configuration_data() conf = configuration_data()
conf.set_quoted('PROJECT_NAME', meson.project_name()) conf.set_quoted('PROJECT_NAME', meson.project_name())
conf.set_quoted('PROJECT_VERSION', meson.project_version()) 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_JPEG_QS', libjpegqs.found())
conf.set('HAVE_LCMS2', lcms2.found()) conf.set('HAVE_LCMS2', lcms2.found())
conf.set('HAVE_LIBRAW', libraw.found()) conf.set('HAVE_LIBRAW', libraw.found())
@ -111,7 +115,7 @@ endif
# XXX: With gdk-pixbuf, this even depends on currently installed modules. # XXX: With gdk-pixbuf, this even depends on currently installed modules.
if meson.is_cross_build() if meson.is_cross_build()
install_data('fiv.desktop', install_data('fiv.desktop',
install_dir : get_option('datadir') + '/applications') install_dir : get_option('datadir') / 'applications')
else else
# XXX: The exe path may not contain spaces--quoting is a bitch in Meson. # XXX: The exe path may not contain spaces--quoting is a bitch in Meson.
desktop = custom_target('desktop', desktop = custom_target('desktop',
@ -122,11 +126,12 @@ else
$0 = $0 type ";" } 1' "exe=$1" "$2"''', 'sh', exe, '@INPUT@'], $0 = $0 type ";" } 1' "exe=$1" "$2"''', 'sh', exe, '@INPUT@'],
capture : true, capture : true,
install : true, install : true,
install_dir : get_option('datadir') + '/applications', install_dir : get_option('datadir') / 'applications',
) )
endif endif
install_data('fiv-browse.desktop', install_data('fiv-browse.desktop',
install_dir : get_option('datadir') + '/applications') install_dir : get_option('datadir') / 'applications')
install_data('fiv.svg', 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)