3 Telescope is a Emacs/w3m-inspired browser for the "small internet"
4 that supports Gemini, Gopher and Finger.
11 - minibuffer live narrowing
12 - multiple protocols support
15 There are still various things missing or, if you prefer, various
16 things that you can help develop :)
19 - tofu oob verification
21 - add other GUIs: at the moment it uses only ncurses, but telescope
22 shouldn't be restricted to TTYs only!
24 [![asciicast](https://asciinema.org/a/426862.svg)](https://asciinema.org/a/426862)
27 ## Why yet another browser?
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
34 More browsers brings more stability as it became more difficult to
35 change the protocol, too.
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.
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
51 - Cooperation: re-use existing conventions to allow inter-operations
52 and easy migrations from/to other clients.
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).
61 The idea is to define three level of verification for a certificate:
63 - **untrusted**: the server fingerprint does NOT match the stored
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.
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
73 At the moment there is no UI for oob-verification though.
78 Telescope depends on ncursesw, libtls (from either LibreSSL or
79 libretls), libevent (either v1 or v2) and pkg-config.
80 [libgrapheme][libgrapheme] is an optional dependency: there's a
81 bundled copy but it's reccomended to install it if available. When
82 building from a git checkout, yacc (or bison) is also needed.
84 To build from a release tarball just execute:
90 The configure script has optional support for building with libraries
91 provided by your distribution instead of using the bundled versions:
93 - `--with-libbsd`: link with [libbsd][libbsd]
94 - `--with-libimsg`: link with the [imsg-compat][imsg-compat] library
96 If you want to build from the git checkout, something that's
97 discouraged for users that don't intend to hack on telescope
102 $ sudo make install # eventually
104 Please keep in mind that the main branch, from time to time, may be
105 accidentally broken on some platforms. Telescope is developed
106 primarily on OpenBSD/amd64 and commits on the main branch don't get
107 always tested in other OSes. Before tagging a release however, a
108 comprehensive testing on various platforms is done to ensure
109 everything is working as intended.
111 [libbsd]: https://libbsd.freedesktop.org
112 [imsg-compat]: https://github.com/bsd-ac/imsg-compat
113 [libgrapheme]: https://libs.suckless.org/libgrapheme/
118 Any form of contribution is appreciated, not only patches or bug
119 reports: feel free to open an issue or send an email to
120 `telescope@omarpolo.com`.
122 If you have a sample configuration, custom theme, a script or anything
123 that could be helpful to others, consider adding it to the `contrib`
129 Telescope stores user files according to the [XDG Base Directory
130 Specification][xdg] by default. The usage and contents of these files
131 are described in [the man page](telescope.1), under "FILES".
133 Only one instance of Telescope can be running at time per user.
138 Telescope is distributed under a BSD-style licence. The main code is
139 under the ISC but for files under `compat/` it varies.
141 `data/emoji.txt` is copyright © 1991-2021 Unicode, Inc. and
142 distributed under the [UNICODE, Inc license
143 agreement][unicode-license].
146 [unicode-license]: https://www.unicode.org/license.html
147 [xdg]: https://specifications.freedesktop.org/basedir-spec/latest/