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
* Subscribe to Gemini feeds
* 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
* Built-in support for Gopher
* Use proxy servers for HTTP, Gopher, or Gemini content

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

The user interface has been designed for both mouse and keyboard based use. When using a mouse 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. You can then type or paste an URL and press Enter to load the page.

As you enter text in the URL input field, Lagrange starts looking for matches in bookmarks, history, identities, and content of cached pages. This provides an easy way to return to a page you've been on recently. 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/unknown/invalid (cannot be opened)

Link colors remain the same regardless of which color theme is being used for page content. (Color themes are discussed in the Customization section.)

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.

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

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.

You can give it a try now with the link below. Either hold down ${ALT}, or press and release F.

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

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

## Sidebars

The sidebars can be toggled via menus or by pressing ${SHIFT+}${CTRL+}L or ${SHIFT+}${CTRL+}P (for the left/right sidebar, respectively). Both sidebars have five tabs:

* Bookmarks: List of bookmarks that you've created. These appear first in search results for quick and easy access.
* Feeds: Entries found on subscribed pages.
* 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+}5 switch between the left sidebar tabs, or hide the sidebar if the current tab's key is pressed. You can also press Escape to dismiss sidebars.

## Bookmarks

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

Bookmarks are listed in alphabetic order in the sidebar. There is no support for folders or manual sorting.

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. If multiple bookmarks are tagged as homepages, a random one is selected.
* A "subscribed" tag means that Lagrange will periodically fetch the bookmarked page and look for Gemini feed links. All the found links that match the required style ("YYYY-MM-DD Entry title") will appear in the Feeds sidebar tab.
* "headings" can be used together with "subscribed" to subscribe to new headings instead of Gemini feed links.

## Feeds

You may be familiar with RSS and Atom XML feeds from the web. Lagrange does _not_ support RSS or Atom, only Gemini feeds. A Gemini feed is simply a regular 'text/gemini' page that contains one or more links whose labels are formatted in a particular way.

=> gemini://gemini.circumlunar.space/docs/companion/subscription.gmi  See "Subscribing to Gemini pages" for more information.

Subscriptions are managed via bookmarks. When you subscribe to a feed page, a bookmark is created and the special "subscribed" tag is applied on it. In the Bookmarks list, this is indicated by a ★ icon. There is no other difference between normal bookmarks and feed subscriptions — you may tag any bookmark as "subscribed" and Lagrange will look through it for feed-style links. The bookmark title is used as the feed title. This defaults to the top heading of the feed index page, but you can edit it to suit your needs.

Feeds are refreshed periodically while Lagrange is running, and also immediately after launching if it has been a while since the previous refresh. You may also manually refresh all feeds via the menus or by pressing ${SHIFT+}${CTRL+}R.

The Feeds sidebar tab displays recent feed entries. From there you can open entries and mark them as read/unread.

To see all entries from all feeds, open the "Feed entries" page. This page also shows how long has it been since the previous feed refresh.
=> about:feeds

## Identities (client certificates)

Gemini uses TLS client certificates for user/session identification purposes. Unlike on the web where user identity tracking is covert and automatic, client certificates must be manually taken into use, and you are able to define how long each certificate remains valid. The term "Identity" is used in Lagrange to refer to client certificates.

The Identities sidebar tab shows all identities known to Lagrange. Press ${CTRL+}4 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 to be non-empty. The generated certificate will use the Common Name as the issuer and subject of the certificate, making 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.

When image or audio content is displayed inline, you can right-click on it and select "Save to Downloads" in the context menu.

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.

The location where downloaded files are saved can be changed in Preferences. The default location is "Downloads" in your home directory.

## Customization

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

### Browsing behavior

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.

### Window and UI options

Lagrange supports configuring dark and light UI modes separately.

There are four different color schemes for the UI: two for dark mode, and two for light mode. These can be selected on the "Window" 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.

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.

### Color themes

Page content color themes are selected on the "Colors" tab of Preferences. The "Dark theme" is active in dark UI mode, and the "Light theme" is active in light UI 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 "Style" tab of the Preferences dialog lets you customize the appearance and layout of page content.

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.

### Proxies

Gemini allows relaying requests via a proxy server. On the "Proxies" tab, you can configure proxy servers for Gemini, Gopher, and HTTP/HTTPS requests.

When an HTTP proxy server is configured, HTTP/HTTPS links will no longer open in the system's default web browser but will be loaded via the proxy, expecting it to serve a 'text/gemini' version of the link contents.

### Keybindings

The "Keys" tab lets you change which keys are bound to UI commands. Click on an item with the mouse and then press the new key combination that you want bound to it. Right-click on a binding to erase it or reset it to the default.

Erasing a binding can be useful to disable certain features. For example, if you have no use for keyboard navigation of links via a modifier key, that binding can be erased and use of the modifier key for other purposes will no longer distract you by showing the link shortcuts.

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
* feeds.txt
* idents.binary and idents/
* mimehooks.txt
* prefs.cfg
* state.binary
* trusted.txt
* visited.txt

# MIME hooks

MIME hooks enable piping Gemini responses through external programs for arbitrary processing. This allows leveraging scripting languages and binary executables to perform format conversions, content transformation, and data analysis.

Hooks are configured using the file "mimehooks.txt" in Lagrange's config directory. Each hook has a regexp that is matched against the response MIME type and parameters, and each matching hook is offered the response body via stdin. The called external programs are free to rewrite the entire response, including the MIME type. If one of the hooks returns a valid response, it is used as the final response of the Gemini request.

Example use cases:
* Parsing an Atom XML feed and generating a Gemini feed index page
* Rendering a MIDI file using Timidity as PCM WAV
* Generate a graph PNG based on values in a CSV
* Converting HTML or Markdown to 'text/gemini'
* Language translations

## Interface

When a hook is called, it is given the MIME type and parameters via command line arguments. The response body is provided via stdin. The request's URL is available in the REQUEST_URL environment variable.

The MIME type and parameters are split at semicolons, so "text/gemini; lang=ja" would be called as:
```
hookprogram text/gemini lang=ja 
```

Output from the program (via stdout) must be a valid "20" Gemini response that includes the new MIME type:
```
20 text/gemini; lang=en\r\n
{...body...}
```

Any output that does not follow this format is considered to mean that the hook refused to process the contents. The next hook will be offered the response instead.

## mimehooks.txt syntax

Like other Lagrange configuration lines, mimehooks.txt has a simple line-oriented syntax. Lagrange must be restarted for changes to the configuration file to take effect.

Each hook is specified as three lines:
* A human-readable label (for reporting to the user)
* MIME type/parameter regular expression
* Command to execute, plus additional arguments each separated with semicolons

For example:
```
Convert Atom to Gemini feed
application/xml
/usr/bin/python3;/home/jaakko/atomconv.py
```

The hook program is executed directly without involving the shell. This means scripts must be invoked via the interpreter executable.

## Example: Converting from Atom to Gemini

The following simple Python script demonstrates how a MIME hook could be used to parse an Atom XML document using Python 3 and output a Gemini feed index page based on the parsed entries. This is just a simple example; a more robust script could include more content from the Atom feed and handle errors, too.
```
import sys
import xml.etree.ElementTree as ET

def atomtag(n):
    return '{http://www.w3.org/2005/Atom}' + n

root = ET.fromstring(sys.stdin.read())
if root.tag != atomtag('feed'): 
    sys.exit(0)
feed_title = ''
feed_author = ''
feed_entries = []
for child in root:
    if child.tag == atomtag('title'):
        feed_title = child.text
    elif child.tag == atomtag('entry'):
        feed_entries.append(child)        
print("20 text/gemini\r")
print(f'# {feed_title}')
for entry in feed_entries:   
    entry_date = ''
    entry_title = ''
    entry_link = ''
    for child in entry:        
        if child.tag == atomtag('updated'): 
            entry_date = child.text[:10]
        elif child.tag == atomtag('title'):
            entry_title = child.text
        elif child.tag == atomtag('link'): 
            entry_link = child.attrib['href']
    print(f'=> {entry_link} {entry_date} {entry_title}')
```

# Open source licenses

=> about:license