path: root/res/about/help.gmi

```
           __   __             __   ___
|     /\  / _` |__)  /\  |\ | / _` |__
|___ /~~\ \__> |  \ /~~\ | \| \__> |___

```
# Help

## What is Lagrange

Lagrange is a GUI client for browsing Geminispace. It offers modern conveniences familiar from web browsers, such as smooth scrolling, inline image viewing, multiple tabs, visual themes, Unicode fonts, bookmarks, history, and page outlines.

Like Gemini, Lagrange has been designed with minimalism in mind. It depends on a small number of essential libraries. It is written in C and uses SDL for hardware-accelerated graphics. OpenSSL is used for secure communications.

=> about:lagrange           About Lagrange
=> https://www.libsdl.org   SDL: Simple DirectMedia Layer
=> https://www.openssl.org  OpenSSL: Cryptography and SSL/TLS Toolkit

### Features

* 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
* Light and dark color themes
* Select and copy text with the mouse
* Find text on the page
* 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)
* Persistent app state — tabs and history are restored on next run
* Configurable keybindings

## What is Gemini

Gemini is a simple protocol for serving content over the internet. It specifies a Markdown inspired format allowing basic plain text document markup. Compared to HTTP and HTML, Gemini is vastly simpler and easier to work with.

=> gemini://gemini.circumlunar.space/docs/faq.gmi Project Gemini FAQ
=> gemini://gemini.circumlunar.space/docs/specification.gmi Protocol and text/gemini specification

## Why not just use a web browser

Modern web browsers are complex beasts. In fact, they are so complex that one can create a fully functional virtual machine inside one and run another operating system!

=> https://win95.ajf.me Windows 95 on DOSBox (using Emscripten)

If one seeks to just read text and view images, this is absurd overkill. Having a universal platform that runs everywhere and on everything is clearly a valuable notion, but it comes with a hefty price tag. The software stack towers ever higher, and hardware needs to be ever more powerful and complicated to run it well. However, everything on the internet doesn't have to rely on this behemoth.

One way to browse Gemini content is via web browser extensions or proxies that translate the content for the web. This may be a sufficient and easy solution for you. However, native clients such as Lagrange also benefit from the simpleness of the protocol and the content. The experience can be optimized, and the software runs well even on simple hardware like the Raspberry Pi.

# User interface

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. The sidebar is hidden by default.
* There is a search bar that appears at the bottom when searching text on the page.

Tip: Try pressing ${CTRL+}4 now to see the page outline.

The user interface has been designed for both mouse and keyboard based use. The most commonly needed features are available via context menus, for example by right-clicking on the currently open page. Keyboard shortcuts on the other hand can provide a very quick and fluid user experience. For example, to open the "CAPCOM" bookmark, one might use the following keyboard shortcuts:

* ${CTRL+}L to activate the URL input field
* Type "cap" which shows the "CAPCOM" bookmark as the first lookup result
* Tab (or ↓) to move focus to the lookup results
* Enter to select "CAPCOM"

## Navigation

### URL entry and quick search

The URL input field is in its typical location in the navigation bar. It can be accessed quickly by pressing ${CTRL+}L.

As you enter text, Lagrange starts looking for matches in bookmarks, history, content of cached pages, and identities. Search results appear below the URL input field in a popup. Press Tab or ↓ to switch input focus to the results.

Search within cached pages is limited to the (small) set of pages that Lagrange keeps in memory for back navigation. Search terms are case insensitive, and if many words are entered, they are all required to appear in the specified order in any matched content.

Note that the navigation stack is saved to a file when Lagrange is shut down and restored on the next launch. This means the next time you launch Lagrange, you can still search the contents of past pages. However, navigation stacks are tab-specific, so closing a tab will delete its history as well.

### Links

The type and destination of a link are indicated by the link's icon and color: ➤ links to the same domain, and 🌐 to a different domain. The colors are:

* Blue for Gemini
* Purple for Gopher
* Orange for HTTP(S)
* Red for other (cannot be opened)

When you move the mouse over a link, additional information about it will appear: the destination domain, with the URL scheme shown for non-Gemini links, and the date of the last visit to the URL.

### Note about 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.

The page cache is saved to a file when Lagrange is shut down so it can be restored on the next launch.

### Opening links in a new tab

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.

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.

### Opening links using the keyboard

When navigating via keyboard, hold down ${ALT} to see link shortcut keys. Try doing so now and see how the link icon below is replaced with a number.

=> gemini://gemini.circumlunar.space/ Project Gemini

Each visible link on the page gets an alphanumeric shortcut. For example, the first link can be opened by pressing ${ALT+}1. The tenth link is ${ALT+}A. Additionally hold down ${CTRL} to open the link in a new tab.

## Tabs

Press ${CTRL+}T to open a new tab, and ${CTRL+}W to close the current tab. Right-clicking on buttons in the tab bar shows a context menu for additional tab-related functions.

The set of open tabs is restored when you launch Lagrange.

## Sidebar

The sidebar can be toggled via menus or by pressing ${SHIFT+}${CTRL+}L. It has four tabs:

* Bookmarks: List of bookmarks that you've created. These appear first in search results for quick and easy access.
* History: Chronological list of visited URLs. This is not a full history of all the URLs you've accessed over time — only unique URLs are shown at the latest access time.
* Identities: TLS client certificates.
* Outline: List of the headings in the currently open tab. Useful when reading longer documents.

${CTRL+}1 through ${CTRL+}4 switch between the sidebar tabs, or hide the sidebar if the current tab's key is pressed.

## Bookmarks

Press ${CTRL+}D to bookmark the currently open URL.

In addition to a title, bookmarks can have tags. Some tags have a special meaning, but you are free to enter whatever you want in the tags field. In quick search results, tags are given extra weight so they appear higher in results.

### Special tags

* Set a "homepage" tag on a bookmark to make it one of the pages that will be opened when pressing the 🏠 button.

## Identities (client certificates)

Gemini uses TLS client certificates for manual user/session identification purposes. This is analogous to logging into a web site, except you are in full control of the information. The term "Identity" is used in Lagrange to refer to client certificates.

The Identities sidebar tab shows all identities known to Lagrange. Press ${CTRL+}3 to show it. This includes identities created in Lagrange and any identities based on imported X.509 certificates.

### Creating a new identity

Click on the 👤 button in the navigation bar and select "New Identity...". The shortcut for this is ${SHIFT+}${CTRL+}N.

Consider any information you enter in the certificate as public; only the Common Name is required and will appear as the issuer and subject of the certificate. This makes it clear that the certificate is self-signed. The other required field is the expiration date in "Valid until". Entering a year is sufficient, and means that the certificate is valid until the end of that year.

The "Temporary" option prevents the identity from being saved persistently — it will be deleted as soon as you quit Lagrange. Otherwise, the certificate and its private key are written to .crt and .pem files.

### Using an identity

You will need to select an identity when you encounter this error message:

> 🔑 Certificate Required

Clicking on an identity in the sidebar will toggle it on/off for the currently open URL. On subsequent page loads, the certificate will then be sent to the server when the URL or any URL under it is fetched. You can click on the 👤 button in the navigation bar to see which identity is being used for the current page.

As the sidebar is not keyboard-navigable, note that identities can also be accessed via lookup results. Identities matching the search terms are shown as the last category in the lookup results list. From there, one can toggle an identity for the current page, or stop using it on all pages.

### Importing existing certificates

At launch, Lagrange looks through its "idents" directory to see if any new certificates have been copied there. (See "Runtime files" below for the location.) The file format must be PEM. Both a certificate (.crt) and its private key (.key) must be found in "idents" and they must have matching file names. For example:
* mycert.crt
* mycert.key
Lagrange will add a note to the imported identities to mark them as "Imported".

## Downloads

Press ${CTRL+}S to save the contents of the current page to the Downloads folder. This works on all pages regardless of whether Lagrange can display the contents or not.

The location where downloaded files are saved can be set in Preferences.

The 🔃 button on the right side of the URL input field is the Reload/Stop button — it reloads the current page or stops an ongoing download. During large downloads, an additional progress indicator appears next to the Stop button.

## Customization

You can find a number of settings in Preferences to customize the user interface and page contents.

### Color themes

Lagrange supports configuring dark and light modes separately. You can select a different page content color theme for dark mode and light mode.

There are four different UI color themes: two for dark mode, and two for light mode. These can be selected on the "General" tab of the Preferences dialog:

* Dark mode: "Pure Black" and "Dark" have a fully black or dark gray UI.
* Light mode: "Pure White" and "Light" have completety white or light gray UI.

On macOS, Lagrange will automatically switch between dark and light modes if the "Use system theme" setting is enabled. On other platforms you'll need to switch manually.

Page content color themes are selected on the "Colors" tab of Preferences. The "Dark theme" is active in dark mode, and the "Light theme" is active in light mode.

* Colorful Dark: All elements of the page are colored; the background is dark and text is light. This mode provides the best visual distinction between different domains because more color combinations are available.
* Colorful Light: A single, bright background color with black text. This is the most colorful light theme. Note that colored backgrounds may reduce readability.
* Black: Gray body text and brightly colored headings on a black background.
* Gray: Slightly brighter version of Black, i.e., gray body text and colored headings on a gray background.
* White: Colored headings on a white background.
* Sepia: Light sepia background with black text. Does not change depending on domain; use this for readability if you prefer a sepia reading experience.
* High Contrast: White background with black text. Does not change depending on domain; use this for readability if you prefer maximum contrast between text and the background.

### Page style

The fonts for headings and other text are selected separately. This way one can achieve a greater number of style variations. Also, headings that are in a different font are more visually distinct and thus easier for one's eyes to scan.

There are two sans-serif and two serif fonts:

* "Nunito" is a friendly rounded sans-serif font.
* "Fira Sans" is a bolder, narrower, and more angular sans-serif font.
* "Literata" is a heavy and serious serif font.
* "Tinos" is a lighter serif font.

Other style options:

* Line width: This setting determines the maximum width for text lines. "Window" disables the maximum limit and fits text lines to the full width of the window. Shorter lines are generally easier to read.
* Quote indicator: Quoted text is shown in an italic font. Additionally, you can select between a quotation mark icon and the traditional vertical line along the left edge of the quote.
* Big 1st paragraph: When enabled, the leading paragraph on the page is shown in a slightly larger font.

Options for wide window sizes:

* Site icon: If there is room on the left side of the page text, the site icon appears there along with the top level heading. This allows one to keep better track of the current reading position in long documents.

### Bindings

The Bindings tab lets you change which keys are bound to UI commands. Currently only basic page scrolling keybindings are available.

Click on an item with the mouse and then press the new key combination that you want bound to it.

To reset all bindings to their defaults, quit Lagrange and delete the "bindings.txt" file in Lagrange's runtime directory. This is a platform-dependent location; see below for more information (under "Runtime files").

# OS integration

## Command line options

### URLs
URLs on the command line are opened after Lagrange has launched. If more than one URL is given, multiple tabs will be opened. For example:
```
$ lagrange gemini://gus.guru/
```

### --echo
Debugging utility: internal events are printed to stdout.

### --sw
Disable hardware accelerated graphics. Note that software rendering is anyway used as a fallback, so usually this option should not be necessary.

## Opening Gemini links

On macOS and Windows, Lagrange registers itself as a "gemini:" URL scheme handler, so you can click on Gemini links in any application to open Lagrange with that URL.

Likewise (on macOS), .gmi/.gemini file extensions are registered as file formats that Lagrange can view so Finder will know how to open those automatically using Lagrange.

## Drop and drop

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.

## Runtime files

Lagrange stores user-specific persistent files in one of the following locations (depending on the operating system):

```
   Windows : C:\Users\Name\AppData\Roaming\fi.skyjake.Lagrange\
     macOS : ~/Library/Application Support/fi.skyjake.Lagrange/
Other Unix : ~/.config/lagrange/
```

* bindings.txt
* bookmarks.txt
* idents.binary and idents/
* prefs.cfg
* state.binary
* trusted.txt
* visited.txt

# Open source licenses

=> about:license