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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
```
__ __ __ ___
| /\ / _` |__) /\ |\ | / _` |__
|___ /~~\ \__> | \ /~~\ | \| \__> |___
```
# 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 UI themes
* Select and copy text with the mouse
* Find text on the page
* Open image links inline on the same page
* 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
## 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.
* Below the navigation bar, there is a tab bar for switching between open 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.
## 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.
## 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.
## Navigation
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.
### Link icons
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)
### 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.
## 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.
## 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 (TLS 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.
### Using an identity
You'll need to select an identity when you encounter this error message:
...
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.
### 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".
# OS integration
## Opening Gemini URLs (macOS)
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, .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/
```
* bookmarks.txt
* idents.binary and idents/
* prefs.cfg
* state.binary
* trusted.txt
* visited.txt
## Command line options
### --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.
# Open source licenses
=> about:license
|
