Revise documentation and help output

Split out clearly internal options.
This commit is contained in:
Přemysl Eric Janouch 2023-04-17 07:17:16 +02:00
parent 44c28f00d6
commit a6560509d9
Signed by: p
GPG Key ID: A0420B94F92B9493
4 changed files with 71 additions and 48 deletions

View File

@ -26,6 +26,15 @@ the _User Guide_.
Options
-------
*--browse*::
When an image is passed, start in browsing mode, and preselect that
image in its containing directory. This is used by *fiv*'s inode/directory
handler to implement the "Open Containing Folder" feature of certain
applications.
*--help-all*::
Show the full list of options, including those provided by GTK+.
*--invalidate-cache*::
Invalidate the wide thumbnail cache, removing thumbnails for files that can
no longer be found.
@ -35,18 +44,11 @@ Options
the list of MIME types within *fiv*'s desktop file when the list
of GdkPixbuf loaders changes.
*--browse*::
When an image is passed, start in browsing mode, and preselect that
image in its containing directory. This is used by *fiv*'s inode/directory
handler to implement the "Open Containing Folder" feature of certain
applications.
*--thumbnail*=_SIZE_::
Generate thumbnails for the first argument, in all sizes not exceeding
_SIZE_, and present the largest of them on the standard output
in an application-specific bitmap format. Available sizes follow directory
names in the _Thumbnail Managing Standard_.
*-V*, *--version*::
Output version information and exit.
Internal options
~~~~~~~~~~~~~~~~
*--extract-thumbnail*::
Present any embedded thumbnail of the first argument on the standard output
in an application-specific bitmap format. When both *--thumbnail*
@ -54,11 +56,16 @@ Options
exiting early if successful. This is used to enhance responsivity
of thumbnail procurement.
*-V*, *--version*::
Output version information and exit.
*--thumbnail*=_SIZE_::
Generate wide thumbnails for the first argument, in all sizes not exceeding
_SIZE_, and present the largest of them on the standard output
in an application-specific bitmap format. Available sizes follow directory
names in the _Thumbnail Managing Standard_.
*--help-all*::
Show the full list of options, including those provided by GTK+.
*--thumbnail-for-search*=_SIZE_::
Transform the first argument to a widely supported image file format,
and present it on the standard output. The image will be downscaled as
necessary so as to not exceed _SIZE_ (see *--thumbnail*).
Reporting bugs
--------------

View File

@ -17,9 +17,9 @@ q:lang(en):after { content: ""; }
<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-07-31</span>
<span id="revdate">2023-04-17</span>
<p class="figure"><img src="fiv.webp" alt="fiv's browser and viewer">
<p class="figure"><img src="fiv.webp" alt="fiv in browser and viewer modes">
<h2>Introduction</h2>
@ -33,30 +33,31 @@ 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.
<p>Controls should generally be accessible through the keyboard. Pressing
<kbd>Ctrl</kbd>&#8239;+&#8239;<kbd>?</kbd> will give you a convenient overview
of all shortcuts. In addition to these, remember that you may often use
<kbd>Ctrl</kbd>&#8239;+&#8239;<kbd>Tab</kbd> and <kbd>F6</kbd> 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.
GVfs, an item for entering arbitrary filesystem paths or URIs, and finally
breadcrumbs leading to the currently opened directory, as well as descendants
of it. At the top, there is a toolbar with view controls.
<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.
<p>You can open items in a new window either by middle clicking on them, or with
the left mouse button while holding the <kbd>Ctrl</kbd> key.
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.
and exited using the <kbd>Enter</kbd> 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.
@ -96,8 +97,8 @@ rm -rf ~/.cache/thumbnails/wide-*
<p>The few configuration options <i>fiv</i> has can be adjusted using
<i>dconf-editor</i>, which can be launched in the appropriate location from
within the application by pressing Ctrl+,. For command line usage, there is
the <i>gsettings</i> utility:
within the application by pressing <kbd>Ctrl</kbd>&#8239;+&#8239;<kbd>,</kbd>.
For command line usage, there is the <i>gsettings</i> utility:
<pre>
gsettings list-recursively name.janouch.fiv

View File

@ -5,4 +5,5 @@ 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; }
pre { padding: 0 1em; } kbd { border: solid #ccc; border-radius: .25em;
border-width: 1px 2px 2px 1px; padding: 0 .25em; font-family: inherit; }

42
fiv.c
View File

@ -2172,32 +2172,46 @@ main(int argc, char *argv[])
const GOptionEntry options[] = {
{G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &args,
NULL, "[PATH | URI]..."},
{"list-supported-media-types", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_NONE, &show_supported_media_types,
"Output supported media types and exit", NULL},
{"browse", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_NONE, &browse,
"Start in filesystem browsing mode", NULL},
{"thumbnail-for-search", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_STRING, &thumbnail_size_search,
"Output an image file suitable for searching by content", "SIZE"},
{"extract-thumbnail", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_NONE, &extract_thumbnail,
"Output any embedded thumbnail (superseding --thumbnail)", NULL},
{"thumbnail", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_STRING, &thumbnail_size,
"Generate thumbnails, up to SIZE, and output that size", "SIZE"},
{"invalidate-cache", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_NONE, &invalidate_cache,
"Invalidate the wide thumbnail cache", NULL},
{"list-supported-media-types", 0, G_OPTION_FLAG_IN_MAIN,
G_OPTION_ARG_NONE, &show_supported_media_types,
"Output supported media types and exit", NULL},
{"version", 'V', G_OPTION_FLAG_IN_MAIN, G_OPTION_ARG_NONE,
&show_version, "Output version information and exit", NULL},
{},
};
const GOptionEntry options_internal[] = {
{"extract-thumbnail", 0, 0,
G_OPTION_ARG_NONE, &extract_thumbnail,
"Output any embedded thumbnail (superseding --thumbnail)", NULL},
{"thumbnail", 0, 0,
G_OPTION_ARG_STRING, &thumbnail_size,
"Generate thumbnails, up to SIZE, and output that size", "SIZE"},
{"thumbnail-for-search", 0, 0,
G_OPTION_ARG_STRING, &thumbnail_size_search,
"Output an image file suitable for searching by content", "SIZE"},
{},
};
GOptionContext *context =
g_option_context_new(" - Image browser and viewer");
g_option_context_add_group(context, gtk_get_option_group(TRUE));
g_option_context_add_main_entries(context, options, NULL);
GOptionGroup *internals = g_option_group_new(
"internal", "Internal Options:", "Show internal options", NULL, NULL);
g_option_group_add_entries(internals, options_internal);
g_option_context_add_group(context, internals);
GError *error = NULL;
gboolean initialized = gtk_init_with_args(
&argc, &argv, " - Image browser and viewer", options, NULL, &error);
gboolean initialized =
g_option_context_parse(context, &argc, &argv, &error);
g_option_context_free(context);
if (show_version) {
const char *version = PROJECT_VERSION;
printf("%s %s\n", PROJECT_NAME, &version[*version == 'v']);