1
# Telescope
2

3
Telescope is a Emacs/w3m-inspired browser for the "small internet"
4
that supports Gemini, Gopher and Finger.
5

6
Features:
7

8
 - tabs
9
 - bookmarks
10
 - privsep
11
 - minibuffer live narrowing
12
 - multiple protocols support
13
 - fully customizable
14

15
There are still various things missing or, if you prefer, various
16
things that you can help develop :)
17

18
 - subscriptions
19
 - tofu oob verification
20
 - client certificates
21
 - add other GUIs: at the moment it uses only ncurses, but telescope
22
   shouldn't be restricted to TTYs only!
23

24
[![asciicast](https://asciinema.org/a/426862.svg)](https://asciinema.org/a/426862)
25

26

27
## Why yet another browser?
28

29
One of the great virtues of Gemini is its simplicity.  It means that
30
writing browsers or server is easy and thus a plethora of those
31
exists.  I myself routinely switch between a couple of them, depending
32
on my mood.
33

34
More browsers brings more stability as it became more difficult to
35
change the protocol, too.
36

37
However, Telescope was ultimately written for fun, on a whim, just to
38
play with ncurses, libtls, libevent and the macros from `sys/queue.h`,
39
but I'd like to finish it into a complete Gemini browser.
40

41

42
## Goals
43

44
 - Fun: hacking on Telescope should be fun.
45
 - Clean: write readable and clean code mostly following the style(9)
46
   guideline.  Don't become a kitchen sink.
47
 - Secure: write secure code with privilege separation to mitigate the
48
   security risks of possible bugs.
49
 - Fast: it features a modern, fast, event-based asynchronous I/O
50
   model.
51
 - Cooperation: re-use existing conventions to allow inter-operations
52
   and easy migrations from/to other clients.
53

54

55
## TOFU
56

57
Telescope aims to use the "Trust, but Verify (where appropriate)"
58
approach outlined here:
59
[gemini://thfr.info/gemini/modified-trust-verify.gmi](gemini://thfr.info/gemini/modified-trust-verify.gmi).
60

61
The idea is to define three level of verification for a certificate:
62

63
 - **untrusted**: the server fingerprint does NOT match the stored
64
   value
65
 - **trusted**: the server fingerprint matches the stored one
66
 - **verified**: the fingerprint matches and has been verified
67
   out-of-band by the client.
68

69
Most of the time, the `trusted` level is enough, but where is
70
appropriate users should be able to verify out-of-band the
71
certificate.
72

73
At the moment there is no UI for oob-verification though.
74

75

76
## Building
77

78
Telescope depends on ncursesw, libtls (from either LibreSSL or
79
libretls), libevent (either v1 or v2) and pkg-config.  When building
80
from a git checkout, yacc (or bison) is also needed.
81

82
To build from a release tarball just execute:
83

84
	$ ./configure
85
	$ make
86
	$ sudo make install
87

88
The configure script has optional support for building with libraries
89
provided by your distribution instead of using the bundled versions:
90

91
 - `--with-libbsd`: link with [libbsd](https://libbsd.freedesktop.org)
92
 - `--with-libimsg`: link with the
93
   [imsg-compat](https://github.com/bsd-ac/imsg-compat) library
94

95
If you want to build from the git checkout, something that's
96
discouraged for users that don't intend to hack on telescope
97

98
	$ ./autogen.sh
99
	$ ./configure
100
	$ make
101
	$ sudo make install	# eventually
102

103
Please keep in mind that the main branch, from time to time, may be
104
accidentally broken on some platforms.  Telescope is developed
105
primarily on OpenBSD/amd64 and commits on the main branch don't get
106
always tested in other OSes.  Before tagging a release however, a
107
comprehensive testing on various platforms is done to ensure
108
everything is working as intended.
109

110

111
## Contributing
112

113
Any form of contribution is appreciated, not only patches or bug
114
reports: feel free to open an issue or send an email to
115
`telescope@omarpolo.com`.
116

117
If you have a sample configuration, custom theme, a script or anything
118
that could be helpful to others, consider adding it to the `contrib`
119
directory.
120

121

122
## User files
123

124
Telescope stores user files according to the [XDG Base Directory
125
Specification][xdg] by default.  The usage and contents of these files
126
are described in [the man page](telescope.1), under "FILES".
127

128
Only one instance of Telescope can be running at time per user.
129

130

131
## License
132

133
Telescope is distributed under a BSD-style licence.  The main code is
134
under the ISC but for files under `compat/` it varies.
135

136
`data/emoji.txt` is copyright © 1991-2021 Unicode, Inc. and
137
distributed under the [UNICODE, Inc license
138
agreement][unicode-license].
139

140

141
[unicode-license]: https://www.unicode.org/license.html
142
[xdg]: https://specifications.freedesktop.org/basedir-spec/latest/