summaryrefslogtreecommitdiff
path: root/res/about/help.gmi
blob: 158204d701f9e3973cce502c0c30cd09aacbd0a9 (plain)
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
```
           __   __             __   ___
|     /\  / _` |__)  /\  |\ | / _` |__
|___ /~~\ \__> |  \ /~~\ | \| \__> |___

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

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

## 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 terms are case insensitive, and if many words are entered, they are all required to appear in the specified order in any matched content.

Press Tab or ↓ to switch input focus to the search results.

Search within cached pages is limited to the (small) set of pages that Lagrange keeps in memory for back navigation. Note that while the navigation stack is saved to a file when Lagrange is shut down and restored on the next launch, it is also tab-specific — a tab's navigation cache is lost when the tab is closed.

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

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

## Bookmarks

...

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

Lagrange can easily create a 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.

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