From a6560509d99d75728c0c857de4859ca9d81f1a0d Mon Sep 17 00:00:00 2001 From: Přemysl Eric Janouch Date: Mon, 17 Apr 2023 07:17:16 +0200 Subject: Revise documentation and help output Split out clearly internal options. --- docs/fiv.adoc | 37 ++++++++++++++++++++++--------------- docs/fiv.html | 37 +++++++++++++++++++------------------ docs/stylesheet.css | 3 ++- fiv.c | 42 ++++++++++++++++++++++++++++-------------- 4 files changed, 71 insertions(+), 48 deletions(-) diff --git a/docs/fiv.adoc b/docs/fiv.adoc index f7f992e..5285d5d 100644 --- a/docs/fiv.adoc +++ b/docs/fiv.adoc @@ -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 -------------- diff --git a/docs/fiv.html b/docs/fiv.html index 5a9b918..72b1963 100644 --- a/docs/fiv.html +++ b/docs/fiv.html @@ -17,9 +17,9 @@ q:lang(en):after { content: "’"; } Přemysl Eric Janouch
p@janouch.name
version 0.0.0, -2022-07-31 +2023-04-17 -

fiv's browser and viewer +

fiv in browser and viewer modes

Introduction

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

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. +

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.

Browser

fiv 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. -

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. +

You can open items in a new window either by middle clicking on them, or with +the left mouse button while holding the Ctrl key. +Right clicking the directory view offers a context menu for opening files, +or even the directory itself, in a different application.

Viewer

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

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

The few configuration options fiv has can be adjusted using dconf-editor, which can be launched in the appropriate location from -within the application by pressing Ctrl+,. For command line usage, there is -the gsettings utility: +within the application by pressing Ctrl + ,. +For command line usage, there is the gsettings utility: 

 gsettings list-recursively name.janouch.fiv
diff --git a/docs/stylesheet.css b/docs/stylesheet.css
index b4b5b2d..daf49f9 100644
--- a/docs/stylesheet.css
+++ b/docs/stylesheet.css
@@ -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; }
diff --git a/fiv.c b/fiv.c
index d6beebf..d74bce3 100644
--- a/fiv.c
+++ b/fiv.c
@@ -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']);
-- 
cgit v1.2.3-70-g09d2