1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
```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
* 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.
# 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.
## 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"
```
|
