3 714541bb 2021-08-01 op Telescope is a Emacs/w3m-inspired browser for the "small internet"
4 714541bb 2021-08-01 op that supports Gemini, Gopher and Finger.
6 5899eca9 2024-02-20 op In features some expected stuff (tabs, bookmarks, history, client
7 5899eca9 2024-02-20 op certificates, ...) with an UI that's very much Emacs and w3m inspired,
8 5899eca9 2024-02-20 op and a privsep design.
10 4def0885 2021-03-12 op There are still various things missing or, if you prefer, various
11 4def0885 2021-03-12 op things that you can help develop :)
13 5899eca9 2024-02-20 op - other "smol internet" protocols
14 4def0885 2021-03-12 op - subscriptions
15 5899eca9 2024-02-20 op - TOFU out-of-band verification and/or DANE
16 5899eca9 2024-02-20 op - multiple UIs: at the moment it uses only ncurses, but telescope
17 0f7e6318 2021-06-20 op shouldn't be restricted to TTYs only!
19 cd2f2c82 2021-07-24 op [](https://asciinema.org/a/426862)
22 cd302034 2021-03-15 op ## Why yet another browser?
24 cd302034 2021-03-15 op One of the great virtues of Gemini is its simplicity. It means that
25 cd302034 2021-03-15 op writing browsers or server is easy and thus a plethora of those
26 cd302034 2021-03-15 op exists. I myself routinely switch between a couple of them, depending
29 5899eca9 2024-02-20 op More browsers means more choice for the users, and more stability for
30 5899eca9 2024-02-20 op the protocol too.
32 cd302034 2021-03-15 op However, Telescope was ultimately written for fun, on a whim, just to
33 5899eca9 2024-02-20 op play with ncurses, libtls, async I/O and the macros from `sys/queue.h`,
34 cd302034 2021-03-15 op but I'd like to finish it into a complete Gemini browser.
39 cd302034 2021-03-15 op - Fun: hacking on Telescope should be fun.
40 5899eca9 2024-02-20 op - Clean: write readable and clean code mostly following the OpenBSD
41 5899eca9 2024-02-20 op style(9) guideline. Don't become a kitchen sink.
42 cd302034 2021-03-15 op - Secure: write secure code with privilege separation to mitigate the
43 cd302034 2021-03-15 op security risks of possible bugs.
44 cd302034 2021-03-15 op - Fast: it features a modern, fast, event-based asynchronous I/O
46 2815e3a0 2024-09-01 op - Cooperation: reuse existing conventions to allow inter-operations
47 656b4b64 2021-03-16 op and easy migrations from/to other clients.
52 3be78a24 2021-03-17 op Telescope aims to use the "Trust, but Verify (where appropriate)"
53 3be78a24 2021-03-17 op approach outlined here:
54 3be78a24 2021-03-17 op [gemini://thfr.info/gemini/modified-trust-verify.gmi](gemini://thfr.info/gemini/modified-trust-verify.gmi).
56 3be78a24 2021-03-17 op The idea is to define three level of verification for a certificate:
58 3be78a24 2021-03-17 op - **untrusted**: the server fingerprint does NOT match the stored
60 3be78a24 2021-03-17 op - **trusted**: the server fingerprint matches the stored one
61 3be78a24 2021-03-17 op - **verified**: the fingerprint matches and has been verified
62 3be78a24 2021-03-17 op out-of-band by the client.
64 3be78a24 2021-03-17 op Most of the time, the `trusted` level is enough, but where is
65 3be78a24 2021-03-17 op appropriate users should be able to verify out-of-band the
68 5899eca9 2024-02-20 op At the moment there is no UI for out-of-band verification though.
73 5e58eeb5 2024-06-06 op Telescope depends on ncursesw, libtls or libretls, yacc/bison and
74 5e58eeb5 2024-06-06 op pkg-config. [libgrapheme][libgrapheme] is an optional dependency:
75 2815e3a0 2024-09-01 op there's a bundled copy but it's recommended to install it with a package
76 5e58eeb5 2024-06-06 op manager if available.
78 5899eca9 2024-02-20 op To build execute:
80 5899eca9 2024-02-20 op $ ./autogen.sh # only from git checkouts
83 5899eca9 2024-02-20 op $ sudo make install # eventually
85 7eaf997f 2021-08-19 op The configure script has optional support for building with libraries
86 94e6f532 2022-05-09 op provided by your distribution instead of using the bundled versions:
88 050e6b17 2022-11-02 op - `--with-libbsd`: link with [libbsd][libbsd]
89 050e6b17 2022-11-02 op - `--with-libimsg`: link with the [imsg-compat][imsg-compat] library
91 7e346d82 2024-06-10 thomas.ad The default-editor can be changed at build-time with the following option:
93 7e346d82 2024-06-10 thomas.ad - `--with-default-editor`: defaults to `ed(1)`
95 7e346d82 2024-06-10 thomas.ad This is useful for distributions such as Debian, which prefers
96 7e346d82 2024-06-10 thomas.ad `sensible-editor(1)` as a wrapper.
98 7e346d82 2024-06-10 thomas.ad This feature is mostly useful with the `mini-edit-external` command in
99 7e346d82 2024-06-10 thomas.ad `telescope`.
101 050e6b17 2022-11-02 op [libbsd]: https://libbsd.freedesktop.org
102 050e6b17 2022-11-02 op [imsg-compat]: https://github.com/bsd-ac/imsg-compat
103 050e6b17 2022-11-02 op [libgrapheme]: https://libs.suckless.org/libgrapheme/
106 908345fb 2021-08-28 op ## Contributing
108 c6cad9e5 2021-07-17 op Any form of contribution is appreciated, not only patches or bug
109 908345fb 2021-08-28 op reports: feel free to open an issue or send an email to
110 908345fb 2021-08-28 op `telescope@omarpolo.com`.
112 908345fb 2021-08-28 op If you have a sample configuration, custom theme, a script or anything
113 61105165 2022-03-29 op that could be helpful to others, consider adding it to the `contrib`
116 b7aa23a0 2024-05-25 op Consider also joining the official
117 b7aa23a0 2024-05-25 op [irc channel](ircs://irc.libera.chat:6697/telescope),
118 b7aa23a0 2024-05-25 op `#telescope` on libera.chat!
121 afa57f78 2021-07-15 op ## User files
123 73389b00 2021-10-08 op Telescope stores user files according to the [XDG Base Directory
124 73389b00 2021-10-08 op Specification][xdg] by default. The usage and contents of these files
125 eb2ed626 2021-10-07 op are described in [the man page](telescope.1), under "FILES".
127 5899eca9 2024-02-20 op At the moment, only one instance of Telescope can be running at time per
133 4def0885 2021-03-12 op Telescope is distributed under a BSD-style licence. The main code is
134 5899eca9 2024-02-20 op either under the ISC or is Public Domain, but some files under `compat/`
135 5899eca9 2024-02-20 op are 3-Clause BSD or MIT. See the first few lines of every file or
136 5899eca9 2024-02-20 op `about:license` inside telescope for the copyright information.
138 fe67a674 2024-01-16 op `data/emoji.txt` is copyright © 2022 Unicode, Inc. and distributed
139 fe67a674 2024-01-16 op under the [UNICODE, Inc license agreement][unicode-license].
142 bf6551ee 2021-07-18 op [unicode-license]: https://www.unicode.org/license.html
143 73389b00 2021-10-08 op [xdg]: https://specifications.freedesktop.org/basedir-spec/latest/
