Updated Help

Features list, custom link icons, split view mode, Gempub, CLI control of running instance.

1 files changed, 94 insertions, 19 deletions

diff --git a/res/about/help.gmi b/res/about/help.gmi
index c710afc9..29a9a110 100644
--- a/res/about/help.gmi
+++ b/res/about/help.gmi
@@ -27,25 +27,29 @@ Like Gemini, Lagrange has been designed with minimalism in mind. It depends on a
 
 * Beautiful typography using Unicode fonts
 * Autogenerated page style and Unicode icon for each Gemini domain
-* Smart suggestions when typing the URL — search bookmarks, history, identities
-* Sidebar for page outline, managing bookmarks and identities, and viewing history
-* Multiple tabs
-* Identity management — create and use TLS client certificates
-* Subscribe to Gemini and Atom feeds
-* Use Gemini pages as a source of bookmarks
 * Light and dark color themes
-* Select and copy text with the mouse
-* Find text on the page
-* Search engine integration
-* Open image links inline on the same page
-* Audio playback: MP3, Ogg Vorbis, WAV
-* Open links via keyboard shortcuts
-* Instant back/forward navigation
 * Smooth scrolling
 * Scaling page content (50%...200%)
 * Scaling factor for the UI (for arbitrary monitor DPI)
+
+* Sidebars for managing bookmarks, identities and subscribed feeds, and viewing browsing history and the page outline
+* Multiple tabs
+* Split view for browsing two pages at once
 * Persistent app state — tabs and history are restored on next run
 * Configurable keybindings
+* Open links via keyboard shortcuts
+* Select and copy text with the mouse
+* Find text on the page
+* Open image and audio links inline on the same page
+
+* Instant back/forward navigation
+* Smart suggestions when typing an URL — search bookmarks, history, identities
+* Search engine integration
+* Identity management — create and use TLS client certificates
+* Subscribe to Gemini and Atom feeds
+* Use Gemini pages as a source of bookmarks
+* Audio playback: MP3, Ogg Vorbis, WAV
+* Read Gempub books and view ZIP archive contents
 * Built-in support for Gopher
 * Use proxy servers for HTTP, Gopher, or Gemini content
 
@@ -65,7 +69,7 @@ Lagrange's user interface is modeled after web browsers:
 
 * There is a navigation bar at the top with Back and Forward buttons.
 * There is a tab bar for switching tabs. The tab bar is hidden if there is only one tab open.
-* There is a sidebar for managing bookmarks and TLS identities, and viewing history and the page outline. Sidebars are hidden by default.
+* There is a sidebar for managing bookmarks, subscribed feeds, and TLS identities, and viewing history and the page outline. Sidebars are hidden by default.
 * There is a search bar that appears at the bottom when searching text on the page.
 
 Tip: Try pressing ${CTRL+}5 now to see the page outline.
@@ -104,6 +108,8 @@ Link colors remain the same regardless of which color theme is being used for pa
 
 When you move the mouse cursor over a link, additional information will appear: the destination domain, with the URL scheme shown for non-Gemini links, and the date of the last visit to the URL.
 
+If a link would normally use the default ➤ icon but there is an Emoji at the beginning of the link label, that Emoji is used as the link icon instead. In these cases, you can always assume that the link is a Gemini link whose destination is the same domain that you're currently on.
+
 ### 1.1.3 Page caching
 
 When navigating to a new page, the old page is cached in memory. If you navigate back, the cached copy of the page is restored. Think of it as rewinding time — you return to a past time as if nothing had happened. The same applies to forward navigation; cached pages are loaded if available. This allows back and forward navigation to happen instantly, without any network requests.
@@ -116,9 +122,15 @@ Maximum size of the cache can be configured on the "Network" tab of Preferences.
 
 Holding down ${CTRL} when left-clicking on a link causes it to open in a new tab. Alternatively, middle-clicking a link has the same effect.
 
+${SHIFT+}${CTRL+}click opens the link in a new background tab.
+
 Right-clicking on a link shows a link-specific context menu. From there, you can also open the link in a new background tab, which will keep the current tab open.
 
-### 1.1.5 Opening links using the keyboard
+### 1.1.5 Opening links to the side
+
+Holding down ${SHIFT} when left-clicking on a link opens it in split view mode on the other side of the split. When in split view mode, your tab pinning preference will determine the tab on which clicked links will open. See section 1.8 for more information about split view modes.
+
+### 1.1.6 Opening links using the keyboard
 
 Lagrange has two modes for navigating links with the keyboard. The first uses a modifier key (${ALT} by default): while the modifier is pressed, alphanumeric shortcuts are shown for each visible link in the window. You can then press the corresponding key, still holding the modifier, to open a link. The second mode is based on letters only and focuses on the page row keys. You press and release the activation key ("F" by default) to show the link shortcut letters. In this mode the shortcuts are not in alphabetic order, but instead roughly sorted based on proximity to the F and J keys. You may find this easier to use since it is a simple sequence of key presses without using modifiers, allowing one to keep fingers on or near the home row.
 
@@ -132,7 +144,11 @@ Press ${CTRL+}T to open a new tab, and ${CTRL+}W to close the current tab. Right
 
 The set of open tabs and their full contents are saved when you quit the application and restored when relaunch it.
 
-### 1.2.1 Auto-reloading
+### 1.2.1 Highlighting of open links
+
+When you open a tab, and the URL of that tab is found in a link on another page, that link will be highlighted. This way you can conveniently see which links are currently open in other tabs. These highlights will assist you in navigating hierarchies and index pages.
+
+### 1.2.2 Auto-reloading
 
 A tab can be set to auto-reload at given intervals. The setting is remembered until the tab is closed. This is helpful if you keep a  periodically updated page open for longer periods of time.
 
@@ -191,6 +207,7 @@ Note that remote bookmarks are read-only: they cannot be edited or tagged. This
 * The "remotesource" tag marks the bookmark as a source of remote bookmarks. All links on the source pages are shown as remote bookmarks in the Bookmarks list.
 * The "remote" tag is used for remote bookmarks. These bookmarks cannot be edited or tagged, but you can make a local duplicate to turn it into a regular bookmark.
 * The "usericon" tag prevents a random icon to be selected for the bookmark. This tag is automatically applied when an icon character is entered in the bookmark editor.
+* The "linksplit" tag
 
 ## 1.5 Subscribing to feeds
 
@@ -253,6 +270,54 @@ The 🔃 button on the right side of the URL input field is the Reload/Stop butt
 
 The location where downloaded files are saved can be changed in Preferences. The default location is "Downloads" in your home directory.
 
+## 1.8 Split view mode
+
+By default, only one tab is visible at a time in the application window. However, sometimes it is beneficial to see two pages at once. For example, many capsules have top-level menus or lists of articles, and keeping the menu/index visible on the side makes navigation less cumbersome.
+
+Split view mode divides the UI into two equivalent parts. You can have multiple tabs open in each split. Closing all tabs on one side will remove the split and return back to the normal unsplit mode.
+
+View splitting is primarily controlled using the view split menu. The default keybinding for showing it is ${CTRL+}J. For convenience it is recommended to use the shortcuts listed in the menu to change split modes. For example, the sequence ${CTRL+}J 2 can be used to quickly activate a 50% horizontal split, and ${CTRL+}J 1 will merge all open tabs back into the normal unsplit view.
+
+Another way to activate split view mode is to click on a link while holding ${SHIFT}.
+
+Each split has its own sidebars, which means that in split view mode you can have a total of four sidebars open at the same time.
+
+### 1.8.1 Switching focus
+
+At any given time, one of the splits has keyboard focus. This is indicated by a colored line at the top of the section, and some UI elements will be dimmed out on the unfocused side.
+
+To switch keyboard focus between the sections, you can use the Next/Previous Tab keybindings or Ctrl+Tab. Next/Previous Tab is particularly convenient as it cycles through all open tabs, jumping to the other side of the split when appropriate.
+
+You may also press Tab to cycle input focus between all the URL input fields.
+
+### 1.8.2 Pinning
+
+While it is sometimes useful to simply have two independent browsers open side by side, by default view splitting is meant to assist in navigating hierarchies and lists. In the typical use case, you'll have a menu or an index page on the left, and a content page open on the right. Links clicked on the left will automatically open on the right.
+
+This is called "pinning" and the behavior can be configured in Preferences. The "Split view pinning" setting on the "General" tab of Preferences controls where links get opened in a split view. There are three modes available:
+
+* "None" causes links to open in the tab where the link is clicked. In this mode, both sides of the split can be navigated independently.
+* "Left Tab" causes links clicked on the left tab to open on the right side. The page open in the left tab is therefore "pinned" and does not change unless you enter a new URL or navigate to the parent or root.
+* "Right Tab" is the same but works the other way around. The page open in the right tab is pinned and clicked links open on the left.
+
+The default pinning mode is "Left Tab".
+
+## 1.9 Viewing local files and directories
+
+"file://" URLs can be used for accessing local files and directories. File types known to Lagrange, such as .gmi, .txt., .png, .jpg, and .zip, can be viewed inside the application. In this release, types of local files are detected solely based on the file extension.
+
+When viewing a directory, its contents are shown as a list of links. A similar page is shown when viewing a directory inside a ZIP archive.
+
+Note that ZIP archives are not decompressed while browsing their directory structure. Each request that accesses a compressed file in an archive will cause only that particular file to be decompressed. This may cause slow response times when dealing with large compressed files.
+
+## 1.10 Gempub
+
+Gempub is an e-book/archival format that is essentially a set of Gemtext files stored in a ZIP archive.
+
+=> https://codeberg.org/oppenlab/gempub  Gempub specification
+
+Lagrange can be used as a Gempub reader. When a .gpub file has been saved locally, you can open it in the application to see the book cover page. On the cover page you will find a link that opens the contents of the book. When clicked, split view mode is automatically enabled and both the book index page and the first chapter are shown (unless split view pinning has been disabled).
+
 # 2 Customization
 
 You can find a number of settings in Preferences to customize the user interface and page contents.
@@ -261,6 +326,10 @@ You can find a number of settings in Preferences to customize the user interface
 
 One important characteristic of Gemini is that you remain in control of what gets loaded and when. The browser will not suddenly fetch a ton of images, autoplay videos, or make surreptitious connections to any tracking servers — each network request is purposeful and manually triggered. With this in mind, the "Load image on scroll" option is provided to assist keyboard-only browsing and to facilitate a focused reading experience. When enabled, if there is an image link visible on the page and you press Space or ↓, it will be loaded and shown inline _instead_ of the view scrolling down. This allows you to read and see all the content of the page while only tapping on a single key on the keyboard.
 
+The "Open archive indices" option controls whether index.gmi pages are automatically opened while browsing the contents of a ZIP archive. The purpose is to simulate the behavior of a Gemini server where opening a directory will by default show its index page. Enabling this option makes navigating an archived copy of a capsule a more streamlined experience.
+
+"Split view pinning" controls which tab links will be opened on when browsing in split view mode. The default mode is "Left Tab", which means that the page in the left tab is pinned (remains unchanged) when clicking on a link. For more information, see section 1.8.
+
 ## 2.2 Window and UI options
 
 Lagrange supports configuring dark and light UI modes separately.
@@ -300,9 +369,9 @@ There are six fonts available:
 
 * "Nunito" is a friendly rounded sans-serif font.
 * "Fira Sans" is a bolder, narrower, and more angular sans-serif font.
+* "Source Sans 3" is the Lagrange UI font (sans-serif).
 * "Literata" is a heavy and serious serif font.
 * "Tinos" is a lighter serif font.
-* "Source Sans Pro" is the Lagrange UI font.
 * "Iosevka" is the monospace font.
 
 Other style options:
@@ -357,7 +426,13 @@ Likewise (on macOS), .gmi/.gemini file extensions are registered as file formats
 
 You can drag and drop .gmi files on the Lagrange window to open them in the current tab. Dropping multiple files opens them in separate tabs. This is the recommended way to view local files, because there is no "Open File" menu item. You may also type "file://" URLs in the URL field.
 
-## 3.4 Runtime files
+## 3.4 Controlling a running instance
+
+Only one instance of the application is allowed to run at once. This is because each instance uses the same runtime files (section 3.5) without any synchronization. A second instance of the application would overwrite any changes made by the first one, leading to lost bookmarks and other state.
+
+If there already is a running instance you can still use the command line to interact with it: you can open and close tabs, change the currently open URL, or list all the open URLs. See --help for a list of the available options.
+
+## 3.5 Runtime files
 
 Lagrange stores user-specific persistent files in one of the following locations (depending on the operating system):
 
@@ -449,7 +524,7 @@ The combined navigation history of all tabs. Each line specifies one URL:
 ```
 The Transient flag is used to indicate redirections and for marking feed entries as read without actually visiting the URL. URLs with the Transient flag do not appear in the History sidebar tab.
 
-## 3.5 Environment variables
+## 3.6 Environment variables
 
 ### LAGRANGE_OVERRIDE_DPI
 Override display DPI detection with a user-provided value. The same value is applied to all displays. This is useful if your display's DPI value is not being detected correctly. Example: