Start a basic user guide
Move some information out there from the README.
This commit is contained in:
25
README.adoc
25
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
|
||||
------------------------
|
||||
|
||||
120
docs/fiv.html
Normal file
120
docs/fiv.html
Normal 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>
|
||||
|
Before Width: | Height: | Size: 152 KiB After Width: | Height: | Size: 152 KiB |
8
docs/stylesheet.css
Normal file
8
docs/stylesheet.css
Normal 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
22
fiv.c
@@ -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);
|
||||
}
|
||||
|
||||
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)
|
||||
{
|
||||
@@ -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");
|
||||
|
||||
13
meson.build
13
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)
|
||||
|
||||
Reference in New Issue
Block a user