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

```
# Help

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

## 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 with full Unicode support
* Autogenerated page style and symbol for each Gemini domain
* Light and dark color themes
* Scaling page content (50%...200%)
* Freely adjustable scaling factor for the UI
* Sidebar for managing bookmarks, subscribed feeds, and viewing browsing history and the page outline
* Multiple tabs
* Split view for browsing two pages at once (iPad only)
* Find text on the page
* Open image and audio links inline on the same page
* 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
* Built-in support for uploading data using the Titan protocol
* Use proxy servers for HTTP, Gopher, or Gemini content

# Work in progress!

This documentation is a work in progress. You may find it useful to alse see the desktop Help page:
=> gemini://git.skyjake.fi:1968/lagrange/release/res/about/help.gmi  Help page (desktop version, latest release)

# 1 User interface

## 1.6 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. This includes identities created in Lagrange and any identities based on imported X.509 certificates.

### 1.6.1 Creating a new identity

Click on the 👤 button in the toolbar and select "New Identity...".

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.

### 1.6.2 Using an identity

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

> 🔑 Certificate Required

Go to Settings > Identities and tap on an identity to 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.

### 1.6.3 Importing existing certificates

To import an existing X.509 certificate as an identity, click on 👤 and select "Import...".

When the Import Identity dialog opens, it checks the currently open page and the system clipboard for any certificates and private keys in PEM format. If found, these are automatically loaded in.

## 1.8 Uploads (with Titan)

Titan is a sister protocol to Gemini that enables sending arbitrary amounts of data from a client to a server. The Gemini protocol itself only enables sending up to 1024 bytes of data in a request. Furthermore, the request URL also counts against that limit, and the sent data must be percent-encoded so it can be parsed as a valid URL. Consequently, Gemini clients can only send very limited amounts of data to a server. Titan solves this by expanding the request so that the request URL is followed by a payload field. When it comes to TLS, Titan is equivalent to Gemini, so the same server and client certificates can be used with both.

=> gemini://transjovian.org/titan  Titan Protocol (by Alex Schroeder)

While Titan and Gemini are related, Titan is a separate protocol and regular Gemini servers are not expected to support it. Whether it makes sense to allow clients to upload large amounts of data is a service-specific question. For example, a server that hosts a gemlog could enable Titan uploads for submitting new posts, or editing existing posts by uploading a revised version.

As far as Lagrange is concerned, Titan is just one of the supported URL schemes. Whenever you try to open a "titan://" URL, no matter if it is manually entered into the URL field, or by clicking on a link, opening a bookmark, feed entry, or via a redirect, a dialog will open where you can specify the data to upload.

The Titan upload dialog supports two ways to enter the data:

* You can type text in the input field on the "Text" tab. It will be sent to the server using 'text/plain' as the media type.
* You can drag and drop a file on the dialog. The details of the file to be uploaded are visible on the "File" tab. The media type can be specified manually if Lagrange does not correctly detect it.

The upload token is a feature of Titan where servers can require a certain token text/passphrase for uploads. It is up to the server how this is interpreted. It could be used as a simple password, or even a command to further instruct the server about what to do with the uploaded data. Please refer to the server's instructions about what to enter here. The token may also be left empty.

The text entered into the upload dialog's main text field is protected against accidental closing of the dialog or the application, or a crash. The previous text is restored when the dialog is reopened. The text field contents are only cleared when the submitted Titan request has been successfully completed.

## 1.9 Split view mode (iPad only)

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 in each split. Closing all tabs on one side will remove the split and return back to the normal unsplit mode.

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.9.1 Switching focus

At any given time, one of the splits has input 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.

If a keyboard is connected, you can use the Next/Previous Tab keybindings or Ctrl+Tab to switch keyboard focus between the sections. 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.9.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 Settings. The "Split view pinning" setting on the "General" page of Settings 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".

The ◧ indicator is shown in the URL input field when the current tab is pinned.

# 2 Customization

## 2.1 Browsing behavior

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

## 2.4 Fonts

This version of Lagrange supports TrueType fonts. To use a new font, simply view a .ttf (or .fontpack) file in the app and a page footer action is available for performing the installation.

The "Fonts" page of Settings contains options that affect the appearance of text in page content, the user interface, and text rendering in general.

To be precise, on this tab you can select which _typefaces_ to use for certain elements of the page and the UI; picking a particular font (including its size, weight, style, etc.) for specific elements is not possible. Lagrange controls the size and styling of text by choosing fonts according to your theme and typeface preferences. The term "font" is often used to mean "typeface" in this document and in the app UI.

The fonts for document headings, body text, preformatted blocks, and the user interface can be chosen separately. There is also a separate font for monospaced body text, used when the protocol-specific "Monospace body" option is enabled.

There are two built-in fonts available:

* "Source Sans" is the default UI font that is also used for page content.
* "Iosevka" is the monospaced font.

There is also an "Iosevka (compact)" variant that actually uses the font's original line spacing. It is the default for preformatted blocks to avoid gaps between lines of ASCII art, but not for body text for better legibility.

See sections 2.4.4 and 5 for more details about font management, compatibility, and configuration.

### 2.4.1 Monospace body

The "Monospace body" option causes all pages to be displayed in a monospace font. For example, most Gopher content has been written with the assumption of a monospace font, so it may provide a better reading experience to enable this for Gopher pages. The selected "Monospace font" is applied to the entire document.

Handling of whitespace in page content also changes when this option is enabled: spaces are no longer normalized so if the source uses multiple spaces somewhere, those are shown as-is.

### 2.4.2 ANSI escapes

=> https://en.wikipedia.org/wiki/ANSI_escape_code  ANSI escape code (Wikipedia):
> ANSI escape sequences are a standard for in-band signaling to control cursor location, color, font styling, and other options on video text terminals and terminal emulators.

Sometimes these codes are used for things like colored ASCII art. However, Lagrange is not a terminal emulator so only a very minimal set of codes have any effect; the rest are ignored.

The "ANSI escapes" setting controls which ANSI escape codes are enabled:

* "FG Color" enables changes to text foreground color.
* "BG Color" enables changes to text background color.
* "Font Style" enables changing the font style: bold, italic, or monospace. (These correspond to codes 1, 3, and 11.)

A warning banner is displayed if any codes are detected on a page. This helps you be aware of potential visual artifacts, like text color that is being forced to black regardless of the page background color. Click on the warning to dismiss it on a per-site basis.

If you serve content via Gemini, please be aware that ANSI escapes may not be supported by clients, and may in fact disrupt the behavior of a client in unexpected ways. For instance, consider a screen reader or a web proxy that doesn't filter out the codes. Only employ ANSI escapes when the user has somehow indicated that is their preference.

### 2.4.3 Other font options

The "Glyph warnings" option controls whether a warning will be shown when a page is missing one or more characters. This is typically due to the page being in a language that is not covered by any of the installed fonts. Clicking on the glyph warning banner opens the font management page.

"Smoothing" enables or disables glyph antialiasing. In this version, it is recommended that smoothing is always enabled. This is because the text renderer does not support hinting of any kind, which means that without smoothing, glyph shapes will be severely distorted. You may still want to try disabling this option if antialiasing causes eye strain for you.

### 2.4.4 Managing fonts

Open "about:fonts" to see all the installed fonts, and enable, disable or uninstall individual fontpacks. At the top of the page, there is a link to the skyjake.fi Font Library: a curated collection of fontpacks that can be freely distributed. From there you can conveniently install more fonts specifically tuned for Lagrange.

The rest of the page is divided to two sections: enabled and disabled fontpacks. Individual packs can be disabled, so they remain installed but not in use. (Tip: Use the Outline sidebar to see a list of all packs, if there are many.) 

Click on the "View file" links to see what each fontpack contains. The fontpack format is described in section 5: it is simply a ZIP archive with some metadata and a bunch of font files. When you install a TrueType font (i.e., copy it to the user's fonts directory), it is treated as a fontpack containing a single file, although no ZIP archive is created for it. Use the "View fontpack.ini template" link to see the generated metadata that can be used as a basis for creating an actual fontpack.

About compatibility: fonts are complex, and while the TrueType format is not the most advanced one, it still has features that are not supported in Lagrange. The technical reason is that glyphs are rasterized using stb_truetype, a rather simple TrueType font library. (It's nice and small, though.) You may find that some fonts simply fail to load correctly, or look wrong in the app.

* Hinting is not supported. 
* Bitmap glyphs are not supported.
* Multi-color glyphs are not supported.

TrueType Collections (.ttc) can be used, with the restriction that each declared font uses a single index from the collection. The index must be appended to the file name:
```.ttc example
regular = "NotoSansCJK-Regular.ttc:2"
```